@viji-dev/core 0.5.0 → 0.5.2

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

@@ -640,7 +640,7 @@ class IFrameManager {
     }
   }
 }
-const workerUrl = "" + new URL("assets/viji.worker-CWKkFyOs.js", import.meta.url).href;
+const workerUrl = "" + new URL("assets/viji.worker-DwYMDyfQ.js", import.meta.url).href;
 const simdLoaderJs = new URL("assets/wasm/vision_wasm_internal.js", import.meta.url).href;
 const simdBinary = new URL("assets/wasm/vision_wasm_internal.wasm", import.meta.url).href;
 const nosimdLoaderJs = new URL("assets/wasm/vision_wasm_nosimd_internal.js", import.meta.url).href;
@@ -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-CmPC-AKu.js").then((n) => n.e);
+        const wasmModule = await import("./essentia-wasm.web-DE6gem4m.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) {
@@ -3558,10 +3558,20 @@ class TempoInduction {
   setDebugMode(_enabled) {
   }
   /**
-   * Reset tempo detection state
+   * Reset tempo detection state.
+   *
+   * Note on coverage: this clears every mutable runtime field that affects
+   * subsequent detection. Earlier versions of `reset()` missed several fields
+   * (per-band envelopes, onset history, grid-lock, warmup, fpsEstimate); they
+   * are included here for correctness — without them, a re-used instance
+   * could carry stale signal-history into a fresh detection session.
    */
   reset() {
     this.onsetEnvelope = [];
+    this.lowBandEnvelope = [];
+    this.midBandEnvelope = [];
+    this.highBandEnvelope = [];
+    this.fpsEstimate = 60;
     this.currentBPM = 120;
     this.confidence = 0;
     this.method = "autocorr";
@@ -3574,6 +3584,107 @@ class TempoInduction {
     this.bpmDriftHistory = [];
     this.driftRate = 0;
     this.tempoChangeConfirmCount = 0;
+    this.onsetHistory = [];
+    this.gridLockBPM = null;
+    this.gridLockScore = 0;
+    this.gridLockTime = 0;
+    this.gridLockMemoryBPM = null;
+    this.gridLockMemoryTime = 0;
+    this.syncopationLevel = 0;
+    this.warmupStartTimeMs = 0;
+    this.warmupComplete = false;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // State serialization (for VijiCore.exportFullState same-process transfer)
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Snapshot continuity-relevant runtime state. Wall-clock fields are in
+   * this instance's `performance.now()` clock space.
+   */
+  exportSessionState() {
+    return {
+      onsetEnvelope: [...this.onsetEnvelope],
+      lowBandEnvelope: [...this.lowBandEnvelope],
+      midBandEnvelope: [...this.midBandEnvelope],
+      highBandEnvelope: [...this.highBandEnvelope],
+      fpsEstimate: this.fpsEstimate,
+      currentBPM: this.currentBPM,
+      confidence: this.confidence,
+      method: this.method,
+      anchorBand: this.anchorBand,
+      methodAgreement: this.methodAgreement,
+      bpmHistory: [...this.bpmHistory],
+      lastUpdateTime: this.lastUpdateTime > 0 ? this.lastUpdateTime : null,
+      hypotheses: this.hypotheses.map((h) => ({
+        bpm: h.bpm,
+        likelihood: h.likelihood,
+        age: h.age,
+        lastEvidence: h.lastEvidence,
+        type: h.type
+      })),
+      inTransition: this.inTransition,
+      bpmDriftHistory: this.bpmDriftHistory.map((e) => ({ time: e.time, bpm: e.bpm })),
+      driftRate: this.driftRate,
+      tempoChangeConfirmCount: this.tempoChangeConfirmCount,
+      onsetHistory: this.onsetHistory.map((e) => ({
+        time: e.time,
+        strength: e.strength,
+        type: e.type
+      })),
+      gridLockBPM: this.gridLockBPM,
+      gridLockScore: this.gridLockScore,
+      gridLockTime: this.gridLockTime,
+      gridLockMemoryBPM: this.gridLockMemoryBPM,
+      gridLockMemoryTime: this.gridLockMemoryTime,
+      syncopationLevel: this.syncopationLevel,
+      warmupStartTimeMs: this.warmupStartTimeMs,
+      warmupComplete: this.warmupComplete
+    };
+  }
+  /**
+   * Replace runtime state from a serialized snapshot. `clockOffset` is added
+   * to all wall-clock fields (zero / null sentinels are left untranslated).
+   */
+  importSessionState(state, clockOffset) {
+    this.onsetEnvelope = [...state.onsetEnvelope];
+    this.lowBandEnvelope = [...state.lowBandEnvelope];
+    this.midBandEnvelope = [...state.midBandEnvelope];
+    this.highBandEnvelope = [...state.highBandEnvelope];
+    this.fpsEstimate = state.fpsEstimate;
+    this.currentBPM = state.currentBPM;
+    this.confidence = state.confidence;
+    this.method = state.method;
+    this.anchorBand = state.anchorBand;
+    this.methodAgreement = state.methodAgreement;
+    this.bpmHistory = [...state.bpmHistory];
+    this.lastUpdateTime = state.lastUpdateTime !== null ? state.lastUpdateTime + clockOffset : 0;
+    this.hypotheses = state.hypotheses.map((h) => ({
+      bpm: h.bpm,
+      likelihood: h.likelihood,
+      age: h.age,
+      lastEvidence: h.lastEvidence + clockOffset,
+      type: h.type
+    }));
+    this.inTransition = state.inTransition;
+    this.bpmDriftHistory = state.bpmDriftHistory.map((e) => ({
+      time: e.time + clockOffset,
+      bpm: e.bpm
+    }));
+    this.driftRate = state.driftRate;
+    this.tempoChangeConfirmCount = state.tempoChangeConfirmCount;
+    this.onsetHistory = state.onsetHistory.map((e) => ({
+      time: e.time + clockOffset,
+      strength: e.strength,
+      type: e.type
+    }));
+    this.gridLockBPM = state.gridLockBPM;
+    this.gridLockScore = state.gridLockScore;
+    this.gridLockTime = state.gridLockTime > 0 ? state.gridLockTime + clockOffset : 0;
+    this.gridLockMemoryBPM = state.gridLockMemoryBPM;
+    this.gridLockMemoryTime = state.gridLockMemoryTime > 0 ? state.gridLockMemoryTime + clockOffset : 0;
+    this.syncopationLevel = state.syncopationLevel;
+    this.warmupStartTimeMs = state.warmupStartTimeMs > 0 ? state.warmupStartTimeMs + clockOffset : 0;
+    this.warmupComplete = state.warmupComplete;
   }
   /**
    * Get detailed debug info for testing/debugging
@@ -4093,6 +4204,75 @@ class PhaseLockedLoop {
     this.phaseOffsetCalibrated = 0;
     this.lastCalibrationTime = 0;
   }
+  // ─────────────────────────────────────────────────────────────────────────
+  // State serialization (for VijiCore.exportFullState same-process transfer)
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Snapshot continuity-relevant runtime state. Wall-clock fields are in this
+   * instance's `performance.now()` clock space; receiver translates by
+   * `clockOffset` on import.
+   */
+  exportSessionState() {
+    return {
+      phase: this.phase,
+      lastBeatTime: this.lastBeatTime,
+      periodMs: this.periodMs,
+      trackedBPM: this.trackedBPM,
+      beatCounter: this.beatCounter,
+      lastOnsetTime: this.lastOnsetTime,
+      bpmHistory: this.bpmHistory.map((e) => ({ time: e.time, bpm: e.bpm })),
+      driftRate: this.driftRate,
+      inBreakdown: this.inBreakdown,
+      tempoConfidence: this.tempoConfidence,
+      inTransition: this.inTransition,
+      currentGain: this.currentGain,
+      lastBarAdvanceTime: this.lastBarAdvanceTime,
+      pendingBarAdvance: this.pendingBarAdvance,
+      lastPhaseWrapTime: this.lastPhaseWrapTime,
+      consecutiveAlignedKicks: this.consecutiveAlignedKicks,
+      lastHardSyncTime: this.lastHardSyncTime,
+      trackingStartTime: this.trackingStartTime,
+      kickPhaseHistory: [...this.kickPhaseHistory],
+      phaseOffsetCalibrated: this.phaseOffsetCalibrated,
+      lastCalibrationTime: this.lastCalibrationTime,
+      lastPhaseError: this.lastPhaseError
+    };
+  }
+  /**
+   * Replace runtime state from a serialized snapshot. `clockOffset` is added
+   * to all wall-clock fields (zero values are treated as "never set" sentinels
+   * and left at zero — same convention as `reset()`).
+   */
+  importSessionState(state, clockOffset) {
+    this.phase = state.phase;
+    this.lastBeatTime = translateTimestamp$1(state.lastBeatTime, clockOffset);
+    this.periodMs = state.periodMs;
+    this.trackedBPM = state.trackedBPM;
+    this.beatCounter = state.beatCounter;
+    this.lastOnsetTime = translateTimestamp$1(state.lastOnsetTime, clockOffset);
+    this.bpmHistory = state.bpmHistory.map((e) => ({
+      time: translateTimestamp$1(e.time, clockOffset),
+      bpm: e.bpm
+    }));
+    this.driftRate = state.driftRate;
+    this.inBreakdown = state.inBreakdown;
+    this.tempoConfidence = state.tempoConfidence;
+    this.inTransition = state.inTransition;
+    this.currentGain = state.currentGain;
+    this.lastBarAdvanceTime = translateTimestamp$1(state.lastBarAdvanceTime, clockOffset);
+    this.pendingBarAdvance = state.pendingBarAdvance;
+    this.lastPhaseWrapTime = translateTimestamp$1(state.lastPhaseWrapTime, clockOffset);
+    this.consecutiveAlignedKicks = state.consecutiveAlignedKicks;
+    this.lastHardSyncTime = translateTimestamp$1(state.lastHardSyncTime, clockOffset);
+    this.trackingStartTime = translateTimestamp$1(state.trackingStartTime, clockOffset);
+    this.kickPhaseHistory = [...state.kickPhaseHistory];
+    this.phaseOffsetCalibrated = state.phaseOffsetCalibrated;
+    this.lastCalibrationTime = translateTimestamp$1(state.lastCalibrationTime, clockOffset);
+    this.lastPhaseError = state.lastPhaseError;
+  }
+}
+function translateTimestamp$1(t, clockOffset) {
+  return t > 0 ? t + clockOffset : 0;
 }
 const FAST_WINDOW_MS = 2e3;
 const MEDIUM_WINDOW_MS = 1e4;
@@ -5437,7 +5617,12 @@ class BeatStateManager {
     return this.state === "LOCKED" || this.state === "BREAKDOWN";
   }
   /**
-   * Reset all state
+   * Reset all state.
+   *
+   * Coverage extended over earlier versions to also clear: per-class
+   * cooldown/rate-cap state, kick interval/BPM history, onset-strength
+   * tracking, band-energy history. Without these, a re-used instance
+   * would carry stale signal-history into a fresh detection session.
    */
   reset() {
     this.state = "TRACKING";
@@ -5450,6 +5635,7 @@ class BeatStateManager {
     this.recentGridScores = [];
     this.lockedBPM = 120;
     this.lastOnsetTime = 0;
+    this.lastKickTime = 0;
     this.eventBuffer = [];
     Object.values(this.envelopes).forEach((env) => env.reset());
     this.debugKickCount = 0;
@@ -5460,6 +5646,153 @@ class BeatStateManager {
       snare: { intervals: [], lastOnsetTime: 0 },
       hat: { intervals: [], lastOnsetTime: 0 }
     };
+    this.recentOnsetStrengths = [];
+    this.averageOnsetStrength = 0.5;
+    this.kickIntervals = [];
+    this.bpmHistory = [];
+    this.bandEnergyHistory = { low: [], mid: [], high: [] };
+    this.eventTimestamps = { kick: [], snare: [], hat: [] };
+    this.lastEventTime = { kick: 0, snare: 0, hat: 0 };
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // State serialization (for VijiCore.exportFullState same-process transfer)
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Snapshot continuity-relevant runtime state. Wall-clock fields are in
+   * this instance's `performance.now()` clock space. Envelope follower state
+   * is intentionally omitted — receiver re-triggers envelopes naturally as
+   * detected events flow.
+   */
+  exportSessionState() {
+    return {
+      state: this.state,
+      stateEnteredTime: this.stateEnteredTime,
+      kickProfile: { ...this.kickProfile },
+      snareProfile: { ...this.snareProfile },
+      hatProfile: { ...this.hatProfile },
+      recentOnsetStrengths: [...this.recentOnsetStrengths],
+      averageOnsetStrength: this.averageOnsetStrength,
+      tempoMethodAgreement: this.tempoMethodAgreement,
+      gridScore: this.gridScore,
+      consistencyScore: this.consistencyScore,
+      anchorClarity: this.anchorClarity,
+      recentGridScores: [...this.recentGridScores],
+      lockedBPM: this.lockedBPM,
+      lastOnsetTime: this.lastOnsetTime,
+      lastKickTime: this.lastKickTime,
+      kickIntervals: [...this.kickIntervals],
+      bpmHistory: [...this.bpmHistory],
+      adaptiveProfiles: {
+        kick: { samples: this.adaptiveProfiles.kick.samples.map((s) => ({ ...s })) },
+        snareIndependent: { samples: this.adaptiveProfiles.snareIndependent.samples.map((s) => ({ ...s })) },
+        snareLayered: { samples: this.adaptiveProfiles.snareLayered.samples.map((s) => ({ ...s })) },
+        hatIndependent: { samples: this.adaptiveProfiles.hatIndependent.samples.map((s) => ({ ...s })) },
+        hatLayered: { samples: this.adaptiveProfiles.hatLayered.samples.map((s) => ({ ...s })) }
+      },
+      adaptiveThresholds: {
+        snareMinMidRatio: this.adaptiveThresholds.snareMinMidRatio,
+        snareMinMidToBass: this.adaptiveThresholds.snareMinMidToBass,
+        kickMaxMidRatio: this.adaptiveThresholds.kickMaxMidRatio,
+        snareIndependent: { ...this.adaptiveThresholds.snareIndependent },
+        snareLayered: { ...this.adaptiveThresholds.snareLayered },
+        hatIndependent: { ...this.adaptiveThresholds.hatIndependent },
+        hatLayered: { ...this.adaptiveThresholds.hatLayered }
+      },
+      ioiTrackers: {
+        kick: { intervals: [...this.ioiTrackers.kick.intervals], lastOnsetTime: this.ioiTrackers.kick.lastOnsetTime },
+        snare: { intervals: [...this.ioiTrackers.snare.intervals], lastOnsetTime: this.ioiTrackers.snare.lastOnsetTime },
+        hat: { intervals: [...this.ioiTrackers.hat.intervals], lastOnsetTime: this.ioiTrackers.hat.lastOnsetTime }
+      },
+      eventBuffer: this.eventBuffer.map((e) => ({
+        event: { ...e.event },
+        expiresAt: e.expiresAt
+      })),
+      bandEnergyHistory: {
+        low: this.bandEnergyHistory.low.map((e) => ({ ...e })),
+        mid: this.bandEnergyHistory.mid.map((e) => ({ ...e })),
+        high: this.bandEnergyHistory.high.map((e) => ({ ...e }))
+      },
+      eventTimestamps: {
+        kick: [...this.eventTimestamps.kick],
+        snare: [...this.eventTimestamps.snare],
+        hat: [...this.eventTimestamps.hat]
+      },
+      lastEventTime: { ...this.lastEventTime }
+    };
+  }
+  /**
+   * Replace runtime state from a serialized snapshot. `clockOffset` is added
+   * to all wall-clock fields (zero values are treated as "never set" sentinels
+   * and left at zero). Envelopes are NOT restored; they re-trigger from
+   * subsequent events.
+   */
+  importSessionState(state, clockOffset) {
+    this.state = state.state;
+    this.stateEnteredTime = translateTimestamp(state.stateEnteredTime, clockOffset);
+    this.kickProfile = { ...state.kickProfile };
+    this.snareProfile = { ...state.snareProfile };
+    this.hatProfile = { ...state.hatProfile };
+    this.recentOnsetStrengths = [...state.recentOnsetStrengths];
+    this.averageOnsetStrength = state.averageOnsetStrength;
+    this.tempoMethodAgreement = state.tempoMethodAgreement;
+    this.gridScore = state.gridScore;
+    this.consistencyScore = state.consistencyScore;
+    this.anchorClarity = state.anchorClarity;
+    this.recentGridScores = [...state.recentGridScores];
+    this.lockedBPM = state.lockedBPM;
+    this.lastOnsetTime = translateTimestamp(state.lastOnsetTime, clockOffset);
+    this.lastKickTime = translateTimestamp(state.lastKickTime, clockOffset);
+    this.kickIntervals = [...state.kickIntervals];
+    this.bpmHistory = [...state.bpmHistory];
+    this.adaptiveProfiles = {
+      kick: { samples: state.adaptiveProfiles.kick.samples.map((s) => ({ ...s, time: s.time + clockOffset })) },
+      snareIndependent: { samples: state.adaptiveProfiles.snareIndependent.samples.map((s) => ({ ...s, time: s.time + clockOffset })) },
+      snareLayered: { samples: state.adaptiveProfiles.snareLayered.samples.map((s) => ({ ...s, time: s.time + clockOffset })) },
+      hatIndependent: { samples: state.adaptiveProfiles.hatIndependent.samples.map((s) => ({ ...s, time: s.time + clockOffset })) },
+      hatLayered: { samples: state.adaptiveProfiles.hatLayered.samples.map((s) => ({ ...s, time: s.time + clockOffset })) }
+    };
+    this.adaptiveThresholds = {
+      snareMinMidRatio: state.adaptiveThresholds.snareMinMidRatio,
+      snareMinMidToBass: state.adaptiveThresholds.snareMinMidToBass,
+      kickMaxMidRatio: state.adaptiveThresholds.kickMaxMidRatio,
+      snareIndependent: { ...state.adaptiveThresholds.snareIndependent },
+      snareLayered: { ...state.adaptiveThresholds.snareLayered },
+      hatIndependent: { ...state.adaptiveThresholds.hatIndependent },
+      hatLayered: { ...state.adaptiveThresholds.hatLayered }
+    };
+    this.ioiTrackers = {
+      kick: {
+        intervals: [...state.ioiTrackers.kick.intervals],
+        lastOnsetTime: translateTimestamp(state.ioiTrackers.kick.lastOnsetTime, clockOffset)
+      },
+      snare: {
+        intervals: [...state.ioiTrackers.snare.intervals],
+        lastOnsetTime: translateTimestamp(state.ioiTrackers.snare.lastOnsetTime, clockOffset)
+      },
+      hat: {
+        intervals: [...state.ioiTrackers.hat.intervals],
+        lastOnsetTime: translateTimestamp(state.ioiTrackers.hat.lastOnsetTime, clockOffset)
+      }
+    };
+    this.eventBuffer = state.eventBuffer.map((e) => ({
+      event: { ...e.event, time: e.event.time + clockOffset },
+      expiresAt: e.expiresAt + clockOffset
+    }));
+    this.bandEnergyHistory = {
+      low: state.bandEnergyHistory.low.map((e) => ({ time: e.time + clockOffset, value: e.value })),
+      mid: state.bandEnergyHistory.mid.map((e) => ({ time: e.time + clockOffset, value: e.value })),
+      high: state.bandEnergyHistory.high.map((e) => ({ time: e.time + clockOffset, value: e.value }))
+    };
+    this.eventTimestamps = {
+      kick: state.eventTimestamps.kick.map((t) => t + clockOffset),
+      snare: state.eventTimestamps.snare.map((t) => t + clockOffset),
+      hat: state.eventTimestamps.hat.map((t) => t + clockOffset)
+    };
+    this.lastEventTime = {
+      kick: translateTimestamp(state.lastEventTime.kick, clockOffset),
+      snare: translateTimestamp(state.lastEventTime.snare, clockOffset),
+      hat: translateTimestamp(state.lastEventTime.hat, clockOffset)
+    };
   }
   /**
    * Enable/disable enhanced debug mode for comprehensive testing
@@ -5474,6 +5807,9 @@ class BeatStateManager {
   printSummary(durationSec) {
   }
 }
+function translateTimestamp(t, clockOffset) {
+  return t > 0 ? t + clockOffset : 0;
+}
 class DiagnosticLogger {
   events = [];
   sessionStart = 0;
@@ -5804,6 +6140,7 @@ Rejection rate: ${(rejections / duration * 60).toFixed(1)} per minute
 const INSTRUMENTS = ["kick", "snare", "hat"];
 const SAMPLE_RATE = 60;
 const TAP_TIMEOUT_MS = 5e3;
+const SESSION_END_IDLE_MS = 500;
 const MAX_CYCLE_LENGTH = 8;
 const FUZZY_TOLERANCE = 0.18;
 const MIN_REPETITIONS = 3;
@@ -5812,6 +6149,7 @@ const MIN_TAP_INTERVAL_MS = 100;
 const MAX_TAP_HISTORY = 64;
 const MIN_EMA_ALPHA = 0.05;
 const PATTERN_SAME_TOLERANCE = 0.15;
+const STATE_SCHEMA_VERSION = 1;
 function createInstrumentState() {
   return {
     mode: "auto",
@@ -5826,7 +6164,10 @@ function createInstrumentState() {
     replayIndex: 0,
     pendingTapEvents: [],
     envelope: new EnvelopeFollower(0, 300, SAMPLE_RATE),
-    envelopeSmoothed: new EnvelopeFollower(5, 500, SAMPLE_RATE)
+    envelopeSmoothed: new EnvelopeFollower(5, 500, SAMPLE_RATE),
+    sessionActive: false,
+    sessionEndTimer: null,
+    tapTimeoutTimer: null
   };
 }
 class OnsetTapManager {
@@ -5835,12 +6176,19 @@ class OnsetTapManager {
     snare: createInstrumentState(),
     hat: createInstrumentState()
   };
+  modeChangeListeners = /* @__PURE__ */ new Set();
+  sessionEndListeners = /* @__PURE__ */ new Set();
+  muteChangeListeners = /* @__PURE__ */ new Set();
+  suppressEmissions = false;
   tap(instrument) {
     const s = this.state[instrument];
     const now = performance.now();
     if (s.muted) {
       s.muted = false;
       s.mutedAt = 0;
+      if (!this.suppressEmissions) {
+        this.fireMuteChange({ instrument, prevMuted: true, muted: false });
+      }
     }
     let ioi = -1;
     if (s.lastTapTime > 0) {
@@ -5856,8 +6204,10 @@ class OnsetTapManager {
     }
     s.lastTapTime = now;
     s.pendingTapEvents.push(now);
+    s.sessionActive = true;
+    this.scheduleSessionTimers(instrument);
     if (s.mode === "auto") {
-      s.mode = "tapping";
+      this.setMode(instrument, "tapping");
       if (ioi > 0) {
         const pattern = this.tryRecognizePattern(instrument);
         if (pattern) this.applyPattern(instrument, pattern);
@@ -5875,7 +6225,10 @@ class OnsetTapManager {
   }
   clear(instrument) {
     const s = this.state[instrument];
-    s.mode = "auto";
+    const prevMuted = s.muted;
+    this.cancelSessionTimers(s);
+    s.sessionActive = false;
+    this.setMode(instrument, "auto");
     s.muted = false;
     s.mutedAt = 0;
     s.tapIOIs = [];
@@ -5888,6 +6241,9 @@ class OnsetTapManager {
     s.pendingTapEvents = [];
     s.envelope.reset();
     s.envelopeSmoothed.reset();
+    if (prevMuted && !this.suppressEmissions) {
+      this.fireMuteChange({ instrument, prevMuted: true, muted: false });
+    }
   }
   getMode(instrument) {
     return this.state[instrument].mode;
@@ -5904,6 +6260,7 @@ class OnsetTapManager {
   setMuted(instrument, muted) {
     const s = this.state[instrument];
     if (s.muted === muted) return;
+    const prevMuted = s.muted;
     const now = performance.now();
     if (muted) {
       s.muted = true;
@@ -5916,15 +6273,116 @@ class OnsetTapManager {
         s.lastTapTime += pauseDuration;
       }
     }
+    if (!this.suppressEmissions) {
+      this.fireMuteChange({ instrument, prevMuted, muted: s.muted });
+    }
   }
   isMuted(instrument) {
     return this.state[instrument].muted;
   }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Listener registration
+  // ─────────────────────────────────────────────────────────────────────────
+  onModeChange(listener) {
+    this.modeChangeListeners.add(listener);
+    return () => {
+      this.modeChangeListeners.delete(listener);
+    };
+  }
+  onSessionEnd(listener) {
+    this.sessionEndListeners.add(listener);
+    return () => {
+      this.sessionEndListeners.delete(listener);
+    };
+  }
+  onMuteChange(listener) {
+    this.muteChangeListeners.add(listener);
+    return () => {
+      this.muteChangeListeners.delete(listener);
+    };
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // State serialization
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Serialize per-instrument onset state for cross-instance transfer.
+   * Wall-clock fields are in this instance's `performance.now()` clock space.
+   */
+  exportSessionState() {
+    return {
+      version: STATE_SCHEMA_VERSION,
+      senderTime: performance.now(),
+      instruments: {
+        kick: this.serializeInstrument("kick"),
+        snare: this.serializeInstrument("snare"),
+        hat: this.serializeInstrument("hat")
+      }
+    };
+  }
+  /**
+   * Replace per-instrument state from a serialized payload. Wall-clock fields
+   * in the payload are translated by `clockOffset` (added to non-null sender
+   * timestamps to map them into the receiver's `performance.now()` clock).
+   * For same-process transfer, `clockOffset = 0`.
+   *
+   * `replayLastEventTime` is rebased forward by whole pattern cycles to
+   * eliminate the catch-up burst that would otherwise fire if the payload
+   * 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.
+   */
+  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;
+    }
+  }
+  /**
+   * Validate a serialized payload's shape before importing. Returns null on
+   * success or a `StateImportError` describing the first failure.
+   */
+  static validateOnsetPayload(state) {
+    if (state === null || typeof state !== "object") {
+      return { code: "malformed", details: "payload is not an object" };
+    }
+    const s = state;
+    if (s.version !== STATE_SCHEMA_VERSION) {
+      return {
+        code: "version-mismatch",
+        details: `expected version ${STATE_SCHEMA_VERSION}, got ${String(s.version)}`,
+        ...typeof s.version === "number" ? { payloadVersion: s.version } : {},
+        expectedVersion: STATE_SCHEMA_VERSION
+      };
+    }
+    if (typeof s.senderTime !== "number") {
+      return { code: "invalid-field", details: "senderTime must be a number", field: "senderTime" };
+    }
+    if (!s.instruments || typeof s.instruments !== "object") {
+      return { code: "invalid-field", details: "instruments must be an object", field: "instruments" };
+    }
+    return null;
+  }
   /**
    * Post-process a beat state produced by BeatStateManager.
    * For instruments in auto mode, values pass through unchanged.
    * For tapping/pattern instruments, auto events are suppressed and
    * tap/pattern events + envelopes are injected instead.
+   *
+   * Safe to call with an empty `beatState` (no audio frames available) —
+   * the host's idle ticker drives this in the no-audio scenario so the
+   * artist API receives tap-driven envelopes and events without an audio
+   * source.
    */
   processFrame(beatState, now, dtMs) {
     const result = { ...beatState, events: [...beatState.events] };
@@ -5964,11 +6422,11 @@ class OnsetTapManager {
           s.tapIOIs = [];
           s.pendingTapEvents = [];
           if (s.pattern) {
-            s.mode = "pattern";
+            this.setMode(inst, "pattern");
             s.replayLastEventTime = now;
             s.replayIndex = 0;
           } else {
-            s.mode = "auto";
+            this.setMode(inst, "auto");
           }
           continue;
         }
@@ -6023,6 +6481,168 @@ 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.
+   */
+  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 });
+    }
+  }
+  fireModeChange(ev) {
+    for (const listener of this.modeChangeListeners) {
+      try {
+        listener(ev);
+      } catch (err) {
+        console.error("Error in onModeChange listener:", err);
+      }
+    }
+  }
+  fireSessionEnd(ev) {
+    for (const listener of this.sessionEndListeners) {
+      try {
+        listener(ev);
+      } catch (err) {
+        console.error("Error in onSessionEnd listener:", err);
+      }
+    }
+  }
+  fireMuteChange(ev) {
+    for (const listener of this.muteChangeListeners) {
+      try {
+        listener(ev);
+      } catch (err) {
+        console.error("Error in onMuteChange listener:", err);
+      }
+    }
+  }
+  /**
+   * Schedule (or reschedule) the per-instrument session timers on every tap.
+   * 500ms timer fires `'pattern'` outcome if instrument is in pattern mode at
+   * fire time. 5s timer fires `'cleared'` outcome if a tapping session
+   * never reached pattern recognition. Either timer transitions mode if the
+   * audio-driven `processFrame` hasn't already done so (controller-side has
+   * no audio path).
+   */
+  scheduleSessionTimers(instrument) {
+    const s = this.state[instrument];
+    this.cancelSessionTimers(s);
+    s.sessionEndTimer = setTimeout(() => this.onSessionEndTimer(instrument), SESSION_END_IDLE_MS);
+    s.tapTimeoutTimer = setTimeout(() => this.onTapTimeoutTimer(instrument), TAP_TIMEOUT_MS);
+  }
+  cancelSessionTimers(s) {
+    if (s.sessionEndTimer !== null) {
+      clearTimeout(s.sessionEndTimer);
+      s.sessionEndTimer = null;
+    }
+    if (s.tapTimeoutTimer !== null) {
+      clearTimeout(s.tapTimeoutTimer);
+      s.tapTimeoutTimer = null;
+    }
+  }
+  /**
+   * 500ms idle timer. Fires `'pattern'` outcome iff the instrument is in
+   * `'pattern'` mode (meaning a recognized pattern survived the idle window).
+   * Other modes are handled by the 5s timer.
+   */
+  onSessionEndTimer(instrument) {
+    const s = this.state[instrument];
+    s.sessionEndTimer = null;
+    if (!s.sessionActive) return;
+    if (s.mode === "pattern" && s.pattern) {
+      s.sessionActive = false;
+      this.fireSessionEnd({ instrument, outcome: "pattern" });
+      if (s.tapTimeoutTimer !== null) {
+        clearTimeout(s.tapTimeoutTimer);
+        s.tapTimeoutTimer = null;
+      }
+    }
+  }
+  /**
+   * 5s tap-idle timer. Resolves the `'cleared'` outcome whether or not
+   * `processFrame` has already transitioned the mode (audio-active path can
+   * race ahead and transition `'tapping' → 'auto'` without firing the event;
+   * we detect that case via `sessionActive` and fire here regardless).
+   */
+  onTapTimeoutTimer(instrument) {
+    const s = this.state[instrument];
+    s.tapTimeoutTimer = null;
+    if (!s.sessionActive) return;
+    if (s.mode === "tapping") {
+      s.tapIOIs = [];
+      s.pendingTapEvents = [];
+      if (s.pattern) {
+        this.setMode(instrument, "pattern");
+        s.replayLastEventTime = performance.now();
+        s.replayIndex = 0;
+        s.sessionActive = false;
+        this.fireSessionEnd({ instrument, outcome: "pattern" });
+      } else {
+        this.setMode(instrument, "auto");
+        s.sessionActive = false;
+        this.fireSessionEnd({ instrument, outcome: "cleared" });
+      }
+    } else if (s.mode === "auto") {
+      s.sessionActive = false;
+      this.fireSessionEnd({ instrument, outcome: "cleared" });
+    } else {
+      s.sessionActive = false;
+    }
+  }
+  serializeInstrument(instrument) {
+    const s = this.state[instrument];
+    return {
+      mode: s.mode,
+      muted: s.muted,
+      pattern: s.pattern ? [...s.pattern] : null,
+      replayLastEventTime: s.replayLastEventTime > 0 ? s.replayLastEventTime : null,
+      replayIndex: s.replayIndex,
+      tapIOIs: [...s.tapIOIs],
+      lastTapTime: s.lastTapTime > 0 ? s.lastTapTime : null,
+      mutedAt: s.mutedAt > 0 ? s.mutedAt : null,
+      refinementIndex: s.refinementIndex,
+      refinementCounts: [...s.refinementCounts]
+    };
+  }
+  applyInstrumentPayload(instrument, payload, clockOffset, now) {
+    const s = this.state[instrument];
+    this.cancelSessionTimers(s);
+    s.sessionActive = false;
+    const translatedReplayLast = payload.replayLastEventTime !== null ? payload.replayLastEventTime + clockOffset : 0;
+    const translatedLastTap = payload.lastTapTime !== null ? payload.lastTapTime + clockOffset : 0;
+    const translatedMutedAt = payload.mutedAt !== null ? payload.mutedAt + clockOffset : 0;
+    let rebasedReplayLast = translatedReplayLast;
+    if (payload.pattern && payload.pattern.length > 0 && translatedReplayLast > 0) {
+      const patternSum = payload.pattern.reduce((a, b) => a + b, 0);
+      if (patternSum > 0) {
+        const elapsed = now - translatedReplayLast;
+        if (elapsed > patternSum) {
+          const cycles = Math.floor(elapsed / patternSum);
+          rebasedReplayLast = translatedReplayLast + cycles * patternSum;
+        }
+      }
+    }
+    s.mode;
+    s.mode = payload.mode;
+    s.muted = payload.muted;
+    s.mutedAt = translatedMutedAt;
+    s.tapIOIs = [...payload.tapIOIs];
+    s.lastTapTime = translatedLastTap;
+    s.pattern = payload.pattern ? [...payload.pattern] : null;
+    s.refinementIndex = payload.refinementIndex;
+    s.refinementCounts = [...payload.refinementCounts];
+    s.replayLastEventTime = rebasedReplayLast;
+    s.replayIndex = payload.replayIndex;
+    s.pendingTapEvents = [];
+    s.envelope.reset();
+    s.envelopeSmoothed.reset();
+  }
   /**
    * Handle a tap that arrives while already in pattern mode.
    * Matching taps refine the pattern via EMA and re-anchor phase.
@@ -6131,7 +6751,7 @@ class OnsetTapManager {
   applyPattern(instrument, pattern) {
     const s = this.state[instrument];
     s.pattern = pattern;
-    s.mode = "pattern";
+    this.setMode(instrument, "pattern");
     s.refinementIndex = 0;
     s.refinementCounts = new Array(pattern.length).fill(MIN_REPETITIONS);
     if (s.replayLastEventTime === 0 || s.replayLastEventTime < s.lastTapTime) {
@@ -6840,6 +7460,13 @@ class AudioSystem {
   beatDetectionEnabled = true;
   onsetDetectionEnabled = true;
   autoGainEnabled = true;
+  // Idle ticker — drives `OnsetTapManager.processFrame` via rAF when no audio
+  // is connected, so taps still produce envelope/event output through the
+  // artist API. Paused when audio connects (worklet/analyser path takes over);
+  // resumed on disconnect. See lifecycle methods below for the strict
+  // start-stop ordering invariant.
+  idleTickerHandle = null;
+  idleTickerLastTime = 0;
   /**
    * Enable or disable comprehensive debug logging for all layers
    * Enables enhanced logging in: MultiOnsetDetection, BeatStateManager
@@ -7304,7 +7931,10 @@ class AudioSystem {
   }
   // Analysis configuration
   fftSize = 2048;
-  // Beat state for main channel (not on AudioChannel because it's main-only)
+  // Beat state for main channel (not on AudioChannel because it's main-only).
+  // `bpm: 0` is the documented "no signal" sentinel; `runBeatPipeline`'s
+  // `lastNonZeroBpm` carry-over fills in a meaningful value as soon as audio
+  // is connected and the first BPM hypothesis is formed.
   audioStateBeat = {
     kick: 0,
     snare: 0,
@@ -7315,7 +7945,7 @@ class AudioSystem {
     hatSmoothed: 0,
     anySmoothed: 0,
     events: [],
-    bpm: 120,
+    bpm: 0,
     confidence: 0,
     isLocked: false
   };
@@ -7345,6 +7975,8 @@ class AudioSystem {
       anySmoothed: new EnvelopeFollower(5, 500, sampleRate)
     };
     this.resetEssentiaBandHistories();
+    this.tickIdle = this.tickIdle.bind(this);
+    this.startIdleTicker();
   }
   /**
    * Get the current audio analysis state (for host-side usage)
@@ -7410,8 +8042,17 @@ 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.
    */
   async connectChannel(ch, audioStream, isMain) {
+    if (isMain) {
+      this.stopIdleTicker();
+    }
     ch.disconnectNodes();
     ch.refreshFFTResources();
     ch.workletFrameCount = 0;
@@ -7420,6 +8061,7 @@ class AudioSystem {
       console.warn(`No audio tracks in stream for channel ${ch.streamIndex}`);
       ch.audioState.isConnected = false;
       this.sendChannelResults(ch, isMain);
+      if (isMain) this.startIdleTicker();
       return;
     }
     try {
@@ -7482,6 +8124,7 @@ class AudioSystem {
       console.error(`Failed to set up audio for channel ${ch.streamIndex}:`, error);
       ch.audioState.isConnected = false;
       ch.disconnectNodes();
+      if (isMain) this.startIdleTicker();
     }
     this.sendChannelResults(ch, isMain);
   }
@@ -7495,17 +8138,30 @@ class AudioSystem {
   }
   /**
    * 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.
    */
   disconnectMainStream() {
     this.mainChannel.disconnectNodes();
     this.mainChannel.audioState.isConnected = false;
     this.mainChannel.isAnalysisRunning = false;
     this.mainChannel.currentStream = null;
+    if (this.mainChannel.frequencyData) {
+      this.mainChannel.frequencyData.fill(0);
+    }
+    if (this.mainChannel.timeDomainData) {
+      this.mainChannel.timeDomainData.fill(0);
+    }
+    this.mainChannel.lastWaveformFrame = null;
     this.resetAudioValues();
     if (this.additionalChannels.size === 0) {
       this.stopAnalysisLoop();
       this.stopStalenessTimer();
     }
+    this.startIdleTicker();
     this.sendChannelResults(this.mainChannel, true);
     this.debugLog("Main audio stream disconnected (host-side)");
   }
@@ -7739,7 +8395,7 @@ class AudioSystem {
       hatSmoothed: 0,
       anySmoothed: 0,
       events: [],
-      bpm: 120,
+      bpm: 0,
       confidence: 0,
       isLocked: false
     };
@@ -7751,6 +8407,7 @@ class AudioSystem {
   resetAudioState() {
     this.stopAnalysisLoop();
     this.stopStalenessTimer();
+    this.stopIdleTicker();
     this.resetEssentiaBandHistories();
     for (const ch of this.additionalChannels.values()) {
       ch.destroy();
@@ -7875,6 +8532,97 @@ class AudioSystem {
   isOnsetMuted(instrument) {
     return this.onsetTapManager.isMuted(instrument);
   }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Onset event subscriptions (forward to OnsetTapManager).
+  // Returned `Unsubscribe` removes the listener.
+  // ─────────────────────────────────────────────────────────────────────────
+  onOnsetModeChange(listener) {
+    return this.onsetTapManager.onModeChange(listener);
+  }
+  onOnsetSessionEnd(listener) {
+    return this.onsetTapManager.onSessionEnd(listener);
+  }
+  onOnsetMuteChange(listener) {
+    return this.onsetTapManager.onMuteChange(listener);
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // State serialization. Onset-only export is cross-device-safe; the full
+  // 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();
+  }
+  importOnsetSessionState(state, clockOffset) {
+    this.onsetTapManager.importSessionState(state, clockOffset);
+  }
+  exportAudioAnalysisState() {
+    return {
+      onset: this.onsetTapManager.exportSessionState().instruments,
+      bpmTracker: this.tempoInduction.exportSessionState(),
+      pll: this.pll.exportSessionState(),
+      beatState: this.stateManager.exportSessionState()
+    };
+  }
+  importAudioAnalysisState(state, clockOffset) {
+    this.onsetTapManager.importSessionState(
+      { version: 1, senderTime: performance.now(), instruments: state.onset },
+      clockOffset
+    );
+    this.tempoInduction.importSessionState(state.bpmTracker, clockOffset);
+    this.pll.importSessionState(state.pll, clockOffset);
+    this.stateManager.importSessionState(state.beatState, clockOffset);
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Idle ticker — drives `OnsetTapManager.processFrame` via rAF when no audio
+  // is connected. Constructs an empty `beatState` and reuses the existing
+  // `processFrame` (verified correctness-preserving on empty input), so taps
+  // produce envelope/event output through the artist API the same way they
+  // do when audio is active.
+  // ─────────────────────────────────────────────────────────────────────────
+  startIdleTicker() {
+    if (this.idleTickerHandle !== null) return;
+    if (typeof requestAnimationFrame === "undefined") return;
+    this.idleTickerLastTime = performance.now();
+    this.idleTickerHandle = requestAnimationFrame(this.tickIdle);
+  }
+  stopIdleTicker() {
+    if (this.idleTickerHandle === null) return;
+    if (typeof cancelAnimationFrame !== "undefined") {
+      cancelAnimationFrame(this.idleTickerHandle);
+    }
+    this.idleTickerHandle = null;
+  }
+  tickIdle(now) {
+    this.idleTickerHandle = null;
+    if (this.mainChannel.audioState.isConnected) return;
+    const dtMs = Math.min(100, now - this.idleTickerLastTime);
+    this.idleTickerLastTime = now;
+    if (this.onsetDetectionEnabled && this.beatDetectionEnabled) {
+      const empty = this.makeEmptyBeatState();
+      this.audioStateBeat = this.onsetTapManager.processFrame(empty, now, dtMs);
+      this.sendChannelResults(this.mainChannel, true);
+    }
+    if (typeof requestAnimationFrame !== "undefined") {
+      this.idleTickerHandle = requestAnimationFrame(this.tickIdle);
+    }
+  }
+  makeEmptyBeatState() {
+    return {
+      kick: 0,
+      snare: 0,
+      hat: 0,
+      any: 0,
+      kickSmoothed: 0,
+      snareSmoothed: 0,
+      hatSmoothed: 0,
+      anySmoothed: 0,
+      events: [],
+      bpm: 0,
+      confidence: 0,
+      isLocked: false
+    };
+  }
   /**
    * Get current BPM (manual or auto-detected)
    */
@@ -8913,6 +9661,10 @@ class VijiCore {
   parameterDefinedListeners = /* @__PURE__ */ new Set();
   parameterErrorListeners = /* @__PURE__ */ new Set();
   capabilitiesChangeListeners = /* @__PURE__ */ new Set();
+  // State-import error listeners. Fire on `importFullState` payloads that fail
+  // version or shape validation; consumers surface meaningful UI feedback
+  // rather than relying on console.warn.
+  stateImportErrorListeners = /* @__PURE__ */ new Set();
   // Performance tracking (basic for Phase 1)
   stats = {
     frameTime: 0,
@@ -9885,6 +10637,86 @@ class VijiCore {
   offParameterError(listener) {
     this.parameterErrorListeners.delete(listener);
   }
+  // ─────────────────────────────────────────────────────────────────────────
+  // State serialization (cross-instance transfer)
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * 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() {
+    this.validateReady();
+    const senderTime = performance.now();
+    const out = { version: 1, senderTime };
+    if (this.audioSystem) {
+      const audio = this.audioSystem.exportAudioAnalysisState();
+      out.onset = audio.onset;
+      out.audio = audio;
+    }
+    return out;
+  }
+  /**
+   * 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, clockOffset) {
+    this.validateReady();
+    const validation = validateCoreStatePayload(state);
+    if (validation) {
+      this.fireStateImportError(validation);
+      return;
+    }
+    if (!this.audioSystem) return;
+    if (state.audio) {
+      this.audioSystem.importAudioAnalysisState(state.audio, clockOffset);
+    } else if (state.onset) {
+      this.audioSystem.importOnsetSessionState(
+        { version: 1, senderTime: state.senderTime, instruments: state.onset },
+        clockOffset
+      );
+    }
+  }
+  /**
+   * 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) {
+    this.stateImportErrorListeners.add(listener);
+    return () => {
+      this.stateImportErrorListeners.delete(listener);
+    };
+  }
+  fireStateImportError(error) {
+    for (const listener of this.stateImportErrorListeners) {
+      try {
+        listener(error);
+      } catch (err) {
+        console.error("Error in onStateImportError listener:", err);
+      }
+    }
+  }
   /**
    * Notify parameter change listeners
    */
@@ -10313,6 +11145,91 @@ class VijiCore {
       isMuted: (instrument) => {
         this.validateReady();
         return this.audioSystem?.isOnsetMuted(instrument) ?? false;
+      },
+      /**
+       * 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) => {
+        this.validateReady();
+        return this.audioSystem?.onOnsetModeChange(listener) ?? (() => {
+        });
+      },
+      /**
+       * 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) => {
+        this.validateReady();
+        return this.audioSystem?.onOnsetSessionEnd(listener) ?? (() => {
+        });
+      },
+      /**
+       * 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
+       *
+       * Idempotent calls (e.g. `setMuted(true)` on an already-muted instrument)
+       * do not fire. Imported state does NOT fire either.
+       *
+       * @returns Unsubscribe function. Call to remove the listener.
+       */
+      onMuteChange: (listener) => {
+        this.validateReady();
+        return this.audioSystem?.onOnsetMuteChange(listener) ?? (() => {
+        });
+      },
+      /**
+       * 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: () => {
+        this.validateReady();
+        return this.audioSystem?.exportOnsetSessionState() ?? {
+          version: 1,
+          senderTime: performance.now(),
+          instruments: {}
+        };
+      },
+      /**
+       * 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, clockOffset) => {
+        this.validateReady();
+        const validation = OnsetTapManager.validateOnsetPayload(state);
+        if (validation) {
+          this.fireStateImportError(validation);
+          return;
+        }
+        this.audioSystem?.importOnsetSessionState(state, clockOffset);
       }
     },
     /**
@@ -10602,6 +11519,7 @@ class VijiCore {
     this.parameterDefinedListeners.clear();
     this.parameterErrorListeners.clear();
     this.capabilitiesChangeListeners.clear();
+    this.stateImportErrorListeners.clear();
     this.unlinkEventSource();
     this.unlinkFrameSources();
     for (const [deviceId] of this.deviceVideoCoordinators) {
@@ -10693,7 +11611,25 @@ class VijiCore {
     }
   }
 }
-const VERSION = "0.5.0";
+function validateCoreStatePayload(state) {
+  if (state === null || typeof state !== "object") {
+    return { code: "malformed", details: "payload is not an object" };
+  }
+  const s = state;
+  if (s.version !== 1) {
+    return {
+      code: "version-mismatch",
+      details: `expected version 1, got ${String(s.version)}`,
+      ...typeof s.version === "number" ? { payloadVersion: s.version } : {},
+      expectedVersion: 1
+    };
+  }
+  if (typeof s.senderTime !== "number") {
+    return { code: "invalid-field", details: "senderTime must be a number", field: "senderTime" };
+  }
+  return null;
+}
+const VERSION = "0.5.2";
 export {
   AudioSystem as A,
   VERSION as V,
@@ -10701,4 +11637,4 @@ export {
   VijiCoreError as b,
   getDefaultExportFromCjs as g
 };
-//# sourceMappingURL=index-Cp9G0z4E.js.map
+//# sourceMappingURL=index-B8LJ9m47.js.map