@viji-dev/core 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -466,6 +466,7 @@ export declare class AudioSystem {
     isOnsetMuted(instrument: InstrumentType): boolean;
     onOnsetModeChange(listener: (ev: OnsetModeChangeEvent) => void): Unsubscribe;
     onOnsetSessionEnd(listener: (ev: OnsetSessionEndEvent) => void): Unsubscribe;
+    onOnsetMuteChange(listener: (ev: OnsetMuteChangeEvent) => void): Unsubscribe;
     exportOnsetSessionState(): SerializedOnsetState;
     importOnsetSessionState(state: SerializedOnsetState, clockOffset: number): void;
     exportAudioAnalysisState(): SerializedAudioAnalysisState;
@@ -1455,6 +1456,12 @@ export declare interface OnsetModeChangeEvent {
     newMode: OnsetMode;
 }
 
+export declare interface OnsetMuteChangeEvent {
+    instrument: OnsetInstrument;
+    prevMuted: boolean;
+    muted: boolean;
+}
+
 export declare interface OnsetSessionEndEvent {
     instrument: OnsetInstrument;
     /**
@@ -2237,7 +2244,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.1";
+export declare const VERSION = "0.5.3";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2877,8 +2884,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.
@@ -3034,26 +3045,51 @@ 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 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.
+             *
+             * @returns Unsubscribe function. Call to remove the listener.
+             */
+            onMuteChange: (listener: (ev: OnsetMuteChangeEvent) => void) => Unsubscribe;
             /**
              * Snapshot per-instrument onset state for cross-instance transfer.
              * Cross-device-safe (no audio analysis state included). Pair with
@@ -3065,7 +3101,12 @@ export declare 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

package/dist/index.js

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

package/package.json

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