@viji-dev/core 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -235,6 +235,8 @@ export declare class AudioSystem {
     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
@@ -349,6 +351,12 @@ export declare class AudioSystem {
     /**
      * 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;
     /**
@@ -357,6 +365,11 @@ export declare class AudioSystem {
     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;
     /**
@@ -451,6 +464,16 @@ export declare class AudioSystem {
      * Check if an instrument onset is muted
      */
     isOnsetMuted(instrument: InstrumentType): boolean;
+    onOnsetModeChange(listener: (ev: OnsetModeChangeEvent) => void): Unsubscribe;
+    onOnsetSessionEnd(listener: (ev: OnsetSessionEndEvent) => void): Unsubscribe;
+    exportOnsetSessionState(): 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)
      */
@@ -1256,6 +1279,22 @@ declare interface ImageParameter {
     category: ParameterCategory;
 }
 
+export declare interface InstrumentSerialized {
+    mode: OnsetMode;
+    muted: boolean;
+    pattern: number[] | null;
+    /** Sender wall-clock; null if never set. */
+    replayLastEventTime: number | null;
+    replayIndex: number;
+    tapIOIs: number[];
+    /** Sender wall-clock; null if never set. */
+    lastTapTime: number | null;
+    /** Sender wall-clock; null if not muted. */
+    mutedAt: number | null;
+    refinementIndex: number;
+    refinementCounts: number[];
+}
+
 declare type InstrumentType = 'kick' | 'snare' | 'hat';
 
 /**
@@ -1404,10 +1443,29 @@ declare interface NumberParameter {
     category: ParameterCategory;
 }
 
+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;
+    newMode: OnsetMode;
+}
+
+export declare interface OnsetSessionEndEvent {
+    instrument: OnsetInstrument;
+    /**
+     * `'pattern'` — 500ms idle since last tap with instrument in `'pattern'` mode.
+     * `'cleared'` — 5s idle in `'tapping'` mode without a recognized pattern;
+     * instrument transitions to `'auto'`. Explicit `clear()` calls do NOT fire
+     * this event (caller-initiated; caller already knows).
+     */
+    outcome: 'pattern' | 'cleared';
+}
+
 export declare interface ParameterAPI {
     define(groups: ParameterGroup[]): void;
     [key: string]: any;
@@ -1660,6 +1718,308 @@ declare interface SelectParameter {
     category: ParameterCategory;
 }
 
+export declare interface SerializedAudioAnalysisState {
+    /** Per-instrument onset state (mirrors SerializedOnsetState.instruments shape). */
+    onset: SerializedOnsetState['instruments'];
+    bpmTracker: SerializedTempoInductionState;
+    pll: SerializedPLLState;
+    beatState: SerializedBeatStateManagerState;
+}
+
+/**
+ * BeatStateManager continuity-relevant state. Treat as opaque on the consumer
+ * side. Envelope follower state is omitted by design — receiver re-triggers
+ * envelopes naturally as detected events flow.
+ */
+export declare interface SerializedBeatStateManagerState {
+    state: 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
+    /** Sender wall-clock; 0 if never set. */
+    stateEnteredTime: number;
+    kickProfile: {
+        avgEnergy: number;
+        bassRatio: number;
+        midRatio: number;
+        trebleRatio: number;
+        sampleCount: number;
+    };
+    snareProfile: {
+        avgEnergy: number;
+        bassRatio: number;
+        midRatio: number;
+        trebleRatio: number;
+        sampleCount: number;
+    };
+    hatProfile: {
+        avgEnergy: number;
+        bassRatio: number;
+        midRatio: number;
+        trebleRatio: number;
+        sampleCount: number;
+    };
+    recentOnsetStrengths: number[];
+    averageOnsetStrength: number;
+    tempoMethodAgreement: number;
+    gridScore: number;
+    consistencyScore: number;
+    anchorClarity: number;
+    recentGridScores: number[];
+    lockedBPM: number;
+    /** Sender wall-clock; 0 if never set. */
+    lastOnsetTime: number;
+    /** Sender wall-clock; 0 if never set. */
+    lastKickTime: number;
+    kickIntervals: number[];
+    bpmHistory: number[];
+    /** Sender wall-clocks in nested `time` fields. */
+    adaptiveProfiles: {
+        kick: {
+            samples: Array<{
+                midRatio: number;
+                midToBass: number;
+                time: number;
+            }>;
+        };
+        snareIndependent: {
+            samples: Array<{
+                strength: number;
+                midRatio: number;
+                trebleRatio: number;
+                sharpness: number;
+                time: number;
+            }>;
+        };
+        snareLayered: {
+            samples: Array<{
+                strength: number;
+                midRatio: number;
+                energy: number;
+                sharpness: number;
+                time: number;
+            }>;
+        };
+        hatIndependent: {
+            samples: Array<{
+                strength: number;
+                trebleRatio: number;
+                energy: number;
+                sharpness: number;
+                time: number;
+            }>;
+        };
+        hatLayered: {
+            samples: Array<{
+                strength: number;
+                trebleRatio: number;
+                energy: number;
+                sharpness: number;
+                time: number;
+            }>;
+        };
+    };
+    adaptiveThresholds: {
+        snareMinMidRatio: number;
+        snareMinMidToBass: number;
+        kickMaxMidRatio: number;
+        snareIndependent: {
+            minStrength: number;
+            minMidRatio: number;
+            minTrebleRatio: number;
+            minSharpness: number;
+        };
+        snareLayered: {
+            minStrength: number;
+            minEnergy: number;
+            minSharpness: number;
+        };
+        hatIndependent: {
+            minStrength: number;
+            minTrebleRatio: number;
+            minSharpness: number;
+        };
+        hatLayered: {
+            minStrength: number;
+            minTrebleRatio: number;
+            minSharpness: number;
+        };
+    };
+    /** Sender wall-clocks in nested `lastOnsetTime`. */
+    ioiTrackers: {
+        kick: {
+            intervals: number[];
+            lastOnsetTime: number;
+        };
+        snare: {
+            intervals: number[];
+            lastOnsetTime: number;
+        };
+        hat: {
+            intervals: number[];
+            lastOnsetTime: number;
+        };
+    };
+    /** Each event has a `time` field (sender wall-clock); `expiresAt` is also wall-clock. */
+    eventBuffer: Array<{
+        event: {
+            type: 'kick' | 'snare' | 'hat';
+            time: number;
+            strength: number;
+            isPredicted?: boolean;
+            bpm?: number;
+        };
+        expiresAt: number;
+    }>;
+    /** Per-band history with sender wall-clocks. */
+    bandEnergyHistory: {
+        low: Array<{
+            time: number;
+            value: number;
+        }>;
+        mid: Array<{
+            time: number;
+            value: number;
+        }>;
+        high: Array<{
+            time: number;
+            value: number;
+        }>;
+    };
+    /** Per-class arrays of sender wall-clocks (rate-cap enforcement). */
+    eventTimestamps: {
+        kick: number[];
+        snare: number[];
+        hat: number[];
+    };
+    /** Per-class last event time (cooldown enforcement); 0 = never fired. */
+    lastEventTime: {
+        kick: number;
+        snare: number;
+        hat: number;
+    };
+}
+
+export declare interface SerializedCoreState {
+    version: 1;
+    /** Sender wall-clock at serialize time. */
+    senderTime: number;
+    /** Onset state only — cross-device-safe, no audio analysis carry-over. */
+    onset?: SerializedOnsetState['instruments'];
+    /**
+     * Full audio analysis state — same-process scene-switch only. Cross-device
+     * transfer should omit this block (sender's audio analysis doesn't apply
+     * to receiver's audio source). Robust to gaps under ~1 second; longer
+     * scene-loads (>5s) may cause stale-timestamp drift in fields like
+     * `gridLockMemoryTime` / `warmupStartTimeMs` — caller should treat as a
+     * degraded path and skip the audio block on stale exports.
+     */
+    audio?: SerializedAudioAnalysisState;
+}
+
+export declare interface SerializedOnsetState {
+    version: 1;
+    /** Sender wall-clock at serialize time. */
+    senderTime: number;
+    /** Per-instrument payload — only included instruments are imported. */
+    instruments: {
+        kick?: InstrumentSerialized;
+        snare?: InstrumentSerialized;
+        hat?: InstrumentSerialized;
+    };
+}
+
+/**
+ * PhaseLockedLoop continuity-relevant state. Treat as opaque on the consumer
+ * side.
+ */
+export declare interface SerializedPLLState {
+    phase: number;
+    /** Sender wall-clock; 0 if never set. */
+    lastBeatTime: number;
+    periodMs: number;
+    trackedBPM: number;
+    beatCounter: number;
+    /** Sender wall-clock; 0 if never set. */
+    lastOnsetTime: number;
+    /** Sender wall-clocks in `time`. */
+    bpmHistory: Array<{
+        time: number;
+        bpm: number;
+    }>;
+    driftRate: number;
+    inBreakdown: boolean;
+    tempoConfidence: number;
+    inTransition: boolean;
+    currentGain: number;
+    /** Sender wall-clock; 0 if never set. */
+    lastBarAdvanceTime: number;
+    pendingBarAdvance: boolean;
+    /** Sender wall-clock; 0 if never set. */
+    lastPhaseWrapTime: number;
+    consecutiveAlignedKicks: number;
+    /** Sender wall-clock; 0 if never set. */
+    lastHardSyncTime: number;
+    /** Sender wall-clock; 0 if never set. */
+    trackingStartTime: number;
+    kickPhaseHistory: number[];
+    phaseOffsetCalibrated: number;
+    /** Sender wall-clock; 0 if never set. */
+    lastCalibrationTime: number;
+    lastPhaseError: number;
+}
+
+/**
+ * TempoInduction continuity-relevant state. Treat as opaque on the consumer
+ * side — the field set is internal and may evolve in future versions
+ * (gated by `version`).
+ */
+export declare interface SerializedTempoInductionState {
+    onsetEnvelope: number[];
+    lowBandEnvelope: number[];
+    midBandEnvelope: number[];
+    highBandEnvelope: number[];
+    fpsEstimate: number;
+    currentBPM: number;
+    confidence: number;
+    method: 'autocorr' | 'ioi' | 'combined';
+    anchorBand: string | null;
+    methodAgreement: number;
+    bpmHistory: number[];
+    /** Sender wall-clock; null if never set. */
+    lastUpdateTime: number | null;
+    hypotheses: Array<{
+        bpm: number;
+        likelihood: number;
+        age: number;
+        /** Sender wall-clock. */
+        lastEvidence: number;
+        type: 'main' | 'half' | 'double' | 'other';
+    }>;
+    inTransition: boolean;
+    /** Sender wall-clocks. */
+    bpmDriftHistory: Array<{
+        time: number;
+        bpm: number;
+    }>;
+    driftRate: number;
+    tempoChangeConfirmCount: number;
+    /** Sender wall-clocks. */
+    onsetHistory: Array<{
+        time: number;
+        strength: number;
+        type: string;
+    }>;
+    gridLockBPM: number | null;
+    gridLockScore: number;
+    /** Sender wall-clock; 0 if not locked. */
+    gridLockTime: number;
+    gridLockMemoryBPM: number | null;
+    /** Sender wall-clock; 0 if no memory. */
+    gridLockMemoryTime: number;
+    syncopationLevel: number;
+    /** Sender wall-clock; 0 if not started. */
+    warmupStartTimeMs: number;
+    warmupComplete: boolean;
+}
+
 /**
  * Configuration object passed to `viji.slider()`. Defines the slider's bounds,
  * increment, label, and UI grouping/visibility.
@@ -1704,6 +2064,17 @@ declare interface SliderParameter {
     category: ParameterCategory;
 }
 
+export declare interface StateImportError {
+    code: 'version-mismatch' | 'malformed' | 'invalid-field';
+    details: string;
+    /** Present for `'version-mismatch'`. */
+    payloadVersion?: number;
+    /** Present for `'version-mismatch'`. */
+    expectedVersion?: number;
+    /** Present for `'invalid-field'`. */
+    field?: string;
+}
+
 /**
  * Configuration object passed to `viji.text()`. The host renders a single-line
  * text input field.
@@ -1863,7 +2234,10 @@ declare interface TouchPoint {
  */
 declare type TrackingState = 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
 
-export declare const VERSION = "0.5.0";
+/** Returned by `on*` listener registration calls; invoke to unsubscribe. */
+export declare type Unsubscribe = () => void;
+
+export declare const VERSION = "0.5.1";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -1898,10 +2272,10 @@ export declare interface VideoAPI {
      * (`enable*`/`disable*`/`getActiveFeatures`/`isProcessing`).
      *
      * Multiple features can be active simultaneously, but each adds CPU/GPU
-     * and WebGL-context cost — toggle only what you need.
+     * and WebGL-context cost; toggle only what you need.
      *
      * `analysedFrame` and the result fields refresh together once per host
-     * frame (atomic snapshot) — within a single `render()` call they are
+     * frame as an atomic snapshot: within a single `render()` call they are
      * always paired.
      */
     cv: VideoCVAPI;
@@ -1914,30 +2288,38 @@ export declare interface VideoAPI {
  *
  * Available only on the main video stream (`viji.video.cv`). Additional
  * streams (`viji.videoStreams[i].cv`) and device videos
- * (`viji.devices[i].video.cv`) do not run CV — their `cv` surface exists for
+ * (`viji.devices[i].video.cv`) do not run CV; their `cv` surface exists for
  * API consistency but the data fields stay at their empty defaults and the
  * `enable*` verbs are no-ops.
  */
 export declare interface VideoCVAPI {
     /**
      * The exact video frame that produced the current `faces` / `hands` /
-     * `pose` / `segmentation` results — the frame MediaPipe actually analysed.
-     * Use this (not `viji.video.currentFrame`) when overlaying pixel-precise
-     * CV-driven effects (face-mesh masks, body-segmentation compositing,
-     * makeup, distortion). `currentFrame` is the just-arrived frame and runs
-     * ~15–40 ms ahead of the analysis; `analysedFrame` is the frame the
-     * landmarks/mask actually correspond to, so the two stay locked under
-     * fast head/body motion.
+     * `pose` / `segmentation` results: the frame MediaPipe actually analysed.
+     *
+     * Choose between `analysedFrame` and `viji.video.currentFrame` by asking
+     * whether the effect reads pixels from the displayed frame at CV-derived
+     * positions. Reach for `analysedFrame` when the answer is yes
+     * (compositing the segmentation mask onto the body, sampling skin tone
+     * under a face landmark, warping the face along its mesh, texture-mapped
+     * face filters): pairing the displayed frame with the CV results is
+     * required for those effects. Stay on `currentFrame` when the answer is
+     * no (drawing landmark dots, particles, debug overlays, geometry driven
+     * by CV positions): `analysedFrame` only refreshes when MediaPipe
+     * completes an inference, which is not every frame, so reaching for it
+     * without a reason makes the displayed video stutter or hold between
+     * inferences.
      *
      * Pairing guarantee: within a single `render()` call, `analysedFrame`
      * is paired with the values of `faces`, `hands`, `pose`, `segmentation`
-     * you read in the same call. They refresh together once per host frame.
+     * read in the same call.
      *
      * `null` until the first CV inference completes after a feature is
      * enabled, after the video disconnects, or after a CV-feature toggle
      * clears state. A common pattern is
      * `viji.video.cv.analysedFrame ?? viji.video.currentFrame` to fall back
-     * to the live feed during the brief startup window.
+     * to the live feed during the brief startup window; expect a small
+     * visual hitch when the source switches as the first inference lands.
      *
      * Read-only: this `OffscreenCanvas` is owned by the engine. Do not
      * mutate it (no `getContext`-and-paint, no `transferToImageBitmap`).
@@ -1950,7 +2332,7 @@ export declare interface VideoCVAPI {
      * analysis, or `null` when no CV result has landed yet (or the stream is
      * disconnected). Cached: re-extracted only when a new CV result arrives,
      * so multiple readers within a render share one allocation. Slow
-     * compared to drawing `analysedFrame` directly — use only when you need
+     * compared to drawing `analysedFrame` directly. Use only when you need
      * pixel values aligned with CV landmark positions (e.g. sampling skin
      * colour at a face landmark).
      */
@@ -2220,6 +2602,7 @@ export declare class VijiCore {
     private parameterDefinedListeners;
     private parameterErrorListeners;
     private capabilitiesChangeListeners;
+    private stateImportErrorListeners;
     private stats;
     constructor(config: VijiCoreConfig);
     /**
@@ -2473,6 +2856,44 @@ export declare class VijiCore {
         message: string;
         code: string;
     }) => void): void;
+    /**
+     * Snapshot the full audio analysis + onset state for cross-instance
+     * transfer. Use for **same-process scene-switch** continuity (a fresh
+     * `VijiCore` can resume detection where the previous one left off).
+     *
+     * For **cross-device** transfer, prefer `audio.onset.exportSessionState`
+     * — the controller's audio analysis state doesn't apply to the host's
+     * audio source and would corrupt detection.
+     *
+     * Wall-clock fields are in this instance's `performance.now()` clock space.
+     * Receiver applies `clockOffset` on import (use `0` for same-process).
+     *
+     * **Staleness caveat**: the audio block is robust to scene-load gaps under
+     * ~1 second. Longer gaps (>5s, e.g. cold cache + slow network) may cause
+     * stale-timestamp drift in `gridLockMemoryTime` / `warmupStartTimeMs`;
+     * callers should treat that as a degraded path and skip the audio block.
+     */
+    exportFullState(): SerializedCoreState;
+    /**
+     * Replace the audio analysis + onset state from a serialized payload.
+     * `clockOffset` is added to all sender-clocked fields (`0` for same-process,
+     * NTP-derived for cross-device). Mutation is synchronous; no `onModeChange`
+     * or `onSessionEnd` events are emitted (state replacement is not a transition).
+     *
+     * Validates `version`; on mismatch, fires `onStateImportError` and leaves
+     * existing state intact.
+     */
+    importFullState(state: SerializedCoreState, clockOffset: number): void;
+    /**
+     * Listen for state-import validation errors. Fires when `importFullState`
+     * or `audio.onset.importSessionState` rejects a payload (version mismatch,
+     * malformed shape, invalid field). Existing state is left intact when
+     * an error fires.
+     *
+     * @returns Unsubscribe function. Call to remove the listener.
+     */
+    onStateImportError(listener: (error: StateImportError) => void): Unsubscribe;
+    private fireStateImportError;
     /**
      * Notify parameter change listeners
      */
@@ -2611,6 +3032,50 @@ export declare class VijiCore {
              * Check if an instrument onset is muted
              */
             isMuted: (instrument: "kick" | "snare" | "hat") => boolean;
+            /**
+             * Listen for instrument mode transitions (`'auto' | 'tapping' | 'pattern'`).
+             * Fires on every transition including the first tap (`'auto' → 'tapping'`)
+             * and pattern recognition (`'tapping' → 'pattern'`). Imported state does
+             * NOT fire mode-change events — state replacement is not a transition.
+             *
+             * @returns Unsubscribe function. Call to remove the listener.
+             */
+            onModeChange: (listener: (ev: OnsetModeChangeEvent) => void) => Unsubscribe;
+            /**
+             * Listen for natural session-end events. Fires when:
+             * - 500ms elapse since last tap with instrument in `'pattern'` mode
+             *   (outcome `'pattern'`), or
+             * - 5s elapse in `'tapping'` mode without a recognized pattern
+             *   (outcome `'cleared'`; instrument transitions to `'auto'`).
+             *
+             * Explicit `clear()` calls do NOT fire this event (caller-initiated;
+             * caller already knows). Imported state does NOT fire either.
+             *
+             * @returns Unsubscribe function. Call to remove the listener.
+             */
+            onSessionEnd: (listener: (ev: OnsetSessionEndEvent) => void) => Unsubscribe;
+            /**
+             * Snapshot per-instrument onset state for cross-instance transfer.
+             * Cross-device-safe (no audio analysis state included). Pair with
+             * `importSessionState` on a receiver. Wall-clock fields are in this
+             * instance's `performance.now()` clock space.
+             */
+            exportSessionState: () => SerializedOnsetState;
+            /**
+             * Replace per-instrument onset state from a serialized payload.
+             * `clockOffset` is added to all sender-clocked fields during import
+             * (use `0` for same-process transfer; NTP-derived offset for cross-device).
+             * Mutation is synchronous; no events are emitted.
+             *
+             * Patterns are rebased forward by whole pattern cycles to eliminate
+             * the catch-up burst that would otherwise occur on stale payloads
+             * (phase-preserving — events still land on the original beat positions
+             * modulo pattern length).
+             *
+             * Validates `version`; on mismatch, fires `onStateImportError` and
+             * leaves existing state intact.
+             */
+            importSessionState: (state: SerializedOnsetState, clockOffset: number) => void;
         };
         /**
          * Advanced audio controls

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A, V, a, b } from "./index-Cp9G0z4E.js";
+import { A, V, a, b } from "./index-Cqh1k_49.js";
 export {
   A as AudioSystem,
   V as VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",