@runtypelabs/persona 3.15.0 → 3.16.0

package/src/components/header-builder.ts

@@ -159,9 +159,11 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
     clearChatButton.style.color =
       clearChatIconColor || HEADER_THEME_CSS.actionIconColor;
 
-    // Add icon
+    // Add icon. display:block eliminates inline-baseline spacing that can
+    // push the icon a fractional pixel off-center inside the button.
     const iconSvg = renderLucideIcon(clearChatIconName, "20px", "currentColor", 1);
     if (iconSvg) {
+      iconSvg.style.display = "block";
       clearChatButton.appendChild(iconSvg);
     }
 
@@ -276,15 +278,17 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
     }
   }
 
-  // Create close button wrapper for tooltip positioning
-  // Only needs ml-auto if clear chat is disabled or top-right positioned
+  // Create close button wrapper for tooltip positioning.
+  // Mirrors the clear-chat wrapper's inline-flex centering so both
+  // header action buttons vertically align identically within the
+  // header's flex row.
   const closeButtonWrapper = createElement(
     "div",
     closeButtonPlacement === "top-right"
       ? "persona-absolute persona-top-4 persona-right-4 persona-z-50"
       : clearChatEnabled && clearChatPlacement === "inline"
-        ? ""
-        : "persona-ml-auto"
+        ? "persona-relative persona-inline-flex persona-items-center persona-justify-center"
+        : "persona-relative persona-ml-auto persona-inline-flex persona-items-center persona-justify-center"
   );
 
   // Create close button with base classes
@@ -309,9 +313,16 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
   closeButton.style.color =
     launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor;
 
-  // Try to render Lucide icon, fallback to text if not provided or fails
-  const closeIconSvg = renderLucideIcon(closeButtonIconName, "20px", "currentColor", 1);
+  // Try to render Lucide icon, fallback to text if not provided or fails.
+  // The X glyph's paths occupy only the middle 50% of its 24x24 viewBox
+  // (from 6,6 to 18,18), while other header icons (e.g. refresh-cw) span
+  // ~75% of the viewBox. Rendering X at a larger intrinsic size brings
+  // its visible extent into parity with sibling icons in the header.
+  // display:block eliminates inline-baseline spacing that can push the
+  // icon a fractional pixel off-center inside the button.
+  const closeIconSvg = renderLucideIcon(closeButtonIconName, "28px", "currentColor", 1);
   if (closeIconSvg) {
+    closeIconSvg.style.display = "block";
     closeButton.appendChild(closeIconSvg);
   } else {
     closeButton.textContent = closeButtonIconText;

package/src/components/header-layouts.ts

@@ -215,7 +215,9 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
     launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor;
 
   const closeButtonIconName = launcher.closeButtonIconName ?? "x";
-  const closeIconSvg = renderLucideIcon(closeButtonIconName, "20px", "currentColor", 2);
+  // Larger intrinsic size compensates for the X glyph's sparse viewBox
+  // (paths only occupy the middle 50%). Matches header-builder.ts.
+  const closeIconSvg = renderLucideIcon(closeButtonIconName, "28px", "currentColor", 1);
   if (closeIconSvg) {
     closeButton.appendChild(closeIconSvg);
   } else {

package/src/defaults.ts

@@ -43,6 +43,12 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
     agentIconSize: "40px",
     headerIconSize: "40px",
     closeButtonSize: "32px",
+    // Zero out browser-default <button> padding so the icon gets the full
+    // 32x32 content box, matching clearChat.paddingX/Y below. Without this,
+    // UA stylesheets add ~1-2px vertical and ~6px horizontal padding that
+    // eats into the border-box width and shrinks the rendered icon.
+    closeButtonPaddingX: "0px",
+    closeButtonPaddingY: "0px",
     callToActionIconName: "arrow-up-right",
     callToActionIconText: "",
     callToActionIconSize: "32px",

package/src/styles/widget.css

@@ -1778,10 +1778,6 @@
   margin-top: 0.5rem;
   padding: 0.25rem 0.5rem;
   border-top: none;
-  border-radius: var(--persona-radius-md, 0.75rem);
-  background-color: var(--persona-surface, #ffffff);
-  border: 1px solid var(--persona-divider, #f1f5f9);
-  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
 }
 
 /* Pill alignment in always-visible mode (block flow: use margin to position) */
@@ -1826,10 +1822,6 @@
     padding: 0.25rem;
     border-top: none;
     width: fit-content;
-    background-color: var(--persona-surface, #ffffff);
-    border: 1px solid var(--persona-divider, #f1f5f9);
-    border-radius: var(--persona-radius-md, 0.75rem);
-    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
   }
 
   /* Pill layout - position based on alignment */
@@ -1932,6 +1924,17 @@
   opacity: 0.9;
 }
 
+/* Vote pop animation */
+@keyframes persona-vote-pop {
+  0% { transform: scale(1); }
+  40% { transform: scale(1.25); }
+  100% { transform: scale(1); }
+}
+
+.persona-message-action-btn.persona-message-action-pop {
+  animation: persona-vote-pop 0.3s ease;
+}
+
 /* Success state (after copy) */
 .persona-message-action-btn.persona-message-action-success {
   background-color: #10b981;

package/src/types.ts

@@ -194,6 +194,17 @@ export type AgentMessageMetadata = {
   iteration?: number;
   turnId?: string;
   agentName?: string;
+  /**
+   * When this message was produced by a step inside a nested flow executed
+   * as a tool, identifies the parent tool call id. Enables renderers to
+   * visually group or indent nested-flow output under its parent tool.
+   */
+  parentToolId?: string;
+  /**
+   * Nested flow step id that produced this message (e.g. a `send-stream`
+   * or `prompt` step inside the nested flow). Stable key for that step.
+   */
+  parentStepId?: string;
 };
 
 export type AgentWidgetRequestMiddlewareContext = {

package/src/ui.ts

@@ -1229,22 +1229,47 @@ export const createAgentExperience = (
     } else if (action === 'upvote' || action === 'downvote') {
       const currentVote = messageVoteState.get(messageId) ?? null;
       const wasActive = currentVote === action;
+      const iconName = action === 'upvote' ? 'thumbs-up' : 'thumbs-down';
 
       if (wasActive) {
-        // Toggle off
+        // Toggle off — revert to outline icon
         messageVoteState.delete(messageId);
         actionBtn.classList.remove("persona-message-action-active");
+        const outlineIcon = renderLucideIcon(iconName, 14, "currentColor", 2);
+        if (outlineIcon) {
+          actionBtn.innerHTML = "";
+          actionBtn.appendChild(outlineIcon);
+        }
       } else {
-        // Clear opposite vote button
+        // Clear opposite vote button and revert its icon
         const oppositeAction = action === 'upvote' ? 'downvote' : 'upvote';
         const oppositeBtn = actionsContainer.querySelector(`[data-action="${oppositeAction}"]`);
         if (oppositeBtn) {
           oppositeBtn.classList.remove("persona-message-action-active");
+          const oppositeIconName = oppositeAction === 'upvote' ? 'thumbs-up' : 'thumbs-down';
+          const outlineIcon = renderLucideIcon(oppositeIconName, 14, "currentColor", 2);
+          if (outlineIcon) {
+            oppositeBtn.innerHTML = "";
+            oppositeBtn.appendChild(outlineIcon);
+          }
         }
 
         messageVoteState.set(messageId, action);
         actionBtn.classList.add("persona-message-action-active");
 
+        // Swap to filled icon
+        const filledIcon = renderLucideIcon(iconName, 14, "currentColor", 2);
+        if (filledIcon) {
+          filledIcon.setAttribute("fill", "currentColor");
+          actionBtn.innerHTML = "";
+          actionBtn.appendChild(filledIcon);
+        }
+
+        // Pop animation
+        actionBtn.classList.remove("persona-message-action-pop");
+        void actionBtn.offsetWidth; // force reflow to restart animation
+        actionBtn.classList.add("persona-message-action-pop");
+
         // Trigger feedback
         const messages = session.getMessages();
         const message = messages.find(m => m.id === messageId);
@@ -4592,9 +4617,11 @@ export const createAgentExperience = (
         const closeButtonIconName = launcher.closeButtonIconName ?? "x";
         const closeButtonIconText = launcher.closeButtonIconText ?? "×";
 
-        // Clear existing content and render new icon
+        // Clear existing content and render new icon.
+        // Larger intrinsic size compensates for the X glyph's sparse
+        // viewBox so the close button visually matches sibling icons.
         closeButton.innerHTML = "";
-        const iconSvg = renderLucideIcon(closeButtonIconName, "20px", "currentColor", 2);
+        const iconSvg = renderLucideIcon(closeButtonIconName, "28px", "currentColor", 1);
         if (iconSvg) {
           closeButton.appendChild(iconSvg);
         } else {

package/src/utils/sequence-buffer.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { SequenceReorderBuffer } from "./sequence-buffer";
+
+describe("SequenceReorderBuffer", () => {
+  let emitted: Array<{ payloadType: string; payload: any }>;
+  let emitter: (payloadType: string, payload: any) => void;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    emitted = [];
+    emitter = (payloadType, payload) => {
+      emitted.push({ payloadType, payload });
+    };
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("passes in-order events through immediately", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    buf.push("step_delta", { seq: 1, text: "a" });
+    buf.push("step_delta", { seq: 2, text: "b" });
+    buf.push("step_delta", { seq: 3, text: "c" });
+
+    expect(emitted).toHaveLength(3);
+    expect(emitted[0].payload.text).toBe("a");
+    expect(emitted[1].payload.text).toBe("b");
+    expect(emitted[2].payload.text).toBe("c");
+    buf.destroy();
+  });
+
+  it("reorders leading out-of-order events (3, 1, 2 → 1, 2, 3)", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    // seq=3 arrives first — should be buffered (3 > nextExpected=1)
+    buf.push("step_delta", { seq: 3, text: "c" });
+    expect(emitted).toHaveLength(0);
+
+    // seq=1 arrives — matches nextExpected, emits, then drains seq=2 (not present), stops
+    buf.push("step_delta", { seq: 1, text: "a" });
+    expect(emitted).toHaveLength(1);
+    expect(emitted[0].payload.text).toBe("a");
+
+    // seq=2 arrives — matches nextExpected=2, emits, drains seq=3 from buffer
+    buf.push("step_delta", { seq: 2, text: "b" });
+    expect(emitted).toHaveLength(3);
+    expect(emitted[1].payload.text).toBe("b");
+    expect(emitted[2].payload.text).toBe("c");
+    buf.destroy();
+  });
+
+  it("reorders mid-stream out-of-order events", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    buf.push("step_delta", { seq: 1, text: "a" });
+    buf.push("step_delta", { seq: 3, text: "c" }); // buffered
+    buf.push("step_delta", { seq: 2, text: "b" }); // emits, drains 3
+
+    expect(emitted).toHaveLength(3);
+    expect(emitted[0].payload.text).toBe("a");
+    expect(emitted[1].payload.text).toBe("b");
+    expect(emitted[2].payload.text).toBe("c");
+    buf.destroy();
+  });
+
+  it("flushes buffered events after gap timeout when a seq is missing", () => {
+    const buf = new SequenceReorderBuffer(emitter, 50);
+    buf.push("step_delta", { seq: 1, text: "a" }); // emits
+    buf.push("step_delta", { seq: 3, text: "c" }); // buffered (waiting for seq 2)
+
+    expect(emitted).toHaveLength(1);
+
+    // Advance past gap timeout — seq=2 never arrives, flush seq=3 anyway
+    vi.advanceTimersByTime(60);
+
+    expect(emitted).toHaveLength(2);
+    expect(emitted[1].payload.text).toBe("c");
+    buf.destroy();
+  });
+
+  it("passes no-seq events through immediately (backward compat)", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    buf.push("flow_start", { flowId: "abc" });
+    buf.push("step_start", { name: "test" });
+
+    expect(emitted).toHaveLength(2);
+    expect(emitted[0].payload.flowId).toBe("abc");
+    expect(emitted[1].payload.name).toBe("test");
+    buf.destroy();
+  });
+
+  it("emits late/duplicate events (seq < nextExpected)", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    // Process seq 1-3 normally to advance nextExpected to 4
+    buf.push("step_delta", { seq: 1, text: "a" });
+    buf.push("step_delta", { seq: 2, text: "b" });
+    buf.push("step_delta", { seq: 3, text: "c" });
+    expect(emitted).toHaveLength(3);
+
+    // Now seq=1 arrives again — it's a duplicate (1 < nextExpected=4), still emitted
+    buf.push("step_delta", { seq: 1, text: "a-dup" });
+    expect(emitted).toHaveLength(4);
+    expect(emitted[3].payload.text).toBe("a-dup");
+    buf.destroy();
+  });
+
+  it("handles mixed seq and no-seq events", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    buf.push("step_delta", { seq: 1, text: "a" });
+    buf.push("status", { status: "streaming" }); // no seq
+    buf.push("step_delta", { seq: 2, text: "b" });
+    buf.push("error", { error: "oops" }); // no seq
+
+    expect(emitted).toHaveLength(4);
+    expect(emitted[0].payload.text).toBe("a");
+    expect(emitted[1].payload.status).toBe("streaming");
+    expect(emitted[2].payload.text).toBe("b");
+    expect(emitted[3].payload.error).toBe("oops");
+    buf.destroy();
+  });
+
+  it("handles large burst of out-of-order events correctly", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    // Send events in reverse order: 10, 9, 8, ..., 1
+    // All are buffered until seq=1 arrives (last), then everything drains
+    const seqs = [10, 9, 8, 7, 6, 5, 4, 3, 2, 1];
+    for (const seq of seqs) {
+      buf.push("step_delta", { seq, text: `chunk-${seq}` });
+    }
+
+    expect(emitted).toHaveLength(10);
+    const emittedTexts = emitted.map(e => e.payload.text);
+    expect(emittedTexts).toEqual([
+      "chunk-1", "chunk-2", "chunk-3", "chunk-4", "chunk-5",
+      "chunk-6", "chunk-7", "chunk-8", "chunk-9", "chunk-10"
+    ]);
+    buf.destroy();
+  });
+
+  it("handles scrambled arrival order", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    const scrambled = [1, 5, 3, 2, 4, 8, 6, 7, 10, 9];
+    for (const seq of scrambled) {
+      buf.push("step_delta", { seq, text: `chunk-${seq}` });
+    }
+
+    expect(emitted).toHaveLength(10);
+    const emittedTexts = emitted.map(e => e.payload.text);
+    expect(emittedTexts).toEqual([
+      "chunk-1", "chunk-2", "chunk-3", "chunk-4", "chunk-5",
+      "chunk-6", "chunk-7", "chunk-8", "chunk-9", "chunk-10"
+    ]);
+    buf.destroy();
+  });
+
+  it("no-seq event flushes pending buffer and cancels the gap timer", () => {
+    const buf = new SequenceReorderBuffer(emitter, 50);
+    buf.push("step_delta", { seq: 1, text: "a" });
+    buf.push("step_delta", { seq: 3, text: "c" }); // buffered, starts gap timer
+    expect(emitted).toHaveLength(1);
+
+    // A no-seq event triggers flushAll, which drains the buffer in seq order
+    // and cancels the gap timer.
+    buf.push("flow_complete", { flowId: "done" });
+    expect(emitted).toHaveLength(3); // a, c, flow_complete
+
+    // The gap timer must no longer fire after the flushAll.
+    vi.advanceTimersByTime(100);
+    expect(emitted).toHaveLength(3);
+    buf.destroy();
+  });
+
+  it("supports sequenceIndex as an alternative to seq", () => {
+    const buf = new SequenceReorderBuffer(emitter);
+    buf.push("reason_delta", { sequenceIndex: 1, text: "a" });
+    buf.push("reason_delta", { sequenceIndex: 3, text: "c" });
+    buf.push("reason_delta", { sequenceIndex: 2, text: "b" });
+
+    expect(emitted).toHaveLength(3);
+    expect(emitted[0].payload.text).toBe("a");
+    expect(emitted[1].payload.text).toBe("b");
+    expect(emitted[2].payload.text).toBe("c");
+    buf.destroy();
+  });
+
+  it("leading gap flushes via timeout when seq=1 never arrives", () => {
+    const buf = new SequenceReorderBuffer(emitter, 50);
+    // Only seq=2 and seq=3 arrive — seq=1 is missing
+    buf.push("step_delta", { seq: 2, text: "b" });
+    buf.push("step_delta", { seq: 3, text: "c" });
+    expect(emitted).toHaveLength(0); // both buffered
+
+    vi.advanceTimersByTime(50);
+    // Gap timer flushes in seq order
+    expect(emitted).toHaveLength(2);
+    expect(emitted[0].payload.text).toBe("b");
+    expect(emitted[1].payload.text).toBe("c");
+    buf.destroy();
+  });
+
+  it("handles a stream whose first seq is > 1 via the gap timeout (no loss)", () => {
+    // Defensive: if the server's counter ever starts above 1 (e.g. a resumed
+    // stream), the hardcoded nextExpectedSeq=1 would buffer the first event.
+    // The gap timer must still flush it so nothing is lost.
+    const buf = new SequenceReorderBuffer(emitter, 50);
+    buf.push("step_delta", { seq: 5, text: "first" });
+    buf.push("step_delta", { seq: 6, text: "second" });
+    expect(emitted).toHaveLength(0);
+
+    vi.advanceTimersByTime(50);
+
+    expect(emitted).toHaveLength(2);
+    expect(emitted[0].payload.text).toBe("first");
+    expect(emitted[1].payload.text).toBe("second");
+
+    // Subsequent in-order events should pass through immediately.
+    buf.push("step_delta", { seq: 7, text: "third" });
+    expect(emitted).toHaveLength(3);
+    expect(emitted[2].payload.text).toBe("third");
+    buf.destroy();
+  });
+
+  it("warns and emits both events on seq collision (does not silently drop)", () => {
+    // Server invariant: seq is unique per stream. If it's ever violated
+    // (bug, replay, mixed counters), Map.set would silently overwrite. The
+    // buffer must detect this, warn, and emit the prior event so nothing is
+    // dropped.
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const buf = new SequenceReorderBuffer(emitter, 50);
+
+    buf.push("step_delta", { seq: 1, text: "a" });
+    // seq=3 buffered, waiting for seq=2
+    buf.push("step_delta", { seq: 3, text: "first-at-3" });
+    expect(emitted).toHaveLength(1);
+
+    // Second event with same seq=3 — prior one should be emitted out-of-order
+    buf.push("reason_delta", { seq: 3, text: "second-at-3" });
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toContain("duplicate seq=3");
+    expect(warnSpy.mock.calls[0][0]).toContain("step_delta");
+    expect(warnSpy.mock.calls[0][0]).toContain("reason_delta");
+
+    // Prior event flushed immediately (out of seq order), nothing lost
+    expect(emitted).toHaveLength(2);
+    expect(emitted[1].payload.text).toBe("first-at-3");
+
+    // seq=2 arrives — advances nextExpected through the buffered second-at-3
+    buf.push("step_delta", { seq: 2, text: "b" });
+    expect(emitted).toHaveLength(4);
+    expect(emitted[2].payload.text).toBe("b");
+    expect(emitted[3].payload.text).toBe("second-at-3");
+
+    warnSpy.mockRestore();
+    buf.destroy();
+  });
+});

package/src/utils/sequence-buffer.ts

@@ -0,0 +1,130 @@
+type BufferedEvent = { payloadType: string; payload: any; seq: number };
+
+export class SequenceReorderBuffer {
+  private nextExpectedSeq: number | null = null;
+  private buffer: Map<number, BufferedEvent> = new Map();
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private emitter: (payloadType: string, payload: any) => void;
+  private gapTimeoutMs: number;
+
+  constructor(emitter: (payloadType: string, payload: any) => void, gapTimeoutMs = 50) {
+    this.emitter = emitter;
+    this.gapTimeoutMs = gapTimeoutMs;
+  }
+
+  push(payloadType: string, payload: any): void {
+    // All three fields are sourced from the same FlowExecutionEngine.sequenceCounter:
+    //   - `seq`: step_delta, text_start, text_end, agent_* events (top-level)
+    //   - `sequenceIndex`: reason_start, reason_delta, reason_complete, source
+    //   - `agentContext.seq`: tool_start, tool_delta, tool_complete (agent loop)
+    const seq = payload?.seq ?? payload?.sequenceIndex ?? payload?.agentContext?.seq;
+
+    // No seq field — emit immediately (backward compat).
+    // If there are buffered events waiting for a gap to fill, flush them
+    // first: the server sending an unsequenced event means it has moved on
+    // and the missing seq numbers are not coming.
+    if (seq === undefined || seq === null) {
+      if (this.buffer.size > 0) {
+        this.flushAll();
+      }
+      this.emitter(payloadType, payload);
+      return;
+    }
+
+    // Server's sequenceCounter resets to 0 on each execution and pre-increments,
+    // so the first sequenced event in any stream is expected to have seq=1.
+    // If a server ever starts at a different number (e.g. a resumed stream),
+    // the 50ms gap timer below is the safety net: the first event gets
+    // buffered, then flushed after the gap elapses. Correctness is preserved;
+    // the only cost is a one-time latency on the leading event.
+    if (this.nextExpectedSeq === null) {
+      this.nextExpectedSeq = 1;
+    }
+
+    // If this is the expected event, emit it and drain consecutive buffered events
+    if (seq === this.nextExpectedSeq) {
+      this.emitter(payloadType, payload);
+      this.nextExpectedSeq = (seq as number) + 1;
+      this.drainConsecutive();
+      return;
+    }
+
+    // If seq < nextExpected, it's a duplicate or late arrival — emit anyway (don't drop)
+    if (seq < this.nextExpectedSeq!) {
+      this.emitter(payloadType, payload);
+      return;
+    }
+
+    // seq > nextExpected — buffer it and start gap timer.
+    // If another event with the same seq is already buffered, the server
+    // broke its "seq is unique per stream" invariant. Rather than silently
+    // overwrite (losing one event) or swallow the new one, emit the prior
+    // event immediately — out of order, but better than dropping it — and
+    // warn so the issue is visible.
+    const existing = this.buffer.get(seq);
+    if (existing !== undefined) {
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(
+          `[persona] SequenceReorderBuffer: duplicate seq=${seq} ` +
+            `(${existing.payloadType} vs ${payloadType}); ` +
+            `emitting earlier event out-of-order to avoid loss`
+        );
+      }
+      this.emitter(existing.payloadType, existing.payload);
+    }
+    this.buffer.set(seq, { payloadType, payload, seq });
+    this.startGapTimer();
+  }
+
+  private drainConsecutive(): void {
+    while (this.buffer.has(this.nextExpectedSeq!)) {
+      const event = this.buffer.get(this.nextExpectedSeq!)!;
+      this.buffer.delete(this.nextExpectedSeq!);
+      this.emitter(event.payloadType, event.payload);
+      this.nextExpectedSeq!++;
+    }
+    // If buffer is empty, clear the gap timer
+    if (this.buffer.size === 0) {
+      this.clearGapTimer();
+    }
+  }
+
+  private startGapTimer(): void {
+    if (this.flushTimer !== null) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushAll();
+    }, this.gapTimeoutMs);
+  }
+
+  private clearGapTimer(): void {
+    if (this.flushTimer !== null) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+
+  private flushAll(): void {
+    this.clearGapTimer();
+    if (this.buffer.size === 0) return;
+
+    // Flush all buffered events in seq order
+    const sorted = [...this.buffer.entries()].sort((a, b) => a[0] - b[0]);
+    for (const [seq, event] of sorted) {
+      this.buffer.delete(seq);
+      this.emitter(event.payloadType, event.payload);
+    }
+    // Update nextExpectedSeq to after the last flushed
+    if (sorted.length > 0) {
+      this.nextExpectedSeq = sorted[sorted.length - 1][0] + 1;
+    }
+  }
+
+  destroy(): void {
+    this.clearGapTimer();
+    this.buffer.clear();
+  }
+
+  flushPending(): void {
+    this.flushAll();
+  }
+}