@viji-dev/core 0.11.8 → 0.13.0

package/dist/index.d.ts

@@ -1,37 +1,3 @@
-/**
- * Analyzes a scene's source code and returns the capabilities it declares,
- * without constructing a core. Composes {@link SceneAnalyzer.detectRendererType}
- * and {@link SceneAnalyzer.detectCapabilities} — the same two steps `VijiCore`
- * performs at construction — so for a given core version the result is
- * identical to a booted core's `getSceneData().capabilities`.
- *
- * Intended for out-of-engine consumers (e.g. server-side persistence of
- * per-scene capabilities). The following properties are an intentional, kept
- * contract:
- * - **Pure and Node-safe** — static analysis only; the scene is never executed
- *   and no DOM, canvas, or worker API is touched. Callable in a bare Node
- *   process.
- * - **Deterministic** — same code string, same result, within a core version.
- * - **Inclusive-biased** — a capability the scene uses is never hidden; a
- *   rare ambiguous case may report an extra one.
- * - **Safe on untrusted input** — linear-time scan and regexes with no throw
- *   paths on any string input.
- *
- * Note for consumers filtering on `video`: the flag means the scene reads the
- * video *image* (pixels/texture). Shader scenes that consume only CV result
- * uniforms report `cv.*` without `video`, so a "reacts to the camera" filter
- * should test `video || any cv key`.
- *
- * @param sceneCode - The artist's scene code (native, p5, or shader)
- * @returns The set of capabilities the scene declares it uses
- * @example
- * ```ts
- * const caps = analyzeSceneCapabilities(scene.code);
- * if (caps.audio) tags.push('audio');
- * ```
- */
-export declare function analyzeSceneCapabilities(sceneCode: string): SceneCapabilities;
-
 declare interface AudioAnalysisState {
     isConnected: boolean;
     currentBPM: number;
@@ -220,618 +186,6 @@ declare interface AudioStreamAPI {
     getWaveform: () => Float32Array;
 }
 
-/**
- * Manages audio analysis and processing for the host side.
- * Handles audio stream processing and provides real-time audio analysis.
- *
- * This system provides:
- * - Real-time audio analysis (RMS, peak, frequency bands)
- * - Beat detection with automatic BPM tracking
- * - Onset detection for audio-reactive triggers
- * - Smooth energy curves with envelope followers
- * - Per-instrument onset tap patterns with automatic pattern recognition
- * - Auto-gain normalization
- * - Spectral feature extraction
- * - AudioContext management and cleanup
- * - Raw FFT data access for custom analysis
- * - Analysis results sent to worker for artist API
- */
-export declare class AudioSystem {
-    private audioContext;
-    private workletRegistered;
-    /**
-     * Persistent export capture tap (main channel only). Created lazily by
-     * `getAudioCaptureStream()`, lives for the AudioSystem lifetime, and is
-     * torn down only in `resetAudioState()`. Deliberately NOT severed by
-     * `disconnectMainStream()`: on mid-recording disconnect the tap stream
-     * goes silent while its tracks stay live, and `connectChannel()` re-wires
-     * each new main source node into it, so the exposed MediaStream stays
-     * stable across `setAudioStream()` swaps (a recorder never renegotiates).
-     */
-    private captureDestination;
-    private mainChannel;
-    private additionalChannels;
-    private analysisInterval;
-    private analysisIntervalMs;
-    private stalenessTimer;
-    private static readonly STALENESS_THRESHOLD_MS;
-    /** Tracks the last non-zero BPM chosen for output to avoid dropping to 0 */
-    private lastNonZeroBpm;
-    /** Tracks which source provided the current BPM (pll | tempo | carry | default) */
-    private lastBpmSource;
-    private lastPhaseLogTime;
-    private onsetLogBuffer;
-    private debugMode;
-    /**
-     * One-way lifecycle flag flipped at the top of `resetAudioState()`.
-     * Gates re-entry into `ensureAudioContext()` and the public stream-mutation
-     * entry points so an in-flight async caller (e.g. a worker RPC firing
-     * mid-teardown) cannot resurrect a fresh `AudioContext` after destroy
-     * has already nulled the field. AudioSystem is single-use after reset.
-     */
-    private destroyed;
-    private diagnosticLogger;
-    private onsetDetection;
-    private essentiaOnsetDetection;
-    private tempoInduction;
-    private pll;
-    private stateManager;
-    private lastKickDetected;
-    /** Raw band snapshot before auto-gain (for debug, main channel only) */
-    private rawBandsPreGain;
-    private readonly bandNames;
-    private essentiaBandHistories;
-    private readonly essentiaHistoryWindowMs;
-    private onsetTapManager;
-    private beatEnvelopeFollowers;
-    private beatDetectionEnabled;
-    private onsetDetectionEnabled;
-    private autoGainEnabled;
-    private idleTickerHandle;
-    private idleTickerLastTime;
-    /**
-     * Enable or disable comprehensive debug logging for all layers
-     * Enables enhanced logging in: MultiOnsetDetection, BeatStateManager
-     */
-    setDebugMode(enabled: boolean): void;
-    /**
-     * Reset Essentia band onset histories (used to feed tempo induction when using the Essentia backend)
-     */
-    private resetEssentiaBandHistories;
-    /**
-     * Update Essentia band onset histories and trim old entries
-     */
-    private updateEssentiaBandHistories;
-    private getEssentiaBandHistory;
-    private getEssentiaAllHistories;
-    /**
-     * Handle frames pushed from AudioWorklet for main channel
-     */
-    private handleMainWorkletFrame;
-    /**
-     * Handle frames pushed from AudioWorklet for an additional channel
-     */
-    private handleAdditionalWorkletFrame;
-    /**
-     * Common analysis pipeline for any channel (FFT, volume, bands, auto-gain, spectral, smoothing).
-     * Returns raw band energies (pre-auto-gain) for optional beat processing by the caller.
-     */
-    private analyzeChannelFrame;
-    /**
-     * Full analysis for the main channel (common analysis + beat pipeline).
-     */
-    private analyzeMainFrame;
-    /**
-     * Lightweight analysis for additional/device channels (no beat detection).
-     */
-    private analyzeAdditionalFrame;
-    /**
-     * Compute FFT on a specific channel's buffers
-     */
-    private computeChannelFFT;
-    /**
-     * Calculate RMS/peak from float PCM frame (-1..1)
-     */
-    private calculateVolumeMetrics;
-    /**
-     * Calculate perceptual/log-ish bands on a specific channel
-     */
-    private calculateChannelBands;
-    /**
-     * Spectral features on a specific channel
-     */
-    private calculateChannelSpectral;
-    /**
-     * Run onset + beat detection pipeline and return BeatState
-     */
-    private runBeatPipeline;
-    /**
-     * Debug logging helper
-     */
-    private debugLog;
-    private fftSize;
-    private audioStateBeat;
-    private analysisSinks;
-    private latestChannelResults;
-    private channelMeta;
-    constructor(sendAnalysisResultsCallback?: (data: any) => void);
-    /**
-     * Get the current audio analysis state (for host-side usage)
-     */
-    getAudioState(): {
-        isConnected: boolean;
-        volume: {
-            current: number;
-            peak: number;
-            smoothed: number;
-        };
-        bands: {
-            low: number;
-            lowMid: number;
-            mid: number;
-            highMid: number;
-            high: number;
-            lowSmoothed: number;
-            lowMidSmoothed: number;
-            midSmoothed: number;
-            highMidSmoothed: number;
-            highSmoothed: number;
-        };
-        spectral: {
-            brightness: number;
-            flatness: number;
-        };
-    };
-    /**
-     * Get a recordable MediaStream carrying the main channel's audio, for
-     * host-side export recording. Main channel only — additional channels and
-     * source-fed device channels (analysis values, no PCM) are not included.
-     *
-     * The underlying destination node is created lazily on first call and then
-     * persists for the AudioSystem lifetime: on a source swap the stream keeps
-     * flowing with the new audio, and on disconnect it goes silent with tracks
-     * still live. Returns `null` when the main channel is not connected at
-     * call time (or after teardown).
-     */
-    getAudioCaptureStream(): MediaStream | null;
-    /**
-     * Initialize Essentia.js (async WASM loading)
-     */
-    private initializeEssentia;
-    /**
-     * Wait for Essentia.js to initialize (for testing/benchmarking)
-     * Returns immediately if already initialized or if initialization failed
-     */
-    waitForEssentia(timeoutMs?: number): Promise<boolean>;
-    /**
-     * Handle audio stream update for main stream (called from VijiCore)
-     */
-    handleAudioStreamUpdate(data: {
-        audioStream?: MediaStream | null;
-        timestamp: number;
-    }): void;
-    /**
-     * Ensure the shared AudioContext is created and resumed.
-     */
-    private ensureAudioContext;
-    /**
-     * Connect a channel to Web Audio nodes (source, worklet/analyser).
-     * Used for both main and additional channels.
-     *
-     * Lifecycle ordering invariant: when wiring the main channel, the idle
-     * ticker MUST be stopped before the first `await` so that an in-flight
-     * tick cannot race the audio path coming online. The ticker callback
-     * additionally guards on `mainChannel.audioState.isConnected` for
-     * belt-and-braces.
-     */
-    private connectChannel;
-    /**
-     * Set the main audio stream for analysis (preserves original public API surface).
-     */
-    private setAudioStream;
-    /**
-     * Disconnect the main audio stream (does NOT close AudioContext -- additional channels may still be active).
-     *
-     * Lifecycle ordering invariant: tear down the audio nodes first, clear any
-     * stale frequency / waveform buffers, then restart the idle ticker. The
-     * ticker callback's defensive `isConnected` guard prevents any stale tick
-     * from observing a half-disconnected state.
-     */
-    private disconnectMainStream;
-    /**
-     * Set up an AudioWorklet node for a specific channel.
-     * Registers the processor module once (shared), creates a new WorkletNode per channel.
-     */
-    private setupChannelWorklet;
-    /**
-     * Ensure the shared analysis interval is running (for analyser-mode channels).
-     */
-    private ensureAnalysisLoop;
-    /**
-     * Stop the shared analysis loop.
-     */
-    private stopAnalysisLoop;
-    /**
-     * Shared staleness timer: checks all channels for stale data.
-     */
-    private startStalenessTimer;
-    private stopStalenessTimer;
-    /**
-     * Pause audio analysis (for tests or temporary suspension)
-     */
-    pauseAnalysis(): void;
-    /**
-     * Resume audio analysis after pause
-     */
-    resumeAnalysis(): void;
-    /**
-     * Shared analysis loop callback: iterates main + additional channels in analyser mode.
-     */
-    private performAnalysis;
-    private applyChannelAutoGain;
-    /**
-     * Update smooth versions of frequency bands on a specific channel
-     */
-    private updateChannelSmoothBands;
-    /**
-     * Send analysis results for a specific channel to the worker.
-     * Tags with streamIndex and conditionally includes beat data (main channel only).
-     */
-    private sendChannelResults;
-    /**
-     * Deliver an analysis message to one sink with PER-SINK typed-array
-     * copies. The host→worker relay transfers `frequencyData`/`waveformData`
-     * buffers (zero-copy receive, `collectTransferables` case
-     * 'audio-analysis-update') — posting the same message object to N sinks
-     * would let the first post DETACH the buffers and starve every other
-     * sink (and the replay cache). One copy per sink per analysis frame is
-     * the unavoidable cost of a transfer-per-receiver delivery.
-     */
-    private deliverAnalysisMessage;
-    /**
-     * Register a result-delivery sink (one per attached core's worker) and
-     * replay current state to it in FIFO order: the latest main-channel
-     * analysis, then per non-main channel its `audio-stream-setup` identity
-     * followed by the latest cached analysis. A mid-stream attach is thereby
-     * indistinguishable from a fresh connect on the receiving worker.
-     */
-    addSink(id: string, send: (message: {
-        type: string;
-        data: any;
-    }) => void): void;
-    /**
-     * Remove a previously registered result-delivery sink.
-     */
-    removeSink(id: string): void;
-    private buildStreamSetupMessage;
-    private emitStreamSetup;
-    /**
-     * Reset audio values to defaults (main channel + beat state)
-     */
-    private resetAudioValues;
-    /**
-     * Reset all audio state (called when destroying).
-     * Disconnects all channels, closes AudioContext, resets all modules.
-     *
-     * Returns a Promise that resolves once `AudioContext.close()` has fully
-     * transitioned the context to `closed`. Callers tearing the system down
-     * (e.g. `VijiCore.destroy()`) MUST await this; otherwise Blink keeps the
-     * context alive in `Pending activities` and leaks ~4 MB per cycle.
-     */
-    resetAudioState(): Promise<void>;
-    private sourceFedIndices;
-    /**
-     * Register a source-fed device channel (no MediaStream). Emits the
-     * `audio-stream-setup` identity to all sinks and starts the staleness
-     * timer. Idempotent.
-     */
-    addDeviceAnalysisChannel(streamIndex: number, deviceId: string): void;
-    /**
-     * Feed a controller analysis packet into a source-fed channel. Instant
-     * values pass through; the smoothed companions are derived host-side via
-     * the channel's envelope followers to absorb network packet bunching
-     * (§3.9 light smoothing). Missing `frequencyData`/`waveform` surface as
-     * empty arrays (the controller omits them unless the scene reads them).
-     */
-    feedDeviceAnalysis(streamIndex: number, payload: {
-        volume?: {
-            current?: number;
-            peak?: number;
-        };
-        bands?: {
-            low?: number;
-            lowMid?: number;
-            mid?: number;
-            highMid?: number;
-            high?: number;
-        };
-        spectral?: {
-            brightness?: number;
-            flatness?: number;
-        };
-        frequencyData?: Uint8Array;
-        waveformData?: Float32Array;
-    }): void;
-    /** Remove a source-fed device channel (sends a disconnected state). */
-    removeDeviceAnalysisChannel(streamIndex: number): void;
-    /**
-     * Add an additional audio stream (lightweight analysis, no beat detection).
-     * When `meta` is provided, the stream identity is recorded and an
-     * `audio-stream-setup` message is emitted to every sink (and replayed to
-     * sinks attached later).
-     * @param streamIndex Global stream index (AUDIO_ADDITIONAL_BASE + n or AUDIO_DEVICE_BASE + n)
-     * @param stream The MediaStream to analyze
-     * @param meta Stream identity for the worker-side two-phase setup protocol
-     */
-    addStream(streamIndex: number, stream: MediaStream, meta?: {
-        streamType: 'additional' | 'device';
-        deviceId?: string;
-    }): Promise<void>;
-    /**
-     * Remove an additional audio stream.
-     */
-    removeStream(streamIndex: number): void;
-    /**
-     * Tear down all additional channels in the base range and rebuild with
-     * corrected indices, re-emitting `audio-stream-setup` for the re-indexed
-     * streams. Mirrors video's reinitializeAdditionalCoordinators pattern.
-     */
-    reinitializeAdditionalChannels(streams: MediaStream[], baseIndex: number): Promise<void>;
-    /**
-     * Get the number of additional audio channels.
-     */
-    getChannelCount(): number;
-    /**
-     * Record a tap for the specified instrument onset.
-     * `options.skipRecognition` opts the tap out of the recognition pipeline
-     * only (no IOI accumulation, no `tryRecognizePattern`, no `applyPattern`).
-     * Mode still flips `'auto' → 'tapping'` so the visual envelope and
-     * audio-event filter run; only the pattern-detection pipeline is bypassed.
-     * Used by host-side relay of forwarded tap messages where another core
-     * owns the authoritative recognition.
-     */
-    tapOnset(instrument: InstrumentType, options?: {
-        skipRecognition?: boolean;
-    }): void;
-    /**
-     * Clear tap pattern for an instrument, restoring auto-detection
-     */
-    clearOnsetTap(instrument: InstrumentType): void;
-    /**
-     * Get the current onset mode for an instrument
-     */
-    getOnsetMode(instrument: InstrumentType): OnsetMode_2;
-    /**
-     * Get pattern info for an instrument (null if no pattern recognized)
-     */
-    getOnsetPatternInfo(instrument: InstrumentType): PatternInfo | null;
-    /**
-     * Mute/unmute an instrument onset (suppresses output without destroying state)
-     */
-    setOnsetMuted(instrument: InstrumentType, muted: boolean): void;
-    /**
-     * Check if an instrument onset is muted
-     */
-    isOnsetMuted(instrument: InstrumentType): boolean;
-    onOnsetModeChange(listener: (ev: OnsetModeChangeEvent) => void): Unsubscribe;
-    onOnsetSessionEnd(listener: (ev: OnsetSessionEndEvent) => void): Unsubscribe;
-    onOnsetMuteChange(listener: (ev: OnsetMuteChangeEvent) => void): Unsubscribe;
-    exportOnsetSessionState(options?: {
-        instruments?: ReadonlyArray<InstrumentType>;
-    }): SerializedOnsetState;
-    importOnsetSessionState(state: SerializedOnsetState, clockOffset: number): void;
-    exportAudioAnalysisState(): SerializedAudioAnalysisState;
-    importAudioAnalysisState(state: SerializedAudioAnalysisState, clockOffset: number): void;
-    private startIdleTicker;
-    private stopIdleTicker;
-    private tickIdle;
-    private makeEmptyBeatState;
-    /**
-     * Get current BPM (manual or auto-detected)
-     */
-    getCurrentBPM(): number;
-    /**
-     * Nudge beat phase
-     */
-    nudgeBeatPhase(amount: number): void;
-    /**
-     * Reset beat phase to next beat
-     */
-    resetBeatPhase(): void;
-    /**
-     * Set FFT size
-     */
-    setFFTSize(size: 2048 | 4096 | 8192): void;
-    /**
-     * Enable/disable auto-gain
-     */
-    setAutoGain(enabled: boolean): void;
-    /**
-     * Enable/disable beat detection
-     */
-    setBeatDetection(enabled: boolean): void;
-    /**
-     * Enable/disable onset detection
-     */
-    setOnsetDetection(enabled: boolean): void;
-    /**
-     * Get complete audio analysis state
-     */
-    getState(): {
-        isConnected: boolean;
-        currentBPM: number;
-        confidence: number;
-        isLocked: boolean;
-        trackingState: string;
-        onsetModes: {
-            kick: OnsetMode_2;
-            snare: OnsetMode_2;
-            hat: OnsetMode_2;
-        };
-    };
-    /**
-     * Get current per-frame audio analysis data (for UI display)
-     * Returns a snapshot of the latest audio analysis values
-     */
-    getCurrentAudioData(): {
-        isConnected: boolean;
-        volume: {
-            current: number;
-            peak: number;
-            smoothed: number;
-        };
-        bands: {
-            low: number;
-            lowMid: number;
-            mid: number;
-            highMid: number;
-            high: number;
-            lowSmoothed: number;
-            lowMidSmoothed: number;
-            midSmoothed: number;
-            highMidSmoothed: number;
-            highSmoothed: number;
-        };
-        beat: {
-            kick: number;
-            snare: number;
-            hat: number;
-            any: number;
-            kickSmoothed: number;
-            snareSmoothed: number;
-            hatSmoothed: number;
-            anySmoothed: number;
-            events: BeatEvent[];
-            bpm: number;
-            confidence: number;
-            isLocked: boolean;
-        };
-        spectral: {
-            brightness: number;
-            flatness: number;
-        };
-    };
-    /**
-     * Get enhanced debug snapshot from all layers
-     */
-    getEnhancedDebugSnapshot(): {
-        onset: {
-            currentBPM: number;
-            debugMode: boolean;
-            totalOnsets: number;
-            currentCluster: {
-                primaryBands: string[];
-                ageMssinceStart: number;
-            } | null;
-            bandStates: Record<string, {
-                lastOnsetTime: number;
-                onsetCount: number;
-                cutoff: number;
-                minEnergy: number;
-            }>;
-        };
-        tempo: {
-            bpm: number;
-            confidence: number;
-        };
-        pll: PLLState;
-        state: {
-            trackingState: TrackingState;
-            isLocked: boolean;
-        };
-    };
-    /**
-     * Get comprehensive debug info for testing/debugging
-     * Exposes internal state of all analysis layers
-     */
-    getDebugInfo(): {
-        onset: Record<BandName, {
-            energy: number;
-            prevEnergy: number;
-            prevEnergy2: number;
-            minEnergy: number;
-            flux: number;
-            cutoff: number;
-            minThreshold: number;
-            minFlux: number;
-            wouldTrigger: boolean;
-            reason: string;
-            debounceMs: number;
-            lastOnsetAgo: number;
-            baselineAlpha?: number;
-            dtMs?: number;
-            fluxPrevOnly?: number;
-            fluxBaseline?: number;
-            initialized?: boolean;
-            lastFluxStored?: number;
-            fluxCalcNow?: number;
-        }>;
-        tempo: {
-            currentBPM: number;
-            confidence: number;
-            method: string;
-            anchorBand: string | null;
-            methodAgreement: number;
-            bpmHistory: number[];
-            envelopeLength: number;
-            lastAutocorrBPM: number;
-            lastIOIBPM: number;
-        };
-        pll: {
-            bpm: number;
-            phase: number;
-            bar: number;
-            driftRate: number;
-            state: PLLState;
-        };
-        state: {
-            trackingState: TrackingState;
-            isLocked: boolean;
-        };
-        levels: {
-            low: number;
-            lowMid: number;
-            mid: number;
-            highMid: number;
-            high: number;
-            volume: number;
-        };
-        rawBands: {
-            low: number;
-            lowMid: number;
-            mid: number;
-            highMid: number;
-            high: number;
-        };
-        bandGains: {
-            low: number;
-            lowMid: number;
-            mid: number;
-            highMid: number;
-            high: number;
-        };
-        volumeGain: number;
-        dtMs: number;
-        analysisIntervalMs: number;
-        events: BeatEvent[];
-    };
-}
-
-/**
- * Multi-band onset detection with hybrid peak-decay + spectral flux approach
- *
- * Industry-grade onset detection that:
- * - Uses 5 frequency bands for precise instrument detection
- * - Combines peak-decay threshold (proven reliable) with spectral flux (transient detection)
- * - Maintains per-band onset history for tempo pattern analysis
- * - Is frame-rate independent (dt-aware)
- * - Prevents double-triggering with adaptive cooldown
- */
-/**
- * Band names for the 5-band analysis
- */
-declare type BandName = 'low' | 'lowMid' | 'mid' | 'highMid' | 'high';
-
 /**
  * Beat event (discrete, timestamped)
  */
@@ -854,8 +208,17 @@ declare interface BeatEvent {
  * then auto-resets to `false`.
  */
 declare interface ButtonConfig {
-    /** Display name shown on the button in the parameter UI. Required. */
-    label: string;
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
+    /** Display name shown on the button in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -873,7 +236,7 @@ declare interface ButtonParameter {
     /** `true` for the single frame after the user clicks the button, `false` otherwise. */
     value: boolean;
     /** Display name shown on the button in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -947,8 +310,17 @@ export declare interface CaptureFrameOptions {
  * label and UI grouping/visibility.
  */
 declare interface ColorConfig {
-    /** Display name shown next to the color swatch in the parameter UI. Required. */
-    label: string;
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
+    /** Display name shown next to the color swatch in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -1009,7 +381,7 @@ declare interface ColorParameter {
         b: number;
     };
     /** Display name shown next to the swatch in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -1023,10 +395,19 @@ declare interface ColorParameter {
  * draggable pad; both `x` and `y` are clamped to `-1..1`.
  */
 declare interface CoordinateConfig {
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
     /** Snap increment for both `x` and `y` components. Default: `0.01`. */
     step?: number;
-    /** Display name shown next to the pad in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the pad in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -1045,7 +426,7 @@ declare interface CoordinateParameter {
     /** Snap increment for both `x` and `y` components. */
     step: number;
     /** Display name shown next to the pad in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -1591,8 +972,17 @@ export declare interface HandData {
  * or a P5 image wrapper (P5 renderer).
  */
 declare interface ImageConfig {
-    /** Display name shown next to the upload field in the parameter UI. Required. */
-    label: string;
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
+    /** Display name shown next to the upload field in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -1612,7 +1002,7 @@ declare interface ImageParameter {
     /** P5-compatible image wrapper. Only available in the P5 renderer; added at runtime by the P5 adapter. */
     readonly p5?: any;
     /** Display name shown next to the upload field in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -1652,8 +1042,6 @@ export declare interface InstrumentSerialized {
     refinementCounts: number[];
 }
 
-declare type InstrumentType = 'kick' | 'snare' | 'hat';
-
 /**
  * Keyboard input state for the current frame: per-key press / hold / release
  * queries (case-insensitive), the live set of held keys, modifier flags, and
@@ -1768,6 +1156,15 @@ export declare interface MouseEventData {
  * label, and UI grouping/visibility for a precise numeric input.
  */
 declare interface NumberConfig {
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
     /** Inclusive minimum value. Default: `0`. */
     min?: number;
     /** Inclusive maximum value. Default: `100`. */
@@ -1780,8 +1177,8 @@ declare interface NumberConfig {
      * (`step: 0.001`).
      */
     step?: number;
-    /** Display name shown next to the input in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the input in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -1804,7 +1201,7 @@ declare interface NumberParameter {
     /** Increment between values. */
     step: number;
     /** Display name shown next to the input in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -1817,8 +1214,6 @@ export declare type OnsetInstrument = 'kick' | 'snare' | 'hat';
 
 declare type OnsetMode = 'auto' | 'tapping' | 'pattern';
 
-declare type OnsetMode_2 = 'auto' | 'tapping' | 'pattern';
-
 export declare interface OnsetModeChangeEvent {
     instrument: OnsetInstrument;
     prevMode: OnsetMode;
@@ -1880,8 +1275,19 @@ export declare interface ParameterConfig {
 }
 
 export declare interface ParameterDefinition {
+    /**
+     * Stable parameter identity. Always equals the Record key under which the
+     * definition is registered in `groups[].parameters` — addressing
+     * (`setParameter`), saved values, presets, locks, and the controller
+     * protocol all resolve by `name`. For script scenes (native/p5) `name` is
+     * the artist's own variable or object-key name, inferred at compile time;
+     * for shader scenes it is the GLSL uniform name. `label` is display-only —
+     * never key UI lists or lookups off `label`.
+     */
+    name: string;
     type: ParameterType;
     defaultValue: ParameterValue;
+    /** Display text shown in parameter UIs. Not an identity — see `name`. */
     label?: string;
     description?: string;
     group?: string;
@@ -1907,12 +1313,6 @@ export declare type ParameterType = 'slider' | 'color' | 'toggle' | 'select' | '
 
 export declare type ParameterValue = string | number | boolean | ImageBitmap | CoordinateValue | null;
 
-declare interface PatternInfo {
-    length: number;
-    intervals: number[];
-    confidence: number;
-}
-
 export declare interface PerformanceStats {
     resolution: Resolution;
     scale: number;
@@ -1951,35 +1351,6 @@ export declare type PeriodCapabilityCounts = Record<InputCapabilityKey, CountPai
     }>;
 };
 
-/**
- * Phase-Locked Loop for stable beat phase tracking
- *
- * Industry-grade phase tracking that:
- * - Maintains expected beat times based on current BPM
- * - Compares actual onsets to expected times (phase error)
- * - Corrects phase gradually to avoid jumps
- * - Handles breakdowns by extrapolating phase
- * - Detects tempo drift in DJ sets
- * - Provides stable bar position (0-3 for 4/4 time)
- */
-/**
- * PLL state for external access
- */
-declare interface PLLState {
-    /** Current phase (0-1, where 0 = beat) */
-    phase: number;
-    /** Current bar position (0-3 for 4/4 time) */
-    bar: number;
-    /** Current BPM being tracked */
-    bpm: number;
-    /** Time since last confirmed beat (ms) */
-    timeSinceLastBeat: number;
-    /** Whether tempo is drifting (DJ transition) */
-    isDrifting: boolean;
-    /** Drift rate (BPM per second, positive = speeding up) */
-    driftRate: number;
-}
-
 /**
  * Unified pointer that abstracts mouse and primary touch into a single input
  * stream. Recommended for click / drag / position-tracking interactions that
@@ -2184,10 +1555,13 @@ export declare interface SceneConsoleMessage {
  * Static metadata about a scene, derived without running it. Returned by
  * `VijiCore.getSceneData()`.
  *
- * `renderer`, `p5CanvasMode`, and `capabilities` are available synchronously
- * once the core is constructed. The parameter counts populate once the scene
- * has registered its parameters (mirroring how parameter data has always
- * surfaced), so read them after the core has initialized the scene.
+ * `renderer`, `p5CanvasMode`, and `capabilities` are **final when
+ * `initialize()` resolves** — the worker analyzes the scene source and reports
+ * the results in its `scene-analysis` ack, which `initialize()` awaits before
+ * resolving. Reads before that return placeholder defaults. The parameter
+ * counts populate once the scene has registered its parameters (mirroring how
+ * parameter data has always surfaced), so read them after the core has
+ * initialized the scene.
  */
 export declare interface SceneData {
     /** Detected renderer the scene targets. */
@@ -2222,9 +1596,19 @@ export declare interface SceneData {
  * - `UNHANDLED_REJECTION`: caught by the worker's `unhandledrejection` handler.
  * - `SHADER_COMPILE_ERROR`: GLSL compile failure (shader mode).
  * - `P5_INIT_ERROR`: failure during P5 mode initialization (e.g. missing `render`).
+ * - `SCENE_PARSE_ERROR`: the script scene could not be parsed by the load-time
+ *   parameter name-inference pass (a genuine syntax error — the scene would not
+ *   have executed either).
+ * - `PARAM_NAME_MISSING`: a `viji.<type>(...)` call was not assigned to a
+ *   variable or object key and carries no explicit `name` — nothing to infer an
+ *   identity from. Assign it to a `const`, or pass `name:'...'`.
+ * - `PARAM_NAME_DUPLICATE`: two parameters resolved to the same name. Names are
+ *   scene-global; rename one, or pass `name:'...'` to distinguish them.
+ * - `PARAM_NAME_INVALID`: an explicit `name` is not a valid identifier or is a
+ *   reserved word (`__proto__`, `constructor`, `prototype`).
  * - `ENGINE_INTERNAL`: engine path with no artist attribution.
  */
-export declare type SceneErrorCode = 'SCENE_CODE_ERROR' | 'RENDER_ERROR' | 'UNCAUGHT_ERROR' | 'UNHANDLED_REJECTION' | 'SHADER_COMPILE_ERROR' | 'P5_INIT_ERROR' | 'ENGINE_INTERNAL';
+export declare type SceneErrorCode = 'SCENE_CODE_ERROR' | 'RENDER_ERROR' | 'UNCAUGHT_ERROR' | 'UNHANDLED_REJECTION' | 'SHADER_COMPILE_ERROR' | 'P5_INIT_ERROR' | 'SCENE_PARSE_ERROR' | 'PARAM_NAME_MISSING' | 'PARAM_NAME_DUPLICATE' | 'PARAM_NAME_INVALID' | 'ENGINE_INTERNAL';
 
 /**
  * Structured scene runtime error envelope surfaced via `VijiCore.onSceneRuntimeError`.
@@ -2315,10 +1699,19 @@ declare interface SegmentationData {
  * as a dropdown or segmented control.
  */
 declare interface SelectConfig {
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
     /** Available choices. The element type (`string` or `number`) becomes the parameter's value type. Required. */
     options: string[] | number[];
-    /** Display name shown next to the dropdown in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the dropdown in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -2337,7 +1730,7 @@ declare interface SelectParameter {
     /** The full list of choices originally configured. */
     options: string[] | number[];
     /** Display name shown next to the dropdown in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -2653,6 +2046,15 @@ export declare interface SerializedTempoInductionState {
  * increment, label, and UI grouping/visibility.
  */
 declare interface SliderConfig {
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
     /** Inclusive minimum value of the slider. Default: `0`. */
     min?: number;
     /** Inclusive maximum value of the slider. Default: `100`. */
@@ -2665,8 +2067,8 @@ declare interface SliderConfig {
      * (`step: 1` on a range of `3..30`) or fine precision (`step: 0.001`).
      */
     step?: number;
-    /** Display name shown next to the control in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the control in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -2689,7 +2091,7 @@ declare interface SliderParameter {
     /** Increment between values. */
     step: number;
     /** Display name shown next to the control in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -2714,8 +2116,17 @@ export declare interface StateImportError {
  * text input field.
  */
 declare interface TextConfig {
-    /** Display name shown next to the text field in the parameter UI. Required. */
-    label: string;
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
+    /** Display name shown next to the text field in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -2736,7 +2147,7 @@ declare interface TextParameter {
     /** Maximum character count enforced by the host UI. */
     maxLength?: number;
     /** Display name shown next to the input in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -2750,8 +2161,17 @@ declare interface TextParameter {
  * label and UI grouping/visibility.
  */
 declare interface ToggleConfig {
-    /** Display name shown next to the switch in the parameter UI. Required. */
-    label: string;
+    /**
+     * Advanced: explicit parameter identity. Normally you do NOT set this —
+     * the parameter's name is inferred from the variable or object key you
+     * assign it to (`const speed = viji.slider(...)` → `speed`). Set `name`
+     * only for parameters not assigned to a variable or key (created in an
+     * array, loop, or factory). Must be a valid identifier and scene-globally
+     * unique. When set, it overrides the inferred name.
+     */
+    name?: string;
+    /** Display name shown next to the switch in the parameter UI. Optional — defaults to the parameter's name. */
+    label?: string;
     /** Optional tooltip / help text shown next to the control. */
     description?: string;
     /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
@@ -2768,7 +2188,7 @@ declare interface ToggleParameter {
     /** Current state of the switch. Updates in real-time when the user toggles it. */
     value: boolean;
     /** Display name shown next to the switch in the parameter UI. */
-    label: string;
+    label?: string;
     /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
     /** Group name under which the control appears in the UI. */
@@ -2862,16 +2282,10 @@ declare interface TouchPoint {
     isEnding: boolean;
 }
 
-/**
- * State machine states
- * NOTE: LEARNING state removed - system now uses continuous rolling window adaptation
- */
-declare type TrackingState = 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
-
 /** Returned by `on*` listener registration calls; invoke to unsubscribe. */
 export declare type Unsubscribe = () => void;
 
-export declare const VERSION = "0.11.8";
+export declare const VERSION = "0.13.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -3057,15 +2471,6 @@ export declare interface VideoCVAPI {
     isProcessing(): boolean;
 }
 
-/**
- * Video stream role, derived from position in the index contract.
- * - main:        primary video with CV (`viji.video`)
- * - additional:  host-provided MediaStreams, no CV (`viji.videoStreams[]`)
- * - device:      device camera streams (`viji.devices[].video`)
- * - directFrame: injected compositor frames (`viji.videoStreams[]`, after additional)
- */
-export declare type VideoStreamType = 'main' | 'additional' | 'device' | 'directFrame';
-
 /**
  * The Viji API surface available to artist code as the global `viji` object.
  * Groups canvas access, timing, connected media APIs, user interaction, device
@@ -3234,6 +2639,7 @@ export declare class VijiCore {
     private isInitialized;
     private isDestroyed;
     private isInitializing;
+    private engineGroupReleased;
     private instanceId;
     private screenRefreshRate;
     private refreshRateRafId;
@@ -3262,6 +2668,8 @@ export declare class VijiCore {
     private sceneConsumesAnalysedFrame;
     private sceneContextType?;
     private parametersInitialized;
+    private isAwaitingSceneAnalysis;
+    private analysisWindowSceneError;
     private parameterListeners;
     private parameterDefinedListeners;
     private parameterErrorListeners;
@@ -3359,9 +2767,36 @@ export declare class VijiCore {
      */
     hide(): void;
     /**
-     * Initializes the core components in sequence
+     * Initializes the core components in sequence. When this resolves the
+     * scene is live and `getSceneData()`'s analysis fields are final.
+     *
+     * Rejection contract — three codes pass through unwrapped so consumers
+     * can branch on them:
+     * - `INITIALIZATION_CANCELLED` — `destroy()` landed while initializing.
+     *   Expected during rapid mount/unmount (hover previews, deck swaps);
+     *   not a failure.
+     * - `INSTANCE_DESTROYED` — called on a destroyed core, or on one whose
+     *   previous `initialize()` failed and released its engine reference;
+     *   construct a fresh core instead.
+     * - `SCENE_DECRYPT_ERROR` — an encrypted (`viji-enc:`) scene could not be
+     *   decrypted (wrong/missing key component, tampered or malformed
+     *   envelope, unsupported envelope version). Permanent for this payload:
+     *   the scene genuinely cannot run — surface a typed error state, do not
+     *   retry.
+     *
+     * Every other failure (including a `scene-analysis` ack failure or
+     * timeout) rejects as `INITIALIZATION_ERROR` with the underlying error in
+     * `details.error`. Note `details` no longer carries the config.
      */
     initialize(): Promise<void>;
+    /**
+     * Release this core's engine-group reference after a failed initialize().
+     * Idempotent; skipped when destroy() owns the teardown (it detaches and
+     * releases itself). Detach + release are safe on partially-attached state:
+     * `detachSink` deletes from maps and `release` is a member-set delete with
+     * a `_destroyed`-guarded last-release dispose.
+     */
+    private releaseEngineGroupOnFailure;
     /**
      * Sets up the interaction system for Phase 7.
      *
@@ -3449,8 +2884,10 @@ export declare class VijiCore {
      * Returns static metadata about the scene: its renderer, the capabilities its
      * code declares it uses, and its parameter shape.
      *
-     * `renderer`, `p5CanvasMode`, and `capabilities` are available immediately
-     * after construction; the parameter counts populate once the scene has
+     * `renderer`, `p5CanvasMode`, and `capabilities` are **final when
+     * `initialize()` resolves** — they are assigned from the worker's
+     * `scene-analysis` ack during initialization; reads before that return
+     * placeholder defaults. The parameter counts populate once the scene has
      * registered its parameters.
      *
      * Distinct from {@link getCapabilities}, which reports what the *host*
@@ -3495,7 +2932,13 @@ export declare class VijiCore {
      */
     unlinkEventSource(): void;
     /**
-     * Link source cores that this core will pull frames from
+     * Link source cores that this core will pull frames from.
+     *
+     * Requires an initialized core: the mixer's renderer type decides the
+     * capture flip orientation, and `sceneRenderer` is final only when
+     * `initialize()` resolves (Design B). A pre-ready call would silently read
+     * the `'native'` default and composite shader mixers un-flipped — silently
+     * wrong output, so it fails loud instead.
      */
     linkFrameSources(...sourceCores: VijiCore[]): void;
     /**
@@ -4424,6 +3867,18 @@ export declare interface VijiCoreConfig {
     _sc?: string;
     /** Initial render hint (logo variant/position), applied before the first frame. */
     _rh?: number;
+    /**
+     * Per-scene key component for encrypted (`viji-enc:`) scene delivery —
+     * an opaque base64url blob served next to the scene payload. Required to
+     * decrypt an encrypted `sceneCode`; ignored for plaintext scenes. Routed
+     * to the worker inside the `set-scene-code` payload on the direct control
+     * port (never through the iframe bootstrap).
+     *
+     * Omitted from the `configuration` getter: serializing ciphertext and the
+     * key component into one log/state dump would make the dump decryptable
+     * with the shipped bundle constant — do not persist or log this value.
+     */
+    _sk?: string;
     /** Called when the scene is visually live (render loop running, branding applied) but before audio/video/WASM setup completes. */
     onRenderStart?: () => void;
     /**