@viji-dev/core 0.5.2 → 0.5.4

package/dist/{index-B8LJ9m47.js → index-_PbbZgmh.js}

@@ -1897,7 +1897,7 @@ class EssentiaOnsetDetection {
     this.initPromise = (async () => {
       try {
         const essentiaModule = await import("./essentia.js-core.es-DnrJE0uR.js");
-        const wasmModule = await import("./essentia-wasm.web-DE6gem4m.js").then((n) => n.e);
+        const wasmModule = await import("./essentia-wasm.web-aU6UPupF.js").then((n) => n.e);
         const EssentiaClass = essentiaModule.Essentia || essentiaModule.default?.Essentia || essentiaModule.default;
         let WASMModule = wasmModule.default || wasmModule.EssentiaWASM || wasmModule.default?.EssentiaWASM;
         if (!WASMModule) {
@@ -6179,33 +6179,46 @@ class OnsetTapManager {
   modeChangeListeners = /* @__PURE__ */ new Set();
   sessionEndListeners = /* @__PURE__ */ new Set();
   muteChangeListeners = /* @__PURE__ */ new Set();
-  suppressEmissions = false;
-  tap(instrument) {
+  /**
+   * Record a tap on `instrument`. Drives the visual envelope, advances
+   * `lastTapTime`, and (by default) feeds the pattern-recognition pipeline.
+   *
+   * `options.skipRecognition: true` retains the visual side and session-timer
+   * scheduling but bypasses the recognition pipeline (no `tapIOIs` push,
+   * no `tryRecognizePattern`, no `applyPattern`, no `handlePatternTap`).
+   * Mode stays whatever it was. Useful for host-side relay of forwarded
+   * controller-tap messages where another instance is doing the
+   * authoritative recognition. The `MIN_TAP_INTERVAL_MS` debounce still
+   * applies (visual rate-limit).
+   */
+  tap(instrument, options) {
     const s = this.state[instrument];
     const now = performance.now();
+    const skipRecognition = options?.skipRecognition === true;
     if (s.muted) {
       s.muted = false;
       s.mutedAt = 0;
-      if (!this.suppressEmissions) {
-        this.fireMuteChange({ instrument, prevMuted: true, muted: false });
-      }
+      this.fireMuteChange({ instrument, prevMuted: true, muted: false });
     }
     let ioi = -1;
     if (s.lastTapTime > 0) {
       ioi = now - s.lastTapTime;
       if (ioi < MIN_TAP_INTERVAL_MS) return;
-      if (ioi > MAX_TAP_INTERVAL_MS) {
-        s.tapIOIs = [];
-        ioi = -1;
-      } else {
-        s.tapIOIs.push(ioi);
-        if (s.tapIOIs.length > MAX_TAP_HISTORY) s.tapIOIs.shift();
+      if (!skipRecognition) {
+        if (ioi > MAX_TAP_INTERVAL_MS) {
+          s.tapIOIs = [];
+          ioi = -1;
+        } else {
+          s.tapIOIs.push(ioi);
+          if (s.tapIOIs.length > MAX_TAP_HISTORY) s.tapIOIs.shift();
+        }
       }
     }
     s.lastTapTime = now;
     s.pendingTapEvents.push(now);
     s.sessionActive = true;
     this.scheduleSessionTimers(instrument);
+    if (skipRecognition) return;
     if (s.mode === "auto") {
       this.setMode(instrument, "tapping");
       if (ioi > 0) {
@@ -6241,7 +6254,7 @@ class OnsetTapManager {
     s.pendingTapEvents = [];
     s.envelope.reset();
     s.envelopeSmoothed.reset();
-    if (prevMuted && !this.suppressEmissions) {
+    if (prevMuted) {
       this.fireMuteChange({ instrument, prevMuted: true, muted: false });
     }
   }
@@ -6273,9 +6286,7 @@ class OnsetTapManager {
         s.lastTapTime += pauseDuration;
       }
     }
-    if (!this.suppressEmissions) {
-      this.fireMuteChange({ instrument, prevMuted, muted: s.muted });
-    }
+    this.fireMuteChange({ instrument, prevMuted, muted: s.muted });
   }
   isMuted(instrument) {
     return this.state[instrument].muted;
@@ -6307,16 +6318,27 @@ class OnsetTapManager {
   /**
    * Serialize per-instrument onset state for cross-instance transfer.
    * Wall-clock fields are in this instance's `performance.now()` clock space.
+   *
+   * `options.instruments` scopes the output to the listed instruments only;
+   * omitted instruments are absent from the payload (the receiver's
+   * `applyInstrumentPayload` skips missing keys, leaving the receiver's
+   * existing state for those instruments untouched). Default = all three —
+   * the full-state-transfer used for same-process scene-switch.
+   *
+   * Cross-device commits should typically scope to the just-completed
+   * instrument so an unrelated instrument's state on the receiver isn't
+   * inadvertently overwritten.
    */
-  exportSessionState() {
+  exportSessionState(options) {
+    const list = options?.instruments ?? INSTRUMENTS;
+    const instruments = {};
+    for (const inst of list) {
+      instruments[inst] = this.serializeInstrument(inst);
+    }
     return {
       version: STATE_SCHEMA_VERSION,
       senderTime: performance.now(),
-      instruments: {
-        kick: this.serializeInstrument("kick"),
-        snare: this.serializeInstrument("snare"),
-        hat: this.serializeInstrument("hat")
-      }
+      instruments
     };
   }
   /**
@@ -6330,22 +6352,22 @@ class OnsetTapManager {
    * is older than one pattern period (phase-preserving — events still land on
    * the original beat positions modulo `patternSum`).
    *
-   * Mutation is synchronous; no events are emitted (state replacement is not
-   * a transition). Throws nothing — malformed payloads should be filtered by
-   * the caller via the `version` field.
+   * Mutation is synchronous. Field-level events (`onModeChange`,
+   * `onMuteChange`) fire when an imported value differs from the current one
+   * — consumer-visible state is consistent with what polling would have
+   * observed. Session-boundary events (`onSessionEnd`) do NOT fire on
+   * import; imports are state replacement, not session boundaries.
+   *
+   * Throws nothing — malformed payloads should be filtered by the caller
+   * via the `version` field.
    */
   importSessionState(state, clockOffset) {
     if (state.version !== STATE_SCHEMA_VERSION) return;
-    this.suppressEmissions = true;
-    try {
-      const now = performance.now();
-      for (const inst of INSTRUMENTS) {
-        const payload = state.instruments[inst];
-        if (!payload) continue;
-        this.applyInstrumentPayload(inst, payload, clockOffset, now);
-      }
-    } finally {
-      this.suppressEmissions = false;
+    const now = performance.now();
+    for (const inst of INSTRUMENTS) {
+      const payload = state.instruments[inst];
+      if (!payload) continue;
+      this.applyInstrumentPayload(inst, payload, clockOffset, now);
     }
   }
   /**
@@ -6482,18 +6504,16 @@ class OnsetTapManager {
   // Private helpers
   // ---------------------------------------------------------------------------
   /**
-   * Single mutation point for `s.mode`. Fires `onModeChange` (when not
-   * suppressed) so listeners stay consistent regardless of which code path
-   * triggered the transition.
+   * Single mutation point for `s.mode`. Fires `onModeChange` so listeners
+   * stay consistent regardless of which code path triggered the transition
+   * (including imports, which fire via `applyInstrumentPayload` directly).
    */
   setMode(instrument, newMode) {
     const s = this.state[instrument];
     const prevMode = s.mode;
     if (prevMode === newMode) return;
     s.mode = newMode;
-    if (!this.suppressEmissions) {
-      this.fireModeChange({ instrument, prevMode, newMode });
-    }
+    this.fireModeChange({ instrument, prevMode, newMode });
   }
   fireModeChange(ev) {
     for (const listener of this.modeChangeListeners) {
@@ -6612,6 +6632,8 @@ class OnsetTapManager {
   }
   applyInstrumentPayload(instrument, payload, clockOffset, now) {
     const s = this.state[instrument];
+    const prevMode = s.mode;
+    const prevMuted = s.muted;
     this.cancelSessionTimers(s);
     s.sessionActive = false;
     const translatedReplayLast = payload.replayLastEventTime !== null ? payload.replayLastEventTime + clockOffset : 0;
@@ -6628,7 +6650,6 @@ class OnsetTapManager {
         }
       }
     }
-    s.mode;
     s.mode = payload.mode;
     s.muted = payload.muted;
     s.mutedAt = translatedMutedAt;
@@ -6642,6 +6663,12 @@ class OnsetTapManager {
     s.pendingTapEvents = [];
     s.envelope.reset();
     s.envelopeSmoothed.reset();
+    if (s.mode !== prevMode) {
+      this.fireModeChange({ instrument, prevMode, newMode: s.mode });
+    }
+    if (s.muted !== prevMuted) {
+      this.fireMuteChange({ instrument, prevMuted, muted: s.muted });
+    }
   }
   /**
    * Handle a tap that arrives while already in pattern mode.
@@ -8497,10 +8524,13 @@ class AudioSystem {
   // Public API Methods for Audio Analysis Configuration
   // ═══════════════════════════════════════════════════════════
   /**
-   * 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) {
-    this.onsetTapManager.tap(instrument);
+  tapOnset(instrument, options) {
+    this.onsetTapManager.tap(instrument, options);
   }
   /**
    * Clear tap pattern for an instrument, restoring auto-detection
@@ -8550,8 +8580,8 @@ class AudioSystem {
   // audio block is for same-process scene-switch transfer (sender's audio
   // analysis state would corrupt receiver's tracking on a different source).
   // ─────────────────────────────────────────────────────────────────────────
-  exportOnsetSessionState() {
-    return this.onsetTapManager.exportSessionState();
+  exportOnsetSessionState(options) {
+    return this.onsetTapManager.exportSessionState(options);
   }
   importOnsetSessionState(state, clockOffset) {
     this.onsetTapManager.importSessionState(state, clockOffset);
@@ -10671,8 +10701,12 @@ 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.
@@ -11104,10 +11138,21 @@ 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) => {
+      tap: (instrument, options) => {
         this.validateReady();
-        this.audioSystem?.tapOnset(instrument);
+        this.audioSystem?.tapOnset(instrument, options);
       },
       /**
        * Clear the tap pattern for an instrument, restoring auto-detection
@@ -11148,9 +11193,13 @@ class VijiCore {
       },
       /**
        * 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.
        */
@@ -11160,14 +11209,20 @@ class VijiCore {
         });
       },
       /**
-       * 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.
        */
@@ -11178,14 +11233,15 @@ class VijiCore {
       },
       /**
        * 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.
        */
@@ -11199,10 +11255,22 @@ 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: () => {
+      exportSessionState: (options) => {
         this.validateReady();
-        return this.audioSystem?.exportOnsetSessionState() ?? {
+        return this.audioSystem?.exportOnsetSessionState(options) ?? {
           version: 1,
           senderTime: performance.now(),
           instruments: {}
@@ -11212,7 +11280,12 @@ class VijiCore {
        * 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
@@ -11629,7 +11702,7 @@ function validateCoreStatePayload(state) {
   }
   return null;
 }
-const VERSION = "0.5.2";
+const VERSION = "0.5.4";
 export {
   AudioSystem as A,
   VERSION as V,
@@ -11637,4 +11710,4 @@ export {
   VijiCoreError as b,
   getDefaultExportFromCjs as g
 };
-//# sourceMappingURL=index-B8LJ9m47.js.map
+//# sourceMappingURL=index-_PbbZgmh.js.map