@viji-dev/core 0.5.2 → 0.5.3

package/dist/index.d.ts

@@ -2244,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.2";
+export declare const VERSION = "0.5.3";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2884,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.
@@ -3041,36 +3045,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.
              */
@@ -3086,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-B8LJ9m47.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.2",
+  "version": "0.5.3",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",