@spatialwalk/avatarkit-rtc 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/index6.js

@@ -1,9 +1,9 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { decodeAnimationKeyframes } from "./index8.js";
 import { logger } from "./index7.js";
-class AnimationHandler {
+import { trackEvent } from "./index8.js";
+const _AnimationHandler = class _AnimationHandler {
   /**
    * @internal
    */
@@ -11,8 +11,6 @@ class AnimationHandler {
     /** @internal */
     __publicField(this, "renderer");
     /** @internal */
-    __publicField(this, "decoder");
-    /** @internal */
     __publicField(this, "config");
     // Frame tracking
     /** @internal */
@@ -43,12 +41,77 @@ class AnimationHandler {
     __publicField(this, "hasHandledTransitionStart", false);
     /** @internal */
     __publicField(this, "hasHandledTransitionEnd", false);
+    // Watchdog for detecting stalled data stream
+    /** @internal */
+    __publicField(this, "lastFrameReceivedTime", 0);
+    /** @internal */
+    __publicField(this, "isInSession", false);
+    /** @internal */
+    __publicField(this, "watchdogTimer", null);
+    /** @internal */
+    __publicField(this, "hasReportedStall", false);
+    /** @internal */
+    __publicField(this, "onStreamStalledCallback", null);
+    /** @internal */
+    __publicField(this, "providerName", "");
+    /** @internal */
+    __publicField(this, "isStalledFallback", false);
+    // True when fallback to idle was triggered due to stall
+    // Playback stats
+    /** @internal */
+    __publicField(this, "playbackStatsTimer", null);
+    /** @internal */
+    __publicField(this, "playbackFrameCount", 0);
+    /** @internal */
+    __publicField(this, "playbackFrameTimestamps", []);
+    /** @internal */
+    __publicField(this, "playbackGapCount", 0);
+    /** @internal */
+    __publicField(this, "playbackExpectedSeq", -1);
+    // Jitter buffer
+    /** @internal */
+    __publicField(this, "bufferState", "direct");
+    /** @internal */
+    __publicField(this, "frameBuffer", /* @__PURE__ */ new Map());
+    /** @internal */
+    __publicField(this, "bufferNextSeq", -1);
+    /** @internal */
+    __publicField(this, "bufferDrainTimer", null);
+    /** @internal */
+    __publicField(this, "bufferLastDrainTime", 0);
+    // Cumulative session stats (never reset until getSessionSummary)
+    /** @internal */
+    __publicField(this, "cumulativeTotalFrames", 0);
+    /** @internal */
+    __publicField(this, "cumulativeLost", 0);
+    /** @internal */
+    __publicField(this, "cumulativeRecovered", 0);
+    /** @internal */
+    __publicField(this, "cumulativeDropped", 0);
+    /** @internal */
+    __publicField(this, "cumulativeFpsReadings", []);
+    // Per-conversation stats for rtc_playback_stats
+    /** @internal */
+    __publicField(this, "conversationFrameCount", 0);
+    /** @internal */
+    __publicField(this, "conversationLost", 0);
+    /** @internal */
+    __publicField(this, "conversationRecovered", 0);
+    /** @internal */
+    __publicField(this, "conversationDropped", 0);
+    /** @internal */
+    __publicField(this, "conversationFpsReadings", []);
+    /** @internal */
+    __publicField(this, "conversationStartTime", 0);
     this.renderer = renderer;
-    this.decoder = config.decoder ?? decodeAnimationKeyframes;
     this.config = {
       transitionStartFrameCount: config.transitionStartFrameCount ?? 8,
-      transitionEndFrameCount: config.transitionEndFrameCount ?? 12
+      transitionEndFrameCount: config.transitionEndFrameCount ?? 12,
+      enableJitterBuffer: config.enableJitterBuffer ?? true,
+      maxBufferDelayMs: config.maxBufferDelayMs ?? 80
     };
+    this.onStreamStalledCallback = config.onStreamStalled ?? null;
+    this.providerName = config.providerName ?? "";
   }
   /**
    * Handle animation data received from RTC provider.
@@ -61,17 +124,42 @@ class AnimationHandler {
     if (this.isPlayingTransition) {
       this.stopTransition();
     }
+    const now = Date.now();
+    if (this.hasReportedStall) {
+      const stallDuration = now - this.lastFrameReceivedTime;
+      logger.info(
+        "AnimationHandler",
+        `Data stream resumed after ${stallDuration}ms stall`
+      );
+      this.hasReportedStall = false;
+    }
+    if (this.isStalledFallback) {
+      logger.info(
+        "AnimationHandler",
+        "Resuming from stall fallback, rendering directly without transition"
+      );
+      this.isStalledFallback = false;
+    }
+    this.lastFrameReceivedTime = now;
     this.animationFrameCount++;
-    this.renderedFrameCount++;
+    this.ensureSessionActive(frameSeq);
+    if (this.config.enableJitterBuffer && frameSeq !== void 0) {
+      this.bufferFrame(protobufData, frameSeq);
+      return;
+    }
     if (frameSeq !== void 0 && this.lastRenderedFrameSeq !== -1) {
-      if (frameSeq <= this.lastRenderedFrameSeq) {
-        logger.info(
+      if (frameSeq < this.lastRenderedFrameSeq) {
+        logger.warn(
           "AnimationHandler",
-          `OUT-OF-ORDER/DUPLICATE: seq=${frameSeq}, lastRendered=${this.lastRenderedFrameSeq}${isRecovered ? " [RECOVERED]" : ""}`
+          `OUT-OF-ORDER: seq=${frameSeq}, lastRendered=${this.lastRenderedFrameSeq}${isRecovered ? " [RECOVERED]" : ""}, discarding`
         );
+        this.conversationDropped++;
+        return;
+      } else if (frameSeq === this.lastRenderedFrameSeq) {
+        return;
       } else if (frameSeq > this.lastRenderedFrameSeq + 1) {
         const gap = frameSeq - this.lastRenderedFrameSeq - 1;
-        logger.info(
+        logger.warn(
           "AnimationHandler",
           `GAP: ${gap} frame(s) between ${this.lastRenderedFrameSeq} and ${frameSeq}${isRecovered ? " [RECOVERED]" : ""}`
         );
@@ -80,9 +168,17 @@ class AnimationHandler {
     if (frameSeq !== void 0) {
       this.lastRenderedFrameSeq = frameSeq;
     }
-    const keyframes = this.decoder(protobufData);
-    if (keyframes && keyframes.length > 0) {
-      this.renderer.renderFrame(keyframes[0]);
+    this.renderedFrameCount++;
+    if (isRecovered) this.conversationRecovered++;
+    this.renderer.renderFromProtobuf(protobufData);
+    this.logRenderedFrame("direct", frameSeq, isRecovered);
+    this.playbackFrameTimestamps.push(performance.now());
+    this.playbackFrameCount++;
+    if (frameSeq !== void 0) {
+      if (this.playbackExpectedSeq >= 0 && frameSeq > this.playbackExpectedSeq) {
+        this.playbackGapCount += frameSeq - this.playbackExpectedSeq;
+      }
+      this.playbackExpectedSeq = frameSeq + 1;
     }
   }
   /**
@@ -93,6 +189,10 @@ class AnimationHandler {
    * @internal
    */
   async handleTransitionData(protobufData, frameCount) {
+    logger.info(
+      "AnimationHandler",
+      `Start transition packet received (bytes=${protobufData.byteLength}, requestedFrames=${frameCount ?? this.config.transitionStartFrameCount}, hasHandledStart=${this.hasHandledTransitionStart}, isInSession=${this.isInSession}, isPlayingTransition=${this.isPlayingTransition}, isGeneratingStart=${this.isGeneratingStartTransition}, lastRenderedSeq=${this.lastRenderedFrameSeq}, bufferState=${this.bufferState}, buffered=${this.frameBuffer.size})`
+    );
     if (this.hasHandledTransitionStart) {
       return;
     }
@@ -106,23 +206,32 @@ class AnimationHandler {
       logger.warn("AnimationHandler", "Renderer not ready for transition");
       return;
     }
-    const keyframes = this.decoder(protobufData);
-    if (!keyframes || keyframes.length === 0) {
-      logger.warn("AnimationHandler", "No target keyframe in transition data");
+    if (this.isInSession && (this.lastRenderedFrameSeq >= 0 || this.frameBuffer.size > 0 || this.bufferState !== "direct")) {
+      this.hasHandledTransitionStart = true;
+      logger.warn(
+        "AnimationHandler",
+        `Ignoring late transition packet after playback start (lastRenderedSeq=${this.lastRenderedFrameSeq}, bufferState=${this.bufferState}, buffered=${this.frameBuffer.size})`
+      );
       return;
     }
     this.hasHandledTransitionStart = true;
     this.hasHandledTransitionEnd = false;
-    const targetFrame = keyframes[0];
+    this.ensureSessionActive();
     const frames = frameCount ?? this.config.transitionStartFrameCount;
-    logger.info("AnimationHandler", `Generating ${frames} transition frames to target`);
+    logger.info(
+      "AnimationHandler",
+      `Generating ${frames} transition frames to target`
+    );
     this.isGeneratingStartTransition = true;
     try {
-      const transitionFrames = await this.renderer.generateTransitionFromIdle(
-        targetFrame,
+      const transitionFrames = await this.renderer.generateTransitionFromProtobuf(
+        protobufData,
         frames
       );
-      logger.info("AnimationHandler", `Generated ${transitionFrames.length} transition frames`);
+      logger.info(
+        "AnimationHandler",
+        `Generated ${transitionFrames.length} transition frames`
+      );
       this.isPlayingTransition = true;
       this.isTransitioningToIdle = false;
       this.transitionFrames = transitionFrames;
@@ -130,7 +239,8 @@ class AnimationHandler {
       this.playTransitionFrame();
     } catch (error) {
       logger.error("AnimationHandler", "Failed to generate transition:", error);
-      this.renderer.renderFrame(targetFrame);
+      this.renderer.renderFromProtobuf(protobufData);
+      this.logRenderedFrame("transition-fallback");
     } finally {
       this.isGeneratingStartTransition = false;
     }
@@ -143,6 +253,13 @@ class AnimationHandler {
    * @internal
    */
   async handleTransitionToIdle(protobufData, frameCount) {
+    if (!this.isInSession) {
+      logger.info(
+        "AnimationHandler",
+        "Ignoring transition end packet with no active session"
+      );
+      return;
+    }
     if (this.hasHandledTransitionEnd) {
       return;
     }
@@ -153,27 +270,31 @@ class AnimationHandler {
       return;
     }
     if (!this.renderer.isReady()) {
-      logger.warn("AnimationHandler", "Renderer not ready for transition to idle");
-      this.renderer.renderFrame(void 0, true);
-      return;
-    }
-    const keyframes = this.decoder(protobufData);
-    if (!keyframes || keyframes.length === 0) {
-      logger.warn("AnimationHandler", "No last keyframe in transition end data, starting idle directly");
+      logger.warn(
+        "AnimationHandler",
+        "Renderer not ready for transition to idle"
+      );
       this.renderer.renderFrame(void 0, true);
+      this.logRenderedFrame("idle");
       return;
     }
     this.hasHandledTransitionEnd = true;
-    const lastFrame = keyframes[0];
+    this.flushBuffer();
     const frames = frameCount ?? this.config.transitionEndFrameCount;
-    logger.info("AnimationHandler", `Generating ${frames} reverse transition frames to idle`);
+    logger.info(
+      "AnimationHandler",
+      `Generating ${frames} reverse transition frames to idle`
+    );
     this.isGeneratingEndTransition = true;
     try {
-      const transitionFrames = await this.renderer.generateTransitionFromIdle(
-        lastFrame,
+      const transitionFrames = await this.renderer.generateTransitionFromProtobuf(
+        protobufData,
         frames
       );
-      logger.info("AnimationHandler", `Generated ${transitionFrames.length} transition frames, reversing for playback`);
+      logger.info(
+        "AnimationHandler",
+        `Generated ${transitionFrames.length} transition frames, reversing for playback`
+      );
       const reversedFrames = transitionFrames.slice().reverse();
       this.isPlayingTransition = true;
       this.isTransitioningToIdle = true;
@@ -181,8 +302,13 @@ class AnimationHandler {
       this.transitionFrameIndex = 0;
       this.playTransitionFrame();
     } catch (error) {
-      logger.error("AnimationHandler", "Failed to generate reverse transition:", error);
+      logger.error(
+        "AnimationHandler",
+        "Failed to generate reverse transition:",
+        error
+      );
       this.renderer.renderFrame(void 0, true);
+      this.logRenderedFrame("idle");
     } finally {
       this.isGeneratingEndTransition = false;
     }
@@ -192,7 +318,34 @@ class AnimationHandler {
    * @internal
    */
   startIdle() {
+    this.reportConversationStats();
+    this.isInSession = false;
+    this.hasReportedStall = false;
     this.renderer.renderFrame(void 0, true);
+    this.logRenderedFrame("idle");
+  }
+  /**
+   * Ensure session-level timers/stats are active.
+   * @internal
+   */
+  ensureSessionActive(frameSeq) {
+    if (this.isInSession) {
+      return;
+    }
+    this.isInSession = true;
+    this.lastFrameReceivedTime = Date.now();
+    this.hasReportedStall = false;
+    if (!this.conversationStartTime) {
+      this.conversationStartTime = Date.now();
+    }
+    this.startWatchdog();
+    this.startPlaybackStats();
+    if (frameSeq !== void 0) {
+      logger.info(
+        "AnimationHandler",
+        `Session started from animation frame seq=${frameSeq}`
+      );
+    }
   }
   /**
    * Reset animation frame tracking (call on session start).
@@ -204,6 +357,8 @@ class AnimationHandler {
     this.animationFrameCount = 0;
     this.hasHandledTransitionStart = false;
     this.hasHandledTransitionEnd = false;
+    this.resetPlaybackStats();
+    this.flushBuffer();
     logger.info("AnimationHandler", "Frame tracking reset");
   }
   /**
@@ -211,7 +366,7 @@ class AnimationHandler {
    * @internal
    */
   isInTransition() {
-    return this.isPlayingTransition;
+    return this.isPlayingTransition || this.isGeneratingStartTransition || this.isGeneratingEndTransition;
   }
   /**
    * Stop transition playback.
@@ -231,6 +386,58 @@ class AnimationHandler {
       clearTimeout(this.transitionTimeoutId);
       this.transitionTimeoutId = null;
     }
+    this.flushBuffer();
+  }
+  /**
+   * Get cumulative session summary for telemetry reporting.
+   * @internal
+   */
+  getSessionSummary() {
+    const avgFps = this.cumulativeFpsReadings.length > 0 ? Math.round(
+      this.cumulativeFpsReadings.reduce((a, b) => a + b, 0) / this.cumulativeFpsReadings.length
+    ) : 0;
+    return {
+      totalFrames: this.cumulativeTotalFrames,
+      totalLost: this.cumulativeLost,
+      totalRecovered: this.cumulativeRecovered,
+      totalDropped: this.cumulativeDropped,
+      avgFps
+    };
+  }
+  /**
+   * Report per-conversation playback stats via telemetry.
+   * Called when a conversation ends (transition to idle).
+   * @internal
+   */
+  reportConversationStats() {
+    if (this.conversationFrameCount === 0) return;
+    const durationMs = this.conversationStartTime ? Date.now() - this.conversationStartTime : 0;
+    const avgFps = this.conversationFpsReadings.length > 0 ? Math.round(
+      this.conversationFpsReadings.reduce((a, b) => a + b, 0) / this.conversationFpsReadings.length
+    ) : 0;
+    const totalExpected = this.conversationFrameCount + this.conversationLost;
+    const lossRate = totalExpected > 0 ? Number((this.conversationLost / totalExpected * 100).toFixed(1)) : 0;
+    trackEvent("rtc_playback_stats", "info", {
+      provider: this.providerName,
+      avg_fps: avgFps,
+      frame_count: this.conversationFrameCount,
+      frames_lost: this.conversationLost,
+      frames_recovered: this.conversationRecovered,
+      frames_dropped: this.conversationDropped,
+      loss_rate: lossRate,
+      duration_ms: durationMs
+    });
+    this.cumulativeTotalFrames += this.conversationFrameCount;
+    this.cumulativeLost += this.conversationLost;
+    this.cumulativeRecovered += this.conversationRecovered;
+    this.cumulativeDropped += this.conversationDropped;
+    this.cumulativeFpsReadings.push(...this.conversationFpsReadings);
+    this.conversationFrameCount = 0;
+    this.conversationLost = 0;
+    this.conversationRecovered = 0;
+    this.conversationDropped = 0;
+    this.conversationFpsReadings = [];
+    this.conversationStartTime = 0;
   }
   /**
    * Clean up resources.
@@ -238,6 +445,339 @@ class AnimationHandler {
    */
   dispose() {
     this.stopTransition();
+    this.stopWatchdog();
+  }
+  /**
+   * Start the watchdog timer to detect stalled data streams.
+   * @internal
+   */
+  startWatchdog() {
+    if (this.watchdogTimer) {
+      return;
+    }
+    this.watchdogTimer = setInterval(() => {
+      if (!this.isInSession) {
+        return;
+      }
+      if (this.isPlayingTransition) {
+        return;
+      }
+      const elapsed = Date.now() - this.lastFrameReceivedTime;
+      if (elapsed > _AnimationHandler.STALL_TIMEOUT_MS && !this.hasReportedStall) {
+        logger.error(
+          "AnimationHandler",
+          `Data stream stalled: no frames received for ${elapsed}ms, falling back to idle`
+        );
+        this.hasReportedStall = true;
+        this.isStalledFallback = true;
+        this.startIdle();
+        if (this.onStreamStalledCallback) {
+          try {
+            this.onStreamStalledCallback();
+          } catch (e) {
+            logger.error(
+              "AnimationHandler",
+              "Error in onStreamStalled callback:",
+              e
+            );
+          }
+        }
+      }
+    }, 1e3);
+  }
+  /**
+   * Stop the watchdog timer.
+   * @internal
+   */
+  stopWatchdog() {
+    if (this.watchdogTimer) {
+      clearInterval(this.watchdogTimer);
+      this.watchdogTimer = null;
+    }
+    this.hasReportedStall = false;
+    this.isStalledFallback = false;
+    this.stopPlaybackStats();
+  }
+  /**
+   * Start the playback stats reporting timer.
+   * @internal
+   */
+  startPlaybackStats() {
+    if (this.playbackStatsTimer) {
+      return;
+    }
+    this.resetPlaybackStats();
+    this.playbackStatsTimer = setInterval(() => {
+      this.reportPlaybackStats();
+    }, 1e3);
+  }
+  /**
+   * Stop the playback stats reporting timer.
+   * @internal
+   */
+  stopPlaybackStats() {
+    if (this.playbackStatsTimer) {
+      clearInterval(this.playbackStatsTimer);
+      this.playbackStatsTimer = null;
+    }
+    this.resetPlaybackStats();
+  }
+  /**
+   * Reset playback stats counters.
+   * @internal
+   */
+  resetPlaybackStats() {
+    this.playbackFrameCount = 0;
+    this.playbackFrameTimestamps = [];
+    this.playbackGapCount = 0;
+    this.playbackExpectedSeq = -1;
+  }
+  /**
+   * Report playback stats (called every 1s by timer).
+   * Logs FPS, frame loss rate, and playback jitter.
+   * @internal
+   */
+  reportPlaybackStats() {
+    if (this.isPlayingTransition) {
+      this.resetPlaybackStats();
+      return;
+    }
+    if (this.playbackFrameCount === 0) {
+      return;
+    }
+    const fps = this.playbackFrameCount;
+    const totalExpected = this.playbackFrameCount + this.playbackGapCount;
+    const lossRate = totalExpected > 0 ? this.playbackGapCount / totalExpected * 100 : 0;
+    let jitter = 0;
+    if (this.playbackFrameTimestamps.length >= 2) {
+      const intervals = [];
+      for (let i = 1; i < this.playbackFrameTimestamps.length; i++) {
+        intervals.push(
+          this.playbackFrameTimestamps[i] - this.playbackFrameTimestamps[i - 1]
+        );
+      }
+      const mean = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+      const variance = intervals.reduce((sum, v) => sum + (v - mean) ** 2, 0) / intervals.length;
+      jitter = Math.sqrt(variance);
+    }
+    logger.info(
+      "AnimationHandler",
+      `Playback stats: fps=${fps}, lossRate=${lossRate.toFixed(1)}%, jitter=${jitter.toFixed(1)}ms`
+    );
+    this.conversationFrameCount += this.playbackFrameCount;
+    this.conversationLost += this.playbackGapCount;
+    this.conversationFpsReadings.push(fps);
+    this.playbackFrameCount = 0;
+    this.playbackFrameTimestamps = [];
+    this.playbackGapCount = 0;
+  }
+  // ── Jitter Buffer ──
+  /**
+   * Insert a frame into the jitter buffer.
+   * Handles dedup, enforces max size, and drives the buffer state machine.
+   * @internal
+   */
+  bufferFrame(protobufData, seq) {
+    if (this.lastRenderedFrameSeq >= 0 && seq <= this.lastRenderedFrameSeq) {
+      logger.warn(
+        "AnimationHandler",
+        `Jitter buffer: dropping stale frame seq=${seq} (lastRendered=${this.lastRenderedFrameSeq})`
+      );
+      this.conversationDropped++;
+      return;
+    }
+    if (this.bufferNextSeq >= 0 && seq < this.bufferNextSeq) {
+      logger.warn(
+        "AnimationHandler",
+        `Jitter buffer: dropping late frame seq=${seq} (nextExpected=${this.bufferNextSeq})`
+      );
+      this.conversationDropped++;
+      return;
+    }
+    if (this.frameBuffer.has(seq)) {
+      return;
+    }
+    this.frameBuffer.set(seq, { protobufData, seq, receivedAt: performance.now() });
+    if (this.frameBuffer.size > _AnimationHandler.BUFFER_MAX_SIZE) {
+      let oldestSeq = Infinity;
+      for (const k of this.frameBuffer.keys()) {
+        if (k < oldestSeq) oldestSeq = k;
+      }
+      this.frameBuffer.delete(oldestSeq);
+      this.conversationDropped++;
+      logger.warn(
+        "AnimationHandler",
+        `Jitter buffer: overflow, dropping seq=${oldestSeq} (nextExpected=${this.bufferNextSeq})`
+      );
+    }
+    switch (this.bufferState) {
+      case "direct":
+        this.bufferState = "filling";
+        if (this.bufferNextSeq < 0) {
+          this.bufferNextSeq = seq;
+        }
+        logger.info(
+          "AnimationHandler",
+          `Jitter buffer: filling (first frame seq=${seq})`
+        );
+        if (this.frameBuffer.size >= _AnimationHandler.BUFFER_INITIAL_FILL) {
+          this.startBufferDrain();
+        }
+        break;
+      case "filling":
+        if (this.frameBuffer.size >= _AnimationHandler.BUFFER_INITIAL_FILL) {
+          this.startBufferDrain();
+        }
+        break;
+      case "starved":
+        this.startBufferDrain();
+        break;
+    }
+  }
+  /**
+   * Drop buffered frames that are now too old to ever be rendered in-order.
+   * @internal
+   */
+  dropStaleBufferedFrames() {
+    if (this.frameBuffer.size === 0) {
+      return;
+    }
+    const minAllowedSeq = Math.max(
+      this.bufferNextSeq,
+      this.lastRenderedFrameSeq + 1
+    );
+    if (minAllowedSeq < 0) {
+      return;
+    }
+    let dropped = 0;
+    for (const seq of Array.from(this.frameBuffer.keys())) {
+      if (seq < minAllowedSeq) {
+        this.frameBuffer.delete(seq);
+        dropped++;
+      }
+    }
+    if (dropped > 0) {
+      logger.warn(
+        "AnimationHandler",
+        `Jitter buffer: dropped ${dropped} stale frame(s) older than seq=${minAllowedSeq}`
+      );
+    }
+  }
+  /**
+   * Find the lowest buffered sequence at or after minSeq.
+   * @internal
+   */
+  findLowestBufferedSeqAtOrAfter(minSeq) {
+    let candidate = Infinity;
+    for (const seq of this.frameBuffer.keys()) {
+      if (seq >= minSeq && seq < candidate) {
+        candidate = seq;
+      }
+    }
+    return candidate === Infinity ? null : candidate;
+  }
+  /**
+   * Begin draining the buffer at 25fps.
+   * @internal
+   */
+  startBufferDrain() {
+    this.bufferState = "draining";
+    if (this.bufferNextSeq < 0) {
+      let minSeq = Infinity;
+      for (const k of this.frameBuffer.keys()) {
+        if (k < minSeq) minSeq = k;
+      }
+      this.bufferNextSeq = minSeq;
+    }
+    logger.info(
+      "AnimationHandler",
+      `Jitter buffer: draining (${this.frameBuffer.size} frames buffered)`
+    );
+    this.bufferLastDrainTime = performance.now();
+    this.drainBufferFrame();
+  }
+  /**
+   * Drain one frame from the buffer and schedule the next drain.
+   * Handles missing frames (skip-ahead after maxBufferDelayMs) and starvation.
+   * @internal
+   */
+  drainBufferFrame() {
+    this.bufferDrainTimer = null;
+    if (this.bufferState !== "draining") {
+      return;
+    }
+    this.dropStaleBufferedFrames();
+    const frame = this.frameBuffer.get(this.bufferNextSeq);
+    if (frame) {
+      this.renderBufferedFrame(frame);
+      this.frameBuffer.delete(this.bufferNextSeq);
+      this.bufferNextSeq++;
+    } else if (this.frameBuffer.size > 0) {
+      const nextSeq = this.findLowestBufferedSeqAtOrAfter(this.bufferNextSeq);
+      if (nextSeq === null) {
+        this.bufferState = "starved";
+        logger.warn(
+          "AnimationHandler",
+          "Jitter buffer: no in-order frames available, pausing drain"
+        );
+        return;
+      }
+      const nextFrame = this.frameBuffer.get(nextSeq);
+      const waitTime = performance.now() - nextFrame.receivedAt;
+      if (waitTime > this.config.maxBufferDelayMs) {
+        const gap = Math.max(0, nextSeq - this.bufferNextSeq);
+        this.playbackGapCount += gap;
+        logger.warn(
+          "AnimationHandler",
+          `Jitter buffer: skipping ${gap} frame(s) from seq ${this.bufferNextSeq} to ${nextSeq} after ${waitTime.toFixed(1)}ms`
+        );
+        this.renderBufferedFrame(nextFrame);
+        this.frameBuffer.delete(nextSeq);
+        this.bufferNextSeq = nextSeq + 1;
+      }
+    } else {
+      this.bufferState = "starved";
+      logger.warn("AnimationHandler", "Jitter buffer: starved, pausing drain");
+      return;
+    }
+    const now = performance.now();
+    const nextTarget = this.bufferLastDrainTime + _AnimationHandler.BUFFER_FRAME_INTERVAL_MS;
+    const delay = Math.max(0, nextTarget - now);
+    this.bufferLastDrainTime = nextTarget;
+    this.bufferDrainTimer = setTimeout(() => this.drainBufferFrame(), delay);
+  }
+  /**
+   * Render a single frame from the buffer and collect playback stats.
+   * @internal
+   */
+  renderBufferedFrame(frame) {
+    if (this.lastRenderedFrameSeq >= 0 && frame.seq <= this.lastRenderedFrameSeq) {
+      logger.warn(
+        "AnimationHandler",
+        `Jitter buffer: refusing out-of-order render seq=${frame.seq} (lastRendered=${this.lastRenderedFrameSeq})`
+      );
+      return;
+    }
+    this.renderer.renderFromProtobuf(frame.protobufData);
+    this.lastRenderedFrameSeq = frame.seq;
+    this.renderedFrameCount++;
+    this.logRenderedFrame("buffer", frame.seq);
+    this.playbackFrameTimestamps.push(performance.now());
+    this.playbackFrameCount++;
+  }
+  /**
+   * Flush the jitter buffer, stop the drain loop, and revert to direct mode.
+   * @internal
+   */
+  flushBuffer() {
+    this.frameBuffer.clear();
+    this.bufferState = "direct";
+    this.bufferNextSeq = -1;
+    this.bufferLastDrainTime = 0;
+    if (this.bufferDrainTimer !== null) {
+      clearTimeout(this.bufferDrainTimer);
+      this.bufferDrainTimer = null;
+    }
   }
   /**
    * Play a single transition frame and schedule the next one.
@@ -256,8 +796,12 @@ class AnimationHandler {
       }
       logger.info("AnimationHandler", "Transition playback complete");
       if (wasTransitioningToIdle) {
-        logger.info("AnimationHandler", "Starting idle animation after transition");
+        logger.info(
+          "AnimationHandler",
+          "Starting idle animation after transition"
+        );
         this.renderer.renderFrame(void 0, true);
+        this.logRenderedFrame("idle");
       }
       return;
     }
@@ -268,6 +812,7 @@ class AnimationHandler {
     }
     const frame = this.transitionFrames[this.transitionFrameIndex];
     this.renderer.renderFrame(frame);
+    this.logRenderedFrame("transition");
     this.transitionFrameIndex++;
     this.transitionTimeoutId = setTimeout(() => {
       if (this.isPlayingTransition) {
@@ -275,7 +820,26 @@ class AnimationHandler {
       }
     }, 40);
   }
-}
+  /**
+   * Emit a per-frame render log for debugging ordering issues.
+   * @internal
+   */
+  logRenderedFrame(source, seq, isRecovered) {
+    logger.info(
+      "AnimationHandler",
+      `Rendered frame: source=${source}, seq=${seq ?? "n/a"}${isRecovered ? " [RECOVERED]" : ""}`
+    );
+  }
+};
+/** @internal */
+__publicField(_AnimationHandler, "STALL_TIMEOUT_MS", 5e3);
+/** @internal */
+__publicField(_AnimationHandler, "BUFFER_MAX_SIZE", 4);
+/** @internal */
+__publicField(_AnimationHandler, "BUFFER_INITIAL_FILL", 2);
+/** @internal */
+__publicField(_AnimationHandler, "BUFFER_FRAME_INTERVAL_MS", 40);
+let AnimationHandler = _AnimationHandler;
 export {
   AnimationHandler
 };