@viji-dev/core 0.12.0 → 0.14.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)
  */
@@ -1688,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
@@ -1862,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;
@@ -1963,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;
@@ -2007,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
@@ -2140,6 +1455,29 @@ export declare type Resolution = {
     height: number;
 };
 
+/**
+ * Payload of the worker's `scene-analysis` ack — the correlated response to
+ * `set-scene-code`. The worker runs static analysis (renderer, capabilities,
+ * p5 canvas mode, analysedFrame consumption) after receiving the scene code
+ * and **before** compiling it, and the host's `initialize()` awaits this ack
+ * to assign the four `SceneData` fields exactly once. Carries booleans/enums
+ * only — never scene source.
+ *
+ * Public since 0.14.0: this is also the return type of `analyzeScene`
+ * (`@viji-dev/core/scene-analysis`), which the worker itself calls to build
+ * the ack — one shape, one producer, two transports.
+ */
+export declare interface SceneAnalysisData {
+    /** Detected renderer the scene targets. */
+    renderer: RendererType;
+    /** P5 canvas mode; present only when `renderer` is `'p5'`. */
+    p5CanvasMode?: P5CanvasMode;
+    /** Capabilities the scene's code declares it uses (inclusive-biased). */
+    capabilities: SceneCapabilities;
+    /** Whether the scene consumes per-frame analysed-frame bitmaps (CV). */
+    consumesAnalysedFrame: boolean;
+}
+
 /**
  * The set of engine capabilities a scene's code declares it uses, derived by
  * static analysis of the scene source (no execution). Detection is
@@ -2967,16 +2305,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.12.0";
+export declare const VERSION = "0.14.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -3162,15 +2494,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