@volter/browser-cdp 0.1.48 → 0.1.49

package/src/preview-browser-host.ts

@@ -1,273 +0,0 @@
-import type { DispatcherOptions, ProtocolPeer } from "@volter/almostcdp/core";
-import { BrowserSandboxBridge, type BrowserSandboxBridgeOptions } from "@volter/browser-runtime/browser-sandbox-bridge.js";
-import { SANDBOX_CHANNEL } from "@volter/browser-runtime/sandbox-protocol.js";
-import { MessagePortTransport } from "@volter/almostcdp/message-port";
-
-type BrowserContextHost = NonNullable<DispatcherOptions["contextHost"]>;
-type BrowserPageHost = NonNullable<DispatcherOptions["pageHost"]>;
-type SharedBridgeOptions = Omit<BrowserSandboxBridgeOptions, "preview" | "origin" | "nonce" | "port" | "onReady" | "onPreviewLoad">;
-
-export interface PreviewBrowserHostOptions {
-  /** Where page frames are mounted; the embedding decides how they are shown. */
-  mount: HTMLElement;
-  /** The deployment's sandbox origin: the default context's pages live on it. */
-  sandboxOrigin: string;
-  /** The sandbox bootstrap document every page frame loads. */
-  sandboxPath?: string;
-  /**
-   * The origin a context's label is served at, where the deployment's sandbox
-   * has its own zone of hosts. By default the label is a subdomain of the
-   * sandbox host, which a loopback name (`c-1.localhost`) or a zone apex serves.
-   */
-  contextOrigin?(label: string): string;
-  bridge: SharedBridgeOptions;
-  /** Registers a created page's surface with the endpoint; resolves once the endpoint lists it. */
-  attachSurface(peer: ProtocolPeer, id: string, signal: AbortSignal): Promise<void>;
-}
-
-export interface PreviewBrowserHost {
-  readonly contextHost: BrowserContextHost;
-  readonly pageHost: BrowserPageHost;
-  dispose(): Promise<void>;
-}
-
-interface Page {
-  frame: HTMLIFrameElement;
-  bridge: BrowserSandboxBridge;
-  contextId?: string;
-}
-
-const CLEAR_TIMEOUT_MS = 15_000;
-/** The page's record of the context origins it made, in its own storage. */
-const ORIGINS_RECORD = "browser-substrate.context-origins";
-/** A context origin in use is held under this lock by the tab using it. */
-const ORIGIN_LOCK = "browser-substrate.context-origin:";
-/** Emptied origins kept for the next contexts; past this, one is emptied for good. */
-const SPARE_ORIGINS = 4;
-
-/**
- * Browser contexts and pages for the tab's CDP endpoint. A context is its own
- * origin, a sibling of the sandbox origin, so its storage and cookies are the
- * browser's own partition; its pages are sandbox frames on that origin, each
- * lent to the endpoint like the preview. A closed context's origin is emptied
- * and given to the next context, keeping its service worker: a fresh origin
- * per context registered a worker per context, and a browser with a debugger
- * attached keeps every one of them running (a suite run reached about 985
- * renderers in ten minutes). Every context shares the tab's container: the
- * servers a page reaches are the project's, as they are for a real browser's
- * contexts.
- */
-export function createPreviewBrowserHost(options: PreviewBrowserHostOptions): PreviewBrowserHost {
-  const sandboxPath = options.sandboxPath ?? "/sandbox.html";
-  const contexts = new Map<string, { origin: string }>();
-  /** Closed contexts' origins, each usable once its emptying has succeeded. */
-  const emptied: { origin: string; ready: Promise<boolean> }[] = [];
-  const held = new Map<string, () => void>();
-
-  // A tab that ends before its contexts are closed leaves their origins, each
-  // with its worker registered and its storage, and no page knew them again
-  // (a morning's work left eight). The page records every origin it makes and
-  // holds a lock on each while it lives: a recorded origin whose lock is free
-  // belongs to no tab, and is taken for the next context or emptied for good.
-  const recorded = (): string[] => {
-    try {
-      const value: unknown = JSON.parse(localStorage.getItem(ORIGINS_RECORD) ?? "[]");
-      return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
-    } catch { return []; }
-  };
-  const record = (origins: string[]): void => {
-    try { localStorage.setItem(ORIGINS_RECORD, JSON.stringify([...new Set(origins)])); } catch { /* storage refused: the origin is still usable */ }
-  };
-  /** Takes an origin's lock, or with `ifFree` only if no tab holds it; resolves whether it is held. */
-  const hold = (origin: string, ifFree: boolean): Promise<boolean> => new Promise((acquired) => {
-    if (!("locks" in navigator)) { acquired(!ifFree); return; }
-    void navigator.locks.request(`${ORIGIN_LOCK}${origin}`, { ifAvailable: ifFree }, (lock) => {
-      if (!lock) { acquired(false); return undefined; }
-      acquired(true);
-      return new Promise<void>((release) => held.set(origin, release));
-    });
-  });
-  /** Empties an origin for good: its worker too. It leaves the record once that succeeded. */
-  const retire = (origin: string): Promise<void> => clearOrigin(origin).then(
-    () => { record(recorded().filter((item) => item !== origin)); },
-    () => undefined,
-  ).finally(() => { held.get(origin)?.(); held.delete(origin); });
-  /** A closed context's origin, emptied for the next context, or for good past the spares. */
-  const release = (origin: string): void => {
-    if (emptied.length >= SPARE_ORIGINS) { void retire(origin); return; }
-    emptied.push({ origin, ready: clearOrigin(origin, "reuse").then(() => true, () => false) });
-  };
-  let adopting = Promise.resolve();
-  for (const origin of recorded()) {
-    // One at a time: each is a frame of its origin loaded to empty it.
-    adopting = adopting.then(async () => { if (await hold(origin, true)) release(origin); });
-  }
-  const pages = new Map<string, Page>();
-
-  const contextOrigin = (): string => {
-    const label = `c-${[...crypto.getRandomValues(new Uint8Array(8))].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
-    if (options.contextOrigin) return new URL(options.contextOrigin(label)).origin;
-    const base = new URL(options.sandboxOrigin);
-    if (/^[0-9.]+$/u.test(base.hostname) || base.hostname.startsWith("[")) {
-      throw new Error(`Isolated browser contexts need a sandbox host name; ${base.hostname} is an address.`);
-    }
-    // workers.dev serves one level of names: a context host under the
-    // sandbox's own name does not exist there.
-    if (base.hostname.endsWith(".workers.dev")) {
-      throw new Error(`Isolated browser contexts need the sandbox on a zone of its own; ${base.hostname} is a workers.dev host.`);
-    }
-    return `${base.protocol}//${label}.${base.host}`;
-  };
-
-  const frameFor = (origin: string, query: Record<string, string>): HTMLIFrameElement => {
-    const frame = document.createElement("iframe");
-    frame.style.cssText = "border:0;width:1280px;height:720px;display:block";
-    const url = new URL(sandboxPath, origin);
-    for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value);
-    frame.src = url.href;
-    options.mount.append(frame);
-    return frame;
-  };
-
-  const closePage = async (id: string): Promise<void> => {
-    const page = pages.get(id);
-    if (!page) return;
-    pages.delete(id);
-    page.bridge.dispose();
-    page.frame.remove();
-  };
-
-  /** Empties an origin's storage from a frame of that origin, then removes the frame. */
-  const clearOrigin = async (origin: string, clear: "1" | "reuse" = "1"): Promise<void> => {
-    const nonce = crypto.randomUUID();
-    const frame = frameFor(origin, { parentOrigin: location.origin, nonce, clear });
-    try {
-      await new Promise<void>((resolve, reject) => {
-        const timer = setTimeout(() => { cleanup(); reject(new Error(`Clearing ${origin} timed out.`)); }, CLEAR_TIMEOUT_MS);
-        const receive = (event: MessageEvent): void => {
-          if (event.origin !== origin || event.source !== frame.contentWindow) return;
-          const data = event.data as { channel?: unknown; nonce?: unknown; type?: unknown; payload?: { message?: string } };
-          if (data?.channel !== SANDBOX_CHANNEL || data.nonce !== nonce) return;
-          if (data.type === "cleared") { cleanup(); resolve(); }
-          else if (data.type === "error") { cleanup(); reject(new Error(data.payload?.message ?? `Clearing ${origin} failed.`)); }
-        };
-        const cleanup = (): void => { clearTimeout(timer); window.removeEventListener("message", receive); };
-        window.addEventListener("message", receive);
-      });
-    } finally {
-      frame.remove();
-    }
-  };
-
-  const contextHost: BrowserContextHost = {
-    async createContext(context, signal) {
-      if (context.proxyServer !== undefined || context.proxyBypassList !== undefined) {
-        throw new Error("A context's network is the tab's; a per-context proxy is unavailable.");
-      }
-      if (context.originsWithUniversalNetworkAccess?.length) {
-        throw new Error("Universal network access for named origins is unavailable in the tab.");
-      }
-      signal.throwIfAborted();
-      let origin: string | undefined;
-      while (!origin && emptied.length > 0) {
-        const candidate = emptied.shift()!;
-        if (await candidate.ready) origin = candidate.origin;
-        // Not emptied: it stays recorded, and a later page tries again.
-        else { held.get(candidate.origin)?.(); held.delete(candidate.origin); }
-        signal.throwIfAborted();
-      }
-      if (!origin) {
-        origin = contextOrigin();
-        await hold(origin, false);
-        record([...recorded(), origin]);
-      }
-      contexts.set(context.id, { origin });
-    },
-    async disposeContext(id) {
-      const context = contexts.get(id);
-      if (!context) return;
-      await Promise.all([...pages].filter(([, page]) => page.contextId === id).map(([pageId]) => closePage(pageId)));
-      contexts.delete(id);
-      // The context is closed once its pages are, so emptying its storage
-      // (a frame of the origin loaded to do it) goes on after the answer, as
-      // Chromium's closing does not wait on disk: awaited, it held
-      // Playwright's context teardown past a test's timeout. The next context
-      // waits for it instead; an origin that could not be emptied is never
-      // given out again.
-      release(context.origin);
-    },
-  };
-
-  const pageHost: BrowserPageHost = {
-    async createPage(page, signal) {
-      const context = page.browserContextId === undefined ? undefined : contexts.get(page.browserContextId);
-      if (page.browserContextId !== undefined && !context) throw new Error("No browser context with given id");
-      const origin = context?.origin ?? new URL(options.sandboxOrigin).origin;
-      const nonce = crypto.randomUUID();
-      // A page opens blank, is attached, and is then taken to the guest
-      // server it names under that port's prefix, the way a client's own
-      // first navigation takes it there, as Chromium's page starts blank and
-      // then loads its URL. Opened on the guest's port and navigated before
-      // attaching, a page never attached (a window.open's popup,
-      // Target.createTarget with a URL): creation hung.
-      const opening = guestAddress(page.url);
-      const port = 0;
-      const frame = frameFor(origin, { parentOrigin: location.origin, nonce, port: String(port) });
-      const bridge = new BrowserSandboxBridge({ ...options.bridge, preview: frame, origin, nonce, port });
-      pages.set(page.id, { frame, bridge, ...(page.browserContextId !== undefined ? { contextId: page.browserContextId } : {}) });
-      const abort = (): void => { void closePage(page.id); };
-      signal.addEventListener("abort", abort, { once: true });
-      try {
-        // The surface registers under the target id before creation resolves.
-        const channel = await bridge.connectProtocol(page.id);
-        const transport = new MessagePortTransport(channel.port);
-        void channel.closed.then((reason) => transport.close(1001, reason));
-        // A page is handed over once its first document has loaded, as
-        // Chromium's is committed before `Target.createTarget` answers: a
-        // client's first navigation otherwise interrupts the frame's own.
-        await bridge.initialPreviewReady;
-        signal.throwIfAborted();
-        await options.attachSurface(transport, page.id, signal);
-        // Attached first, then taken to its URL: a navigation while the
-        // surface attached kept it from ever attaching.
-        if (opening) await bridge.navigate(`${origin}/__virtual__/${opening.port}${opening.path}`);
-      } catch (cause) {
-        await closePage(page.id);
-        throw cause;
-      } finally {
-        signal.removeEventListener("abort", abort);
-      }
-    },
-    closePage,
-  };
-
-  return {
-    contextHost,
-    pageHost,
-    async dispose() {
-      await Promise.allSettled([...pages.keys()].map(closePage));
-      const origins = [...contexts.values()].map((context) => context.origin);
-      contexts.clear();
-      await adopting;
-      for (const entry of emptied.splice(0)) if (await entry.ready) origins.push(entry.origin);
-      await Promise.allSettled(origins.map(retire));
-    },
-  };
-}
-
-/**
- * The guest server a page is opened on: `about:blank` opens the default port,
- * a loopback URL opens its own port and path. Anything else is not served in
- * the tab.
- */
-function guestAddress(url: string): { port: number; path: string } | undefined {
-  if (url === "" || url === "about:blank") return undefined;
-  let parsed: URL;
-  try { parsed = new URL(url); } catch { throw new Error(`Invalid page URL: ${url}`); }
-  const loopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
-  if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || !loopback) {
-    throw new Error(`A page opens on a guest server of the tab; ${url} is not one.`);
-  }
-  const port = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
-  return { port, path: `${parsed.pathname}${parsed.search}${parsed.hash}` };
-}

package/src/preview-cdp-endpoint.ts

@@ -1,206 +0,0 @@
-import { createSocketEndpoint, type ByteSocket, type SocketEndpoint } from "@volter/almostcdp/socket";
-import type { ProtocolPeer } from "@volter/almostcdp/core";
-import { MessagePortTransport } from "@volter/almostcdp/message-port";
-import type { BrowserSandboxBridge } from "@volter/browser-runtime/browser-sandbox-bridge.js";
-import type { BrowserServerBridge } from "@volter/browser-runtime/browser-http.js";
-import type { BrowserVirtualWebSocketRegistry, VirtualWebSocketHandlers } from "@volter/browser-runtime/browser-virtual-websocket.js";
-import { createPreviewBrowserHost, type PreviewBrowserHostOptions } from "./preview-browser-host.js";
-
-/** A loopback listener of the tab: WALI's `listenTcp`, a Node container's `listenNet`. */
-export type PreviewCdpListener = (port: number, accept: (socket: ByteSocket) => void) => () => void;
-
-export interface PreviewCdpPublication {
-  readonly port: number;
-  /** What a client inside the tab passes to `connectOverCDP`. */
-  readonly url: string;
-  /** A browser-level client over a transport the host decodes, such as a launch pipe. */
-  attachClient(peer: ProtocolPeer): void;
-  close(): Promise<void>;
-}
-
-const REATTACH_DELAY_MS = 250;
-
-/**
- * The preview as a Chrome DevTools Protocol endpoint on a loopback port of the
- * tab. AlmostCDP serves discovery and the DevTools WebSockets on each accepted
- * connection; the preview's surface is lent through the authenticated sandbox
- * bridge and lent again whenever the sandbox document is replaced, which a
- * client sees as its page target closing and a new one appearing.
- */
-export function publishPreviewCdp(options: {
-  /**
-   * The preview's bridge, which lends the preview as a page target. Without
-   * one the endpoint still serves contexts and pages a client creates, which
-   * is all a launched browser needs.
-   */
-  bridge?: BrowserSandboxBridge;
-  port: number;
-  listen: PreviewCdpListener;
-  targetId?: string;
-  /**
-   * Browser contexts and pages beyond the preview: `Target.createBrowserContext`
-   * and `Target.createTarget` open sandbox frames here. Without it they refuse.
-   */
-  browser?: Omit<PreviewBrowserHostOptions, "attachSurface">;
-  /**
-   * The same endpoint as a server in the tab's port table, so a page of the
-   * tab reaches it and a live tunnel of that port carries it off the machine.
-   */
-  portTable?: { port: number; ports: Pick<BrowserServerBridge, "registerServer" | "unregisterServer">; webSockets: BrowserVirtualWebSocketRegistry };
-  /**
-   * The endpoint's discovery documents alone (`/json/version`, `/json/list`)
-   * in the tab's port table, where a program's `fetch` to a loopback port
-   * goes: Puppeteer reads `browserURL` so. The WebSocket they name stays on
-   * the listener, which the tab's programs reach and a page of the tab does
-   * not, so a page learns the address and cannot drive the browser.
-   */
-  discoveryTable?: { port: number; ports: Pick<BrowserServerBridge, "registerServer" | "unregisterServer"> };
-  /**
-   * Where a download a page makes is written: the path Playwright names in
-   * its client's filesystem, which is the container's. Without it the
-   * endpoint refuses download policy by name.
-   */
-  downloads?: { write(path: string, bytes: Uint8Array): Promise<void> };
-  /**
-   * Reads a file a client names by path for a page's file input
-   * (DOM.setFileInputFiles): the client's filesystem, the container's. The
-   * page is given those files' bytes alone. Without it the endpoint refuses
-   * file paths by name.
-   */
-  files?: {
-    read(path: string): Promise<{ data: Uint8Array; name?: string; type?: string; lastModified?: number }>;
-    /** A directory's files by their paths relative to it (a folder upload); undefined for a file. */
-    list?(path: string): Promise<string[] | undefined>;
-  };
-}): PreviewCdpPublication {
-  const { bridge, port } = options;
-  let endpoint!: SocketEndpoint;
-  const host = options.browser ? createPreviewBrowserHost({
-    ...options.browser,
-    attachSurface: (peer, id, signal) => attachAndAwait(endpoint, peer, id, signal),
-  }) : undefined;
-  endpoint = createSocketEndpoint({
-    address: `127.0.0.1:${port}`,
-    ...(host ? { contextHost: host.contextHost, pageHost: host.pageHost } : {}),
-    ...(options.downloads ? { downloadHost: { write: (_context: string | undefined, path: string, bytes: Uint8Array) => options.downloads!.write(path, bytes) } } : {}),
-    ...(options.files ? { fileHost: options.files } : {}),
-  });
-  const unlisten = options.listen(port, (socket) => endpoint.serve(socket));
-  const unpublish = options.portTable ? servePortTable(endpoint, options.portTable)
-    : options.discoveryTable ? serveDiscovery(endpoint, options.discoveryTable) : undefined;
-  const targetId = options.targetId ?? "preview";
-  let closed = false;
-
-  if (bridge) void (async () => {
-    while (!closed) {
-      try {
-        const channel = await bridge.connectProtocol(targetId);
-        const transport = new MessagePortTransport(channel.port);
-        void channel.closed.then((reason) => transport.close(1001, reason));
-        if (closed) { transport.close(1001, "Preview CDP publication closed"); return; }
-        const lost = new Promise<void>((resolve) => transport.on("close", resolve));
-        endpoint.attachSurface(transport);
-        await lost;
-      } catch (error) {
-        // A disposed bridge never lends its preview again; every other failure
-        // (not yet ready, a dropped transfer, a replaced document) is retried.
-        if (error instanceof Error && error.message === "Browser sandbox bridge is disposed.") return;
-      }
-      if (!closed) await new Promise((resolve) => setTimeout(resolve, REATTACH_DELAY_MS));
-    }
-  })();
-
-  return {
-    port,
-    url: `http://127.0.0.1:${port}`,
-    attachClient: (peer) => endpoint.attachClient(peer),
-    async close() {
-      if (closed) return;
-      closed = true;
-      unlisten();
-      unpublish?.();
-      await endpoint.close();
-      await host?.dispose();
-    },
-  };
-}
-
-/** Lends a page surface and resolves once the endpoint lists it under its target id. */
-async function attachAndAwait(endpoint: SocketEndpoint, peer: ProtocolPeer, id: string, signal: AbortSignal): Promise<void> {
-  let lost = false;
-  peer.on("close", () => { lost = true; });
-  endpoint.attachSurface(peer);
-  while (!endpoint.targets().some((target) => target.id === id)) {
-    signal.throwIfAborted();
-    if (lost) throw new Error("The page surface closed before it registered.");
-    await new Promise((resolve) => setTimeout(resolve, 10));
-  }
-}
-
-/**
- * Discovery as the port's HTTP server and DevTools WebSockets as its socket
- * endpoint. Discovery names the address the request came in on: a loopback
- * host plainly, any other host (a live tunnel's) behind TLS.
- */
-/** The discovery documents as a GET-only server of the port table. */
-function serveDiscovery(
-  endpoint: SocketEndpoint,
-  table: { port: number; ports: Pick<BrowserServerBridge, "registerServer" | "unregisterServer"> },
-): () => void {
-  const encoder = new TextEncoder();
-  table.ports.registerServer({
-    listening: true,
-    address: () => ({ port: table.port, address: "0.0.0.0", family: "IPv4" }),
-    async handleRequest(method, url, headers) {
-      if (method !== "GET" && method !== "HEAD") return { statusCode: 405, headers: { allow: "GET, HEAD" } };
-      const host = headers.host ?? headers.Host ?? `127.0.0.1:${table.port}`;
-      const loopback = /^(localhost|127\.0\.0\.1|\[::1\])(:|$)/u.test(host);
-      const { status, body } = endpoint.discovery(new URL(url, "http://localhost").pathname, loopback ? host : `wss://${host}`);
-      return { statusCode: status, headers: { "content-type": "application/json; charset=UTF-8" }, ...(method === "GET" ? { body: encoder.encode(JSON.stringify(body)) } : {}) };
-    },
-  }, table.port);
-  return () => table.ports.unregisterServer(table.port);
-}
-
-function servePortTable(
-  endpoint: SocketEndpoint,
-  table: { port: number; ports: Pick<BrowserServerBridge, "registerServer" | "unregisterServer">; webSockets: BrowserVirtualWebSocketRegistry },
-): () => void {
-  const unregisterDiscovery = serveDiscovery(endpoint, table);
-  const unregisterSockets = table.webSockets.register(table.port, {
-    open(path: string, _protocols: readonly string[], handlers: VirtualWebSocketHandlers) {
-      const messageListeners: ((data: { toString(): string }) => void)[] = [];
-      const closeListeners: (() => void)[] = [];
-      let state = 1;
-      const finish = (): void => {
-        if (state === 3) return;
-        state = 3;
-        for (const listener of closeListeners) listener();
-      };
-      const peer: ProtocolPeer = {
-        get readyState() { return state; },
-        send: (data) => { if (state === 1) handlers.message({ kind: "text", text: data }); },
-        close: (code, reason) => { if (state !== 1) return; handlers.close(code, reason, true); finish(); },
-        on: ((event: "message" | "close", listener: ((data: { toString(): string }) => void) | (() => void)) => {
-          if (event === "message") messageListeners.push(listener as (data: { toString(): string }) => void);
-          else closeListeners.push(listener as () => void);
-        }) as ProtocolPeer["on"],
-      };
-      queueMicrotask(() => {
-        handlers.open("");
-        endpoint.connect(peer, path);
-      });
-      return {
-        send(data) {
-          if (data.kind !== "text") { peer.close(1003, "CDP messages are text"); return; }
-          for (const listener of messageListeners) listener(data.text);
-        },
-        close(code = 1000, reason = "") { handlers.close(code, reason, true); finish(); },
-      };
-    },
-  });
-  return () => {
-    unregisterSockets();
-    unregisterDiscovery();
-  };
-}

package/src/sandbox-surface.ts

@@ -1,27 +0,0 @@
-import { connectDomSurface } from "@volter/almostcdp/dom";
-import { MessagePortTransport } from "@volter/almostcdp/message-port";
-import { createCaptureAdapter } from "@volter/almostcdp/capture-stream";
-import { createDomAccessibility } from "@volter/almostcdp/accessibility";
-import { registerPreviewProtocolSurface } from "@volter/browser-runtime/sandbox-preview-inspector.js";
-
-/**
- * The sandbox page lends its preview as an AlmostCDP DOM surface. Imported by
- * the sandbox bootstrap of an embedding that publishes the tab's CDP
- * endpoint; the runtime itself lends no protocol.
- */
-registerPreviewProtocolSurface((port, id, hooks) => connectDomSurface({
-  id,
-  target: hooks.window,
-  validateDocument: hooks.validateDocument,
-  urls: hooks.urls,
-  transport: new MessagePortTransport(port),
-  navigation: hooks.navigation,
-  // The sandbox bridge carries the preview's document requests through the
-  // surface's network door, so a navigation answers with its outcome.
-  carriedDocuments: true,
-  documentStart: hooks.documentStart,
-  capture: createCaptureAdapter((params) => hooks.capture(params), "dom-rasterized"),
-  // The accessibility tree read from the page's DOM, as a client's
-  // Accessibility.getFullAXTree asks (chrome-devtools-mcp's snapshot).
-  accessibility: createDomAccessibility(),
-}));

package/src/tab-chromium.ts

@@ -1,143 +0,0 @@
-import type { BrowserRuntime } from "@volter/browser-runtime";
-import type { BrowserSandboxBridge } from "@volter/browser-runtime/browser-sandbox-bridge.js";
-import { CHROMIUM_FACE_PROGRAMS, chromiumFaceRunner, placeChromiumFace, playwrightChromiumRevisions } from "./chromium-face.js";
-import type { PreviewBrowserHostOptions } from "./preview-browser-host.js";
-import { publishPreviewCdp, type PreviewCdpListener, type PreviewCdpPublication } from "./preview-cdp-endpoint.js";
-
-/** The port a client in the tab passes to `connectOverCDP`, as Chromium's default. */
-export const TAB_CDP_PORT = 9222;
-
-export interface TabChromiumOptions {
-  runtime: BrowserRuntime;
-  /** The preview's bridge, to publish the preview itself as a page target; a launched browser does not need it. */
-  bridge?: BrowserSandboxBridge;
-  /** A loopback listener of the tab, such as a Node container's `listenNet`. */
-  listen: PreviewCdpListener;
-  /** Where browser contexts and pages the endpoint creates are opened. */
-  browser: Omit<PreviewBrowserHostOptions, "attachSurface">;
-  /** The home Playwright's registry looks under: the `HOME` the tab's programs run with. */
-  home: string;
-  /** The project roots whose installed playwright-core pins are read for the revisions to place. */
-  roots: readonly string[];
-  /** The same endpoint in the tab's port table, so a page of the tab or a shared port reaches it. */
-  portTable?: Parameters<typeof publishPreviewCdp>[0]["portTable"];
-  /** The discovery documents alone in the tab's port table, under the endpoint's port. */
-  discoveryTable?: Parameters<typeof publishPreviewCdp>[0]["discoveryTable"];
-  port?: number;
-}
-
-export interface TabChromium {
-  readonly publication: PreviewCdpPublication;
-  dispose(): Promise<void>;
-}
-
-/**
- * A Chromium for the tab's own Playwright: the preview published as a CDP
- * endpoint, and the face registered under Chromium's executable names and
- * placed where each installed playwright-core's registry looks, so a project's
- * unchanged `playwright` launches it over its debugging pipe. A page's
- * download is written where the Playwright client in the container reads it.
- */
-export function installTabChromium(options: TabChromiumOptions): TabChromium {
-  const { runtime } = options;
-  const fs = runtime.filesystem;
-  const publication = publishPreviewCdp({
-    ...(options.bridge ? { bridge: options.bridge } : {}),
-    port: options.port ?? TAB_CDP_PORT,
-    listen: options.listen,
-    browser: options.browser,
-    ...(options.portTable ? { portTable: options.portTable } : {}),
-    ...(options.discoveryTable ? { discoveryTable: options.discoveryTable } : {}),
-    downloads: {
-      async write(path, bytes) {
-        fs.mkdirSync(path.slice(0, path.lastIndexOf("/")) || "/", { recursive: true });
-        fs.writeFileSync(path, bytes);
-      },
-    },
-    files: {
-      async read(path) {
-        const stat = fs.statSync(path);
-        if (!stat.isFile()) throw new Error(`Not a file: ${path}`);
-        const name = path.slice(path.lastIndexOf("/") + 1);
-        return { data: await fs.readFile(path), name, type: mimeTypeOf(name), lastModified: Math.round(stat.mtimeMs) };
-      },
-      async list(path) {
-        if (!fs.statSync(path).isDirectory()) return undefined;
-        const files: string[] = [];
-        const walk = (directory: string, prefix: string): void => {
-          for (const name of fs.readdirSync(directory).map(String).sort()) {
-            const entry = `${directory}/${name}`;
-            if (fs.statSync(entry).isDirectory()) walk(entry, `${prefix}${name}/`);
-            else files.push(`${prefix}${name}`);
-          }
-        };
-        walk(path.replace(/\/+$/u, ""), "");
-        return files;
-      },
-    },
-  });
-  const face = chromiumFaceRunner((peer) => publication.attachClient(peer));
-  for (const name of CHROMIUM_FACE_PROGRAMS) runtime.registerProgram(name, face, { descriptors: true });
-  const stopPlacing = keepFacePlaced(runtime, options.home, options.roots);
-  return {
-    publication,
-    async dispose() {
-      stopPlacing();
-      await publication.close();
-    },
-  };
-}
-
-/**
- * Where the tab has no Chromium to give (a page that runs its project in-page,
- * with no sandbox to lend frames from), the face is still placed, and
- * launching it says why and where the Chromium is. Without it a project's
- * Playwright reports a missing executable and advises `npx playwright
- * install`, a download that can never run in a tab.
- */
-export function installUnavailableTabChromium(options: {
-  runtime: BrowserRuntime;
-  home: string;
-  roots: readonly string[];
-  /** One line naming what to do instead. */
-  reason: string;
-}): () => void {
-  const message = `chromium: ${options.reason}\n`;
-  const refuse = async (_argv: readonly string[], run: { onStderr?: (text: string) => void }) => {
-    run.onStderr?.(message);
-    return { stdout: "", stderr: message, exitCode: 1 };
-  };
-  // Declared like the real face: Playwright launches it with its pipe on fds
-  // 3 and 4, and a program refusing those would be refused first, generically.
-  for (const name of CHROMIUM_FACE_PROGRAMS) options.runtime.registerProgram(name, refuse, { descriptors: true });
-  return keepFacePlaced(options.runtime, options.home, options.roots);
-}
-
-/** Places the face for every playwright-core revision the roots install, again whenever that set changes. */
-function keepFacePlaced(runtime: BrowserRuntime, home: string, roots: readonly string[]): () => void {
-  const fs = runtime.filesystem;
-  let placed = "";
-  const place = async (): Promise<void> => {
-    const revisions = (await playwrightChromiumRevisions(fs, roots)).sort().join(",");
-    if (revisions === placed) return;
-    placed = revisions;
-    // Playwright looks under os.homedir(), which is HOME.
-    await placeChromiumFace(fs, `${home}/.cache/ms-playwright`, revisions ? revisions.split(",") : []);
-  };
-  // Playwright can arrive with the image or later; its pin is one file, read when it changes.
-  const placing = setInterval(() => { void place().catch((cause: unknown) => console.error("Chromium face placement failed:", cause)); }, 2_000);
-  void place().catch((cause: unknown) => console.error("Chromium face placement failed:", cause));
-  return () => clearInterval(placing);
-}
-
-/** A file's type as Chromium gives a picked file one: by its extension. */
-function mimeTypeOf(name: string): string {
-  const extension = name.slice(name.lastIndexOf(".") + 1).toLowerCase();
-  return ({
-    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
-    ico: "image/x-icon", bmp: "image/bmp", avif: "image/avif", txt: "text/plain", html: "text/html", htm: "text/html",
-    css: "text/css", js: "text/javascript", mjs: "text/javascript", json: "application/json", xml: "text/xml", csv: "text/csv",
-    pdf: "application/pdf", zip: "application/zip", gz: "application/gzip", wasm: "application/wasm", mp3: "audio/mpeg",
-    wav: "audio/wav", ogg: "audio/ogg", mp4: "video/mp4", webm: "video/webm", woff: "font/woff", woff2: "font/woff2",
-  } as Record<string, string>)[extension] ?? "";
-}

package/tsconfig.build.json

@@ -1,5 +0,0 @@
-{
-  "extends": "../../tsconfig.package.json",
-  "compilerOptions": { "rootDir": "src", "outDir": "dist", "types": [] },
-  "include": ["src/**/*.ts"]
-}