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

package/server/runtime-jpeg-shutdown.test.ts

@@ -0,0 +1,210 @@
+/** Real acquisition methods with fake CDP; shutdown never waits for uncertain image work. */
+import { EventEmitter } from "node:events";
+import { afterEach, expect, it, vi } from "vitest";
+import { DEFAULT_JPEG_QUALITY } from "../shared/capture-settings";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+import { CdpConnection } from "./cdp";
+
+class Connection extends EventEmitter {
+  isOpen = true;
+  send = vi.fn(async () => ({}));
+  close = vi.fn(() => {
+    this.isOpen = false;
+    this.emit("disconnect");
+  });
+}
+
+/** Replace external process operations only, retaining real page/start/capture guards. */
+function fixture() {
+  const runtime = new AgentBrowserRuntime({
+    nativeVideo: true,
+    binaryPath: "/tmp/unlaunched-browser",
+    executablePath: "/tmp/unlaunched-chromium",
+    profilePath: "/tmp/uncreated-profile",
+    ipcDirectory: "/tmp/uncreated-ipc",
+    session: "jpeg-shutdown-test",
+  });
+  const connection = new Connection();
+  const page = {
+    connection,
+    send: vi.fn(async (method: string): Promise<unknown> => {
+      if (method === "Page.getNavigationHistory") return { currentIndex: 0, entries: [] };
+      if (method === "Page.getLayoutMetrics") return { cssVisualViewport: { pageX: 0, pageY: 0 } };
+      return {};
+    }),
+  };
+  const control = runtime as unknown as {
+    invoke(args: string[]): Promise<unknown>;
+    assertVersion(): Promise<void>;
+    connectCdp(): Promise<void>;
+    captureScreenshot(): Promise<unknown>;
+    page: typeof page | null;
+    heldButtons: Set<string>;
+    heldKeys: Map<string, { key: string; code: string }>;
+    screencastFrame: unknown;
+  };
+  Object.assign(runtime, {
+    page,
+    connection,
+    emulationAppliedPage: page,
+    viewport: { width: 1280, height: 800, deviceScaleFactor: 1, mobile: false, touch: false },
+  });
+  control.invoke = vi.fn(async () => ({ cdpUrl: "ws://127.0.0.1:1/fixture" }));
+  control.assertVersion = vi.fn(async () => {});
+  return { runtime, control, page, connection };
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+it.each(["Page.enable", "Page.getNavigationHistory"])(
+  "explicit JPEG startup cannot resume from %s after shutdown",
+  async (blockedMethod) => {
+    const { runtime, page, control } = fixture();
+    const entered = Promise.withResolvers<void>();
+    const blocked = Promise.withResolvers<void>();
+    const send = page.send.getMockImplementation()!;
+    page.send.mockImplementation(async (method) => {
+      if (method === blockedMethod) {
+        entered.resolve();
+        await blocked.promise;
+      }
+      return await send(method);
+    });
+    const reconnect = vi.spyOn(runtime, "reconnect");
+    const result = runtime.startScreencast().catch((error: unknown) => error);
+    await entered.promise;
+    await runtime.shutdown();
+    blocked.resolve();
+    expect(await result).toMatchObject({ message: "Browser runtime is shutting down" });
+    expect(reconnect).not.toHaveBeenCalled();
+    expect(page.send.mock.calls.some(([method]) => method === "Page.startScreencast")).toBe(false);
+    expect(control.invoke).toHaveBeenCalledTimes(1);
+  },
+);
+
+it("optional frame startup rejects shutdown without attempting screenshot fallback", async () => {
+  const { runtime, page, control } = fixture();
+  const entered = Promise.withResolvers<void>();
+  const blocked = Promise.withResolvers<void>();
+  page.send.mockImplementation(async (method) => {
+    if (method === "Page.enable") {
+      entered.resolve();
+      await blocked.promise;
+    }
+    return {};
+  });
+  const fallback = vi.spyOn(control, "captureScreenshot");
+  const result = runtime.frame(1024, DEFAULT_JPEG_QUALITY, 0).catch((error: unknown) => error);
+  await entered.promise;
+  await runtime.shutdown();
+  blocked.resolve();
+  expect(await result).toMatchObject({ message: "Browser runtime is shutting down" });
+  expect(fallback).not.toHaveBeenCalled();
+});
+
+it("a screenshot-only read cannot publish late pixels or capture after blocked metrics", async () => {
+  const { runtime, page, control } = fixture();
+  const entered = Promise.withResolvers<void>();
+  const blocked = Promise.withResolvers<void>();
+  const send = page.send.getMockImplementation()!;
+  page.send.mockImplementation(async (method) => {
+    if (method === "Page.getLayoutMetrics") {
+      entered.resolve();
+      await blocked.promise;
+    }
+    return await send(method);
+  });
+  const result = runtime.frame(1024, 100, 0).catch((error: unknown) => error);
+  await entered.promise;
+  await runtime.shutdown();
+  blocked.resolve();
+  expect(await result).toMatchObject({ message: "Browser runtime is shutting down" });
+  expect(page.send.mock.calls.some(([method]) => method === "Page.captureScreenshot")).toBe(false);
+  expect(control.screencastFrame).toBeNull();
+});
+
+it("an already dispatched screenshot cannot cache or return its late bytes after shutdown", async () => {
+  const { runtime, page } = fixture();
+  const entered = Promise.withResolvers<void>();
+  const blocked = Promise.withResolvers<void>();
+  const send = page.send.getMockImplementation()!;
+  page.send.mockImplementation(async (method) => {
+    if (method === "Page.captureScreenshot") {
+      entered.resolve();
+      await blocked.promise;
+      return { data: "late-pixels" };
+    }
+    return await send(method);
+  });
+  const result = runtime.frame(1024, 100, 0).catch((error: unknown) => error);
+  await entered.promise;
+  await runtime.shutdown();
+  blocked.resolve();
+  expect(await result).toMatchObject({ message: "Browser runtime is shutting down" });
+  expect(
+    page.send.mock.calls.filter(([method]) => method === "Page.captureScreenshot"),
+  ).toHaveLength(1);
+  await expect(runtime.frame(1024, 100, 0)).rejects.toThrow("closed");
+});
+
+it("reconnect paused at version discovery cannot invoke native connection after shutdown", async () => {
+  const { runtime, control } = fixture();
+  const entered = Promise.withResolvers<void>();
+  const blocked = Promise.withResolvers<void>();
+  control.assertVersion = vi.fn(async () => {
+    entered.resolve();
+    await blocked.promise;
+  });
+  const result = runtime.reconnect().catch((error: unknown) => error);
+  await entered.promise;
+  await runtime.shutdown();
+  blocked.resolve();
+  expect(await result).toMatchObject({ message: "Browser runtime is shutting down" });
+  expect(control.invoke).toHaveBeenCalledTimes(1);
+  expect(control.invoke).toHaveBeenCalledWith([
+    "--session",
+    "jpeg-shutdown-test",
+    "--json",
+    "close",
+  ]);
+});
+
+it("late opened CDP connection is closed without publication or target attachment", async () => {
+  const { runtime, control } = fixture();
+  const entered = Promise.withResolvers<void>();
+  const blocked = Promise.withResolvers<CdpConnection>();
+  const late = new Connection();
+  vi.spyOn(CdpConnection, "connect").mockImplementation(async () => {
+    entered.resolve();
+    return await blocked.promise;
+  });
+  const result = control.connectCdp().catch((error: unknown) => error);
+  await entered.promise;
+  await runtime.shutdown();
+  blocked.resolve(late as unknown as CdpConnection);
+  expect(await result).toMatchObject({ message: "Browser runtime is shutting down" });
+  expect(late.close).toHaveBeenCalledTimes(1);
+  expect(late.send).not.toHaveBeenCalled();
+  expect(control.page).toBeNull();
+});
+
+it("shutdown still releases original held input, then all fresh acquisition stays closed", async () => {
+  const { runtime, page, control } = fixture();
+  control.heldButtons.add("left");
+  control.heldKeys.set("ControlLeft", { key: "Control", code: "ControlLeft" });
+  await runtime.shutdown();
+  expect(page.send).toHaveBeenCalledWith(
+    "Input.dispatchMouseEvent",
+    expect.objectContaining({ type: "mouseReleased", button: "left" }),
+    { mutation: true },
+  );
+  expect(page.send).toHaveBeenCalledWith(
+    "Input.dispatchKeyEvent",
+    expect.objectContaining({ type: "keyUp", code: "ControlLeft" }),
+    { mutation: true },
+  );
+  await expect(runtime.reconnect()).rejects.toThrow("shutting down");
+  await expect(runtime.launch()).rejects.toThrow("shutting down");
+  await expect(runtime.frame(1024, DEFAULT_JPEG_QUALITY, 0)).rejects.toThrow("closed");
+  expect(control.invoke).toHaveBeenCalledTimes(1);
+});

package/server/runtime-jpeg-source-order.test.ts

@@ -0,0 +1,201 @@
+/** Actual runtime JPEG path, fake CDP only. Swap time must survive transport delay. */
+import { EventEmitter } from "node:events";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { DEFAULT_JPEG_QUALITY } from "../shared/capture-settings";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+
+function jpeg(tag: number): string {
+  return Buffer.from([
+    255,
+    216,
+    255,
+    224,
+    0,
+    3,
+    tag,
+    255,
+    192,
+    0,
+    11,
+    8,
+    3,
+    32,
+    5,
+    0,
+    1,
+    1,
+    17,
+    0,
+    255,
+    217,
+  ]).toString("base64");
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(1_800_000_000_000);
+  vi.spyOn(performance, "now").mockImplementation(() => Date.now());
+});
+afterEach(() => {
+  vi.clearAllTimers();
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+function fixture() {
+  const runtime = new AgentBrowserRuntime({
+    nativeVideo: true,
+    binaryPath: "/tmp/unlaunched",
+    executablePath: "/tmp/unlaunched",
+    profilePath: "/tmp/uncreated",
+    ipcDirectory: "/tmp/uncreated",
+    session: "source-order-fixture",
+  });
+  const connection = Object.assign(new EventEmitter(), { isOpen: true });
+  const page = Object.assign(new EventEmitter(), {
+    connection,
+    send: vi.fn(async (method: string): Promise<unknown> => {
+      if (method === "Page.getFrameTree") return { frameTree: { frame: { id: "root" } } };
+      if (method === "Page.getNavigationHistory")
+        return {
+          currentIndex: 0,
+          entries: [{ id: 1, url: "https://source.invalid/", title: "Fixture" }],
+        };
+      if (method === "Page.getLayoutMetrics") return { cssVisualViewport: { pageX: 0, pageY: 0 } };
+      if (method === "Page.captureScreenshot") return { data: jpeg(9) };
+      return {};
+    }),
+  });
+  Object.assign(runtime, {
+    page,
+    connection,
+    emulationAppliedPage: page,
+    screencastActive: true,
+    viewport: { width: 1280, height: 800, deviceScaleFactor: 1, mobile: false, touch: false },
+  });
+  const internal = runtime as unknown as {
+    invalidateScreencastFrame(): void;
+    onScreencastFrame(page: unknown, event: unknown): void;
+    bindPageEvents(page: unknown): Promise<void>;
+  };
+  const emit = (sourceMs: number | undefined, tag = 1) =>
+    internal.onScreencastFrame(page, {
+      data: jpeg(tag),
+      sessionId: 17,
+      metadata: {
+        deviceWidth: 1280,
+        deviceHeight: 800,
+        ...(sourceMs === undefined ? {} : { timestamp: sourceMs / 1000 }),
+      },
+    });
+  return { runtime, internal, page, emit };
+}
+
+/** Zero-wait stream polling still uses a native timer; settle that fake timer
+ * without advancing the source clock or extending the freshness assertion. */
+async function readFrame(runtime: AgentBrowserRuntime) {
+  const pending = runtime.frame(100, DEFAULT_JPEG_QUALITY, 0);
+  await vi.advanceTimersByTimeAsync(0);
+  return pending;
+}
+
+it("preserves native swap time and its remaining one-second source lifetime", async () => {
+  const { runtime, emit } = fixture();
+  const sourceMs = Date.now() - 600;
+  emit(sourceMs);
+  const frame = await readFrame(runtime);
+  expect(frame.transport).toBe("cdp-screencast");
+  expect(frame.capturedAt).toBe(new Date(sourceMs).toISOString());
+  await vi.advanceTimersByTimeAsync(401);
+  expect((await readFrame(runtime)).transport).toBe("screenshot");
+});
+
+it.each([20, 10_000])(
+  "refuses a queued pre-input swap aged %sms even when it arrives after invalidation",
+  async (ageMs) => {
+    const { runtime, internal, page, emit } = fixture();
+    const sourceMs = Date.now() - ageMs;
+    internal.invalidateScreencastFrame();
+    emit(sourceMs);
+    const frame = await readFrame(runtime);
+    expect(frame.transport).toBe("screenshot");
+    expect(frame.dataBase64).toBe(jpeg(9));
+    expect(page.send).toHaveBeenCalledWith("Page.screencastFrameAck", { sessionId: 17 });
+  },
+);
+
+it.each([0, 20, 50])(
+  "post-input source offset +%sms cannot borrow clock tolerance to authorize old pixels",
+  async (offsetMs) => {
+    const { runtime, internal, page, emit } = fixture();
+    internal.invalidateScreencastFrame();
+    emit(Date.now() + offsetMs);
+    const frame = await readFrame(runtime);
+    expect(frame.transport).toBe("screenshot");
+    expect(frame.dataBase64).toBe(jpeg(9));
+    expect(page.send).toHaveBeenCalledWith("Page.screencastFrameAck", { sessionId: 17 });
+  },
+);
+
+it("a genuinely later swap beyond post-input uncertainty keeps its native timestamp", async () => {
+  const { runtime, internal, emit } = fixture();
+  internal.invalidateScreencastFrame();
+  await vi.advanceTimersByTimeAsync(51);
+  const sourceMs = Date.now();
+  emit(sourceMs);
+  const frame = await readFrame(runtime);
+  expect(frame.transport).toBe("cdp-screencast");
+  expect(frame.capturedAt).toBe(new Date(sourceMs).toISOString());
+});
+
+it.each([undefined, NaN, Infinity, 1_800_000_000_051, 1_799_999_998_999])(
+  "refuses missing, invalid, future or expired source time %s",
+  async (sourceMs) => {
+    const { runtime, emit } = fixture();
+    emit(sourceMs);
+    expect((await readFrame(runtime)).transport).toBe("screenshot");
+  },
+);
+
+it("out-of-order or duplicate swaps cannot replace a newer admitted JPEG", async () => {
+  const { runtime, emit } = fixture();
+  emit(Date.now(), 2);
+  const newest = await readFrame(runtime);
+  emit(Date.now() - 10, 1);
+  emit(Date.now(), 3);
+  expect(await readFrame(runtime)).toBe(newest);
+  expect(newest.dataBase64).toBe(jpeg(2));
+});
+
+it.each(["Page.frameNavigated", "Page.navigatedWithinDocument"])(
+  "%s revokes cached and queued former-document JPEG",
+  async (event) => {
+    const { runtime, internal, page, emit } = fixture();
+    await internal.bindPageEvents(page);
+    const oldSourceMs = Date.now();
+    emit(oldSourceMs);
+    const prior = await readFrame(runtime);
+    await vi.advanceTimersByTimeAsync(20);
+    page.emit(
+      event,
+      event === "Page.frameNavigated"
+        ? { frame: { id: "root", loaderId: "next", url: "https://next.invalid/" } }
+        : { frameId: "root", url: "https://next.invalid/#next" },
+    );
+    emit(oldSourceMs, 2);
+    const next = await readFrame(runtime);
+    expect(next).not.toBe(prior);
+    expect(next.transport).toBe("screenshot");
+    expect(next.dataBase64).toBe(jpeg(9));
+  },
+);
+
+it("child-frame and unrelated same-document events leave current main-frame pixels intact", async () => {
+  const { runtime, internal, page, emit } = fixture();
+  await internal.bindPageEvents(page);
+  emit(Date.now());
+  const before = await readFrame(runtime);
+  page.emit("Page.frameNavigated", { frame: { id: "child", parentId: "root" } });
+  page.emit("Page.navigatedWithinDocument", { frameId: "child", url: "https://child.invalid/#x" });
+  expect(await readFrame(runtime)).toBe(before);
+});

package/server/runtime-launch-environment.test.ts

@@ -0,0 +1,111 @@
+/** Per-instance display context reaches native CLI children without changing host or session authority. */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+
+const temporary: string[] = [];
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+
+const exec = vi.hoisted(() => ({
+  calls: [] as { file: string; args: string[]; env: NodeJS.ProcessEnv }[],
+}));
+// Records the exact child launch instead of running a platform-specific script.
+vi.mock("node:child_process", () => ({
+  execFile: (
+    file: string,
+    args: string[],
+    options: { env: NodeJS.ProcessEnv },
+    callback: (error: null, result: { stdout: string }) => void,
+  ) => {
+    exec.calls.push({ file, args, env: options.env });
+    callback(null, { stdout: args.includes("--version") ? "0.38.2\n" : "{}\n" });
+  },
+}));
+
+async function fixture(launchEnvironment?: Readonly<Record<string, string>>) {
+  const directory = await mkdtemp(join(tmpdir(), "shared-browser-runtime-env-"));
+  temporary.push(directory);
+  const binary = join(directory, "owned-cli");
+  const runtime = new AgentBrowserRuntime({
+    binaryPath: binary,
+    executablePath: join(directory, "unlaunched-chromium"),
+    profilePath: join(directory, "owned-profile"),
+    ipcDirectory: join(directory, "owned-ipc"),
+    session: "owned-environment",
+    ...(launchEnvironment ? { launchEnvironment } : {}),
+  });
+  const native = runtime as unknown as {
+    assertVersion(): Promise<void>;
+    invoke(args: string[]): Promise<unknown>;
+  };
+  /** Environment the owned CLI child received for the call with these arguments. */
+  const launched = (args: string[]) => {
+    const call = exec.calls.find(
+      (candidate) => candidate.file === binary && candidate.args.join() === args.join(),
+    );
+    if (!call) throw new Error(`CLI was not launched with ${args.join(" ")}`);
+    return {
+      display: call.env.DISPLAY ?? null,
+      authority: call.env.XAUTHORITY ?? null,
+      wayland: call.env.WAYLAND_DISPLAY ?? null,
+      socket: call.env.AGENT_BROWSER_SOCKET_DIR,
+    };
+  };
+  return { directory, runtime, native, launched };
+}
+
+describe("trusted private display launch environment", () => {
+  it("passes display/auth to every CLI child, copies settings, and keeps host environment unchanged", async () => {
+    const before = {
+      display: process.env.DISPLAY,
+      authority: process.env.XAUTHORITY,
+      wayland: process.env.WAYLAND_DISPLAY,
+    };
+    const environment = { DISPLAY: ":24701", XAUTHORITY: "/tmp/owned-private-auth" };
+    const f = await fixture(environment);
+    environment.DISPLAY = ":24702";
+    await f.native.assertVersion();
+    for (const args of [["owned-request"], ["owned-reconnect"], ["--version"]]) {
+      if (args[0] !== "--version") await f.native.invoke(args);
+      expect(f.launched(args)).toEqual({
+        display: ":24701",
+        authority: "/tmp/owned-private-auth",
+        wayland: null,
+        socket: join(f.directory, "owned-ipc"),
+      });
+    }
+    expect({
+      display: process.env.DISPLAY,
+      authority: process.env.XAUTHORITY,
+      wayland: process.env.WAYLAND_DISPLAY,
+    }).toEqual(before);
+    await f.runtime.shutdown();
+  });
+  it("preserves the ordinary host display path when no private environment is provided", async () => {
+    const f = await fixture();
+    await f.native.invoke(["ordinary"]);
+    expect(f.launched(["ordinary"])).toMatchObject({
+      display: process.env.DISPLAY ?? null,
+      authority: process.env.XAUTHORITY ?? null,
+      wayland: process.env.WAYLAND_DISPLAY ?? null,
+      socket: join(f.directory, "owned-ipc"),
+    });
+    await f.runtime.shutdown();
+  });
+  it("refuses missing, remote or extra values that could override managed IPC/profile/session identity", async () => {
+    for (const value of [
+      { DISPLAY: ":24701" },
+      { DISPLAY: "remote.example:0", XAUTHORITY: "/tmp/auth" },
+      { DISPLAY: ":24701", XAUTHORITY: "relative-auth" },
+      { DISPLAY: ":24701", XAUTHORITY: "/tmp/auth", AGENT_BROWSER_SOCKET_DIR: "/tmp/other-ipc" },
+      { DISPLAY: ":24701", XAUTHORITY: "/tmp/auth", HOME: "/tmp/other-home" },
+    ]) {
+      await expect(fixture(value)).rejects.toThrow("display environment is invalid");
+    }
+  });
+});