glitcher_api/

registry.rs

//! Action Registry - Maps action IDs to handlers
//!
//! Provides hybrid type-safety with String names for UI triggers and
//! numeric IDs for fast execution path.
//!
//! ## Architecture
//!
//! - **UI Layer**: Triggers actions by string name ("reset", "randomize")
//! - **Registry**: Maps names → numeric IDs (HashMap)
//! - **Executor**: Dispatches by numeric ID (Vec indexing)
//!
//! ## Standard Actions
//!
//! Reserved IDs 0-99 for built-in actions:
//! - `0`: Reset - Return parameters to defaults
//! - `1`: Randomize - Randomize within widget ranges
//!
//! ## Custom Actions
//!
//! IDs 100+ for plugin-defined actions, executed via WASM.
//!
//! ## Usage
//!
//! ```rust,ignore
//! use glitcher_api::registry::ActionRegistry;
//! use glitcher_api::actions::ActionContext;
//!
//! let registry = ActionRegistry::from_manifest(manifest);
//!
//! // UI trigger by name
//! let updates = registry.trigger("reset", &ctx, 0)?;
//!
//! // Fast path by ID
//! let updates = registry.execute(standard_actions::RESET, &ctx, 0)?;
//! ```

use crate::{actions::ActionContext, ActionError, NodeManifest, ParamUpdate};
use std::collections::HashMap;

/// Numeric action ID for fast dispatch
pub type ActionId = u32;

/// Standard action ID constants (0-99 reserved)
pub mod standard_actions {
    use super::ActionId;
    pub const RESET: ActionId = 0;
    pub const RANDOMIZE: ActionId = 1;
}

/// Action handler variants
#[derive(Debug, Clone)]
pub enum ActionHandler {
    /// Standard action handled by host
    Standard(StandardAction),
    /// Custom action requiring WASM execution
    Custom(String),
}

/// Standard built-in actions
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StandardAction {
    Reset,
    Randomize,
}

/// Action registry for a node
///
/// Maintains bidirectional mapping between action names and IDs,
/// and dispatches to appropriate handlers.
pub struct ActionRegistry {
    /// String name → numeric ID mapping (for UI triggers)
    id_map: HashMap<String, ActionId>,

    /// Numeric ID → handler mapping (fast HashMap lookup)
    handlers: HashMap<ActionId, ActionHandler>,

    /// Reference to node manifest (needed for action execution)
    manifest: NodeManifest,
}

impl ActionRegistry {
    /// Create registry from node manifest
    ///
    /// Registers standard actions (IDs 0-2) and custom actions (IDs 100+).
    ///
    /// # Arguments
    /// * `manifest` - Node manifest containing action definitions
    ///
    /// # Returns
    /// * `Self` - Initialized action registry
    pub fn from_manifest(manifest: NodeManifest) -> Self {
        let mut id_map = HashMap::new();
        let mut handlers = HashMap::new();

        // Reserve standard action slots (0-1)
        // These are always present, even if not declared in manifest
        id_map.insert("reset".to_string(), standard_actions::RESET);
        handlers.insert(
            standard_actions::RESET,
            ActionHandler::Standard(StandardAction::Reset),
        );

        id_map.insert("randomize".to_string(), standard_actions::RANDOMIZE);
        handlers.insert(
            standard_actions::RANDOMIZE,
            ActionHandler::Standard(StandardAction::Randomize),
        );

        // Register custom actions from manifest (IDs 100+)
        let mut next_id = 100;
        for action in &manifest.actions {
            // Skip if already registered as standard action
            if !id_map.contains_key(&action.id) {
                id_map.insert(action.id.clone(), next_id);
                handlers.insert(next_id, ActionHandler::Custom(action.id.clone()));
                next_id += 1;
            }
        }

        Self {
            id_map,
            handlers,
            manifest,
        }
    }

    /// Trigger action by name (UI path)
    ///
    /// Looks up action ID by name and dispatches.
    ///
    /// # Arguments
    /// * `name` - Action name (e.g., "reset", "randomize")
    /// * `ctx` - Action context with current parameter state
    /// * `seed` - Random seed for randomize action
    ///
    /// # Returns
    /// * `Ok(Vec<ParamUpdate>)` - Parameter updates to apply
    /// * `Err(ActionError)` - Action not found or execution failed
    pub fn trigger(
        &self,
        name: &str,
        ctx: &ActionContext,
        seed: u64,
    ) -> Result<Vec<ParamUpdate>, ActionError> {
        let id = self
            .id_map
            .get(name)
            .ok_or_else(|| ActionError::ActionNotFound(name.to_string()))?;

        self.execute(*id, ctx, seed)
    }

    /// Execute action by numeric ID (fast path)
    ///
    /// Directly dispatches to handler without name lookup.
    ///
    /// # Arguments
    /// * `id` - Numeric action ID
    /// * `ctx` - Action context with current parameter state
    /// * `seed` - Random seed for randomize action
    ///
    /// # Returns
    /// * `Ok(Vec<ParamUpdate>)` - Parameter updates to apply
    /// * `Err(ActionError)` - Invalid ID or execution failed
    pub fn execute(
        &self,
        id: ActionId,
        ctx: &ActionContext,
        seed: u64,
    ) -> Result<Vec<ParamUpdate>, ActionError> {
        let handler = self
            .handlers
            .get(&id)
            .ok_or_else(|| ActionError::ActionNotFound(id.to_string()))?;

        match handler {
            ActionHandler::Standard(action) => self.execute_standard(action, ctx, seed),
            ActionHandler::Custom(name) => Err(ActionError::ExecutionFailed(format!(
                "Custom action '{}' requires WASM execution (not available in registry)",
                name
            ))),
        }
    }

    /// Execute standard built-in action
    ///
    /// Dispatches to appropriate action implementation.
    fn execute_standard(
        &self,
        action: &StandardAction,
        ctx: &ActionContext,
        seed: u64,
    ) -> Result<Vec<ParamUpdate>, ActionError> {
        match action {
            StandardAction::Reset => crate::actions::calculate_reset_values(&self.manifest, ctx)
                .map_err(ActionError::ExecutionFailed),

            StandardAction::Randomize => {
                crate::actions::calculate_random_values(&self.manifest, ctx, seed)
                    .map_err(ActionError::ExecutionFailed)
            }
        }
    }

    /// Get action ID by name (for debugging)
    pub fn get_id(&self, name: &str) -> Option<ActionId> {
        self.id_map.get(name).copied()
    }

    /// Get action count (standard + custom)
    pub fn action_count(&self) -> usize {
        self.handlers.len()
    }

    /// Check if action is standard (built-in)
    pub fn is_standard(&self, id: ActionId) -> bool {
        id < 100
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{
        ActionConfig, ActionDef, ExecutionModel, NodeCategory, ParamType, ShaderParam,
        SliderConfig, WidgetConfig,
    };

    fn create_test_manifest() -> NodeManifest {
        NodeManifest {
            api_version: 1,
            display_name: "Test Node".to_string(),
            version: "1.0.0".to_string(),
            author: "Test".to_string(),
            description: "Test node".to_string(),
            category: NodeCategory::Effector,
            tags: vec![],
            model: ExecutionModel::FragmentShader,
            parameters: vec![ShaderParam {
                name: "strength".to_string(),
                data_type: ParamType::ScalarF32,
                widget: WidgetConfig::Slider(SliderConfig {
                    min: 0.0,
                    max: 1.0,
                    step: 0.01,
                }),
            }],
            ports: vec![],
            output_resolution_scale: 1.0,
            output_hint: None,
            actions: vec![
                ActionDef {
                    id: "custom-action-1".to_string(),
                    label: "Custom Action 1".to_string(),
                    config: ActionConfig::Trigger,
                },
                ActionDef {
                    id: "custom-action-2".to_string(),
                    label: "Custom Action 2".to_string(),
                    config: ActionConfig::BeatSync,
                },
            ],
            embedded_textures: vec![],
        }
    }

    #[test]
    fn test_registry_creation() {
        let manifest = create_test_manifest();
        let registry = ActionRegistry::from_manifest(manifest);

        // Standard actions should be registered
        assert_eq!(registry.get_id("reset"), Some(standard_actions::RESET));
        assert_eq!(
            registry.get_id("randomize"),
            Some(standard_actions::RANDOMIZE)
        );

        // Custom actions should start at ID 100
        assert_eq!(registry.get_id("custom-action-1"), Some(100));
        assert_eq!(registry.get_id("custom-action-2"), Some(101));

        // Total: 2 standard + 2 custom = 4
        assert_eq!(registry.action_count(), 4);
    }

    #[test]
    fn test_trigger_by_name() {
        let manifest = create_test_manifest();
        let registry = ActionRegistry::from_manifest(manifest);
        let ctx = ActionContext {
            params: &[],
            beat_info: None,
            is_high_frequency: false,
        };

        // Reset action should succeed
        let result = registry.trigger("reset", &ctx, 0);
        assert!(result.is_ok());
        let updates = result.unwrap();
        assert_eq!(updates.len(), 1); // One parameter

        // Randomize action should succeed
        let result = registry.trigger("randomize", &ctx, 42);
        assert!(result.is_ok());

        // Unknown action should fail
        let result = registry.trigger("unknown", &ctx, 0);
        assert!(matches!(result, Err(ActionError::ActionNotFound(_))));
    }

    #[test]
    fn test_execute_by_id() {
        let manifest = create_test_manifest();
        let registry = ActionRegistry::from_manifest(manifest);
        let ctx = ActionContext {
            params: &[],
            beat_info: None,
            is_high_frequency: false,
        };

        // Execute reset by ID
        let result = registry.execute(standard_actions::RESET, &ctx, 0);
        assert!(result.is_ok());

        // Execute randomize by ID
        let result = registry.execute(standard_actions::RANDOMIZE, &ctx, 42);
        assert!(result.is_ok());

        // Invalid ID should fail
        let result = registry.execute(999, &ctx, 0);
        assert!(matches!(result, Err(ActionError::ActionNotFound(_))));
    }

    #[test]
    fn test_custom_action_fails_without_wasm() {
        let manifest = create_test_manifest();
        let registry = ActionRegistry::from_manifest(manifest);
        let ctx = ActionContext {
            params: &[],
            beat_info: None,
            is_high_frequency: false,
        };

        // Custom action should fail (no WASM executor in registry)
        let result = registry.trigger("custom-action-1", &ctx, 0);
        assert!(matches!(result, Err(ActionError::ExecutionFailed(_))));
    }

    #[test]
    fn test_is_standard() {
        let manifest = create_test_manifest();
        let registry = ActionRegistry::from_manifest(manifest);

        assert!(registry.is_standard(0)); // RESET
        assert!(registry.is_standard(1)); // RANDOMIZE
        assert!(!registry.is_standard(100)); // Custom action
        assert!(!registry.is_standard(101)); // Custom action
    }
}