@omercnet/paseo-shared-browser 1.2.1 → 1.2.2-next.237.1

package/server/video-source-recovery.test.ts

@@ -0,0 +1,20 @@
+import { expect, it } from "vitest";
+import { createVideoSourceRecovery } from "./video-source-recovery";
+
+it("uses monotonic cooldown and clears permanent refusal only on exact configuration replacement", () => {
+  let now = 0;
+  const recovery = createVideoSourceRecovery(() => now);
+  const context = { connection: {}, page: {}, viewport: {}, attachmentGeneration: 0 };
+  recovery.failed(context, "startup");
+  expect(recovery.blocked(context)).toBe("startup");
+  now = 2999;
+  expect(recovery.blocked(context)).toBe("startup");
+  now = 3000;
+  expect(recovery.blocked(context)).toBeNull();
+  recovery.failed(context, "source-dimensions");
+  now = 1_000_000;
+  expect(recovery.blocked({ ...context })).toBe("source-dimensions");
+  expect(recovery.blocked({ ...context, viewport: {} })).toBeNull();
+  recovery.failed(context, "source-dimensions");
+  expect(recovery.blocked({ ...context, attachmentGeneration: 1 })).toBeNull();
+});

package/server/video-source-recovery.ts

@@ -0,0 +1,64 @@
+/** Native source recovery is viewing-only and never retries a browser mutation.
+ * Transient failures wait three monotonic seconds after failure admission, and
+ * retirement independently gates replacement. A proven
+ * size mismatch remains blocked until the owning attachment or viewport changes.
+ */
+import { performance } from "node:perf_hooks";
+
+export const VIDEO_SOURCE_RECOVERY_COOLDOWN_MS = 3_000;
+export type VideoSourceFailureCode =
+  | "startup"
+  | "source-stopped"
+  | "source-reset"
+  | "source-dimensions";
+export interface VideoSourceRecoveryContext {
+  connection: unknown;
+  page: unknown;
+  viewport: unknown;
+  attachmentGeneration: number;
+}
+
+/** Keep failure admission separate from track lifetime, so demand cannot pin a
+ * failed source and a stopped permanent failure cannot spin up replacements. */
+export function createVideoSourceRecovery(now: () => number = () => performance.now()) {
+  let context: VideoSourceRecoveryContext | null = null;
+  let failure: VideoSourceFailureCode | null = null;
+  let retryAfter = 0;
+  const sameContext = (value: VideoSourceRecoveryContext): boolean => {
+    if (context === null) {
+      return false;
+    }
+    return (
+      value.connection === context.connection &&
+      value.page === context.page &&
+      value.viewport === context.viewport &&
+      value.attachmentGeneration === context.attachmentGeneration
+    );
+  };
+  const selectContext = (value: VideoSourceRecoveryContext) => {
+    if (sameContext(value)) {
+      return;
+    }
+    context = { ...value };
+    failure = null;
+    retryAfter = 0;
+  };
+  return {
+    /** Returns a private reason while acquisition is blocked. Document changes
+     * alone cannot cure a mismatch in this exact configured pixel geometry. */
+    blocked(value: VideoSourceRecoveryContext): VideoSourceFailureCode | null {
+      selectContext(value);
+      if (failure === "source-dimensions" || now() < retryAfter) {
+        return failure;
+      }
+      return null;
+    },
+    /** Start the cooldown before asynchronous retirement, closing the admission
+     * gap even when cleanup is slow. Cleanup completion remains mandatory. */
+    failed(value: VideoSourceRecoveryContext, code: VideoSourceFailureCode): void {
+      selectContext(value);
+      failure = code;
+      retryAfter = now() + VIDEO_SOURCE_RECOVERY_COOLDOWN_MS;
+    },
+  };
+}

package/server/viewer-capture-lifetime.ts

@@ -0,0 +1,51 @@
+/**
+ * Releases optional capture resources when their last viewer lease expires.
+ * Pixel receipts are not ownership: failed startup can still own a track/helper.
+ * The browser itself stays alive. Callers recheck current viewers before cleanup.
+ */
+export interface ViewerCaptureLifetime {
+  /** Start or refresh cleanup scheduling after capture is attempted. */
+  arm(): void;
+  /** Cancel this lifetime during explicit cleanup or session disposal. */
+  cancel(): void;
+}
+
+/** Own one unreferenced timer per session, using current viewer expiry facts. */
+export function createViewerCaptureLifetime(options: {
+  now(): number;
+  latestExpiry(): number | null;
+  onExpired(): Promise<void>;
+}): ViewerCaptureLifetime {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let revision = 0;
+
+  function cancel(): void {
+    revision += 1;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  }
+
+  function arm(): void {
+    cancel();
+    const expiry = options.latestExpiry();
+    if (expiry === null) return;
+    const scheduledRevision = revision;
+    timer = setTimeout(
+      async () => {
+        timer = null;
+        if (scheduledRevision !== revision) return;
+        const currentExpiry = options.latestExpiry();
+        if (currentExpiry !== null && currentExpiry > options.now()) {
+          arm();
+          return;
+        }
+        // A slow cleanup must not clear a newer viewer's schedule or replay work.
+        await options.onExpired().catch(() => undefined);
+      },
+      Math.max(1, expiry - options.now()),
+    );
+    timer.unref?.();
+  }
+
+  return { arm, cancel };
+}

package/server/virtual-display.test.ts

@@ -0,0 +1,184 @@
+import { EventEmitter } from "node:events";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { beforeEach, expect, it, vi } from "vitest";
+import { createPrivateVirtualDisplay, encodeDisplayAuthority } from "./virtual-display";
+
+/** Host-native path: production joins with the platform separator. */
+const fixtureDirectory = join(tmpdir(), "private-display-fixture");
+
+const fake = vi.hoisted(() => ({
+  access: vi.fn(),
+  chmod: vi.fn(),
+  mkdtemp: vi.fn(),
+  rm: vi.fn(),
+  writeFile: vi.fn(),
+  spawn: vi.fn(),
+  connect: vi.fn(),
+}));
+vi.mock("node:fs/promises", () => fake);
+vi.mock("node:child_process", () => ({ spawn: fake.spawn }));
+vi.mock("node:net", () => ({ createConnection: fake.connect }));
+
+let child: EventEmitter & {
+  pid: number;
+  exitCode: number | null;
+  signalCode: string | null;
+  stdio: unknown[];
+  kill: ReturnType<typeof vi.fn>;
+};
+let ready: Readable;
+beforeEach(() => {
+  vi.clearAllMocks();
+  fake.access.mockResolvedValue(undefined);
+  fake.chmod.mockResolvedValue(undefined);
+  fake.mkdtemp.mockResolvedValue(fixtureDirectory);
+  fake.writeFile.mockResolvedValue(undefined);
+  fake.rm.mockResolvedValue(undefined);
+  ready = new Readable({ read() {} });
+  child = Object.assign(new EventEmitter(), {
+    pid: 123,
+    exitCode: null,
+    signalCode: null,
+    stdio: [null, null, null, ready],
+    kill: vi.fn(() => {
+      child.signalCode = "SIGTERM";
+      child.emit("exit", null, "SIGTERM");
+      return true;
+    }),
+  });
+  fake.spawn.mockImplementation((_path, args) => {
+    queueMicrotask(() => ready.push(`${args[0].slice(1)}\n`));
+    return child;
+  });
+  fake.connect.mockImplementation(() => {
+    const socket = Object.assign(new EventEmitter(), {
+      destroy: vi.fn(),
+      write: vi.fn((packet: Buffer) => {
+        const response = Buffer.alloc(8);
+        response[0] = packet.readUInt16LE(8) === 16 ? 1 : 0;
+        response.writeUInt16LE(11, 2);
+        queueMicrotask(() => socket.emit("data", response));
+      }),
+    });
+    queueMicrotask(() => socket.emit("connect"));
+    return socket;
+  });
+});
+
+it("keeps non-Linux and missing Xvfb on the original path without side effects", async () => {
+  expect(await createPrivateVirtualDisplay({ platform: "win32" })).toBeNull();
+  expect(fake.access).not.toHaveBeenCalled();
+  fake.access.mockRejectedValue(Object.assign(new Error(), { code: "ENOENT" }));
+  expect(await createPrivateVirtualDisplay({ platform: "linux" })).toBeNull();
+  expect(fake.spawn).not.toHaveBeenCalled();
+  expect(fake.mkdtemp).not.toHaveBeenCalled();
+});
+
+it("uses an authenticated private high abstract-only display and idempotent cleanup", async () => {
+  const originalDisplay = process.env.DISPLAY;
+  const display = await createPrivateVirtualDisplay({ platform: "linux" });
+  expect(display).not.toBeNull();
+  const args = fake.spawn.mock.calls[0]![1] as string[];
+  expect(Number(args[0]!.slice(1))).toBeGreaterThanOrEqual(20_000);
+  expect(args).toEqual([
+    args[0],
+    "-screen",
+    "0",
+    "3840x3840x24",
+    "-nolisten",
+    "unix",
+    "-nolisten",
+    "tcp",
+    "-nolock",
+    "-auth",
+    join(fixtureDirectory, "authority"),
+    "-displayfd",
+    "3",
+  ]);
+  expect(fake.chmod).toHaveBeenCalledWith(fixtureDirectory, 0o700);
+  expect(fake.writeFile.mock.calls[0]![2]).toEqual({ mode: 0o600, flag: "wx" });
+  expect(fake.connect).toHaveBeenCalledTimes(2); // Authorized and anonymous denial.
+  expect(fake.connect.mock.calls[0]![0].path).toBe(`\0/tmp/.X11-unix/X${args[0]!.slice(1)}`);
+  expect(process.env.DISPLAY).toBe(originalDisplay);
+  display!.assertAvailable();
+  await display!.stop();
+  await display!.stop();
+  expect(child.kill).toHaveBeenCalledTimes(1);
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+  expect(() => display!.assertAvailable()).toThrow("ended");
+});
+
+it("refuses a changed readiness identity before transmitting the secret", async () => {
+  fake.spawn.mockImplementation(() => {
+    queueMicrotask(() => ready.push("0\n"));
+    return child;
+  });
+  await expect(createPrivateVirtualDisplay({ platform: "linux" })).rejects.toThrow(
+    "identity changed",
+  );
+  expect(fake.connect).not.toHaveBeenCalled();
+  expect(child.kill).toHaveBeenCalledTimes(1);
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+});
+
+it("bounds a never-ready child and removes its authority file", async () => {
+  fake.spawn.mockReturnValue(child);
+  await expect(createPrivateVirtualDisplay({ platform: "linux", timeoutMs: 5 })).rejects.toThrow(
+    "not ready",
+  );
+  expect(child.kill).toHaveBeenCalledTimes(1);
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+});
+
+it("handles spawn failure and prevents silent headless fallback", async () => {
+  fake.spawn.mockImplementation(() => {
+    queueMicrotask(() => child.emit("error", new Error("fixture spawn failure")));
+    return child;
+  });
+  await expect(createPrivateVirtualDisplay({ platform: "linux" })).rejects.toThrow(
+    "failed to start",
+  );
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+});
+
+it("refuses a display which accepts clients without the private cookie", async () => {
+  fake.connect.mockImplementation(() => {
+    const socket = Object.assign(new EventEmitter(), {
+      destroy: vi.fn(),
+      write: () => {
+        const response = Buffer.alloc(8);
+        response[0] = 1;
+        response.writeUInt16LE(11, 2);
+        queueMicrotask(() => socket.emit("data", response));
+      },
+    });
+    queueMicrotask(() => socket.emit("connect"));
+    return socket;
+  });
+  await expect(createPrivateVirtualDisplay({ platform: "linux" })).rejects.toThrow(
+    "unauthenticated",
+  );
+  expect(child.kill).toHaveBeenCalledTimes(1);
+});
+
+it("invalidates on unexpected child exit without starting a replacement", async () => {
+  const display = await createPrivateVirtualDisplay({ platform: "linux" });
+  child.exitCode = 1;
+  child.emit("exit", 1);
+  expect(() => display!.assertAvailable()).toThrow("ended");
+  await display!.stop();
+  expect(fake.spawn).toHaveBeenCalledTimes(1);
+  expect(child.kill).not.toHaveBeenCalled();
+});
+
+it("encodes the display-scoped authority format and rejects malformed inputs", () => {
+  const cookie = Buffer.alloc(16, 7);
+  const authority = encodeDisplayAuthority("23067", cookie);
+  expect(authority.readUInt16BE(0)).toBe(65_535);
+  expect(authority.includes(Buffer.from("MIT-MAGIC-COOKIE-1"))).toBe(true);
+  expect(authority.subarray(-16)).toEqual(cookie);
+  expect(() => encodeDisplayAuthority("0", cookie)).toThrow();
+  expect(() => encodeDisplayAuthority("23067", Buffer.alloc(2))).toThrow();
+});

package/server/virtual-display.ts

@@ -0,0 +1,236 @@
+/**
+ * Owns one authenticated, invisible Linux X display per browser runtime. Abstract
+ * Unix transport avoids WSLg's protected pathname directory; TCP is never enabled.
+ * The display stays alive across CDP reconnects. Startup failure is definitive:
+ * callers must not silently relaunch a partly initialized browser headlessly.
+ */
+import { type ChildProcess, spawn } from "node:child_process";
+import { randomBytes, randomInt } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Readable } from "node:stream";
+import { MAX_VIEWPORT } from "../shared/viewport-limits";
+import { RuntimeLostError } from "./runtime-protocol";
+
+const AUTH_NAME = "MIT-MAGIC-COOKIE-1";
+const STARTUP_MS = 5_000;
+
+/** Fixed-text startup failure; safe to show operators because it never embeds paths or secrets. */
+export class PrivateDisplayError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PrivateDisplayError";
+  }
+}
+
+export interface PrivateVirtualDisplay {
+  readonly launchEnvironment: Readonly<{ DISPLAY: string; XAUTHORITY: string }>;
+  /** Throws RuntimeLostError after the display exits; it never creates a replacement display. */
+  assertAvailable(): void;
+  /** Idempotently terminates only the owned child and removes its private auth file. */
+  stop(): Promise<void>;
+}
+
+/** Serializes a FamilyWild Xauthority record, scoped to this display and cookie. */
+export function encodeDisplayAuthority(display: string, cookie: Buffer): Buffer {
+  if (!/^\d{4,5}$/.test(display) || Number(display) > 65_535 || cookie.length !== 16) {
+    throw new PrivateDisplayError("Invalid private display authority");
+  }
+  const fields = [Buffer.alloc(0), Buffer.from(display), Buffer.from(AUTH_NAME), cookie];
+  const family = Buffer.alloc(2);
+  family.writeUInt16BE(65_535);
+  return Buffer.concat([
+    family,
+    ...fields.flatMap((field) => {
+      const length = Buffer.alloc(2);
+      length.writeUInt16BE(field.length);
+      return [length, field];
+    }),
+  ]);
+}
+
+/** Performs a bounded X11 setup exchange to prove the owned secret is accepted. */
+export async function authenticateDisplay(display: string, cookie: Buffer): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const socket = createConnection({ path: `\0/tmp/.X11-unix/X${display}` });
+    let settled = false;
+    let received = Buffer.alloc(0);
+    const finish = (ready: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(ready);
+    };
+    const timer = setTimeout(() => finish(false), 200);
+    socket.once("error", () => finish(false));
+    socket.once("close", () => finish(false));
+    socket.once("connect", () => {
+      const name = Buffer.from(AUTH_NAME);
+      const header = Buffer.alloc(12);
+      header[0] = 0x6c; // X11 little-endian client, protocol 11.
+      header.writeUInt16LE(11, 2);
+      header.writeUInt16LE(name.length, 6);
+      header.writeUInt16LE(cookie.length, 8);
+      socket.write(Buffer.concat([header, name, Buffer.alloc(2), cookie]));
+    });
+    socket.on("data", (chunk) => {
+      if (received.length + chunk.length > 32_768) return finish(false);
+      received = Buffer.concat([received, chunk]);
+      if (received.length >= 8) {
+        finish(received[0] === 1 && received.readUInt16LE(2) === 11);
+      }
+    });
+  });
+}
+
+/** Reads only the exact child readiness FD before sending its cookie to a socket. */
+async function waitDisplayReady(
+  child: ChildProcess,
+  display: string,
+  timeoutMs: number,
+): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const ready = child.stdio[3] as Readable;
+    let response = "";
+    const finish = (error?: Error) => {
+      clearTimeout(timer);
+      ready.removeListener("data", onData);
+      ready.removeListener("error", onError);
+      child.removeListener("error", onError);
+      child.removeListener("exit", onExit);
+      ready.destroy();
+      if (error) reject(error);
+      else resolve();
+    };
+    const onError = () =>
+      finish(new PrivateDisplayError("Private browser display failed to start"));
+    const onExit = () =>
+      finish(new PrivateDisplayError("Private browser display ended before readiness"));
+    const onData = (chunk: Buffer) => {
+      response += chunk.toString("ascii");
+      if (response.length > 16)
+        return finish(new PrivateDisplayError("Invalid private display readiness"));
+      if (response.includes("\n")) {
+        finish(
+          response === `${display}\n`
+            ? undefined
+            : new PrivateDisplayError("Private display identity changed"),
+        );
+      }
+    };
+    const timer = setTimeout(
+      () => finish(new PrivateDisplayError("Private browser display was not ready")),
+      timeoutMs,
+    );
+    ready.on("data", onData);
+    ready.once("error", onError);
+    child.once("error", onError);
+    child.once("exit", onExit);
+  });
+}
+
+/** Stops a spawned child before deleting the secret it may still be reading. */
+async function stopDisplayChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null || !child.pid) return;
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => child.kill("SIGKILL"), 1_000);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    child.kill("SIGTERM");
+  });
+}
+
+/**
+ * Starts Xvfb only for Linux hidden browsers when the existing executable exists.
+ * Absence returns null. Present-but-broken Xvfb fails closed with bounded cleanup.
+ * No process.env mutation, network listener, host display, or dependency install.
+ * One 3840x3840x24 framebuffer is bounded at about 57 MiB before server overhead;
+ * Chromium CPU/memory costs remain those of the existing browser runtime.
+ */
+export async function createPrivateVirtualDisplay(
+  options: { platform?: NodeJS.Platform; executablePath?: string; timeoutMs?: number } = {},
+): Promise<PrivateVirtualDisplay | null> {
+  if ((options.platform ?? process.platform) !== "linux") return null;
+  const executable = options.executablePath ?? "/usr/bin/Xvfb";
+  try {
+    await access(executable, constants.X_OK);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new PrivateDisplayError("Private browser display executable is not usable");
+  }
+  const display = String(randomInt(20_000, 60_000));
+  const directory = await mkdtemp(join(tmpdir(), "paseo-browser-display-"));
+  const authPath = join(directory, "authority");
+  const cookie = randomBytes(16);
+  let child: ChildProcess | null = null;
+  let stopPromise: Promise<void> | null = null;
+  let exited = false;
+  const stop = () =>
+    (stopPromise ??= (async () => {
+      exited = true;
+      try {
+        if (child) await stopDisplayChild(child);
+      } finally {
+        await rm(directory, { recursive: true, force: true });
+      }
+    })());
+  try {
+    await chmod(directory, 0o700);
+    await writeFile(authPath, encodeDisplayAuthority(display, cookie), { mode: 0o600, flag: "wx" });
+    child = spawn(
+      executable,
+      [
+        `:${display}`,
+        "-screen",
+        "0",
+        `${MAX_VIEWPORT.width}x${MAX_VIEWPORT.height}x24`,
+        "-nolisten",
+        "unix",
+        "-nolisten",
+        "tcp",
+        "-nolock",
+        "-auth",
+        authPath,
+        "-displayfd",
+        "3",
+      ],
+      { stdio: ["ignore", "ignore", "ignore", "pipe"] },
+    );
+    child.once("error", () => {
+      exited = true;
+    });
+    child.once("exit", () => {
+      exited = true;
+    });
+    // An explicit high display plus readiness FD does not invoke Xvfb's scan
+    // starting at :0. The child's pipe proves it bound that exact listener first.
+    await waitDisplayReady(
+      child,
+      display,
+      Math.min(STARTUP_MS, Math.max(1, options.timeoutMs ?? STARTUP_MS)),
+    );
+    if (exited || !(await authenticateDisplay(display, cookie))) {
+      throw new PrivateDisplayError("Private browser display authentication failed");
+    }
+    if (await authenticateDisplay(display, Buffer.alloc(0))) {
+      throw new PrivateDisplayError("Private browser display accepted an unauthenticated client");
+    }
+    if (exited) throw new PrivateDisplayError("Private browser display ended");
+    return {
+      launchEnvironment: Object.freeze({ DISPLAY: `:${display}`, XAUTHORITY: authPath }),
+      assertAvailable() {
+        if (exited) throw new RuntimeLostError("Private browser display ended");
+      },
+      stop,
+    };
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+}

package/shared/browser-display-preferences.ts

@@ -0,0 +1,46 @@
+/**
+ * Host-persisted display favorites through Paseo's settings service. These values
+ * affect viewing quality and picker convenience, never input ownership, page
+ * navigation, emulation or pixel density. Version1 migration retains the bitrate
+ * formerly coupled to JPEG quality.
+ * Retired IDs remain parseable; the current catalogue prunes them at the view.
+ */
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+import { DEFAULT_CAPTURE_QUALITY } from "./capture-settings";
+import { DEVICE_PRESETS } from "./device-presets";
+import {
+  resolveVideoEncoderSettings,
+  videoBitrateSchema,
+  videoFrameRateSchema,
+} from "./video-settings";
+
+export const browserDisplayPreferencesSchema = z.object({
+  captureQuality: z.enum(["low", "medium", "high", "maximum"]).default(DEFAULT_CAPTURE_QUALITY),
+  videoBitrate: videoBitrateSchema.default(12_000_000),
+  videoFps: videoFrameRateSchema.default(30),
+  favoritePresetIds: z.array(z.string().min(1).max(128)).max(DEVICE_PRESETS.length).default([]),
+});
+
+export type BrowserDisplayPreferences = z.output<typeof browserDisplayPreferencesSchema>;
+
+/** One revisioned document per plugin host, shared across that host's panels. */
+export const browserDisplayPreferences = defineSettings({
+  id: "display-preferences",
+  scope: "host",
+  version: 2,
+  migrate(values, fromVersion) {
+    if (fromVersion !== 1 || !values || typeof values !== "object") return values;
+    const previous = values as Record<string, unknown>;
+    const quality =
+      previous.captureQuality === "low" || previous.captureQuality === "medium"
+        ? previous.captureQuality
+        : "high";
+    return {
+      ...previous,
+      videoBitrate: resolveVideoEncoderSettings({ quality }).bitrate,
+      videoFps: 30,
+    };
+  },
+  schema: browserDisplayPreferencesSchema,
+});

package/shared/browser-video.ts

@@ -0,0 +1,80 @@
+/**
+ * Encoded browser-tab video over the existing authenticated Paseo RPC transport.
+ * Opt-in on the daemon and decoded by WebCodecs on the web; every other client retains JPEG.
+ * Packets never grant control; only a decoded
+ * presentation with current browser authority can provide an input target.
+ */
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { browserFrameSchema, browserStateSchema } from "./browser";
+import { videoBitrateSchema, videoFrameRateSchema } from "./video-settings";
+import { MAX_VIEWPORT } from "./viewport-limits";
+
+export const VIDEO_MAX_PACKET_BYTES = 2 * 1024 * 1024;
+export const VIDEO_MAX_BATCH_BYTES = 4 * 1024 * 1024;
+export const VIDEO_MAX_BATCH_PACKETS = 32;
+export const VIDEO_MAX_WAIT_MS = 500;
+export const VIDEO_FRAME_RATE = 30;
+/** Maximum future source-clock skew admitted by the calibrated native capture. */
+export const VIDEO_SOURCE_CLOCK_TOLERANCE_MS = 50;
+
+const opaqueIdSchema = browserFrameSchema.shape.frameId;
+const sequenceSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const base64PacketSchema = z
+  .string()
+  .min(1)
+  .max(Math.ceil(VIDEO_MAX_PACKET_BYTES / 3) * 4);
+
+/** Geometry and generation shared by JPEG and decoded video input admission. */
+export const browserFrameAuthoritySchema = browserFrameSchema.omit({
+  mimeType: true,
+  transport: true,
+  dataBase64: true,
+  byteLength: true,
+});
+export type BrowserFrameAuthority = z.infer<typeof browserFrameAuthoritySchema>;
+
+/** Native encoded output; timestamps are source VideoFrame microseconds, not wall-clock time. */
+export const nativeVideoPacketSchema = z.object({
+  streamId: opaqueIdSchema,
+  captureGeneration: sequenceSchema,
+  sequence: sequenceSchema,
+  timestampUs: sequenceSchema,
+  type: z.enum(["key", "delta"]),
+  codec: z.string().min(1).max(64),
+  width: z.number().int().positive().max(MAX_VIEWPORT.width),
+  height: z.number().int().positive().max(MAX_VIEWPORT.height),
+  descriptionBase64: z.string().max(16_384).optional(),
+  dataBase64: base64PacketSchema,
+  capturedAt: z.string().datetime(),
+});
+export type NativeVideoPacket = z.infer<typeof nativeVideoPacketSchema>;
+
+export const browserVideoPacketSchema = nativeVideoPacketSchema.extend({
+  frame: browserFrameAuthoritySchema,
+});
+export type BrowserVideoPacket = z.infer<typeof browserVideoPacketSchema>;
+
+export const readBrowserVideoRpc = defineRpc({
+  name: "shared-browser.video.read",
+  input: z.object({
+    viewerToken: opaqueIdSchema,
+    quality: z.enum(["low", "medium", "high"]).default("high"),
+    bitrate: videoBitrateSchema.optional(),
+    fps: videoFrameRateSchema.optional(),
+    streamId: opaqueIdSchema.nullable().default(null),
+    afterSequence: sequenceSchema.default(0),
+    requestKeyFrame: z.boolean().default(false),
+    waitMs: z.number().int().min(0).max(VIDEO_MAX_WAIT_MS).default(250),
+  }),
+  output: z.object({
+    state: browserStateSchema,
+    status: z.enum(["ready", "waiting", "reset", "unsupported"]),
+    streamId: opaqueIdSchema.nullable(),
+    packets: z.array(browserVideoPacketSchema).max(VIDEO_MAX_BATCH_PACKETS),
+    reason: z.string().max(256).optional(),
+    reasonCode: z.enum(["encoder-capacity", "video-disabled"]).optional(),
+  }),
+});
+export type BrowserVideoReadInput = z.infer<typeof readBrowserVideoRpc.input>;
+export type BrowserVideoReadReply = z.infer<typeof readBrowserVideoRpc.output>;