@viji-dev/core 0.5.2 → 0.5.4

package/dist/index.d.ts

@@ -441,9 +441,14 @@ export declare class AudioSystem {
      */
     getChannelCount(): number;
     /**
-     * Record a tap for the specified instrument onset
+     * Record a tap for the specified instrument onset.
+     * `options.skipRecognition` retains visual envelope + session timing but
+     * bypasses the recognition pipeline — used by host-side relay of forwarded
+     * tap messages where another core is doing the authoritative recognition.
      */
-    tapOnset(instrument: InstrumentType): void;
+    tapOnset(instrument: InstrumentType, options?: {
+        skipRecognition?: boolean;
+    }): void;
     /**
      * Clear tap pattern for an instrument, restoring auto-detection
      */
@@ -467,7 +472,9 @@ export declare class AudioSystem {
     onOnsetModeChange(listener: (ev: OnsetModeChangeEvent) => void): Unsubscribe;
     onOnsetSessionEnd(listener: (ev: OnsetSessionEndEvent) => void): Unsubscribe;
     onOnsetMuteChange(listener: (ev: OnsetMuteChangeEvent) => void): Unsubscribe;
-    exportOnsetSessionState(): SerializedOnsetState;
+    exportOnsetSessionState(options?: {
+        instruments?: ReadonlyArray<InstrumentType>;
+    }): SerializedOnsetState;
     importOnsetSessionState(state: SerializedOnsetState, clockOffset: number): void;
     exportAudioAnalysisState(): SerializedAudioAnalysisState;
     importAudioAnalysisState(state: SerializedAudioAnalysisState, clockOffset: number): void;
@@ -2244,7 +2251,7 @@ 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.5.2";
+export declare const VERSION = "0.5.4";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2884,8 +2891,12 @@ export declare class VijiCore {
     /**
      * 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).
+     * NTP-derived for cross-device). Mutation is synchronous.
+     *
+     * Field-level events (`onModeChange`, `onMuteChange`) fire when imported
+     * values differ from current — consumer-visible state stays consistent
+     * with what polling would have observed. Session-boundary events
+     * (`onSessionEnd`) do NOT fire on import.
      *
      * Validates `version`; on mismatch, fires `onStateImportError` and leaves
      * existing state intact.
@@ -3011,8 +3022,21 @@ export declare class VijiCore {
              * Tap an onset for a specific instrument.
              * First tap switches the instrument from auto to tapping mode.
              * If a repeating pattern is recognized, it continues after tapping stops.
+             *
+             * `options.skipRecognition: true` keeps the visual envelope and session
+             * timing but bypasses pattern recognition entirely (no IOI accumulation,
+             * no mode transition, no `applyPattern`, no `handlePatternTap`). Use
+             * this when relaying tap messages from another instance that owns the
+             * authoritative recognition (e.g. host receiving forwarded controller
+             * taps over WebRTC). The receiving core's mode is then driven only by
+             * `importSessionState` from the authoritative sender.
+             *
+             * The `MIN_TAP_INTERVAL_MS` debounce still applies regardless of the
+             * `skipRecognition` flag.
              */
-            tap: (instrument: "kick" | "snare" | "hat") => void;
+            tap: (instrument: "kick" | "snare" | "hat", options?: {
+                skipRecognition?: boolean;
+            }) => void;
             /**
              * Clear the tap pattern for an instrument, restoring auto-detection
              */
@@ -3041,36 +3065,47 @@ export declare class VijiCore {
             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.
+             * Fires whenever the underlying mode field actually changes, regardless
+             * of which code path triggered it — first tap (`'auto' → 'tapping'`),
+             * pattern recognition (`'tapping' → 'pattern'`), the 5s tap timeout
+             * (`'tapping' → 'auto'`), explicit `clear()`, or `importSessionState`
+             * landing a different mode value.
+             *
+             * Idempotent transitions (already in target mode) do not fire.
              *
              * @returns Unsubscribe function. Call to remove the listener.
              */
             onModeChange: (listener: (ev: OnsetModeChangeEvent) => void) => Unsubscribe;
             /**
-             * Listen for natural session-end events. Fires when:
+             * Listen for natural session-end events. Fires only on natural session
+             * boundaries:
              * - 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.
+             * Does NOT fire on:
+             * - Explicit `clear()` calls (caller-initiated; not a natural boundary).
+             * - `importSessionState` (state replacement; not a session boundary).
+             *
+             * Field-change events (`onModeChange`, `onMuteChange`) fire on imports
+             * when fields differ; this event does not because session-end is a
+             * different category — about session lifecycle, not field state.
              *
              * @returns Unsubscribe function. Call to remove the listener.
              */
             onSessionEnd: (listener: (ev: OnsetSessionEndEvent) => void) => Unsubscribe;
             /**
              * Listen for instrument mute-state transitions (`true ↔ false`). Fires
-             * whenever the underlying mute state actually changes, regardless of
-             * which method triggered it:
-             * - `setMuted(instrument, muted)` when `prev !== next`
-             * - `tap(instrument)` auto-unmute on first tap of a muted instrument
-             * - `clear(instrument)` when the instrument was muted
+             * whenever the underlying mute field actually changes, regardless of
+             * which code path triggered it:
+             * - `setMuted(instrument, muted)` when `prev !== next`.
+             * - `tap(instrument)` auto-unmute on first tap of a muted instrument.
+             * - `clear(instrument)` when the instrument was muted at call time.
+             * - `importSessionState` landing a different muted value.
              *
              * Idempotent calls (e.g. `setMuted(true)` on an already-muted instrument)
-             * do not fire. Imported state does NOT fire either.
+             * do not fire.
              *
              * @returns Unsubscribe function. Call to remove the listener.
              */
@@ -3080,13 +3115,32 @@ export declare class VijiCore {
              * 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.
+             *
+             * `options.instruments` scopes the snapshot to the listed instruments
+             * only; omitted instruments are absent from the payload. The receiver
+             * leaves its existing state for those instruments untouched (the
+             * receiver's `applyInstrumentPayload` skips missing keys). Default =
+             * all three.
+             *
+             * Cross-device commits should typically scope to the just-completed
+             * instrument (e.g. `exportSessionState({ instruments: [ev.instrument] })`
+             * inside an `onSessionEnd` handler) so the receiver's unrelated
+             * instrument state isn't inadvertently overwritten by the sender's
+             * default values.
              */
-            exportSessionState: () => SerializedOnsetState;
+            exportSessionState: (options?: {
+                instruments?: ReadonlyArray<"kick" | "snare" | "hat">;
+            }) => 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.
+             * Mutation is synchronous.
+             *
+             * Field-level events fire when imported values differ from current:
+             * `onModeChange` if the imported mode is different, `onMuteChange` if
+             * the imported muted state is different. Session-boundary events
+             * (`onSessionEnd`) do NOT fire — imports aren't session boundaries.
              *
              * Patterns are rebased forward by whole pattern cycles to eliminate
              * the catch-up burst that would otherwise occur on stale payloads

package/dist/index.js

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

package/package.json

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