glitcher_api/

lib.rs

//! # Glitcher API
//!
//! WebAssembly Interface Types for Glitcher Engine render node plugins.
//!
//! ## Overview
//!
//! This crate provides the WIT-generated Rust types that define the contract
//! between the Glitcher Engine host and WASM plugins. Plugins act as "Definition
//! Providers" - they supply node metadata and WGSL shader source code.
//!
//! ## Architecture
//!
//! ```text
//! WASM Plugin (Guest)          Glitcher Engine (Host)
//! ┌─────────────────┐          ┌─────────────────────┐
//! │ get-manifest()  │────WIT──>│ Load metadata       │
//! │ get-shader()    │────WIT──>│ Compile WGSL        │
//! └─────────────────┘          │ Execute on GPU      │
//!                              └─────────────────────┘
//! ```
//!
//! ## Usage
//!
//! ### For Plugin Authors (Guest)
//!
//! ```rust,ignore
//! use glitcher_api::*;
//!
//! wit_bindgen::generate!({
//!     world: "plugin",
//!     exports: {
//!         "glitcher:engine/render-node": MyNode,
//!     }
//! });
//!
//! struct MyNode;
//!
//! impl Guest for MyNode {
//!     fn get_manifest() -> NodeManifest {
//!         NodeManifest {
//!             api_version: 1,
//!             display_name: "My Effect".into(),
//!             model: ExecutionModel::FragmentShader,
//!             parameters: vec![
//!                 ShaderParam {
//!                     name: "strength".into(),
//!                     data_type: ParamType::F32,
//!                     widget: WidgetConfig::Slider(SliderConfig {
//!                         min: 0.0,
//!                         max: 1.0,
//!                         step: 0.01,
//!                     }),
//!                 }
//!             ],
//!             textures: vec![
//!                 TexturePort {
//!                     name: "input".into(),
//!                     binding_slot: 0,
//!                     writable: false,
//!                 }
//!             ],
//!             output_resolution_scale: 1.0,
//!         }
//!     }
//!
//!     fn get_shader_source() -> String {
//!         r#"
//!         struct Params {
//!             strength: f32,
//!         }
//!
//!         @group(1) @binding(0) var<uniform> params: Params;
//!         @group(2) @binding(0) var input_texture: texture_2d<f32>;
//!
//!         @fragment
//!         fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
//!             // Your shader code here
//!             return textureSample(input_texture, sampler, uv);
//!         }
//!         "#.into()
//!     }
//! }
//! ```
//!
//! ### For Host Implementation
//!
//! ```rust,ignore
//! use glitcher_api::*;
//! use wasmtime::*;
//!
//! // Load and instantiate WASM plugin
//! let module = Module::from_file(&engine, "plugin.wasm")?;
//! let instance = linker.instantiate(&mut store, &module)?;
//!
//! // Call WIT functions
//! let get_manifest = instance
//!     .get_typed_func::<(), NodeManifest>(&mut store, "get-manifest")?;
//! let manifest = get_manifest.call(&mut store, ())?;
//!
//! // Validate and use manifest
//! assert_eq!(manifest.api_version, 1);
//! ```
//!
//! ## Type System
//!
//! All types are strongly typed through WIT, eliminating string-based parsing:
//!
//! - [`ParamType`]: WGSL-compatible parameter types (f32, vec3, mat4, etc.)
//! - [`WidgetConfig`]: UI widget configurations (slider, color-picker, etc.)
//! - [`ExecutionModel`]: Fragment shader or compute shader
//! - [`NodeManifest`]: Complete node definition
//!
//! ## Memory Layout
//!
//! The host calculates GPU buffer layouts using std140 rules based on [`ParamType`].
//! Plugins don't need to worry about alignment or padding.
//!
//! ## Binding Conventions
//!
//! Shaders must follow these binding group conventions:
//!
//! - **Group 0**: System globals (time, resolution, mouse) - Host-managed
//! - **Group 1**: Node parameters - Single uniform buffer at binding 0
//! - **Group 2**: Textures - Bindings match [`TexturePort::binding_slot`]
//!
//! ## API Versioning
//!
//! The [`NodeManifest::api_version`] field ensures compatibility:
//!
//! - Current version: **1**
//! - Host rejects plugins with mismatched versions
//! - Breaking changes increment the version number

// Re-export WIT-generated types
wit_bindgen::generate!({
    path: "wit",
    world: "plugin",
});

// Re-export from sub-interfaces for backwards compatibility
pub use exports::glitcher::engine::actions::{
    ActionConfig, ActionDef, ActionError, BeatInfo, ParamComputeConfig, ParamRangeError, ParamRef,
    ParamUpdate,
};
pub use exports::glitcher::engine::ports::{
    ControlOutput, NodePort, PortConfig, TextureStorageConfig,
};
pub use exports::glitcher::engine::render_node::{
    CustomCategory, CustomOutputHint, EmbeddedTexture, Guest, NodeCategory, NodeManifest,
    OutputHint,
};
pub use exports::glitcher::engine::types::{
    ExecutionModel, ParamType, ParamValue, StorageTextureFormat, WorkgroupSize,
};
pub use exports::glitcher::engine::widgets::{
    ButtonGroupConfig, ControlPreviewConfig, CustomWidget, DropdownConfig, ShaderParam,
    SliderConfig, WidgetConfig,
};

/// Current API version
///
/// This constant should match the version used by the host.
/// Plugins should use this in their manifest:
///
/// ```rust,ignore
/// NodeManifest {
///     api_version: glitcher_api::CURRENT_API_VERSION,
///     // ...
/// }
/// ```
pub const CURRENT_API_VERSION: u32 = 1;

/// Standard action implementations
pub mod actions;

/// Action registry for name→ID mapping and dispatch
pub mod registry;

/// Hook system for action execution events
pub mod hooks;

/// Builtin plugin provider interface
pub mod builtin;

/// Helper to create a slider widget config
pub fn slider(min: f32, max: f32, step: f32) -> WidgetConfig {
    WidgetConfig::Slider(SliderConfig { min, max, step })
}

/// Helper to create a dropdown widget config
///
/// Best for: Many options or detailed work (combobox style)
pub fn dropdown(options: Vec<String>) -> WidgetConfig {
    WidgetConfig::Dropdown(DropdownConfig { options })
}

/// Helper to create a button group widget config
///
/// Best for: Live performance with quick visual selection (2-6 options)
pub fn button_group(options: Vec<String>) -> WidgetConfig {
    WidgetConfig::ButtonGroup(ButtonGroupConfig { options })
}

/// Helper to create a compute shader execution model
pub fn compute_shader(x: u32, y: u32, z: u32) -> ExecutionModel {
    ExecutionModel::ComputeShader(WorkgroupSize { x, y, z })
}

/// Helper to create a fragment shader execution model
pub fn fragment_shader() -> ExecutionModel {
    ExecutionModel::FragmentShader
}

// =============================================================================
// Port Helpers
// =============================================================================

/// Helper to create a texture input port
///
/// # Example
/// ```rust,ignore
/// let port = texture_input("input", 0);
/// ```
pub fn texture_input(name: &str, binding_slot: u32) -> NodePort {
    NodePort {
        name: name.to_string(),
        config: PortConfig::TextureInput(binding_slot),
    }
}

/// Helper to create a texture output port
///
/// Note: Most nodes have implicit output (their rendered texture).
/// Explicit output ports are used for compute shaders with multiple outputs.
pub fn texture_output(name: &str, binding_slot: u32) -> NodePort {
    NodePort {
        name: name.to_string(),
        config: PortConfig::TextureOutput(binding_slot),
    }
}

/// Helper to create a texture storage port (read/write for compute shaders)
///
/// # Example
/// ```rust,ignore
/// let port = texture_storage("trail_map", 0, StorageTextureFormat::Rgba8Unorm);
/// let port = texture_storage("agent_map", 1, StorageTextureFormat::Rgba32Float);
/// ```
pub fn texture_storage(name: &str, binding_slot: u32, format: StorageTextureFormat) -> NodePort {
    NodePort {
        name: name.to_string(),
        config: PortConfig::TextureStorage(TextureStorageConfig {
            binding_slot,
            format,
            is_input: false,
        }),
    }
}

/// Helper to create a texture storage input port (read/write for compute shaders, accepts connections)
///
/// Use this for compute shader ports that need to receive input from other nodes.
/// The engine will automatically blit from the connected texture output to this storage texture.
///
/// # Example
/// ```rust,ignore
/// let port = texture_storage_input("input", 0, StorageTextureFormat::Rgba8Unorm);
/// ```
pub fn texture_storage_input(
    name: &str,
    binding_slot: u32,
    format: StorageTextureFormat,
) -> NodePort {
    NodePort {
        name: name.to_string(),
        config: PortConfig::TextureStorage(TextureStorageConfig {
            binding_slot,
            format,
            is_input: true,
        }),
    }
}

/// Helper to create a control output port
///
/// Use this for ParamCompute MODs that generate control signals (LFO, envelope, etc.)
///
/// ## Note: No control_input helper
///
/// All parameters are implicitly controllable - any parameter can receive
/// modulation from a control-output port without explicit declaration.
/// The target parameter is selected via UI (ControlTargetSelector widget),
/// not hardcoded in the MOD.
///
/// # Example
/// ```rust,ignore
/// let port = control_output_port("lfo_out");
/// ```
pub fn control_output_port(name: &str) -> NodePort {
    NodePort {
        name: name.to_string(),
        config: PortConfig::ControlOutput,
    }
}

// =============================================================================
// PortConfig Helper Methods
// =============================================================================

/// Extension trait for PortConfig helpers
pub trait PortConfigExt {
    /// Check if this is a texture port (input, output, or storage)
    fn is_texture(&self) -> bool;
    /// Check if this is a texture input port
    fn is_texture_input(&self) -> bool;
    /// Check if this is a texture output port
    fn is_texture_output(&self) -> bool;
    /// Check if this is a texture storage port
    fn is_texture_storage(&self) -> bool;
    /// Check if this is a control output port
    fn is_control_output(&self) -> bool;
    /// Check if this is an input port (texture input only - control input is implicit)
    fn is_input(&self) -> bool;
    /// Check if this is an output port (texture output, storage, or control output)
    fn is_output(&self) -> bool;
    /// Get binding slot (for texture ports)
    fn binding_slot(&self) -> Option<u32>;
}

impl PortConfigExt for PortConfig {
    fn is_texture(&self) -> bool {
        matches!(
            self,
            PortConfig::TextureInput(_)
                | PortConfig::TextureOutput(_)
                | PortConfig::TextureStorage(_)
        )
    }

    fn is_texture_input(&self) -> bool {
        matches!(self, PortConfig::TextureInput(_))
    }

    fn is_texture_output(&self) -> bool {
        matches!(self, PortConfig::TextureOutput(_))
    }

    fn is_texture_storage(&self) -> bool {
        matches!(self, PortConfig::TextureStorage(_))
    }

    fn is_control_output(&self) -> bool {
        matches!(self, PortConfig::ControlOutput)
    }

    fn is_input(&self) -> bool {
        // Note: No ControlInput - all parameters are implicitly controllable
        match self {
            PortConfig::TextureInput(_) => true,
            PortConfig::TextureStorage(config) => config.is_input,
            _ => false,
        }
    }

    fn is_output(&self) -> bool {
        match self {
            PortConfig::TextureOutput(_) => true,
            PortConfig::ControlOutput => true,
            // Storage textures with is_input=false are treated as outputs
            PortConfig::TextureStorage(config) => !config.is_input,
            _ => false,
        }
    }

    fn binding_slot(&self) -> Option<u32> {
        match self {
            PortConfig::TextureInput(slot) => Some(*slot),
            PortConfig::TextureOutput(slot) => Some(*slot),
            PortConfig::TextureStorage(config) => Some(config.binding_slot),
            PortConfig::ControlOutput => None,
        }
    }
}

// =============================================================================
// Test Helpers (cfg(test) only)
// =============================================================================

/// Test-only builder for NodeManifest with sensible defaults.
///
/// Use this in tests to avoid updating every test when new fields are added.
/// Search for `test_manifest_builder` to find all usages when adding new fields.
///
/// # Example
/// ```rust,ignore
/// let manifest = test_manifest_builder()
///     .display_name("My Test Node")
///     .category(NodeCategory::Effector)
///     .build();
/// ```
#[cfg(any(test, feature = "test-utils"))]
pub fn test_manifest_builder() -> TestManifestBuilder {
    TestManifestBuilder::default()
}

#[cfg(any(test, feature = "test-utils"))]
#[derive(Default)]
pub struct TestManifestBuilder {
    display_name: Option<String>,
    category: Option<NodeCategory>,
    parameters: Vec<ShaderParam>,
    ports: Vec<NodePort>,
    actions: Vec<ActionDef>,
}

#[cfg(any(test, feature = "test-utils"))]
impl TestManifestBuilder {
    pub fn display_name(mut self, name: &str) -> Self {
        self.display_name = Some(name.to_string());
        self
    }

    pub fn category(mut self, cat: NodeCategory) -> Self {
        self.category = Some(cat);
        self
    }

    pub fn parameters(mut self, params: Vec<ShaderParam>) -> Self {
        self.parameters = params;
        self
    }

    pub fn ports(mut self, ports: Vec<NodePort>) -> Self {
        self.ports = ports;
        self
    }

    pub fn actions(mut self, actions: Vec<ActionDef>) -> Self {
        self.actions = actions;
        self
    }

    pub fn build(self) -> NodeManifest {
        NodeManifest {
            api_version: CURRENT_API_VERSION,
            display_name: self.display_name.unwrap_or_else(|| "Test Node".to_string()),
            version: "1.0.0".to_string(),
            author: "Test".to_string(),
            description: "Test node".to_string(),
            category: self.category.unwrap_or(NodeCategory::Effector),
            tags: vec![],
            model: ExecutionModel::FragmentShader,
            parameters: self.parameters,
            ports: self.ports,
            output_resolution_scale: 1.0,
            output_hint: None,
            actions: self.actions,
            embedded_textures: vec![],
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_api_version_constant() {
        assert_eq!(CURRENT_API_VERSION, 1);
    }

    #[test]
    fn test_slider_helper() {
        let widget = slider(0.0, 1.0, 0.01);
        match widget {
            WidgetConfig::Slider(config) => {
                assert_eq!(config.min, 0.0);
                assert_eq!(config.max, 1.0);
                assert_eq!(config.step, 0.01);
            }
            _ => panic!("Expected slider variant"),
        }
    }

    #[test]
    fn test_compute_shader_helper() {
        let model = compute_shader(8, 8, 1);
        match model {
            ExecutionModel::ComputeShader(size) => {
                assert_eq!(size.x, 8);
                assert_eq!(size.y, 8);
                assert_eq!(size.z, 1);
            }
            _ => panic!("Expected compute shader variant"),
        }
    }

    #[test]
    fn test_fragment_shader_helper() {
        let model = fragment_shader();
        assert!(matches!(model, ExecutionModel::FragmentShader));
    }

    #[test]
    fn test_dropdown_helper() {
        let options = vec![
            "Normal".to_string(),
            "Add".to_string(),
            "Multiply".to_string(),
        ];
        let widget = dropdown(options.clone());
        match widget {
            WidgetConfig::Dropdown(config) => {
                assert_eq!(config.options.len(), 3);
                assert_eq!(config.options[0], "Normal");
                assert_eq!(config.options[1], "Add");
                assert_eq!(config.options[2], "Multiply");
            }
            _ => panic!("Expected dropdown variant"),
        }
    }

    #[test]
    fn test_button_group_helper() {
        let options = vec!["A".to_string(), "B".to_string(), "C".to_string()];
        let widget = button_group(options.clone());
        match widget {
            WidgetConfig::ButtonGroup(config) => {
                assert_eq!(config.options.len(), 3);
                assert_eq!(config.options[0], "A");
            }
            _ => panic!("Expected button_group variant"),
        }
    }

    // Action System types tests
    #[test]
    fn test_action_config_variants() {
        let _trigger = ActionConfig::Trigger;
        let _toggle = ActionConfig::Toggle;
        let _beat_sync = ActionConfig::BeatSync;
    }

    #[test]
    fn test_action_def_creation() {
        let action = ActionDef {
            id: "reset".to_string(),
            label: "Reset".to_string(),
            config: ActionConfig::Trigger,
        };
        assert_eq!(action.id, "reset");
        assert_eq!(action.label, "Reset");
    }

    #[test]
    fn test_param_value_variants() {
        let _f32_val = ParamValue::ScalarF32(1.0);
        let _i32_val = ParamValue::ScalarI32(42);
        let _u32_val = ParamValue::ScalarU32(100);
        let _bool_val = ParamValue::ScalarBool(true);
        let _vec2_val = ParamValue::Vec2F32((1.0, 2.0));
        let _vec3_val = ParamValue::Vec3F32((1.0, 2.0, 3.0));
        let _vec4_val = ParamValue::Vec4F32((1.0, 2.0, 3.0, 4.0));
    }

    #[test]
    fn test_param_update_creation() {
        let update = ParamUpdate {
            param_index: 0,
            value: ParamValue::ScalarF32(0.5),
        };
        assert_eq!(update.param_index, 0);
    }

    #[test]
    fn test_beat_info_creation() {
        let beat = BeatInfo {
            bpm: 120.0,
            phase: 0.5,
            bar_position: 0.25,
        };
        assert_eq!(beat.bpm, 120.0);
        assert_eq!(beat.phase, 0.5);
        assert_eq!(beat.bar_position, 0.25);
    }

    #[test]
    fn test_action_error_variants() {
        let _not_found = ActionError::ActionNotFound("test".to_string());
        let _invalid_state = ActionError::InvalidState("test".to_string());
        let _exec_failed = ActionError::ExecutionFailed("test".to_string());
        let _out_of_range = ActionError::ParameterOutOfRange(ParamRangeError {
            param: "test".to_string(),
            value: "1.0".to_string(),
        });
    }
}

// =============================================================================
// System Globals
// =============================================================================

/// System globals shared across all nodes
///
/// Bound to @group(0) @binding(0) in all shaders.
/// This provides common values that are the same for all nodes in a render pass.
///
/// Layout follows std140 rules:
/// - vec2 = 8 bytes, 8-byte aligned
/// - vec4 = 16 bytes, 16-byte aligned
/// - Total size must be multiple of 16 bytes
#[repr(C)]
#[derive(Debug, Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
pub struct SystemGlobals {
    /// Time since engine start in seconds
    pub time: f32,
    /// Delta time since last frame in seconds
    pub delta_time: f32,
    /// Current frame count
    pub frame_count: u32,
    /// Padding for std140 alignment (vec4 boundary)
    _padding1: u32,

    /// Screen resolution in pixels (width, height)
    pub resolution: [f32; 2],
    /// Mouse position normalized to 0.0-1.0 (x, y)
    pub mouse: [f32; 2],

    /// Audio analysis: overall volume (0.0-1.0)
    pub audio_volume: f32,
    /// Audio analysis: bass frequencies (0.0-1.0)
    pub audio_bass: f32,
    /// Audio analysis: mid frequencies (0.0-1.0)
    pub audio_mid: f32,
    /// Audio analysis: high frequencies (0.0-1.0)
    pub audio_high: f32,

    // === Beat Sync ===
    /// Current BPM (beats per minute)
    pub beat_bpm: f32,
    /// Beat phase (0.0-1.0, 0.0 = on beat)
    pub beat_phase: f32,
    /// Cumulative beat count
    pub beat_count: u32,
    /// Padding for std140 alignment
    _padding2: u32,

    // === External Inputs (Creative Coding / SNS) ===
    /// External input 1 (OSC, sensor, SNS, etc.)
    pub external_input_1: f32,
    /// External input 2 (OSC, sensor, SNS, etc.)
    pub external_input_2: f32,
    /// External input 3 (OSC, sensor, SNS, etc.)
    pub external_input_3: f32,
    /// External input 4 (OSC, sensor, SNS, etc.)
    pub external_input_4: f32,
}

impl Default for SystemGlobals {
    fn default() -> Self {
        Self {
            time: 0.0,
            delta_time: 0.0,
            frame_count: 0,
            _padding1: 0,
            resolution: [1920.0, 1080.0],
            mouse: [0.5, 0.5],
            audio_volume: 0.0,
            audio_bass: 0.0,
            audio_mid: 0.0,
            audio_high: 0.0,
            beat_bpm: 120.0,
            beat_phase: 0.0,
            beat_count: 0,
            _padding2: 0,
            external_input_1: 0.0,
            external_input_2: 0.0,
            external_input_3: 0.0,
            external_input_4: 0.0,
        }
    }
}

impl SystemGlobals {
    /// Size in bytes (must be multiple of 16 for std140)
    /// Layout: time(4) + delta_time(4) + frame_count(4) + pad(4) = 16
    ///         resolution(8) + mouse(8) = 16
    ///         audio_volume(4) + audio_bass(4) + audio_mid(4) + audio_high(4) = 16
    ///         beat_bpm(4) + beat_phase(4) + beat_count(4) + pad(4) = 16
    ///         external_input_1(4) + external_input_2(4) + external_input_3(4) + external_input_4(4) = 16
    ///         Total: 80 bytes
    pub const SIZE: u64 = 80;

    /// Convert to byte array for GPU upload
    pub fn as_bytes(&self) -> &[u8] {
        bytemuck::bytes_of(self)
    }
}

// =============================================================================
// External Trigger State
// =============================================================================

/// Per-node external trigger state
///
/// Bound to @group(4) @binding(0) for nodes with external trigger actions.
/// Similar to BeatSync, but for external events (OSC, SNS, HTTP, etc.)
///
/// ## Memory Layout (std140)
/// - 4 floats = 16 bytes total
#[repr(C)]
#[derive(Clone, Copy, Debug, Default, bytemuck::Pod, bytemuck::Zeroable)]
pub struct ExternalTriggerState {
    /// Time when this node was last triggered (seconds since engine start)
    pub last_trigger_time: f32,

    /// Trigger type/source identifier (e.g., 0=OSC, 1=SNS mention, 2=HTTP webhook)
    pub trigger_type: f32,

    /// Intensity/value at trigger time (0.0-1.0, can be > 1.0 for boosted events)
    pub trigger_intensity: f32,

    /// Custom parameter for event-specific data
    pub custom_param: f32,
}

impl ExternalTriggerState {
    /// Size in bytes (16 bytes, std140 aligned)
    pub const SIZE: u64 = 16;

    /// Convert to byte array for GPU upload
    pub fn as_bytes(&self) -> &[u8] {
        bytemuck::bytes_of(self)
    }
}

// =============================================================================
// Parameter Modulation Types
// =============================================================================

/// Modulation waveform types for LFO
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ModWaveform {
    /// No modulation
    #[default]
    Off,
    /// Sine wave (smooth oscillation)
    Sin,
    /// Sawtooth wave (linear ramp)
    Saw,
    /// Square wave (on/off)
    Square,
    /// Random (sample & hold)
    Random,
}

impl ModWaveform {
    /// Get display name
    pub fn name(&self) -> &'static str {
        match self {
            ModWaveform::Off => "Off",
            ModWaveform::Sin => "Sin",
            ModWaveform::Saw => "Saw",
            ModWaveform::Square => "Sq",
            ModWaveform::Random => "Rnd",
        }
    }

    /// Get all waveform variants
    pub fn all() -> &'static [ModWaveform] {
        &[
            ModWaveform::Off,
            ModWaveform::Sin,
            ModWaveform::Saw,
            ModWaveform::Square,
            ModWaveform::Random,
        ]
    }
}

/// Beat division for modulation timing
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum BeatDivision {
    /// 1/4 beat
    Quarter,
    /// 1/2 beat
    Half,
    /// 1 beat (default)
    #[default]
    One,
    /// 2 beats
    Two,
    /// 4 beats (1 bar)
    Four,
}

impl BeatDivision {
    /// Get display name
    pub fn name(&self) -> &'static str {
        match self {
            BeatDivision::Quarter => "1/4",
            BeatDivision::Half => "1/2",
            BeatDivision::One => "1",
            BeatDivision::Two => "2",
            BeatDivision::Four => "4",
        }
    }

    /// Get beat multiplier (how many beats per cycle)
    pub fn multiplier(&self) -> f32 {
        match self {
            BeatDivision::Quarter => 0.25,
            BeatDivision::Half => 0.5,
            BeatDivision::One => 1.0,
            BeatDivision::Two => 2.0,
            BeatDivision::Four => 4.0,
        }
    }

    /// Get all beat division variants
    pub fn all() -> &'static [BeatDivision] {
        &[
            BeatDivision::Quarter,
            BeatDivision::Half,
            BeatDivision::One,
            BeatDivision::Two,
            BeatDivision::Four,
        ]
    }
}

/// Audio frequency band for audio-reactive modulation
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum AudioBand {
    /// Low frequencies (bass)
    #[default]
    Bass,
    /// Mid frequencies
    Mid,
    /// High frequencies (treble)
    High,
    /// Overall volume (average of all bands)
    Volume,
}

impl AudioBand {
    /// Get display name
    pub fn name(&self) -> &'static str {
        match self {
            AudioBand::Bass => "Bass",
            AudioBand::Mid => "Mid",
            AudioBand::High => "High",
            AudioBand::Volume => "Vol",
        }
    }

    /// Get all audio band variants
    pub fn all() -> &'static [AudioBand] {
        &[
            AudioBand::Bass,
            AudioBand::Mid,
            AudioBand::High,
            AudioBand::Volume,
        ]
    }
}

/// Audio-reactive modulation configuration
#[derive(Debug, Clone, Copy, Default)]
pub struct AudioReactConfig {
    /// Which frequency band to react to
    pub band: AudioBand,
    /// Sensitivity multiplier (0.0 - 2.0, 1.0 = normal)
    pub sensitivity: f32,
    /// Smoothing factor (0.0 = instant, 1.0 = very smooth)
    pub smoothing: f32,
    /// Whether audio modulation is enabled
    pub enabled: bool,
}

/// Audio-reactive parameters from audio analysis
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct AudioReactiveParams {
    /// Detected BPM
    pub bpm: f32,
    /// Beat intensity (0.0-1.0)
    pub beat_intensity: f32,
    /// Low frequency energy (bass)
    pub low_freq: f32,
    /// Mid frequency energy
    pub mid_freq: f32,
    /// High frequency energy (treble)
    pub high_freq: f32,
    /// Time since last beat
    pub time_since_beat: f32,
    /// Whether we're currently on a beat
    pub on_beat: bool,
}

/// Modulation settings for a single parameter
///
/// Supports both LFO (beat-synced oscillation) and audio-reactive modulation.
/// These can be combined for complex parameter animation.
#[derive(Debug, Clone, Copy, Default)]
pub struct ParamModulation {
    /// LFO waveform type
    pub waveform: ModWaveform,
    /// Beat division for LFO timing
    pub division: BeatDivision,
    /// LFO modulation depth (0.0 - 1.0)
    pub depth: f32,
    /// Minimum value for modulation range
    pub min: f32,
    /// Maximum value for modulation range
    pub max: f32,
    /// Random state (for Random waveform)
    pub random_value: f32,
    /// Audio-reactive modulation config
    pub audio_react: AudioReactConfig,
    /// Smoothed audio value (internal state for exponential smoothing)
    pub smoothed_audio: f32,
}

impl ParamModulation {
    /// Create a new modulation with specified range
    pub fn new(min: f32, max: f32) -> Self {
        Self {
            waveform: ModWaveform::Off,
            division: BeatDivision::One,
            depth: 1.0,
            min,
            max,
            random_value: 0.5,
            audio_react: AudioReactConfig::default(),
            smoothed_audio: 0.0,
        }
    }

    /// Calculate modulated value based on beat phase (0.0 - 1.0)
    pub fn calculate(&self, phase: f32, base_value: f32) -> f32 {
        let mut result = base_value;
        let range = self.max - self.min;

        // Apply LFO modulation
        if self.waveform != ModWaveform::Off {
            let lfo_value = match self.waveform {
                ModWaveform::Off => 0.5,
                ModWaveform::Sin => (phase * std::f32::consts::TAU).sin() * 0.5 + 0.5,
                ModWaveform::Saw => phase,
                ModWaveform::Square => {
                    if phase < 0.5 {
                        0.0
                    } else {
                        1.0
                    }
                }
                ModWaveform::Random => self.random_value,
            };

            let lfo_mod = self.min + lfo_value * range * self.depth;
            result = base_value * (1.0 - self.depth) + lfo_mod * self.depth;
        }

        // Apply audio-reactive modulation (additive)
        if self.audio_react.enabled {
            let audio_mod = self.smoothed_audio * self.audio_react.sensitivity * range;
            result = (result + audio_mod).clamp(self.min, self.max);
        }

        result
    }

    /// Calculate the full modulated value with audio input
    ///
    /// Updates internal smoothed audio state and applies all modulation sources.
    pub fn calculate_with_audio(
        &mut self,
        phase: f32,
        base_value: f32,
        audio: &AudioReactiveParams,
        delta_time: f32,
    ) -> f32 {
        // Update smoothed audio value
        if self.audio_react.enabled {
            let raw_audio = match self.audio_react.band {
                AudioBand::Bass => audio.low_freq,
                AudioBand::Mid => audio.mid_freq,
                AudioBand::High => audio.high_freq,
                AudioBand::Volume => (audio.low_freq + audio.mid_freq + audio.high_freq) / 3.0,
            };

            // Exponential smoothing
            let smooth_factor = 1.0 - self.audio_react.smoothing;
            let alpha = 1.0 - (-delta_time * 10.0 * smooth_factor).exp();
            self.smoothed_audio = self.smoothed_audio * (1.0 - alpha) + raw_audio * alpha;
        }

        self.calculate(phase, base_value)
    }

    /// Check if any modulation is active
    pub fn is_active(&self) -> bool {
        self.waveform != ModWaveform::Off || self.audio_react.enabled
    }
}

// =============================================================================
// Loader Types (shared between glitcher-loader and glitcher-engine)
// =============================================================================

/// Decoded embedded texture data (ready for GPU upload)
///
/// This is the result of decoding an embedded texture from a WASM plugin.
/// The pixel data is in RGBA8 format, ready to be uploaded to the GPU.
#[derive(Debug, Clone)]
pub struct DecodedTexture {
    /// Unique key for runtime lookup (matches `EmbeddedTexture::key`)
    pub key: String,
    /// Decoded RGBA8 pixel data
    pub pixels: Vec<u8>,
    /// Width in pixels
    pub width: u32,
    /// Height in pixels
    pub height: u32,
}

impl DecodedTexture {
    /// Create a new decoded texture
    pub fn new(key: impl Into<String>, pixels: Vec<u8>, width: u32, height: u32) -> Self {
        Self {
            key: key.into(),
            pixels,
            width,
            height,
        }
    }

    /// Get the expected byte size for RGBA8 format
    pub fn expected_size(&self) -> usize {
        (self.width * self.height * 4) as usize
    }

    /// Validate that pixel data size matches dimensions
    pub fn is_valid(&self) -> bool {
        self.pixels.len() == self.expected_size()
    }
}

/// A loaded WASM plugin with extracted metadata
///
/// This is the output of `PluginLoader::load()` and the input to
/// `GlitchEngine::register_plugin()`. It contains everything needed
/// to create GPU resources for the plugin.
///
/// ## Usage
///
/// ```rust,ignore
/// // In glitcher-loader
/// let loaded = loader.load(&wasm_bytes)?;
///
/// // In glitcher-engine
/// let node_id = engine.register_plugin(&loaded)?;
/// ```
#[derive(Debug, Clone)]
pub struct LoadedPlugin {
    /// Node manifest from `get-manifest()` WIT function
    pub manifest: NodeManifest,
    /// WGSL shader source from `get-shader-source()` WIT function
    pub shader_source: String,
    /// Decoded embedded textures (ready for GPU upload)
    pub embedded_textures: Vec<DecodedTexture>,
}

impl LoadedPlugin {
    /// Create a new loaded plugin
    pub fn new(
        manifest: NodeManifest,
        shader_source: String,
        embedded_textures: Vec<DecodedTexture>,
    ) -> Self {
        Self {
            manifest,
            shader_source,
            embedded_textures,
        }
    }

    /// Get the display name from manifest
    pub fn display_name(&self) -> &str {
        &self.manifest.display_name
    }

    /// Check if this plugin has embedded textures
    pub fn has_embedded_textures(&self) -> bool {
        !self.embedded_textures.is_empty()
    }
}