@omercnet/paseo-shared-browser 1.2.2 → 2.0.0

package/server/runtime-video.test.ts

@@ -0,0 +1,444 @@
+import { EventEmitter } from "node:events";
+import { performance } from "node:perf_hooks";
+import { describe, expect, it, vi } from "vitest";
+
+const fixture = vi.hoisted(() => ({
+  captures: [] as {
+    options: unknown;
+    idleExpired: boolean;
+    sourceFailure: "startup" | "source-stopped" | "source-reset" | "source-dimensions" | null;
+    read: ReturnType<typeof vi.fn>;
+    stop: ReturnType<typeof vi.fn>;
+    invalidateQueuedFrames: ReturnType<typeof vi.fn>;
+  }[],
+}));
+vi.mock("./native-video-capture", () => ({
+  NativeVideoCapture: class {
+    options: unknown;
+    idleExpired = false;
+    sourceFailure: "startup" | "source-stopped" | "source-reset" | "source-dimensions" | null =
+      null;
+    read = vi.fn(async () => ({ status: "ready", streamId: "stream", packets: [] }));
+    stop = vi.fn(async () => {});
+    invalidateQueuedFrames = vi.fn();
+    constructor(options: unknown) {
+      this.options = options;
+      fixture.captures.push(this);
+    }
+  },
+}));
+
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+
+function setup() {
+  fixture.captures = [];
+  const runtime = new AgentBrowserRuntime({
+    nativeVideo: true,
+    binaryPath: "/tmp/owned-bin",
+    executablePath: "/tmp/owned-chrome",
+    profilePath: "/tmp/owned-profile",
+    ipcDirectory: "/tmp/owned-ipc",
+    session: "fixture",
+  });
+  const internal = runtime as unknown as {
+    page: unknown;
+    connection: unknown;
+    viewport: unknown;
+    emulationAppliedPage: unknown;
+    attachmentGeneration: number;
+    documentGeneration: number;
+    restoreConfiguredEmulation(page: unknown): Promise<void>;
+    assertVersion(): Promise<void>;
+    connectCdp(): Promise<void>;
+    invoke(args: string[]): Promise<unknown>;
+  };
+  const connection = Object.assign(new EventEmitter(), { isOpen: true, close: vi.fn() });
+  const page = Object.assign(new EventEmitter(), {
+    connection,
+    targetId: "exact",
+    send: vi.fn(async (method: string): Promise<unknown> => {
+      if (method === "Page.getFrameTree") {
+        return { frameTree: { frame: { id: "root", loaderId: "prior-loader" } } };
+      }
+      if (method === "Page.reload") {
+        // Real reload admission observes a fresh main-frame commit, which may
+        // arrive before the ACK. No DOM readiness is needed for this barrier.
+        page.emit("Page.frameNavigated", {
+          frame: { id: "root", loaderId: "reload-loader", url: "https://fixture.invalid/" },
+        });
+      }
+      return {};
+    }),
+  });
+  internal.connection = connection;
+  internal.page = page;
+  internal.emulationAppliedPage = page;
+  internal.viewport = {
+    width: 412,
+    height: 839,
+    captureScale: 2,
+    deviceScaleFactor: 3,
+    mobile: true,
+    touch: true,
+  };
+  return { runtime, internal, page, connection };
+}
+describe("native video runtime fence", () => {
+  it.each(["startup", "source-stopped", "source-reset"] as const)(
+    "retires %s failure under continued demand and retries only after cooldown",
+    async (failure) => {
+      vi.useFakeTimers();
+      const clock = vi.spyOn(performance, "now").mockImplementation(() => Date.now());
+      const { runtime } = setup();
+      try {
+        await runtime.readVideo({ quality: "high", waitMs: 0 });
+        const former = fixture.captures[0]!;
+        former.sourceFailure = failure;
+        expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("reset");
+        expect(former.stop).toHaveBeenCalledOnce();
+        for (let i = 0; i < 20; i++) await runtime.readVideo({ quality: "high", waitMs: 0 });
+        expect(fixture.captures).toHaveLength(1);
+        await vi.advanceTimersByTimeAsync(2999);
+        await runtime.readVideo({ quality: "high", waitMs: 0 });
+        expect(fixture.captures).toHaveLength(1);
+        await vi.advanceTimersByTimeAsync(1);
+        expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("ready");
+        expect(fixture.captures).toHaveLength(2);
+      } finally {
+        await runtime.stopVideo();
+        clock.mockRestore();
+        vi.useRealTimers();
+      }
+    },
+  );
+
+  it("never retries a permanent size failure for the same viewport, including after navigation", async () => {
+    vi.useFakeTimers();
+    const clock = vi.spyOn(performance, "now").mockImplementation(() => Date.now());
+    const { runtime, internal } = setup();
+    try {
+      internal.viewport = {
+        width: 412,
+        height: 839,
+        captureScale: 1,
+        deviceScaleFactor: 2.625,
+        mobile: true,
+        touch: true,
+      };
+      await runtime.readVideo({ quality: "high", waitMs: 0 });
+      expect(fixture.captures[0]!.options).toMatchObject({ width: 412, height: 839 });
+      fixture.captures[0]!.sourceFailure = "source-dimensions";
+      expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("unsupported");
+      expect(fixture.captures[0]!.stop).toHaveBeenCalledOnce();
+      internal.documentGeneration++;
+      await vi.advanceTimersByTimeAsync(60_000);
+      for (let i = 0; i < 20; i++) {
+        expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe(
+          "unsupported",
+        );
+      }
+      expect(fixture.captures).toHaveLength(1);
+      await runtime.setCaptureDensity(2, 2.625);
+      expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("ready");
+      expect(fixture.captures).toHaveLength(2);
+      expect(fixture.captures[1]!.options).toMatchObject({ width: 824, height: 1678 });
+      expect(internal.viewport).toMatchObject({ width: 412, height: 839, captureScale: 2 });
+    } finally {
+      await runtime.stopVideo();
+      clock.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("keeps concurrent failed-source retirement fenced even after its cooldown", async () => {
+    vi.useFakeTimers();
+    const clock = vi.spyOn(performance, "now").mockImplementation(() => Date.now());
+    const { runtime } = setup();
+    const release = Promise.withResolvers<void>();
+    try {
+      await runtime.readVideo({ quality: "high", waitMs: 0 });
+      const former = fixture.captures[0]!;
+      former.sourceFailure = "source-stopped";
+      former.stop.mockImplementationOnce(() => release.promise);
+      let settled = false;
+      const retirement = runtime.readVideo({ quality: "high", waitMs: 0 }).then((reply) => {
+        settled = true;
+        return reply;
+      });
+      for (let i = 0; i < 10; i++) await Promise.resolve();
+      // Backend teardown can outlive the outer plugin RPC deadline. The reader
+      // must release its admission slot while replacement capture stays fenced.
+      await vi.advanceTimersByTimeAsync(35000);
+      expect(settled).toBe(true);
+      const readers = await Promise.all(
+        Array.from({ length: 8 }, () => runtime.readVideo({ quality: "high", waitMs: 0 })),
+      );
+      expect(readers.every((value) => value.status === "reset")).toBe(true);
+      expect(fixture.captures).toHaveLength(1);
+      let cleanupSettled = false;
+      const cleanup = runtime.stopVideo().then(() => {
+        cleanupSettled = true;
+      });
+      await vi.advanceTimersByTimeAsync(1);
+      expect(cleanupSettled).toBe(false);
+      release.resolve();
+      await cleanup;
+      await retirement;
+      await Promise.all(
+        Array.from({ length: 8 }, () => runtime.readVideo({ quality: "high", waitMs: 0 })),
+      );
+      expect(fixture.captures).toHaveLength(2);
+      expect(former.stop).toHaveBeenCalledOnce();
+    } finally {
+      release.resolve();
+      await runtime.stopVideo();
+      clock.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("a single cohort failure never retires a source used by a healthy peer", async () => {
+    const { runtime } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const shared = fixture.captures[0]!;
+    shared.read.mockResolvedValueOnce({
+      status: "unsupported",
+      streamId: "high",
+      packets: [],
+      reason: "Native video quality is unavailable",
+    });
+    expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("unsupported");
+    expect((await runtime.readVideo({ quality: "low", waitMs: 0 })).status).toBe("ready");
+    expect(shared.stop).not.toHaveBeenCalled();
+    expect(fixture.captures).toHaveLength(1);
+    await runtime.stopVideo();
+  });
+  it("forwards exact encoder settings and refuses invalid values before creating a source", async () => {
+    const { runtime } = setup();
+    await expect(runtime.readVideo({ quality: "high", bitrate: 1, fps: 30 })).rejects.toThrow();
+    expect(fixture.captures).toHaveLength(0);
+    await runtime.readVideo({ quality: "low", bitrate: 24_000_000, fps: 60, waitMs: 0 });
+    expect(fixture.captures[0]!.read).toHaveBeenLastCalledWith({
+      quality: "low",
+      bitrate: 24_000_000,
+      fps: 60,
+      waitMs: 0,
+    });
+    await runtime.stopVideo();
+  });
+
+  it("retires an idle source under the stop barrier and resumes on the next read", async () => {
+    const { runtime } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const expired = fixture.captures[0]!;
+    expired.idleExpired = true;
+    const stopping = Promise.withResolvers<void>();
+    expired.stop.mockImplementationOnce(() => stopping.promise);
+    let settled = false;
+    const retirement = runtime.readVideo({ quality: "high", waitMs: 0 }).then((reply) => {
+      settled = true;
+      return reply;
+    });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+    expect(settled).toBe(true);
+    expect(await runtime.readVideo({ quality: "high", waitMs: 0 })).toMatchObject({
+      status: "reset",
+      packets: [],
+    });
+    expect(fixture.captures).toHaveLength(1);
+    stopping.resolve();
+    await runtime.stopVideo();
+    expect(await retirement).toMatchObject({ status: "reset", packets: [] });
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures).toHaveLength(2);
+    expect(expired.stop).toHaveBeenCalledOnce();
+    await runtime.stopVideo();
+  });
+
+  it("turns expiry during a read into a recoverable reset, not permanent unsupported", async () => {
+    const { runtime } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const expired = fixture.captures[0]!;
+    expired.read.mockImplementationOnce(async () => {
+      expired.idleExpired = true;
+      return { status: "unsupported", packets: [] };
+    });
+    expect(await runtime.readVideo({ quality: "high", waitMs: 0 })).toMatchObject({
+      status: "reset",
+      packets: [],
+    });
+    expect(await runtime.readVideo({ quality: "high", waitMs: 0 })).toMatchObject({
+      status: "reset",
+      packets: [],
+    });
+    await runtime.stopVideo();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures).toHaveLength(2);
+    await runtime.stopVideo();
+  });
+
+  it("creates the exact physical capture pixels and retains live pointer continuity", async () => {
+    const { runtime } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures[0]?.options).toMatchObject({
+      targetId: "exact",
+      width: 824,
+      height: 1678,
+    });
+    await runtime.mouseMove(10, 10);
+    expect(fixture.captures[0]?.invalidateQueuedFrames).not.toHaveBeenCalled();
+    await runtime.stopVideo();
+  });
+  it("document change while a read is pending returns reset without packets", async () => {
+    const { runtime, internal } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    let resolveRead: (value: unknown) => void = () => {};
+    fixture.captures[0]!.read.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveRead = resolve;
+        }),
+    );
+    const pending = runtime.readVideo({ quality: "high", waitMs: 500 });
+    await Promise.resolve();
+    await Promise.resolve();
+    internal.documentGeneration++;
+    resolveRead({ status: "ready", streamId: "old", packets: [{ dataBase64: "old" }] });
+    expect(await pending).toMatchObject({ status: "reset", packets: [] });
+    await runtime.stopVideo();
+  });
+  it("successful explicit reload clears queued video, never the shared source on mouse motion", async () => {
+    const { runtime } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    await runtime.reload();
+    expect(fixture.captures[0]?.invalidateQueuedFrames).toHaveBeenCalledOnce();
+    await runtime.stopVideo();
+  });
+  it("replacement attachment cannot reuse a former capture's ownership callback", async () => {
+    const { runtime, internal } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const owned = fixture.captures[0]!.options as { isCurrent(): boolean };
+    expect(owned.isCurrent()).toBe(true);
+    internal.attachmentGeneration++;
+    expect(owned.isCurrent()).toBe(false);
+    await runtime.stopVideo();
+  });
+  it("blocks replacement capture during an awaited resize stop, then uses the new exact pixels", async () => {
+    const { runtime } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const former = fixture.captures[0]!;
+    const stopping = Promise.withResolvers<void>();
+    former.stop.mockImplementationOnce(() => stopping.promise);
+
+    const resize = runtime.emulate({
+      width: 1280,
+      height: 1280,
+      captureScale: 1,
+      deviceScaleFactor: 1,
+      mobile: false,
+      touch: false,
+    });
+    expect((former.options as { isCurrent(): boolean }).isCurrent()).toBe(false);
+    expect(await runtime.readVideo({ quality: "high", waitMs: 0 })).toMatchObject({
+      status: "reset",
+      packets: [],
+    });
+    expect(fixture.captures).toHaveLength(1);
+    stopping.resolve();
+    await resize;
+
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures).toHaveLength(2);
+    expect(fixture.captures[1]!.options).toMatchObject({ width: 1280, height: 1280 });
+    expect((fixture.captures[1]!.options as { isCurrent(): boolean }).isCurrent()).toBe(true);
+    await runtime.stopVideo();
+  });
+  it("holds the stop barrier even when no device operation follows", async () => {
+    const { runtime } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const deferred = Promise.withResolvers<void>();
+    fixture.captures[0]!.stop.mockImplementationOnce(() => deferred.promise);
+    const stopping = runtime.stopVideo();
+    expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("reset");
+    expect(fixture.captures).toHaveLength(1);
+    deferred.resolve();
+    await stopping;
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures).toHaveLength(2);
+    await runtime.stopVideo();
+  });
+  it("binds the source to the exact saved viewport object, even with unchanged attachment", async () => {
+    const { runtime, internal } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const owner = fixture.captures[0]!.options as { isCurrent(): boolean };
+    internal.viewport = {
+      width: 1280,
+      height: 800,
+      captureScale: 1,
+      deviceScaleFactor: 1,
+      mobile: false,
+      touch: false,
+    };
+    expect(owner.isCurrent()).toBe(false);
+    await runtime.stopVideo();
+  });
+  it("restoration owns a continuous source barrier without creating a helper from native metrics", async () => {
+    const { runtime, internal, page } = setup();
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    const deferred = Promise.withResolvers<void>();
+    fixture.captures[0]!.stop.mockImplementationOnce(() => deferred.promise);
+    internal.emulationAppliedPage = null;
+    const restoring = internal.restoreConfiguredEmulation(page);
+    expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("reset");
+    expect(fixture.captures).toHaveLength(1);
+    deferred.resolve();
+    await restoring;
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures[1]!.options).toMatchObject({ width: 824, height: 1678 });
+    await runtime.stopVideo();
+  });
+  it("blocks startup throughout target selection and releases the gate after a rejected target", async () => {
+    const { runtime } = setup();
+    const listing = Promise.withResolvers<[]>();
+    vi.spyOn(runtime, "targets").mockImplementationOnce(() => listing.promise);
+    const selection = runtime.selectTarget("not-saved");
+    const rejection = expect(selection).rejects.toThrow("Unknown page target");
+    expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("reset");
+    expect(fixture.captures).toHaveLength(0);
+    listing.resolve([]);
+    await rejection;
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures).toHaveLength(1);
+    await runtime.stopVideo();
+  });
+  it("blocks capture while reconnect is restoring the saved page", async () => {
+    const { runtime, internal, page, connection } = setup();
+    const readiness = Promise.withResolvers<void>();
+    internal.assertVersion = () => readiness.promise;
+    internal.connectCdp = async () => {
+      internal.connection = connection;
+      internal.page = page;
+      internal.emulationAppliedPage = page;
+    };
+    const reconnecting = runtime.reconnect();
+    expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("reset");
+    expect(fixture.captures).toHaveLength(0);
+    readiness.resolve();
+    await reconnecting;
+    await runtime.readVideo({ quality: "high", waitMs: 0 });
+    expect(fixture.captures).toHaveLength(1);
+    await runtime.stopVideo();
+  });
+  it("never starts a source during or after shutdown while native close is pending", async () => {
+    const { runtime, internal } = setup();
+    const closing = Promise.withResolvers<void>();
+    internal.invoke = () => closing.promise;
+    const shutdown = runtime.shutdown();
+    expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("reset");
+    expect(fixture.captures).toHaveLength(0);
+    closing.resolve();
+    await shutdown;
+    expect((await runtime.readVideo({ quality: "high", waitMs: 0 })).status).toBe("reset");
+    expect(fixture.captures).toHaveLength(0);
+  });
+});

package/server/screencast-source-time.ts

@@ -0,0 +1,46 @@
+/** Native JPEG source ordering, independent of arrival time and image decoding.
+ * CDP Page.ScreencastFrameMetadata.timestamp is frame-swap TimeSinceEpoch in
+ * seconds. Missing/stale metadata cannot certify queued pixels after input.
+ * Refused frames still get acknowledged by the runtime and use screenshot fallback.
+ */
+import { CAPTURE_MAX_AGE_MS } from "./capture-transport-policy";
+
+// Match the existing native-video source-clock bound. This is clock tolerance,
+// never an extension of the one-second native source freshness window.
+const SOURCE_CLOCK_TOLERANCE_MS = 50;
+
+/** Own one ordering watermark per runtime. Invalidation revokes every swap at or
+ * before its wall-clock boundary plus clock uncertainty; accepted age retains the original monotonic
+ * expiry even when an event spent time queued before arrival. */
+export function createScreencastSourceTime() {
+  let notBeforeMs = -Infinity;
+  let lastSourceMs = -Infinity;
+
+  return {
+    invalidate(nowMs: number): void {
+      notBeforeMs = Math.max(notBeforeMs, nowMs);
+    },
+    accept(timestampSeconds: number | undefined, wallNowMs: number, monotonicNowMs: number) {
+      if (typeof timestampSeconds !== "number" || !Number.isFinite(timestampSeconds)) return null;
+      const sourceMs = timestampSeconds * 1000;
+      const ageMs = wallNowMs - sourceMs;
+      if (
+        !Number.isFinite(sourceMs) ||
+        ageMs < -SOURCE_CLOCK_TOLERANCE_MS ||
+        ageMs > CAPTURE_MAX_AGE_MS ||
+        // The accepted future-clock tolerance also applies to an old swap.
+        // Require source time beyond the entire uncertainty interval after input.
+        sourceMs <= notBeforeMs + SOURCE_CLOCK_TOLERANCE_MS ||
+        sourceMs <= lastSourceMs
+      ) {
+        return null;
+      }
+      lastSourceMs = sourceMs;
+      return {
+        capturedAt: new Date(sourceMs).toISOString(),
+        // Future clock tolerance does not buy extra freshness after receipt.
+        receivedAt: monotonicNowMs - Math.max(0, ageMs),
+      };
+    },
+  };
+}

package/server/stale-wheel-admission.test.ts

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { it } from "vitest";
+import {
+  type BrowserGestureAuthority,
+  createBrowserInputQueue,
+} from "../client/browser-input-queue";
+import { type BrowserRuntimeClient, SessionManager } from "./browser-policy";
+
+it("recovers a captured-before-wheel frame that decodes after invalidation without repeating the first wheel", async () => {
+  // No native process or profile: actual queue + policy, with delayed decoder and deterministic clock.
+  let token = 0;
+  let now = 1_000;
+  const calls: string[] = [];
+  const client: BrowserRuntimeClient = {
+    connect: async () => ({ epoch: 1 }),
+    ensureWorkspace: async (workspaceId) => ({
+      workspaceId,
+      runtimeId: "r".repeat(32),
+      createdAt: 1,
+    }),
+    requestWorkspace: async (_workspace, 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(now).toISOString(),
+        };
+      if (operation === "cursor") return "default";
+      return null;
+    },
+    archiveWorkspace: async () => {},
+    closeWorkspace: async () => {},
+    disconnect: () => {},
+  };
+  const manager = new SessionManager({
+    client,
+    validateWorkspace: async () => true,
+    now: () => now,
+    frameCacheMs: 0,
+    issueToken: () => String(++token).padStart(32, "0"),
+  });
+  await manager.connect();
+  const { viewerToken } = await manager.attach("owned-fixture", "Viewer");
+  const { controlToken } = await manager.acquireControl(viewerToken);
+  const a = await manager.capture(viewerToken);
+  const context = {
+    viewerToken,
+    controlToken,
+    expected: {
+      sessionId: a.state.sessionId,
+      runtimeId: a.state.runtimeId!,
+      bridgeEpoch: a.state.bridgeEpoch!,
+      navigationGeneration: a.state.navigationGeneration,
+      viewportGeneration: a.state.viewportGeneration,
+    },
+  };
+  const target = (frame: NonNullable<typeof a.frame>) => ({
+    frameId: frame.frameId,
+    navigationGeneration: frame.navigationGeneration,
+    viewportGeneration: frame.viewportGeneration,
+  });
+  let current: BrowserGestureAuthority = {
+    ...context,
+    target: target(a.frame!),
+  };
+  const errors: unknown[] = [];
+  let decoderPending: NonNullable<typeof a.frame> | null = null;
+  let waited = 0;
+  const queue = createBrowserInputQueue({
+    authority: () => current,
+    transport: {
+      begin: (input) => manager.beginGesture(input),
+      end: (input) => manager.endGesture(input),
+      update: async (input) => {
+        // A different capture is already issued before input; its slow decoder commits after the wheel reply.
+        now++;
+        decoderPending = (await manager.capture(viewerToken)).frame!;
+        const result = await manager.updateGesture(input);
+        current = { ...context, target: target(decoderPending) };
+        return result;
+      },
+    },
+    onState: () => {},
+    onCursor: () => {},
+    onError: (error) => errors.push(error),
+    onFinish: () => {},
+    waitForFrame: async () => {
+      waited++;
+      now++;
+      const fresh = await manager.capture(viewerToken);
+      current = { ...context, target: target(fresh.frame!) };
+    },
+  });
+  const flush = async () => {
+    for (let i = 0; i < 100; i++) await Promise.resolve();
+  };
+  try {
+    queue.enqueue({
+      kind: "scroll",
+      point: { x: 100, y: 100, width: 1280, height: 800 },
+      deltaX: 0,
+      deltaY: 40,
+    });
+    await flush();
+    queue.finish();
+    await flush();
+    assert.equal(errors.length, 0);
+    assert.notEqual(current.target.frameId, a.frame!.frameId);
+    queue.enqueue({
+      kind: "scroll",
+      point: { x: 100, y: 100, width: 1280, height: 800 },
+      deltaX: 0,
+      deltaY: 40,
+    });
+    await flush();
+    assert.equal(waited, 1);
+    assert.equal(errors.length, 0);
+    assert.equal(calls.filter((call) => call === "mouse.wheel").length, 2);
+    assert.equal(calls.filter((call) => call === "input.begin").length, 2);
+  } finally {
+    queue.cancel();
+    manager.disconnect();
+  }
+});

package/server/supervisor-client.ts

@@ -41,6 +41,7 @@ export class SupervisorClient {
   private token = "";
   private epoch = 0;
   private heartbeatTimer: NodeJS.Timeout | null = null;
+  private heartbeatInFlight: Promise<void> | null = null;
   private receiveBuffer = "";
   private readonly takeover: boolean;
   private reconnecting: Promise<BridgeLease> | null = null;
@@ -145,6 +146,17 @@ export class SupervisorClient {
       workspaceId,
     });
   }
+
+  async closeWorkspace(workspaceId: string, runtimeId: string): Promise<void> {
+    await this.ensureLease();
+    await this.send({
+      method: "workspace.close",
+      bridgeId: this.bridgeId,
+      epoch: this.epoch,
+      workspaceId,
+      runtimeId,
+    });
+  }
   async requestBrowser<Result = JsonValue>(operation: string, input: JsonValue): Promise<Result> {
     await this.ensureLease();
     return (await this.send({
@@ -248,17 +260,28 @@ export class SupervisorClient {
   private armHeartbeat(intervalMs: number): void {
     this.clearHeartbeat();
     this.heartbeatTimer = setInterval(() => {
-      void this.send({ method: "bridge.heartbeat", bridgeId: this.bridgeId, epoch: this.epoch })
+      // A delayed response must not produce duplicate maintenance or let an old
+      // connection's completion replace or close the current bridge lease.
+      if (this.heartbeatInFlight) return;
+      const socket = this.socket;
+      const epoch = this.epoch;
+      const operation = this.send({ method: "bridge.heartbeat", bridgeId: this.bridgeId, epoch })
         .then((result) => {
+          if (this.socket !== socket || this.epoch !== epoch) return;
           const lease = result as BridgeLease;
           this.epoch = lease.epoch;
           this.lease = lease;
         })
-        .catch((error: unknown) =>
+        .catch((error: unknown) => {
+          if (this.socket !== socket || this.epoch !== epoch) return;
           this.handleClose(
             error instanceof Error ? error : new Error("Supervisor heartbeat failed"),
-          ),
-        );
+          );
+        })
+        .finally(() => {
+          if (this.heartbeatInFlight === operation) this.heartbeatInFlight = null;
+        });
+      this.heartbeatInFlight = operation;
     }, intervalMs);
     this.heartbeatTimer.unref();
   }
@@ -267,6 +290,7 @@ export class SupervisorClient {
     if (!this.heartbeatTimer) return;
     clearInterval(this.heartbeatTimer);
     this.heartbeatTimer = null;
+    this.heartbeatInFlight = null;
   }
 
   private async ensureLease(): Promise<void> {