@viji-dev/core 0.4.6 → 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,14 +2234,19 @@ declare interface TouchPoint {
  */
 declare type TrackingState = 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
 
-export declare const VERSION = "0.3.29";
+/** 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 computer-vision results
- * (faces, hands, pose, segmentation). Activate individual CV features through `cv.*`.
+ * Real-time video API: drawable frame, dimensions, and the source-side
+ * properties of the connected stream. All computer-vision data and controls
+ * (faces, hands, pose, segmentation, the analysed frame, and feature
+ * enable/disable verbs) live on `viji.video.cv`.
  *
- * When `isConnected` is `false`, `currentFrame` is `null`, all dimensions are `0`,
- * and CV result fields hold their empty defaults.
+ * When `isConnected` is `false`, `currentFrame` is `null`, all dimensions are
+ * `0`, and every member of `cv` holds its empty default.
  */
 export declare interface VideoAPI {
     /** `true` when a video stream is connected. When `false`, all other fields hold their default empty values. */
@@ -1889,6 +2265,78 @@ export declare interface VideoAPI {
      * use only when you need to read individual pixel values.
      */
     getFrameData: () => ImageData | null;
+    /**
+     * Computer-vision surface for this video stream. Holds both the data
+     * outputs (`faces`, `hands`, `pose`, `segmentation`, `analysedFrame`,
+     * `getAnalysedFrameData`) and the verbs that activate them
+     * (`enable*`/`disable*`/`getActiveFeatures`/`isProcessing`).
+     *
+     * Multiple features can be active simultaneously, but each adds CPU/GPU
+     * and WebGL-context cost; toggle only what you need.
+     *
+     * `analysedFrame` and the result fields refresh together once per host
+     * frame as an atomic snapshot: within a single `render()` call they are
+     * always paired.
+     */
+    cv: VideoCVAPI;
+}
+
+/**
+ * Computer-vision surface attached to a `VideoAPI`. Combines paired CV data
+ * outputs (the analysed frame and its detection / segmentation results) with
+ * the verbs that activate the underlying MediaPipe pipelines.
+ *
+ * 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
+ * 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.
+     *
+     * 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`
+     * 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; 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`).
+     * Drawing it as a source (`ctx.drawImage`, `gl.texImage2D`,
+     * `p5.image(...)`) is the only supported usage.
+     */
+    analysedFrame: OffscreenCanvas | null;
+    /**
+     * Returns `analysedFrame` as raw RGBA `ImageData` for per-pixel CPU
+     * 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
+     * pixel values aligned with CV landmark positions (e.g. sampling skin
+     * colour at a face landmark).
+     */
+    getAnalysedFrameData: () => ImageData | null;
     /** Detected faces (empty array when face detection is off or no faces are visible). */
     faces: FaceData[];
     /** Detected hands (up to 2; empty array when hand tracking is off or no hands are visible). */
@@ -1898,50 +2346,42 @@ export declare interface VideoAPI {
     /** Body segmentation mask, or `null` when segmentation is off. */
     segmentation: SegmentationData | null;
     /**
-     * Computer-vision feature control. Each `enable*` method toggles a specific CV
-     * pipeline; results land in the corresponding `faces` / `hands` / `pose` /
-     * `segmentation` field on the next available frame. Multiple features can be
-     * active simultaneously, but each adds CPU/GPU and WebGL-context cost.
+     * Toggle face detection (bounding box, center, confidence, id).
+     * @returns Resolves once the underlying pipeline has finished switching.
      */
-    cv: {
-        /**
-         * Toggle face detection (bounding box, center, confidence, id).
-         * @returns Resolves once the underlying pipeline has finished switching.
-         */
-        enableFaceDetection(enabled: boolean): Promise<void>;
-        /**
-         * Toggle 468-point face mesh + head pose (`pitch`, `yaw`, `roll`). Implies
-         * face detection.
-         * @returns Resolves once the pipeline has finished switching.
-         */
-        enableFaceMesh(enabled: boolean): Promise<void>;
-        /**
-         * Toggle 7 expressions + 52 ARKit blendshape coefficients on each face.
-         * Implies face mesh.
-         * @returns Resolves once the pipeline has finished switching.
-         */
-        enableEmotionDetection(enabled: boolean): Promise<void>;
-        /**
-         * Toggle 21-point hand landmarks + ML-classified gesture confidences for up
-         * to two hands.
-         * @returns Resolves once the pipeline has finished switching.
-         */
-        enableHandTracking(enabled: boolean): Promise<void>;
-        /**
-         * Toggle 33-point BlazePose body landmarks (face / torso / arms / legs).
-         * @returns Resolves once the pipeline has finished switching.
-         */
-        enablePoseDetection(enabled: boolean): Promise<void>;
-        /**
-         * Toggle per-pixel person/background segmentation mask.
-         * @returns Resolves once the pipeline has finished switching.
-         */
-        enableBodySegmentation(enabled: boolean): Promise<void>;
-        /** Returns the list of CV features currently enabled on this stream. */
-        getActiveFeatures(): CVFeature[];
-        /** Returns `true` if the CV worker is actively processing frames. */
-        isProcessing(): boolean;
-    };
+    enableFaceDetection(enabled: boolean): Promise<void>;
+    /**
+     * Toggle 468-point face mesh + head pose (`pitch`, `yaw`, `roll`). Implies
+     * face detection.
+     * @returns Resolves once the pipeline has finished switching.
+     */
+    enableFaceMesh(enabled: boolean): Promise<void>;
+    /**
+     * Toggle 7 expressions + 52 ARKit blendshape coefficients on each face.
+     * Implies face mesh.
+     * @returns Resolves once the pipeline has finished switching.
+     */
+    enableEmotionDetection(enabled: boolean): Promise<void>;
+    /**
+     * Toggle 21-point hand landmarks + ML-classified gesture confidences for up
+     * to two hands.
+     * @returns Resolves once the pipeline has finished switching.
+     */
+    enableHandTracking(enabled: boolean): Promise<void>;
+    /**
+     * Toggle 33-point BlazePose body landmarks (face / torso / arms / legs).
+     * @returns Resolves once the pipeline has finished switching.
+     */
+    enablePoseDetection(enabled: boolean): Promise<void>;
+    /**
+     * Toggle per-pixel person/background segmentation mask.
+     * @returns Resolves once the pipeline has finished switching.
+     */
+    enableBodySegmentation(enabled: boolean): Promise<void>;
+    /** Returns the list of CV features currently enabled on this stream. */
+    getActiveFeatures(): CVFeature[];
+    /** Returns `true` if the CV worker is actively processing frames. */
+    isProcessing(): boolean;
 }
 
 /**
@@ -2162,6 +2602,7 @@ export declare class VijiCore {
     private parameterDefinedListeners;
     private parameterErrorListeners;
     private capabilitiesChangeListeners;
+    private stateImportErrorListeners;
     private stats;
     constructor(config: VijiCoreConfig);
     /**
@@ -2415,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
      */
@@ -2553,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