@omercnet/paseo-shared-browser 1.2.2 → 2.0.0-next.249.1

package/server/live-input-supervisor.test.ts

@@ -0,0 +1,147 @@
+import { expect, it } from "vitest";
+import { browserStateSchema } from "../shared/browser";
+import type { JsonValue, RuntimeRequest } from "./runtime-protocol";
+import { RuntimeSupervisor } from "./supervisor";
+
+/** Exercise the immutable supervisor's human RPC path without a plugin or browser process. */
+it("routes validated human gestures, fences replaced plugin bridges and never exposes live gesture operations to agent tickets", async () => {
+  const calls: string[] = [];
+  const supervisor = new RuntimeSupervisor({
+    owner: {
+      create: async () => ({ runtimeId: "r".repeat(32) }),
+      request: async (_runtime, operation) => {
+        calls.push(operation);
+        if (operation === "identity") return { userAgent: "Fixture Chromium" };
+        if (operation === "state")
+          return {
+            url: "https://fixture.invalid",
+            title: "Fixture",
+            canGoBack: false,
+            canGoForward: false,
+            inputGeneration: "0:0",
+          };
+        if (operation === "frame")
+          return {
+            dataBase64: "eA==",
+            byteLength: 1,
+            width: 1280,
+            height: 800,
+            capturedAt: new Date().toISOString(),
+          };
+        if (operation === "cursor") return "pointer";
+        return null;
+      },
+      stop: async () => {},
+    },
+  });
+  const lease = supervisor.claimBridge("bridge");
+  const request = async (
+    operation: string,
+    input: unknown,
+    epoch = lease.epoch,
+    bridgeId = "bridge",
+  ) =>
+    supervisor.dispatch({
+      version: 3,
+      id: "request",
+      token: "unused-by-direct-fixture",
+      bridgeId,
+      epoch,
+      method: "browser.request",
+      operation,
+      input: input as JsonValue,
+    });
+  try {
+    const attached = (await request("attach", {
+      workspaceId: "workspace",
+      viewerLabel: "Viewer",
+    })) as { viewerToken: string };
+    const acquired = (await request("acquire-control", { viewerToken: attached.viewerToken })) as {
+      controlToken: string;
+    };
+    const capture = (await request("capture", { viewerToken: attached.viewerToken })) as {
+      state: unknown;
+      frame: { frameId: string };
+    };
+    const state = browserStateSchema.parse(capture.state);
+    const expected = {
+      sessionId: state.sessionId,
+      runtimeId: state.runtimeId!,
+      bridgeEpoch: state.bridgeEpoch!,
+      navigationGeneration: state.navigationGeneration,
+      viewportGeneration: state.viewportGeneration,
+    };
+    const context = {
+      viewerToken: attached.viewerToken,
+      controlToken: acquired.controlToken,
+      expected,
+    };
+    const target = {
+      frameId: capture.frame.frameId,
+      navigationGeneration: state.navigationGeneration,
+      viewportGeneration: state.viewportGeneration,
+    };
+    const begun = (await request("gesture.begin", {
+      ...context,
+      target,
+      pointerKind: "mouse",
+    })) as { gestureId: string; nextSequence: number };
+    await request("gesture.update", {
+      ...context,
+      gestureId: begun.gestureId,
+      sequence: 1,
+      event: {
+        kind: "key",
+        type: "down",
+        key: "Control",
+        code: "ControlLeft",
+        modifiers: 2,
+        repeat: false,
+      },
+    });
+    expect(calls.filter((value) => value === "input.key")).toHaveLength(1);
+    const afterKey = (await request("capture", { viewerToken: attached.viewerToken })) as {
+      frame: { frameId: string };
+    };
+    await request("gesture.update", {
+      ...context,
+      gestureId: begun.gestureId,
+      sequence: 2,
+      target: { ...target, frameId: afterKey.frame.frameId },
+      event: { kind: "down", point: { x: 10, y: 20, width: 1280, height: 800 } },
+    });
+    expect(calls.filter((value) => value === "mouse.down")).toHaveLength(1);
+    await expect(
+      request("gesture.update", {
+        ...context,
+        gestureId: begun.gestureId,
+        sequence: 3,
+        event: {
+          kind: "scroll",
+          point: { x: 10, y: 20, width: 1280, height: 800 },
+          deltaX: 0,
+          deltaY: Infinity,
+        },
+      }),
+    ).rejects.toThrow();
+    supervisor.claimBridge("replacement", true);
+    await expect(
+      request("gesture.end", { ...context, gestureId: begun.gestureId, sequence: 1, cancel: true }),
+    ).rejects.toThrow("lease");
+    // The old channel's supervisor-side cleanup still reaches its owned runtime.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(calls.filter((value) => value === "input.end")).toHaveLength(1);
+    await expect(
+      supervisor.dispatch({
+        version: 3,
+        id: "request",
+        method: "agent.request",
+        ticket: "invalid",
+        operation: "gesture.begin",
+        input: {},
+      } as unknown as RuntimeRequest),
+    ).rejects.toThrow();
+  } finally {
+    await supervisor.stopAll();
+  }
+});

package/server/mcp-entry.ts

@@ -3,13 +3,13 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { browserTabIdSchema } from "../shared/browser";
+import { MAX_AGENT_VIEWPORT as MAX_VIEWPORT, MIN_VIEWPORT } from "../shared/viewport-limits";
 import type { JsonValue } from "./runtime-protocol";
 import { resolveSupervisorPaths } from "./supervisor";
 import { AgentSupervisorClient } from "./supervisor-client";
 
 const TICKET_ENV = "PASEO_SHARED_BROWSER_TICKET";
-const MIN_VIEWPORT = { width: 320, height: 480 } as const;
-const MAX_VIEWPORT = { width: 1600, height: 1200 } as const;
 
 const pointSchema = z.object({
   x: z.number().finite().nonnegative(),
@@ -130,6 +130,48 @@ async function main(): Promise<void> {
     },
   );
 
+  server.registerTool(
+    "shared_browser_tabs",
+    {
+      description: "List tabs in this agent's workspace and identify this agent's selected tab.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: true, idempotentHint: true },
+    },
+    async () => textResult(await client.request("tabs.list", {})),
+  );
+
+  server.registerTool(
+    "shared_browser_tab_open",
+    {
+      description: "Open and select a new tab in the shared browser profile for this agent only.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async () => textResult(await client.request("tabs.create", {})),
+  );
+
+  server.registerTool(
+    "shared_browser_tab_select",
+    {
+      description:
+        "Select an existing tab for this agent only. Capture its current frame before sending input.",
+      inputSchema: z.object({ tabId: browserTabIdSchema }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ tabId }) => textResult(await client.request("tabs.select", { tabId })),
+  );
+
+  server.registerTool(
+    "shared_browser_tab_close",
+    {
+      description:
+        "Close this agent's selected and controlled tab for every viewer. Other tabs remain open.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+    },
+    async () => textResult(await client.request("tabs.close", {})),
+  );
+
   server.registerTool(
     "shared_browser_acquire_control",
     {

package/server/native-video-backpressure.test.ts

@@ -0,0 +1,228 @@
+/** Exercise producer backpressure using the actual shipped helper program.
+ * Unencoded source skips preserve intact dependencies; lost encoded output still
+ * requires a key. Delayed outputs/ACKs model ordinary codec and relay pressure.
+ */
+import { createContext, runInContext } from "node:vm";
+import { expect, it } from "vitest";
+import { NATIVE_VIDEO_EXTENSION_SOURCE } from "./native-video-extension-source";
+
+/** Delayed native codec output and ACKs, with the shipped trusted program unmodified. */
+async function fixture(failFirstEncoder = false) {
+  const packets: { sequence: number; type: string; timestampUs: number }[] = [];
+  let deliver: (result: unknown) => void = () => {};
+  const reader = {
+    read: () =>
+      new Promise((resolve) => {
+        deliver = resolve;
+      }),
+    cancel: async () => deliver({ done: true }),
+  };
+  const pending: { timestamp: number; type: string }[] = [];
+  const encoded: { timestamp: number; keyFrame: boolean }[] = [];
+  let encoder: Encoder;
+  const instances: Encoder[] = [];
+  class Encoder {
+    static async isConfigSupported(candidate: unknown) {
+      return { supported: true, config: candidate };
+    }
+    encodeQueueSize = 0;
+    constructor(readonly callbacks: { output(chunk: unknown, metadata: unknown): void }) {
+      encoder = this;
+      instances.push(this);
+    }
+    configure() {}
+    reset() {}
+    close() {}
+    encode(frame: { timestamp: number }, options: { keyFrame: boolean }) {
+      if (failFirstEncoder && this === instances[0]) throw new Error("Codec stopped");
+      this.encodeQueueSize++;
+      encoded.push({ timestamp: frame.timestamp, keyFrame: options.keyFrame });
+      pending.push({ timestamp: frame.timestamp, type: options.keyFrame ? "key" : "delta" });
+    }
+    output() {
+      const value = pending.shift();
+      if (!value) throw new Error("No queued fixture frame");
+      this.encodeQueueSize--;
+      this.callbacks.output(
+        { ...value, byteLength: 10, copyTo: (bytes: Uint8Array) => bytes.fill(1) },
+        {},
+      );
+    }
+  }
+  const context = createContext({
+    chrome: {
+      debugger: { getTargets: async () => [{ id: "exact", type: "page", tabId: 7 }] },
+      tabCapture: { getMediaStreamId: async () => "stream" },
+    },
+    navigator: {
+      mediaDevices: {
+        getUserMedia: async () => ({
+          getVideoTracks: () => [{ getSettings: () => ({ width: 320, height: 240 }) }],
+          getTracks: () => [{ stop() {} }],
+        }),
+      },
+    },
+    MediaStreamTrackProcessor: class {
+      readable = { getReader: () => reader };
+    },
+    VideoEncoder: Encoder,
+    nativeVideoPacket: (json: string) => packets.push(JSON.parse(json)),
+    performance: { now: () => 100 },
+    Uint8Array,
+    Map,
+    Set,
+    Object,
+    JSON,
+    Number,
+    btoa: (value: string) => Buffer.from(value, "binary").toString("base64"),
+  });
+  runInContext(NATIVE_VIDEO_EXTENSION_SOURCE, context);
+  await runInContext('startCapture("exact",320,240,1)', context);
+  await runInContext('addEncoder("high","stream",12000000,30)', context);
+  if (failFirstEncoder) {
+    await runInContext('addEncoder("low","healthy",2000000,30)', context);
+  }
+  const turn = () => new Promise<void>((resolve) => setImmediate(resolve));
+  return {
+    packets,
+    encoded,
+    async frame(timestamp: number) {
+      deliver({
+        value: { timestamp, displayWidth: 320, displayHeight: 240, close() {} },
+        done: false,
+      });
+      await turn();
+    },
+    output: () => encoder!.output(),
+    ack: () =>
+      runInContext(
+        'for(const p of fixturePackets) acknowledge("stream",p.sequence)',
+        Object.assign(context, { fixturePackets: packets }),
+      ),
+    request: () => runInContext('requestKeyFrame("high")', context),
+    stop: () => runInContext("stopCapture()", context),
+  };
+}
+
+it("preserves encoded deltas during source backpressure with no extra recovery key", async () => {
+  const f = await fixture();
+  try {
+    await f.frame(0);
+    f.output();
+    f.ack();
+    await f.frame(33333);
+    await f.frame(66666);
+    await f.frame(99999);
+    expect(f.encoded).toHaveLength(3);
+    f.output();
+    f.output();
+    f.ack();
+    await f.frame(133332);
+    f.output();
+    expect(f.packets.map((p) => [p.timestampUs, p.type])).toEqual([
+      [0, "key"],
+      [33333, "delta"],
+      [66666, "delta"],
+      [133332, "delta"],
+    ]);
+    expect(f.encoded.filter((e) => e.keyFrame)).toHaveLength(1);
+  } finally {
+    await f.stop();
+  }
+});
+
+it("keeps two-packet ACK pressure bounded without restarting an intact codec chain", async () => {
+  const f = await fixture();
+  try {
+    await f.frame(0);
+    f.output();
+    await f.frame(33333);
+    f.output();
+    await f.frame(66666);
+    expect(f.encoded).toHaveLength(2);
+    f.ack();
+    await f.frame(99999);
+    f.output();
+    expect(f.packets.map((packet) => packet.type)).toEqual(["key", "delta", "delta"]);
+    expect(f.encoded.filter((entry) => entry.keyFrame)).toHaveLength(1);
+  } finally {
+    await f.stop();
+  }
+});
+
+it("adds a requested key without suppressing an intact pending delta", async () => {
+  const f = await fixture();
+  try {
+    await f.frame(0);
+    f.output();
+    f.ack();
+    await f.frame(33333);
+    f.request();
+    f.output();
+    await f.frame(66666);
+    f.output();
+    expect(f.packets.map((p) => p.type)).toEqual(["key", "delta", "key"]);
+  } finally {
+    await f.stop();
+  }
+});
+
+it("still suppresses dependencies after an actual encoded output is dropped", async () => {
+  const f = await fixture();
+  try {
+    await f.frame(0);
+    f.output();
+    f.ack();
+    await f.frame(33333);
+    await f.frame(66666);
+    f.output();
+    await f.frame(99999);
+    f.output();
+    f.output();
+    expect(f.packets.map((p) => p.timestampUs)).toEqual([0, 33333, 66666]);
+    f.ack();
+    await f.frame(133332);
+    f.output();
+    expect(f.packets.at(-1)?.type).toBe("key");
+  } finally {
+    await f.stop();
+  }
+});
+
+it("shipped packet conversion is exact with native and legacy byte APIs", () => {
+  for (const native of [true, false]) {
+    const context = createContext({
+      btoa: (value: string) => Buffer.from(value, "binary").toString("base64"),
+    });
+    runInContext(NATIVE_VIDEO_EXTENSION_SOURCE, context);
+    if (!native) runInContext("Uint8Array.prototype.toBase64 = undefined", context);
+    for (const size of [0, 1, 2, 65537, 1048576]) {
+      const value = runInContext(
+        `bytes64(Uint8Array.from({length:${size}},(_,i)=>(i*17+13)%256))`,
+        context,
+      );
+      const expected = Buffer.alloc(size);
+      for (let i = 0; i < size; i += 1) expected[i] = (i * 17 + 13) % 256;
+      expect(value).toBe(expected.toString("base64"));
+    }
+  }
+});
+
+it("isolates synchronous encoder failure while a healthy peer keeps receiving frames", async () => {
+  const f = await fixture(true);
+  try {
+    await f.frame(0);
+    f.output();
+    f.ack();
+    await f.frame(33333);
+    f.output();
+    expect(f.packets).toContainEqual({ error: "Native video encoder stopped", streamId: "stream" });
+    expect(f.packets).not.toContainEqual({ error: "Native video capture stopped" });
+    expect(f.packets.filter((packet) => packet.type).map((packet) => packet.type)).toEqual([
+      "key",
+      "delta",
+    ]);
+  } finally {
+    await f.stop();
+  }
+});

package/server/native-video-buffer.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { createNativeVideoBuffer, videoSourceTime } from "./native-video-buffer";
+import type { RuntimeVideoPacket } from "./native-video-packet";
+
+const packet = (
+  sequence: number,
+  type: "key" | "delta" = "delta",
+  capturedAt = 1000,
+): RuntimeVideoPacket => ({
+  streamId: "stream",
+  captureGeneration: 1,
+  sequence,
+  type,
+  timestampUs: 1000000 + sequence,
+  codec: "vp8",
+  width: 1280,
+  height: 800,
+  dataBase64: Buffer.from("owned-packet").toString("base64"),
+  capturedAt: new Date(capturedAt).toISOString(),
+  capturedAtMonotonicMs: capturedAt,
+});
+describe("native encoded receipt buffer", () => {
+  it("maps actual TimeTicks age instead of refreshing a delayed packet", () => {
+    const clock = { sourceMs: 112000000, monotonicMs: 500, wallMs: 2000 };
+    expect(videoSourceTime(112000100000, clock, 700, 2200)).toEqual({
+      capturedAt: new Date(2100).toISOString(),
+      capturedAtMonotonicMs: 600,
+    });
+    expect(videoSourceTime(112000100000, clock, 1701, 2200)).toBeNull();
+    expect(videoSourceTime(112001000000, clock, 700, 2200)).toBeNull();
+  });
+  it("does not bootstrap a decoder from an arbitrary delta", () => {
+    const buffer = createNativeVideoBuffer();
+    buffer.add(packet(1));
+    expect(buffer.read(0, 1100)).toEqual([]);
+    buffer.add(packet(2, "key"));
+    buffer.add(packet(3));
+    expect(buffer.read(0, 1100).map((p) => p.sequence)).toEqual([2, 3]);
+  });
+  it("lost output suppresses dependent deltas until a keyframe", () => {
+    const buffer = createNativeVideoBuffer();
+    buffer.add(packet(1, "key"));
+    buffer.add(packet(3));
+    buffer.add(packet(4));
+    expect(buffer.read(1, 1100)).toEqual([]);
+    buffer.add(packet(5, "key"));
+    buffer.add(packet(6));
+    expect(buffer.read(1, 1100).map((p) => p.sequence)).toEqual([5, 6]);
+  });
+  it("never relabels or returns source frames beyond one second", () => {
+    const buffer = createNativeVideoBuffer();
+    buffer.add(packet(1, "key"));
+    expect(buffer.read(0, 2000)[0]?.capturedAt).toBe(new Date(1000).toISOString());
+    expect(buffer.read(0, 2001)).toEqual([]);
+  });
+  it("bounds slow consumers and restarts from a retained keyframe", () => {
+    const buffer = createNativeVideoBuffer();
+    for (let i = 1; i <= 80; i++) buffer.add(packet(i, i % 10 === 0 ? "key" : "delta"));
+    const result = buffer.read(0, 1100);
+    expect(result.length).toBeLessThanOrEqual(32);
+    expect(result[0]?.type).toBe("key");
+    expect(result.at(-1)?.sequence).toBe(80);
+  });
+  it("signals recovery for a missing key, but not ordinary waiting on a valid chain", () => {
+    const buffer = createNativeVideoBuffer();
+    expect(buffer.needsKeyFrame(0, 1100)).toBe(false);
+    buffer.add(packet(1, "key"));
+    expect(buffer.needsKeyFrame(1, 1100)).toBe(false);
+    buffer.add(packet(3));
+    expect(buffer.needsKeyFrame(1, 1100)).toBe(true);
+    buffer.add(packet(4, "key"));
+    expect(buffer.needsKeyFrame(1, 1100)).toBe(false);
+    expect(buffer.needsKeyFrame(4, 2101)).toBe(false);
+    expect(buffer.needsKeyFrame(0, 2101)).toBe(true);
+  });
+  it("requests a bootstrap key after ring eviction without disturbing a current decoder", () => {
+    const buffer = createNativeVideoBuffer();
+    buffer.add(packet(1, "key"));
+    for (let sequence = 2; sequence <= 40; sequence++) buffer.add(packet(sequence));
+    expect(buffer.read(0, 1100)).toEqual([]);
+    expect(buffer.needsKeyFrame(0, 1100)).toBe(true);
+    expect(buffer.needsKeyFrame(39, 1100)).toBe(false);
+    expect(buffer.read(39, 1100).map((item) => item.sequence)).toEqual([40]);
+  });
+  it("a document barrier clears queued pixels without recycling sequence authority", () => {
+    const buffer = createNativeVideoBuffer();
+    buffer.add(packet(1, "key"));
+    buffer.clear();
+    buffer.add(packet(2));
+    expect(buffer.read(0, 1100)).toEqual([]);
+    buffer.add(packet(3, "key"));
+    expect(buffer.read(0, 1100).map((p) => p.sequence)).toEqual([3]);
+  });
+});
+
+it("sends the latest complete key chain instead of an obsolete multi-megabyte backlog", () => {
+  const buffer = createNativeVideoBuffer();
+  const large = (sequence: number, type: "key" | "delta") => ({
+    ...packet(sequence, type),
+    dataBase64: Buffer.alloc(type === "key" ? 512 * 1024 : 128 * 1024, sequence).toString("base64"),
+  });
+  buffer.add(large(1, "key"));
+  for (let sequence = 2; sequence <= 24; sequence++) buffer.add(large(sequence, "delta"));
+  buffer.add(large(25, "key"));
+  buffer.add(large(26, "delta"));
+  for (const after of [0, 1, 12, 24]) {
+    const selected = buffer.read(after, 1100);
+    expect(selected.map((value) => value.sequence)).toEqual([25, 26]);
+    expect(
+      selected.reduce((bytes, value) => bytes + Buffer.byteLength(value.dataBase64, "base64"), 0),
+    ).toBe(640 * 1024);
+    expect(buffer.needsKeyFrame(after, 1100)).toBe(false);
+  }
+  // Fast and slow viewers have independent cursors; no arbitrary delta skips.
+  expect(buffer.read(25, 1100).map((value) => value.sequence)).toEqual([26]);
+  expect(buffer.read(26, 1100)).toEqual([]);
+});
+
+it("never catches up across a delta dependency without a newer complete key", () => {
+  const buffer = createNativeVideoBuffer();
+  buffer.add(packet(1, "key"));
+  for (let sequence = 2; sequence <= 20; sequence++) buffer.add(packet(sequence));
+  expect(buffer.read(1, 1100).map((value) => value.sequence)).toEqual(
+    Array.from({ length: 19 }, (_, i) => i + 2),
+  );
+});
+
+it.each([-75_000, 75_000])(
+  "retains source age rather than calibration wall time after a %i ms correction",
+  (jump) => {
+    const clock = { sourceMs: 112000000, monotonicMs: 500 };
+    const time = videoSourceTime(112000100000, clock, 700, 2200 + jump)!;
+    expect(time.capturedAtMonotonicMs).toBe(600);
+    expect(Date.parse(time.capturedAt)).toBe(2100 + jump);
+    const buffer = createNativeVideoBuffer();
+    buffer.add({ ...packet(1, "key"), ...time });
+    expect(buffer.read(0, 700)).toHaveLength(1);
+    expect(buffer.read(0, 1601)).toEqual([]);
+    expect(videoSourceTime(112000100000, clock, 1701, 2200 + jump)).toBeNull();
+  },
+);

package/server/native-video-buffer.ts

@@ -0,0 +1,114 @@
+/** Bounded per-encoder packet history. Gaps return a fresh keyframe, never a broken delta chain. */
+import {
+  VIDEO_MAX_BATCH_BYTES,
+  VIDEO_MAX_BATCH_PACKETS,
+  VIDEO_SOURCE_CLOCK_TOLERANCE_MS,
+} from "../shared/browser-video";
+import type { RuntimeVideoPacket } from "./native-video-packet";
+export const NATIVE_VIDEO_MAX_AGE_MS = 1000;
+const MAX_RING_BYTES = 8 * 1024 * 1024;
+export interface VideoSourceClock {
+  sourceMs: number;
+  monotonicMs: number;
+}
+/** Map Chromium TimeTicks into Node elapsed time and validate source age.
+ * Wall-clock corrections affect outward metadata only, never retained freshness. */
+export function videoSourceTime(
+  timestampUs: number,
+  clock: VideoSourceClock,
+  nowMonotonicMs: number,
+  nowWallMs: number,
+): Pick<RuntimeVideoPacket, "capturedAt" | "capturedAtMonotonicMs"> | null {
+  const elapsedMs = timestampUs / 1000 - clock.sourceMs;
+  const capturedAtMonotonicMs = clock.monotonicMs + elapsedMs;
+  const ageMs = nowMonotonicMs - capturedAtMonotonicMs;
+  if (
+    !Number.isFinite(ageMs) ||
+    ageMs < -VIDEO_SOURCE_CLOCK_TOLERANCE_MS ||
+    ageMs > NATIVE_VIDEO_MAX_AGE_MS
+  )
+    return null;
+  // Wall time is presentation metadata only. Calibrating it once would make
+  // NTP/WSL clock corrections turn fresh pixels into future or expired frames.
+  return {
+    capturedAt: new Date(nowWallMs - ageMs).toISOString(),
+    capturedAtMonotonicMs,
+  };
+}
+/** Retain source receipts with dependency-safe cursors. Read clocks are Node elapsed milliseconds. */
+export function createNativeVideoBuffer() {
+  let packets: RuntimeVideoPacket[] = [];
+  let bytes = 0;
+  let lastSequence = 0;
+  let needsKey = true;
+  const size = (packet: RuntimeVideoPacket) => Buffer.byteLength(packet.dataBase64, "base64");
+  return {
+    /** Caller already validated identity/source age. A missing sequence suppresses dependent deltas. */
+    add(packet: RuntimeVideoPacket): boolean {
+      if (packet.sequence <= lastSequence) return false;
+      if (lastSequence && packet.sequence !== lastSequence + 1) needsKey = true;
+      lastSequence = packet.sequence;
+      if (needsKey && packet.type !== "key") return false;
+      if (packet.type === "key") needsKey = false;
+      packets.push(packet);
+      bytes += size(packet);
+      while (packets.length > VIDEO_MAX_BATCH_PACKETS || bytes > MAX_RING_BYTES) {
+        const removed = packets.shift();
+        if (removed) bytes -= size(removed);
+      }
+      return true;
+    },
+    clear(): void {
+      packets = [];
+      bytes = 0;
+      needsKey = true;
+    },
+    /** Ask for a fresh key only when this reader cannot recover its retained chain.
+     * No observed packet yet and an up-to-date decoder waiting for its next delta
+     * are ordinary waiting, not reasons to generate repeated recovery keys. */
+    needsKeyFrame(afterSequence: number, nowMonotonicMs: number): boolean {
+      if (!lastSequence) return false;
+      if (needsKey) return true;
+      const fresh = packets.filter(
+        (packet) =>
+          nowMonotonicMs - packet.capturedAtMonotonicMs >= -VIDEO_SOURCE_CLOCK_TOLERANCE_MS &&
+          nowMonotonicMs - packet.capturedAtMonotonicMs <= NATIVE_VIDEO_MAX_AGE_MS,
+      );
+      const first = fresh[0];
+      if (!first) return afterSequence < lastSequence;
+      if (afterSequence === 0 || afterSequence < first.sequence - 1) {
+        return !fresh.some((packet) => packet.type === "key");
+      }
+      return false;
+    },
+    /** Returning no packet is honest when all retained source receipts are older than one second. */
+    read(afterSequence: number, nowMonotonicMs: number): RuntimeVideoPacket[] {
+      let candidates = packets.filter(
+        (packet) =>
+          nowMonotonicMs - packet.capturedAtMonotonicMs >= -VIDEO_SOURCE_CLOCK_TOLERANCE_MS &&
+          nowMonotonicMs - packet.capturedAtMonotonicMs <= NATIVE_VIDEO_MAX_AGE_MS,
+      );
+      const first = candidates[0];
+      if (!first) return [];
+      candidates = candidates.filter((packet) => packet.sequence > afterSequence);
+      // An independently decodable newer key supersedes all earlier pictures.
+      // Catch up before serialization/transport instead of sending a stale GOP.
+      // Never skip an arbitrary delta: its successor can depend on that picture.
+      const keyIndex = candidates.findLastIndex((packet) => packet.type === "key");
+      if (keyIndex >= 0) {
+        candidates = candidates.slice(keyIndex);
+      } else if (afterSequence < first.sequence - 1 || afterSequence === 0) {
+        return [];
+      }
+      let batchBytes = 0;
+      const batch: RuntimeVideoPacket[] = [];
+      for (const packet of candidates) {
+        const packetBytes = size(packet);
+        if (batchBytes + packetBytes > VIDEO_MAX_BATCH_BYTES) break;
+        batchBytes += packetBytes;
+        batch.push(packet);
+      }
+      return batch;
+    },
+  };
+}