@octoseq/visualiser 0.1.0-main.6402764 → 0.1.0-main.856feb5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@octoseq/visualiser",
-    "version": "0.1.0-main.6402764",
+    "version": "0.1.0-main.856feb5",
     "description": "WASM-based visualiser for Octoseq",
     "license": "MIT",
     "repository": {

package/pkg/visualiser.d.ts

@@ -8,6 +8,10 @@ export class WasmVisualiser {
    * Check if a script is currently loaded.
    */
   has_script(): boolean;
+  /**
+   * Check if a signal variable exists in the current script.
+   */
+  has_signal(name: string): boolean;
   /**
    * Load a Rhai script for controlling the visualiser.
    * Returns true if the script was loaded successfully.
@@ -18,12 +22,30 @@ export class WasmVisualiser {
    * The signal will be available as `inputs.<name>` in Rhai scripts.
    */
   push_signal(name: string, samples: Float32Array, sample_rate: number): void;
+  /**
+   * Run script in analysis mode to collect debug.emit() signals.
+   *
+   * This runs the script headlessly across the full track duration,
+   * collecting all debug.emit() calls without rendering.
+   *
+   * Returns a JSON-serialized AnalysisResultJson.
+   */
+  run_analysis(script: string, duration: number, time_step: number): string;
   /**
    * Clear all named signals.
    */
   clear_signals(): void;
   set_sigmoid_k(k: number): void;
+  /**
+   * Isolate a single entity for rendering (useful for debugging).
+   * Only this entity will be rendered.
+   */
+  isolate_entity(entity_id: bigint): void;
   push_zoom_data(samples: Float32Array, sample_rate: number): void;
+  /**
+   * Clear entity isolation, resume normal rendering.
+   */
+  clear_isolation(): void;
   /**
    * Get current state values for debugging.
    * Returns [time, scene_entity_count, mesh_count, line_count]
@@ -33,7 +55,187 @@ export class WasmVisualiser {
    * Get the last script error message, if any.
    */
   get_script_error(): string | undefined;
+  /**
+   * Get the list of available signal names.
+   * Returns a JSON array of signal names.
+   */
+  get_signal_names(): string;
+  /**
+   * Get a list of all registered mesh asset IDs.
+   * Returns a JSON array of asset IDs.
+   */
+  list_mesh_assets(): string;
+  /**
+   * Push pre-extracted events for a band.
+   *
+   * Events are extracted by the TypeScript layer using the existing peak picker,
+   * then pushed here for script access via `inputs.bands[id].events`.
+   *
+   * The JSON format should be an array of event objects with:
+   * - time: f32
+   * - weight: f32
+   * - beat_position: Option<f32>
+   * - beat_phase: Option<f32>
+   * - cluster_id: Option<u32>
+   *
+   * Returns true if successful, false if parsing failed.
+   */
+  push_band_events(band_id: string, events_json: string): boolean;
+  /**
+   * Push a band-scoped signal for use in scripts.
+   * The signal will be available as `inputs.bands[band_id].{feature}` in Rhai scripts.
+   * Stores under both band_id and band_label for dual-access support.
+   *
+   * - `band_id`: The unique ID of the frequency band.
+   * - `band_label`: The user-visible label of the band.
+   * - `feature`: Signal type ("energy", "onset", "flux").
+   * - `samples`: Signal data.
+   * - `sample_rate`: Sample rate of the signal.
+   */
+  push_band_signal(band_id: string, band_label: string, feature: string, samples: Float32Array, sample_rate: number): void;
+  /**
+   * Set the musical time structure for beat-aware signal processing.
+   * The JSON format matches the TypeScript MusicalTimeStructure type.
+   * Returns true if successful, false if parsing failed.
+   */
+  set_musical_time(json: string): boolean;
+  /**
+   * Clear all band event streams.
+   */
+  clear_band_events(): void;
+  /**
+   * Push a named event stream (e.g., "beatCandidates") for script access.
+   *
+   * The event stream will be available as `inputs.<name>` in Rhai scripts.
+   * This is used for MIR-derived events like beat candidates, onset peaks, etc.
+   *
+   * The JSON format should be an array of event objects with:
+   * - time: f32
+   * - weight: f32
+   * - beat_position: Option<f32>
+   * - beat_phase: Option<f32>
+   * - cluster_id: Option<u32>
+   *
+   * Returns true if successful, false if parsing failed.
+   */
+  push_event_stream(name: string, events_json: string): boolean;
+  /**
+   * Set debug visualization options.
+   */
+  set_debug_options(wireframe: boolean, bounding_boxes: boolean): void;
+  /**
+   * Clear all band signals.
+   */
+  clear_band_signals(): void;
+  /**
+   * Clear the musical time structure.
+   * Beat-aware operations will fall back to 120 BPM default.
+   */
+  clear_musical_time(): void;
+  /**
+   * Get frequency bounds for all active bands at a given time.
+   * Returns a JSON array of { bandId, label, lowHz, highHz, enabled } objects.
+   */
+  get_band_bounds_at(time: number): string;
+  /**
+   * Get all Signal variables from the current script.
+   * Returns a JSON array of ScriptSignalInfo objects.
+   */
+  get_script_signals(): string;
   push_rotation_data(samples: Float32Array, sample_rate: number): void;
+  /**
+   * Render with a frame budget timeout.
+   *
+   * If the frame takes longer than `budget_ms` to process, it will be dropped
+   * and a warning logged. This prevents expensive scripts from freezing the browser.
+   *
+   * Returns true if the frame completed, false if it was dropped due to budget.
+   */
+  render_with_budget(dt: number, budget_ms: number): boolean;
+  /**
+   * Clear all named event streams.
+   */
+  clear_event_streams(): void;
+  /**
+   * Check if frequency bands are currently set.
+   */
+  has_frequency_bands(): boolean;
+  /**
+   * Register a mesh asset from OBJ content.
+   * The asset will be available as `mesh.load(asset_id)` in scripts.
+   * Returns true if successful, false if parsing failed.
+   */
+  register_mesh_asset(asset_id: string, obj_content: string): boolean;
+  /**
+   * Set the frequency band structure for band-aware processing.
+   * The JSON format matches the TypeScript FrequencyBandStructure type.
+   * Returns true if successful, false if parsing failed.
+   */
+  set_frequency_bands(json: string): boolean;
+  /**
+   * Analyze a signal chain with localized sampling.
+   *
+   * Returns JSON with either:
+   * - SignalChainAnalysis on success
+   * - { "error": "message" } on failure
+   *
+   * Parameters:
+   * - signal_name: Name of the signal variable in the script
+   * - center_time: Time to center analysis around (seconds)
+   * - window_beats: Number of beats before/after center to sample
+   * - sample_count: Number of samples to take
+   */
+  analyze_signal_chain(signal_name: string, center_time: number, window_beats: number, sample_count: number): string;
+  /**
+   * Get the number of events for a specific band.
+   * Returns 0 if no events are stored for this band.
+   */
+  get_band_event_count(band_id: string): number;
+  /**
+   * Get list of band keys (IDs and labels) that have signals.
+   * Returns a JSON array of strings.
+   */
+  get_band_signal_keys(): string;
+  /**
+   * Clear the frequency band structure.
+   */
+  clear_frequency_bands(): void;
+  /**
+   * Unregister a mesh asset.
+   * Returns true if the asset was unregistered, false if it didn't exist.
+   */
+  unregister_mesh_asset(asset_id: string): boolean;
+  /**
+   * Get the number of events in a named event stream.
+   * Returns 0 if no events are stored for this name.
+   */
+  get_event_stream_count(name: string): number;
+  /**
+   * Get the number of frequency bands.
+   */
+  get_frequency_band_count(): number;
+  /**
+   * Run script in analysis mode with event extraction support.
+   *
+   * This runs the script headlessly across the full track duration,
+   * collecting all debug.emit() calls AND extracting events from
+   * any signal.pick.events() calls.
+   *
+   * Returns a JSON-serialized ExtendedAnalysisResultJson.
+   */
+  run_analysis_with_events(script: string, duration: number, time_step: number): string;
+  /**
+   * Get entity positions as JSON for debugging.
+   * Returns a JSON array of objects with id, type, and position fields.
+   */
+  get_entity_positions_json(): string;
+  /**
+   * Drain and return any pending structured script diagnostics as JSON.
+   *
+   * Intended for UI consumption. Calling this clears the pending diagnostics
+   * queue so repeated polling does not duplicate messages.
+   */
+  take_script_diagnostics_json(): string;
   constructor();
   render(dt: number): void;
   resize(width: number, height: number): void;
@@ -43,6 +245,15 @@ export class WasmVisualiser {
 
 export function create_visualiser(canvas: HTMLCanvasElement): Promise<WasmVisualiser>;
 
+/**
+ * Get the host-defined Script API metadata as a JSON string.
+ *
+ * This is a stable, versioned description of the scripting API surface and is
+ * intended to drive editor UX (autocomplete/hover/docs) and future language
+ * bindings.
+ */
+export function get_script_api_metadata_json(): string;
+
 export function init_panic_hook(): void;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
@@ -51,21 +262,53 @@ export interface InitOutput {
   readonly memory: WebAssembly.Memory;
   readonly __wbg_wasmvisualiser_free: (a: number, b: number) => void;
   readonly create_visualiser: (a: any) => any;
+  readonly get_script_api_metadata_json: () => [number, number];
+  readonly wasmvisualiser_analyze_signal_chain: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+  readonly wasmvisualiser_clear_band_events: (a: number) => void;
+  readonly wasmvisualiser_clear_band_signals: (a: number) => void;
+  readonly wasmvisualiser_clear_event_streams: (a: number) => void;
+  readonly wasmvisualiser_clear_frequency_bands: (a: number) => void;
+  readonly wasmvisualiser_clear_isolation: (a: number) => void;
+  readonly wasmvisualiser_clear_musical_time: (a: number) => void;
   readonly wasmvisualiser_clear_signals: (a: number) => void;
+  readonly wasmvisualiser_get_band_bounds_at: (a: number, b: number) => [number, number];
+  readonly wasmvisualiser_get_band_event_count: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_get_band_signal_keys: (a: number) => [number, number];
   readonly wasmvisualiser_get_current_vals: (a: number) => [number, number];
+  readonly wasmvisualiser_get_entity_positions_json: (a: number) => [number, number];
+  readonly wasmvisualiser_get_event_stream_count: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_get_frequency_band_count: (a: number) => number;
   readonly wasmvisualiser_get_script_error: (a: number) => [number, number];
+  readonly wasmvisualiser_get_script_signals: (a: number) => [number, number];
+  readonly wasmvisualiser_get_signal_names: (a: number) => [number, number];
+  readonly wasmvisualiser_has_frequency_bands: (a: number) => number;
   readonly wasmvisualiser_has_script: (a: number) => number;
+  readonly wasmvisualiser_has_signal: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_isolate_entity: (a: number, b: bigint) => void;
+  readonly wasmvisualiser_list_mesh_assets: (a: number) => [number, number];
   readonly wasmvisualiser_load_script: (a: number, b: number, c: number) => number;
   readonly wasmvisualiser_new: () => number;
+  readonly wasmvisualiser_push_band_events: (a: number, b: number, c: number, d: number, e: number) => number;
+  readonly wasmvisualiser_push_band_signal: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
   readonly wasmvisualiser_push_data: (a: number, b: number, c: number, d: number) => void;
+  readonly wasmvisualiser_push_event_stream: (a: number, b: number, c: number, d: number, e: number) => number;
   readonly wasmvisualiser_push_signal: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
   readonly wasmvisualiser_push_zoom_data: (a: number, b: number, c: number, d: number) => void;
+  readonly wasmvisualiser_register_mesh_asset: (a: number, b: number, c: number, d: number, e: number) => number;
   readonly wasmvisualiser_render: (a: number, b: number) => void;
+  readonly wasmvisualiser_render_with_budget: (a: number, b: number, c: number) => number;
   readonly wasmvisualiser_resize: (a: number, b: number, c: number) => void;
+  readonly wasmvisualiser_run_analysis: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+  readonly wasmvisualiser_run_analysis_with_events: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+  readonly wasmvisualiser_set_debug_options: (a: number, b: number, c: number) => void;
+  readonly wasmvisualiser_set_frequency_bands: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_set_musical_time: (a: number, b: number, c: number) => number;
   readonly wasmvisualiser_set_sigmoid_k: (a: number, b: number) => void;
   readonly wasmvisualiser_set_time: (a: number, b: number) => void;
-  readonly init_panic_hook: () => void;
+  readonly wasmvisualiser_take_script_diagnostics_json: (a: number) => [number, number];
+  readonly wasmvisualiser_unregister_mesh_asset: (a: number, b: number, c: number) => number;
   readonly wasmvisualiser_push_rotation_data: (a: number, b: number, c: number, d: number) => void;
+  readonly init_panic_hook: () => void;
   readonly wasm_bindgen__convert__closures_____invoke__h53437a38721e89f7: (a: number, b: number, c: any) => void;
   readonly wasm_bindgen__closure__destroy__hf5eaa61ced318e08: (a: number, b: number) => void;
   readonly wasm_bindgen__convert__closures_____invoke__h9d1c5a23ecfcd5c8: (a: number, b: number, c: any) => void;

package/pkg/visualiser.js

@@ -293,6 +293,17 @@ export class WasmVisualiser {
         const ret = wasm.wasmvisualiser_has_script(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+     * Check if a signal variable exists in the current script.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has_signal(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_has_signal(this.__wbg_ptr, ptr0, len0);
+        return ret !== 0;
+    }
     /**
      * Load a Rhai script for controlling the visualiser.
      * Returns true if the script was loaded successfully.
@@ -319,6 +330,32 @@ export class WasmVisualiser {
         const len1 = WASM_VECTOR_LEN;
         wasm.wasmvisualiser_push_signal(this.__wbg_ptr, ptr0, len0, ptr1, len1, sample_rate);
     }
+    /**
+     * Run script in analysis mode to collect debug.emit() signals.
+     *
+     * This runs the script headlessly across the full track duration,
+     * collecting all debug.emit() calls without rendering.
+     *
+     * Returns a JSON-serialized AnalysisResultJson.
+     * @param {string} script
+     * @param {number} duration
+     * @param {number} time_step
+     * @returns {string}
+     */
+    run_analysis(script, duration, time_step) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(script, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.wasmvisualiser_run_analysis(this.__wbg_ptr, ptr0, len0, duration, time_step);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * Clear all named signals.
      */
@@ -331,6 +368,14 @@ export class WasmVisualiser {
     set_sigmoid_k(k) {
         wasm.wasmvisualiser_set_sigmoid_k(this.__wbg_ptr, k);
     }
+    /**
+     * Isolate a single entity for rendering (useful for debugging).
+     * Only this entity will be rendered.
+     * @param {bigint} entity_id
+     */
+    isolate_entity(entity_id) {
+        wasm.wasmvisualiser_isolate_entity(this.__wbg_ptr, entity_id);
+    }
     /**
      * @param {Float32Array} samples
      * @param {number} sample_rate
@@ -340,6 +385,12 @@ export class WasmVisualiser {
         const len0 = WASM_VECTOR_LEN;
         wasm.wasmvisualiser_push_zoom_data(this.__wbg_ptr, ptr0, len0, sample_rate);
     }
+    /**
+     * Clear entity isolation, resume normal rendering.
+     */
+    clear_isolation() {
+        wasm.wasmvisualiser_clear_isolation(this.__wbg_ptr);
+    }
     /**
      * Get current state values for debugging.
      * Returns [time, scene_entity_count, mesh_count, line_count]
@@ -364,6 +415,194 @@ export class WasmVisualiser {
         }
         return v1;
     }
+    /**
+     * Get the list of available signal names.
+     * Returns a JSON array of signal names.
+     * @returns {string}
+     */
+    get_signal_names() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmvisualiser_get_signal_names(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Get a list of all registered mesh asset IDs.
+     * Returns a JSON array of asset IDs.
+     * @returns {string}
+     */
+    list_mesh_assets() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmvisualiser_list_mesh_assets(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Push pre-extracted events for a band.
+     *
+     * Events are extracted by the TypeScript layer using the existing peak picker,
+     * then pushed here for script access via `inputs.bands[id].events`.
+     *
+     * The JSON format should be an array of event objects with:
+     * - time: f32
+     * - weight: f32
+     * - beat_position: Option<f32>
+     * - beat_phase: Option<f32>
+     * - cluster_id: Option<u32>
+     *
+     * Returns true if successful, false if parsing failed.
+     * @param {string} band_id
+     * @param {string} events_json
+     * @returns {boolean}
+     */
+    push_band_events(band_id, events_json) {
+        const ptr0 = passStringToWasm0(band_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(events_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_push_band_events(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        return ret !== 0;
+    }
+    /**
+     * Push a band-scoped signal for use in scripts.
+     * The signal will be available as `inputs.bands[band_id].{feature}` in Rhai scripts.
+     * Stores under both band_id and band_label for dual-access support.
+     *
+     * - `band_id`: The unique ID of the frequency band.
+     * - `band_label`: The user-visible label of the band.
+     * - `feature`: Signal type ("energy", "onset", "flux").
+     * - `samples`: Signal data.
+     * - `sample_rate`: Sample rate of the signal.
+     * @param {string} band_id
+     * @param {string} band_label
+     * @param {string} feature
+     * @param {Float32Array} samples
+     * @param {number} sample_rate
+     */
+    push_band_signal(band_id, band_label, feature, samples, sample_rate) {
+        const ptr0 = passStringToWasm0(band_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(band_label, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(feature, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len2 = WASM_VECTOR_LEN;
+        const ptr3 = passArrayF32ToWasm0(samples, wasm.__wbindgen_malloc);
+        const len3 = WASM_VECTOR_LEN;
+        wasm.wasmvisualiser_push_band_signal(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, sample_rate);
+    }
+    /**
+     * Set the musical time structure for beat-aware signal processing.
+     * The JSON format matches the TypeScript MusicalTimeStructure type.
+     * Returns true if successful, false if parsing failed.
+     * @param {string} json
+     * @returns {boolean}
+     */
+    set_musical_time(json) {
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_set_musical_time(this.__wbg_ptr, ptr0, len0);
+        return ret !== 0;
+    }
+    /**
+     * Clear all band event streams.
+     */
+    clear_band_events() {
+        wasm.wasmvisualiser_clear_band_events(this.__wbg_ptr);
+    }
+    /**
+     * Push a named event stream (e.g., "beatCandidates") for script access.
+     *
+     * The event stream will be available as `inputs.<name>` in Rhai scripts.
+     * This is used for MIR-derived events like beat candidates, onset peaks, etc.
+     *
+     * The JSON format should be an array of event objects with:
+     * - time: f32
+     * - weight: f32
+     * - beat_position: Option<f32>
+     * - beat_phase: Option<f32>
+     * - cluster_id: Option<u32>
+     *
+     * Returns true if successful, false if parsing failed.
+     * @param {string} name
+     * @param {string} events_json
+     * @returns {boolean}
+     */
+    push_event_stream(name, events_json) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(events_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_push_event_stream(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        return ret !== 0;
+    }
+    /**
+     * Set debug visualization options.
+     * @param {boolean} wireframe
+     * @param {boolean} bounding_boxes
+     */
+    set_debug_options(wireframe, bounding_boxes) {
+        wasm.wasmvisualiser_set_debug_options(this.__wbg_ptr, wireframe, bounding_boxes);
+    }
+    /**
+     * Clear all band signals.
+     */
+    clear_band_signals() {
+        wasm.wasmvisualiser_clear_band_signals(this.__wbg_ptr);
+    }
+    /**
+     * Clear the musical time structure.
+     * Beat-aware operations will fall back to 120 BPM default.
+     */
+    clear_musical_time() {
+        wasm.wasmvisualiser_clear_musical_time(this.__wbg_ptr);
+    }
+    /**
+     * Get frequency bounds for all active bands at a given time.
+     * Returns a JSON array of { bandId, label, lowHz, highHz, enabled } objects.
+     * @param {number} time
+     * @returns {string}
+     */
+    get_band_bounds_at(time) {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmvisualiser_get_band_bounds_at(this.__wbg_ptr, time);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Get all Signal variables from the current script.
+     * Returns a JSON array of ScriptSignalInfo objects.
+     * @returns {string}
+     */
+    get_script_signals() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmvisualiser_get_script_signals(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * @param {Float32Array} samples
      * @param {number} sample_rate
@@ -373,6 +612,226 @@ export class WasmVisualiser {
         const len0 = WASM_VECTOR_LEN;
         wasm.wasmvisualiser_push_data(this.__wbg_ptr, ptr0, len0, sample_rate);
     }
+    /**
+     * Render with a frame budget timeout.
+     *
+     * If the frame takes longer than `budget_ms` to process, it will be dropped
+     * and a warning logged. This prevents expensive scripts from freezing the browser.
+     *
+     * Returns true if the frame completed, false if it was dropped due to budget.
+     * @param {number} dt
+     * @param {number} budget_ms
+     * @returns {boolean}
+     */
+    render_with_budget(dt, budget_ms) {
+        const ret = wasm.wasmvisualiser_render_with_budget(this.__wbg_ptr, dt, budget_ms);
+        return ret !== 0;
+    }
+    /**
+     * Clear all named event streams.
+     */
+    clear_event_streams() {
+        wasm.wasmvisualiser_clear_event_streams(this.__wbg_ptr);
+    }
+    /**
+     * Check if frequency bands are currently set.
+     * @returns {boolean}
+     */
+    has_frequency_bands() {
+        const ret = wasm.wasmvisualiser_has_frequency_bands(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Register a mesh asset from OBJ content.
+     * The asset will be available as `mesh.load(asset_id)` in scripts.
+     * Returns true if successful, false if parsing failed.
+     * @param {string} asset_id
+     * @param {string} obj_content
+     * @returns {boolean}
+     */
+    register_mesh_asset(asset_id, obj_content) {
+        const ptr0 = passStringToWasm0(asset_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(obj_content, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_register_mesh_asset(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        return ret !== 0;
+    }
+    /**
+     * Set the frequency band structure for band-aware processing.
+     * The JSON format matches the TypeScript FrequencyBandStructure type.
+     * Returns true if successful, false if parsing failed.
+     * @param {string} json
+     * @returns {boolean}
+     */
+    set_frequency_bands(json) {
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_set_frequency_bands(this.__wbg_ptr, ptr0, len0);
+        return ret !== 0;
+    }
+    /**
+     * Analyze a signal chain with localized sampling.
+     *
+     * Returns JSON with either:
+     * - SignalChainAnalysis on success
+     * - { "error": "message" } on failure
+     *
+     * Parameters:
+     * - signal_name: Name of the signal variable in the script
+     * - center_time: Time to center analysis around (seconds)
+     * - window_beats: Number of beats before/after center to sample
+     * - sample_count: Number of samples to take
+     * @param {string} signal_name
+     * @param {number} center_time
+     * @param {number} window_beats
+     * @param {number} sample_count
+     * @returns {string}
+     */
+    analyze_signal_chain(signal_name, center_time, window_beats, sample_count) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(signal_name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.wasmvisualiser_analyze_signal_chain(this.__wbg_ptr, ptr0, len0, center_time, window_beats, sample_count);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Get the number of events for a specific band.
+     * Returns 0 if no events are stored for this band.
+     * @param {string} band_id
+     * @returns {number}
+     */
+    get_band_event_count(band_id) {
+        const ptr0 = passStringToWasm0(band_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_get_band_event_count(this.__wbg_ptr, ptr0, len0);
+        return ret >>> 0;
+    }
+    /**
+     * Get list of band keys (IDs and labels) that have signals.
+     * Returns a JSON array of strings.
+     * @returns {string}
+     */
+    get_band_signal_keys() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmvisualiser_get_band_signal_keys(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Clear the frequency band structure.
+     */
+    clear_frequency_bands() {
+        wasm.wasmvisualiser_clear_frequency_bands(this.__wbg_ptr);
+    }
+    /**
+     * Unregister a mesh asset.
+     * Returns true if the asset was unregistered, false if it didn't exist.
+     * @param {string} asset_id
+     * @returns {boolean}
+     */
+    unregister_mesh_asset(asset_id) {
+        const ptr0 = passStringToWasm0(asset_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_unregister_mesh_asset(this.__wbg_ptr, ptr0, len0);
+        return ret !== 0;
+    }
+    /**
+     * Get the number of events in a named event stream.
+     * Returns 0 if no events are stored for this name.
+     * @param {string} name
+     * @returns {number}
+     */
+    get_event_stream_count(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmvisualiser_get_event_stream_count(this.__wbg_ptr, ptr0, len0);
+        return ret >>> 0;
+    }
+    /**
+     * Get the number of frequency bands.
+     * @returns {number}
+     */
+    get_frequency_band_count() {
+        const ret = wasm.wasmvisualiser_get_frequency_band_count(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Run script in analysis mode with event extraction support.
+     *
+     * This runs the script headlessly across the full track duration,
+     * collecting all debug.emit() calls AND extracting events from
+     * any signal.pick.events() calls.
+     *
+     * Returns a JSON-serialized ExtendedAnalysisResultJson.
+     * @param {string} script
+     * @param {number} duration
+     * @param {number} time_step
+     * @returns {string}
+     */
+    run_analysis_with_events(script, duration, time_step) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(script, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.wasmvisualiser_run_analysis_with_events(this.__wbg_ptr, ptr0, len0, duration, time_step);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Get entity positions as JSON for debugging.
+     * Returns a JSON array of objects with id, type, and position fields.
+     * @returns {string}
+     */
+    get_entity_positions_json() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmvisualiser_get_entity_positions_json(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Drain and return any pending structured script diagnostics as JSON.
+     *
+     * Intended for UI consumption. Calling this clears the pending diagnostics
+     * queue so repeated polling does not duplicate messages.
+     * @returns {string}
+     */
+    take_script_diagnostics_json() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmvisualiser_take_script_diagnostics_json(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
     constructor() {
         const ret = wasm.wasmvisualiser_new();
         this.__wbg_ptr = ret >>> 0;
@@ -419,6 +878,27 @@ export function create_visualiser(canvas) {
     return ret;
 }
 
+/**
+ * Get the host-defined Script API metadata as a JSON string.
+ *
+ * This is a stable, versioned description of the scripting API surface and is
+ * intended to drive editor UX (autocomplete/hover/docs) and future language
+ * bindings.
+ * @returns {string}
+ */
+export function get_script_api_metadata_json() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.get_script_api_metadata_json();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 export function init_panic_hook() {
     wasm.init_panic_hook();
 }
@@ -1070,6 +1550,10 @@ function __wbg_get_imports() {
         const ret = arg0.offset;
         return ret;
     };
+    imports.wbg.__wbg_performance_c77a440eff2efd9b = function(arg0) {
+        const ret = arg0.performance;
+        return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+    };
     imports.wbg.__wbg_popErrorScope_af0b22f136a861d6 = function(arg0) {
         const ret = arg0.popErrorScope();
         return ret;
@@ -1273,9 +1757,9 @@ function __wbg_get_imports() {
     imports.wbg.__wbg_writeTexture_246118eb2f5a1592 = function(arg0, arg1, arg2, arg3, arg4) {
         arg0.writeTexture(arg1, arg2, arg3, arg4);
     };
-    imports.wbg.__wbindgen_cast_1ad8672233d2fd7b = function(arg0, arg1) {
-        // Cast intrinsic for `Closure(Closure { dtor_idx: 2007, function: Function { arguments: [Externref], shim_idx: 2008, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-        const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__hf5eaa61ced318e08, wasm_bindgen__convert__closures_____invoke__h53437a38721e89f7);
+    imports.wbg.__wbindgen_cast_0f9673e2fc640759 = function(arg0, arg1) {
+        // Cast intrinsic for `Closure(Closure { dtor_idx: 3204, function: Function { arguments: [NamedExternref("GPUUncapturedErrorEvent")], shim_idx: 3205, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+        const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__heb49a8f426ac2d2e, wasm_bindgen__convert__closures_____invoke__h9d1c5a23ecfcd5c8);
         return ret;
     };
     imports.wbg.__wbindgen_cast_2241b6af4c4b2941 = function(arg0, arg1) {
@@ -1283,9 +1767,9 @@ function __wbg_get_imports() {
         const ret = getStringFromWasm0(arg0, arg1);
         return ret;
     };
-    imports.wbg.__wbindgen_cast_762879c56a766cac = function(arg0, arg1) {
-        // Cast intrinsic for `Closure(Closure { dtor_idx: 1873, function: Function { arguments: [NamedExternref("GPUUncapturedErrorEvent")], shim_idx: 1874, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-        const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__heb49a8f426ac2d2e, wasm_bindgen__convert__closures_____invoke__h9d1c5a23ecfcd5c8);
+    imports.wbg.__wbindgen_cast_5ba18adeaae4eb95 = function(arg0, arg1) {
+        // Cast intrinsic for `Closure(Closure { dtor_idx: 3336, function: Function { arguments: [Externref], shim_idx: 3337, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+        const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__hf5eaa61ced318e08, wasm_bindgen__convert__closures_____invoke__h53437a38721e89f7);
         return ret;
     };
     imports.wbg.__wbindgen_cast_cb9088102bce6b30 = function(arg0, arg1) {

package/pkg/visualiser_bg.wasm.d.ts

@@ -3,21 +3,53 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_wasmvisualiser_free: (a: number, b: number) => void;
 export const create_visualiser: (a: any) => any;
+export const get_script_api_metadata_json: () => [number, number];
+export const wasmvisualiser_analyze_signal_chain: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+export const wasmvisualiser_clear_band_events: (a: number) => void;
+export const wasmvisualiser_clear_band_signals: (a: number) => void;
+export const wasmvisualiser_clear_event_streams: (a: number) => void;
+export const wasmvisualiser_clear_frequency_bands: (a: number) => void;
+export const wasmvisualiser_clear_isolation: (a: number) => void;
+export const wasmvisualiser_clear_musical_time: (a: number) => void;
 export const wasmvisualiser_clear_signals: (a: number) => void;
+export const wasmvisualiser_get_band_bounds_at: (a: number, b: number) => [number, number];
+export const wasmvisualiser_get_band_event_count: (a: number, b: number, c: number) => number;
+export const wasmvisualiser_get_band_signal_keys: (a: number) => [number, number];
 export const wasmvisualiser_get_current_vals: (a: number) => [number, number];
+export const wasmvisualiser_get_entity_positions_json: (a: number) => [number, number];
+export const wasmvisualiser_get_event_stream_count: (a: number, b: number, c: number) => number;
+export const wasmvisualiser_get_frequency_band_count: (a: number) => number;
 export const wasmvisualiser_get_script_error: (a: number) => [number, number];
+export const wasmvisualiser_get_script_signals: (a: number) => [number, number];
+export const wasmvisualiser_get_signal_names: (a: number) => [number, number];
+export const wasmvisualiser_has_frequency_bands: (a: number) => number;
 export const wasmvisualiser_has_script: (a: number) => number;
+export const wasmvisualiser_has_signal: (a: number, b: number, c: number) => number;
+export const wasmvisualiser_isolate_entity: (a: number, b: bigint) => void;
+export const wasmvisualiser_list_mesh_assets: (a: number) => [number, number];
 export const wasmvisualiser_load_script: (a: number, b: number, c: number) => number;
 export const wasmvisualiser_new: () => number;
+export const wasmvisualiser_push_band_events: (a: number, b: number, c: number, d: number, e: number) => number;
+export const wasmvisualiser_push_band_signal: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
 export const wasmvisualiser_push_data: (a: number, b: number, c: number, d: number) => void;
+export const wasmvisualiser_push_event_stream: (a: number, b: number, c: number, d: number, e: number) => number;
 export const wasmvisualiser_push_signal: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const wasmvisualiser_push_zoom_data: (a: number, b: number, c: number, d: number) => void;
+export const wasmvisualiser_register_mesh_asset: (a: number, b: number, c: number, d: number, e: number) => number;
 export const wasmvisualiser_render: (a: number, b: number) => void;
+export const wasmvisualiser_render_with_budget: (a: number, b: number, c: number) => number;
 export const wasmvisualiser_resize: (a: number, b: number, c: number) => void;
+export const wasmvisualiser_run_analysis: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const wasmvisualiser_run_analysis_with_events: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const wasmvisualiser_set_debug_options: (a: number, b: number, c: number) => void;
+export const wasmvisualiser_set_frequency_bands: (a: number, b: number, c: number) => number;
+export const wasmvisualiser_set_musical_time: (a: number, b: number, c: number) => number;
 export const wasmvisualiser_set_sigmoid_k: (a: number, b: number) => void;
 export const wasmvisualiser_set_time: (a: number, b: number) => void;
-export const init_panic_hook: () => void;
+export const wasmvisualiser_take_script_diagnostics_json: (a: number) => [number, number];
+export const wasmvisualiser_unregister_mesh_asset: (a: number, b: number, c: number) => number;
 export const wasmvisualiser_push_rotation_data: (a: number, b: number, c: number, d: number) => void;
+export const init_panic_hook: () => void;
 export const wasm_bindgen__convert__closures_____invoke__h53437a38721e89f7: (a: number, b: number, c: any) => void;
 export const wasm_bindgen__closure__destroy__hf5eaa61ced318e08: (a: number, b: number) => void;
 export const wasm_bindgen__convert__closures_____invoke__h9d1c5a23ecfcd5c8: (a: number, b: number, c: any) => void;