@brianmsm/quarto-bento 0.0.0-stage → 0.1.0

package/distribution/runtime/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Norman Peña Calero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/distribution/runtime/_extensions/qbento/_extension.yml

@@ -0,0 +1,24 @@
+title: Quarto Bento
+version: 0.1.0
+quarto-required: ">=1.10.19"
+contributes:
+  engines:
+    - path: producer-activation.js
+  project:
+    project:
+      type: default
+      # Quarto 1.10 resolves bare extension hooks to absolute, unquoted commands.
+      # Keep these fixed project-relative paths so spaces in the project are safe.
+      pre-render: _extensions/qbento/pre.ts
+      post-render: _extensions/qbento/post.ts
+    filters:
+      - guard.lua
+    format: qbento-html
+  formats:
+    html:
+      theme: none
+      output-ext: qbento-stage.html
+      fig-format: svg
+      filters:
+        - at: post-quarto
+          path: capture.lua

package/distribution/runtime/_extensions/qbento/capture.lua

@@ -0,0 +1,21 @@
+-- Quarto writes a disposable stage; the post hook safely publishes the final deck.
+function Pandoc(doc)
+  local input = quarto.doc.input_file
+  local stage = pandoc.path.filename(input):gsub('%.qmd$', '.qbento-stage.html')
+  if pandoc.path.filename(PANDOC_STATE.output_file) ~= stage then
+    error('UNSAFE_QUARTO_OUTPUT: qbento-html must write ' .. stage .. '; remove output-file/--output overrides')
+  end
+  local dir = pandoc.path.directory(input)
+  local receiptFile = assert(io.open(pandoc.path.join({dir, '.qbento', 'quarto-run.json'}), 'r'),
+    'QUARTO_PROJECT_REQUIRED: use project type qbento and its pre/post hooks')
+  local receipt = quarto.json.decode(receiptFile:read('*a'))
+  receiptFile:close()
+  if receipt.source ~= input then error('QUARTO_SOURCE_MISMATCH: receipt belongs to a different source') end
+  local capture = {
+    token = receipt.token,
+    ast = quarto.json.decode(pandoc.write(pandoc.Pandoc(doc.blocks, { title = doc.meta.title }), 'json'))
+  }
+  local out = assert(io.open(pandoc.path.join({dir, '.qbento', 'quarto-stage', 'executed.json'}), 'w'))
+  out:write(quarto.json.encode(capture))
+  out:close()
+end

package/distribution/runtime/_extensions/qbento/guard.lua

@@ -0,0 +1,7 @@
+-- Project-wide: also protects the final deck when --to selects a different format.
+function Pandoc(doc)
+  local output = tostring(PANDOC_STATE.output_file)
+  if output:match('%.bento%.html$') then
+    error('UNSAFE_QUARTO_OUTPUT: Quarto may not write a .bento.html directly; use qbento-html staging and guarded publication')
+  end
+end

package/distribution/runtime/_extensions/qbento/post.ts

@@ -0,0 +1,2 @@
+import { afterQuartoRender } from "./runtime/src/integration/quarto.ts";
+await afterQuartoRender();

package/distribution/runtime/_extensions/qbento/pre.ts

@@ -0,0 +1,2 @@
+import { beforeQuartoRender } from "./runtime/src/integration/quarto.ts";
+await beforeQuartoRender();

package/distribution/runtime/_extensions/qbento/producer-activation.js

@@ -0,0 +1,129 @@
+import { producerEnvironment } from "./runtime/src/render/producer-environment.ts";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Quarto 1.10.19's public engine initializer runs in its parent process. This
+// narrowly scoped compatibility adapter leaves the selected engine as knitr.
+const directory = fileURLToPath(new URL("../../", import.meta.url));
+const profile = fileURLToPath(
+  new URL("./runtime/src/render/producer-profile.R", import.meta.url),
+);
+const manifestPath = resolve(
+  directory,
+  ".qbento/quarto-stage/producer-manifest.json",
+);
+const receiptPath = resolve(directory, ".qbento/quarto-run.json");
+const activation = Symbol.for("quarto-bento.producer-activation");
+
+export default {
+  name: "qbento-producer-activation",
+  // The R launcher adapter is accepted against this exact installed revision.
+  quartoRequired: "=1.10.19",
+  defaultExt: ".qmd",
+  defaultYaml: () => [],
+  defaultContent: () => [],
+  validExtensions: () => [],
+  claimsFile: () => false,
+  claimsLanguage: () => false,
+  canFreeze: false,
+  generatesFigures: false,
+  init(quarto) {
+    if (Deno.env.get("QBENTO_INTERNAL_RENDER") === "1") return;
+    const original = quarto.system?.execProcess;
+    if (
+      typeof original !== "function" ||
+      typeof quarto.path?.resource !== "function"
+    ) {
+      throw new Error(
+        "UNSUPPORTED_QUARTO_PRODUCER_ADAPTER: expected Quarto's shared R launcher API",
+      );
+    }
+    if (original[activation] === directory) return;
+    if (original[activation]) {
+      throw new Error(
+        "UNSUPPORTED_QUARTO_PRODUCER_ADAPTER: another project already activated the R launcher",
+      );
+    }
+    const rmdScript = quarto.path.resource("rmd/rmd.R");
+    const adapter = async function (options, stdin, ...rest) {
+      if (
+        !(options.args ?? []).includes(rmdScript) || typeof stdin !== "string"
+      ) return original.call(this, options, stdin, ...rest);
+
+      const request = JSON.parse(stdin);
+      if (request.action !== "execute") {
+        return original.call(this, options, stdin, ...rest);
+      }
+      const input = request.params?.input;
+      if (
+        typeof input !== "string" || !input.endsWith(".qmd") ||
+        dirname(resolve(input)) !== resolve(directory)
+      ) return original.call(this, options, stdin, ...rest);
+
+      const run = JSON.parse(Deno.readTextFileSync(receiptPath));
+      if (
+        run.version !== 1 || run.source !== resolve(input) ||
+        run.process?.pid !== Deno.pid ||
+        typeof run.producerHash !== "string" ||
+        !/^[a-f0-9]{64}$/.test(run.producerHash)
+      ) {
+        throw new Error(
+          "INVALID_PRODUCER_RECEIPT: the R execution has no current guarded source receipt",
+        );
+      }
+      const manifest = JSON.parse(Deno.readTextFileSync(manifestPath));
+      if (manifest.chunks.length === 0) {
+        return original.call(this, options, stdin, ...rest);
+      }
+      const startup = await producerEnvironment({
+        cwd: options.cwd ?? directory,
+        command: options.cmd,
+        args: options.args,
+        env: options.env,
+      });
+      const selected = startup.originalProfile;
+      // These values affect this R subprocess only. Inspection, user scripts,
+      // other engines and the user's shell keep their original environment.
+      return original.call(
+        this,
+        {
+          ...options,
+          args: ["--no-environ", ...startup.args],
+          env: {
+            ...startup.effective,
+            R_PROFILE_USER: profile,
+            ...(startup.args.includes("--no-site-file") ? {} : {
+              R_PROFILE: fileURLToPath(
+                new URL(
+                  "./runtime/src/render/producer-site-profile.R",
+                  import.meta.url,
+                ),
+              ),
+            }),
+            QBENTO_ORIGINAL_R_SITE_SET:
+              startup.effective.R_PROFILE === undefined ? "0" : "1",
+            QBENTO_ORIGINAL_R_SITE: startup.effective.R_PROFILE ?? "",
+            QBENTO_PRODUCER_PROFILE: profile,
+            QBENTO_ORIGINAL_R_PROFILE_SET: selected === undefined ? "0" : "1",
+            QBENTO_ORIGINAL_R_PROFILE_USER: selected ?? "",
+            QBENTO_PRODUCER_MANIFEST: manifestPath,
+          },
+        },
+        stdin,
+        ...rest,
+      );
+    };
+    adapter[activation] = directory;
+    quarto.system.execProcess = adapter;
+    if (quarto.system.execProcess !== adapter) {
+      throw new Error(
+        "UNSUPPORTED_QUARTO_PRODUCER_ADAPTER: Quarto's R launcher cannot be activated",
+      );
+    }
+  },
+  launch() {
+    throw new Error(
+      "UNSUPPORTED_QUARTO_PRODUCER_ADAPTER: producer activation must not replace an execution engine",
+    );
+  },
+};

package/distribution/runtime/src/bridge/browser.js

@@ -0,0 +1,168 @@
+/**
+ * Version-bound public-API bridge for Bento 3d6f7f1fcdf2308e875345ce4f1e0ec0820c914b.
+ * No Store hooks exist on window.bento. Polling observes snapshots, NOT every
+ * intermediate operation. Save always reads the live document synchronously.
+ */
+export function isDisabledCollaboration(value) {
+  return !!value && Object.keys(value).sort().join(",") === "key,on,room" &&
+    value.room === "" && value.key === "" && value.on === false;
+}
+
+export const BENTO_REVISION = "3d6f7f1fcdf2308e875345ce4f1e0ec0820c914b";
+
+/**
+ * @template {{docId:string, format:string, version:number, slides:Array<{id:string}>}} D
+ * @param {{doc:D, selection:string[], loadDoc:(json:string)=>any, undo:()=>void, redo:()=>void}} api
+ * @param {{docId:string,persist:(snapshot:{doc:D,docId:string,revision:number})=>Promise<unknown>,onEvent?:(event:any)=>void,pollMs?:number}} options
+ */
+export function createBentoBridge(api, options) {
+  if (
+    !api ||
+    !["loadDoc", "undo", "redo"].every((k) => typeof api[k] === "function") ||
+    !Array.isArray(api.selection)
+  ) {
+    throw new Error(
+      "BENTO_BRIDGE_INCOMPATIBLE: full editor public API required",
+    );
+  }
+  const emit = options.onEvent ?? (() => {});
+  let disposed = false;
+  let revision = 0;
+  let savedRevision = 0;
+  let queue = Promise.resolve();
+  const read = () => {
+    const doc = JSON.parse(JSON.stringify(api.doc));
+    if (doc.docId !== options.docId) {
+      throw new Error("BENTO_IDENTITY_CHANGED: open deck differs from project");
+    }
+    if (
+      doc.format !== "bento/slides" || doc.version !== 1 ||
+      !Array.isArray(doc.slides)
+    ) throw new Error("BENTO_BRIDGE_INCOMPATIBLE: document format");
+    if (doc.collab && !isDisabledCollaboration(doc.collab)) {
+      throw new Error(
+        "BENTO_COLLAB_DISABLED: collaborative documents cannot enter Studio",
+      );
+    }
+    return doc;
+  };
+  let current = read();
+  let fingerprint = JSON.stringify(current);
+  let selection = JSON.stringify(api.selection);
+  const active = () => {
+    if (disposed) throw new Error("BENTO_BRIDGE_DISPOSED");
+  };
+  const poll = (reason = "poll") => {
+    active();
+    const doc = read();
+    const next = JSON.stringify(doc);
+    if (next !== fingerprint) {
+      const previousOrder = current.slides.map((s) => s.id);
+      current = doc;
+      fingerprint = next;
+      revision++;
+      emit({
+        type: "document",
+        reason,
+        revision,
+        doc: structuredClone(doc),
+        dirty: true,
+      });
+      const order = doc.slides.map((s) => s.id);
+      if (JSON.stringify(order) !== JSON.stringify(previousOrder)) {
+        emit({ type: "slides", reason, revision, order, previousOrder });
+      }
+    }
+    const selected = JSON.stringify(api.selection);
+    if (selected !== selection) {
+      selection = selected;
+      emit({ type: "selection", selection: JSON.parse(selected) });
+    }
+    return { doc: structuredClone(current), docId: options.docId, revision };
+  };
+  const timer = options.pollMs === 0 ? undefined : setInterval(() => {
+    try {
+      poll();
+    } catch (error) {
+      emit({ type: "error", error });
+    }
+  }, Math.max(options.pollMs ?? 200, 50));
+  return {
+    poll,
+    snapshot: () => poll("snapshot"),
+    get dirty() {
+      poll();
+      return revision !== savedRevision;
+    },
+    get revision() {
+      return revision;
+    },
+    save() {
+      const snapshot = poll("save");
+      // Sequential persistence prevents a slower earlier request overwriting a
+      // later save. A failed write does not poison the next retry or clear dirty.
+      const task = queue.then(async () => {
+        emit({ type: "saving", revision: snapshot.revision });
+        try {
+          const receipt = await options.persist(snapshot);
+          savedRevision = snapshot.revision;
+          if (!disposed) poll("save-complete");
+          emit({
+            type: "saved",
+            revision: snapshot.revision,
+            dirty: revision !== savedRevision,
+            receipt,
+          });
+          return receipt;
+        } catch (error) {
+          emit({ type: "save-error", revision: snapshot.revision, error });
+          throw error;
+        }
+      });
+      queue = task.then(() => {}, () => {});
+      return task;
+    },
+    /** Project restoration, not importing a different document. Undoable. */
+    load(doc) {
+      active();
+      if (doc.docId !== options.docId) {
+        throw new Error("BENTO_IDENTITY_CHANGED: refusing foreign document");
+      }
+      if (doc.collab && !isDisabledCollaboration(doc.collab)) {
+        throw new Error("BENTO_COLLAB_DISABLED");
+      }
+      const before = JSON.stringify(api.doc);
+      const report = api.loadDoc(JSON.stringify(doc));
+      if (!report) {
+        throw new Error("BENTO_LOAD_REJECTED: document remains unchanged");
+      }
+      if (Array.isArray(report.dropped) && report.dropped.length) {
+        api.undo();
+        if (JSON.stringify(api.doc) !== before) {
+          throw new Error("BENTO_LOAD_ROLLBACK_FAILED");
+        }
+        emit({ type: "load-rejected", report });
+        throw new Error(
+          "BENTO_LOAD_LOSSY: unsupported fields; original document restored",
+        );
+      }
+      poll("load");
+      emit({ type: "loaded", report });
+      return report;
+    },
+    undo() {
+      active();
+      api.undo();
+      return poll("undo");
+    },
+    redo() {
+      active();
+      api.redo();
+      return poll("redo");
+    },
+    dispose() {
+      if (timer !== undefined) clearInterval(timer);
+      disposed = true;
+    },
+  };
+}

package/distribution/runtime/src/bridge/isolation.ts

@@ -0,0 +1,55 @@
+import { isDisabledCollaboration } from "./browser.js";
+
+/** Non-secret off sentinel prevents upstream's unconditional credential mint. */
+export function prepareIsolatedDocument<T extends object>(
+  doc: T,
+): T & { collab: { room: string; key: string; on: false } } {
+  const current = (doc as { collab?: unknown }).collab;
+  if (current && !isDisabledCollaboration(current)) {
+    throw new Error("BENTO_COLLAB_DISABLED: refuse a collaborative input");
+  }
+  return { ...structuredClone(doc), collab: { room: "", key: "", on: false } };
+}
+
+/** Insert before all upstream executable scripts, including in standalone HTML.
+ * The upstream pristine-shell capture therefore retains this adapter on Save.
+ * This changes capabilities in this document's realm, never the browser profile.
+ */
+export const ISOLATION_MARKER = "qbento-isolated-host-v1";
+export const ISOLATION_BOOTSTRAP = String.raw`(() => {
+  'use strict';
+  if (globalThis.__qbentoIsolatedHost) return;
+  Object.defineProperty(globalThis, '__qbentoIsolatedHost', {value: 'qbento-isolated-host-v1'});
+  // Upstream has no collaboration-off hook and always constructs this channel.
+  class IsolatedChannel extends EventTarget {
+    constructor(name) { super(); this.name = String(name); this.onmessage = null; this.onmessageerror = null; }
+    postMessage() {} close() {}
+  }
+  Object.defineProperty(globalThis, 'BroadcastChannel', {value:IsolatedChannel, configurable:false, writable:false});
+  // The project journal, not stale same-docId browser recovery, owns Studio state.
+  Object.defineProperty(globalThis, 'indexedDB', {value:undefined, configurable:false, writable:false});
+  class DisabledSocket { constructor() { throw new Error('QBENTO_COLLAB_DISABLED: live sharing unavailable'); } }
+  Object.defineProperty(globalThis, 'WebSocket', {value:DisabledSocket, configurable:false, writable:false});
+  // The UI must not offer a disabled transport. Native local HTML Save still works.
+  const disableShare = () => {
+    document.querySelectorAll('.ed-btn-share').forEach(button => {
+      button.disabled = true;
+      button.title = 'Live sharing is unavailable in Quarto-Bento';
+      button.setAttribute('aria-disabled', 'true');
+    });
+  };
+  new MutationObserver(disableShare).observe(document.documentElement, {childList:true, subtree:true});
+  document.addEventListener('click', event => {
+    if (event.target instanceof Element && event.target.closest('.ed-btn-share,.ed-share-pop')) {
+      event.preventDefault(); event.stopImmediatePropagation();
+    }
+  }, true);
+  disableShare();
+})();`;
+
+/** Offline shell policy. Host Studio persistence is same-origin HTTP only.
+ * Place this meta CSP before upstream styles/scripts, and preferably also send
+ * as an HTTP response header. No remote fonts/assets/widgets or relay sockets.
+ */
+export const OFFLINE_CSP =
+  "default-src 'none'; script-src 'unsafe-inline' 'self' blob:; style-src 'unsafe-inline' 'self'; img-src data: blob: 'self'; font-src data: blob: 'self'; media-src data: blob: 'self'; connect-src 'self'; worker-src blob:; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";

package/distribution/runtime/src/browser/chromium.ts

@@ -0,0 +1,218 @@
+/** Optional installed Chromium, private headless profile, bounded local CDP lifetime. */
+export interface ChromiumClient {
+  send<T = Record<string, unknown>>(
+    method: string,
+    params?: Record<string, unknown>,
+  ): Promise<T>;
+  events: { method: string; params: Record<string, unknown> }[];
+  version: string;
+}
+/** A missing result means a valid prefix of Chromium's two-line endpoint file. */
+export function chromiumEndpoint(contents: string): string | undefined {
+  const invalid = () => {
+    throw new Error("INVALID_CHROMIUM_ENDPOINT");
+  };
+  const newline = contents.indexOf("\n");
+  if (newline < 0) {
+    const port = contents.endsWith("\r") ? contents.slice(0, -1) : contents;
+    if (!/^\d{0,5}$/.test(port) || Number(port) > 65535) invalid();
+    // A zero-only five-digit port cannot become a valid port by appending.
+    if (port.length === 5 && Number(port) === 0) invalid();
+    if (contents.endsWith("\r") && (!port || Number(port) === 0)) invalid();
+    return undefined;
+  }
+  const port = contents.slice(0, newline).replace(/\r$/, "");
+  if (!/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+    invalid();
+  }
+  const rawPath = contents.slice(newline + 1);
+  const path = rawPath.replace(/(?:\r?\n|\r)$/, "");
+  const shape = "/devtools/browser/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
+  if (path.length > shape.length) invalid();
+  for (let i = 0; i < path.length; i++) {
+    if (shape[i] === "x" ? !/[a-f0-9]/.test(path[i]) : path[i] !== shape[i]) {
+      invalid();
+    }
+  }
+  if (path.length < shape.length) {
+    // A newline commits the path; a short committed path is malformed.
+    if (rawPath.endsWith("\n") || rawPath.endsWith("\r")) invalid();
+    return undefined;
+  }
+  if (rawPath.endsWith("\r")) return undefined;
+  return `ws://127.0.0.1:${port}${path}`;
+}
+export async function withHeadlessChromium<T>(
+  options: { chromium?: string; timeoutMs?: number },
+  action: (client: ChromiumClient) => Promise<T>,
+): Promise<T> {
+  const dir = await Deno.makeTempDir({ prefix: "qbento-chromium-" });
+  let child: Deno.ChildProcess | undefined, socket: WebSocket | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+  const pending = new Map<
+    number,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+  const stop = () => {
+    stopped = true;
+    socket?.close();
+    try {
+      child?.kill("SIGKILL");
+    } catch { /* already exited */ }
+    for (const call of pending.values()) {
+      call.reject(new Error("CHROMIUM_CLOSED: capture ended"));
+    }
+    pending.clear();
+  };
+  const removeProfile = async () => {
+    for (let attempt = 0; attempt < 6; attempt++) {
+      try {
+        await Deno.remove(dir, { recursive: true });
+        break;
+      } catch (error) {
+        if (error instanceof Deno.errors.NotFound) break;
+        if (attempt === 5) throw error;
+        await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+      }
+    }
+  };
+  try {
+    try {
+      child = new Deno.Command(options.chromium ?? "chromium", {
+        args: [
+          "--headless",
+          "--no-first-run",
+          "--no-default-browser-check",
+          "--disable-background-networking",
+          "--disable-extensions",
+          "--disable-sync",
+          "--no-pings",
+          "--remote-debugging-address=127.0.0.1",
+          "--remote-debugging-port=0",
+          `--user-data-dir=${dir}`,
+          "about:blank",
+        ],
+        stdout: "null",
+        stderr: "null",
+      }).spawn();
+    } catch (error) {
+      throw new Error(
+        `CHROMIUM_REQUIRED: install/configure a compatible local Chromium for this optional static fallback; ${
+          String(error)
+        }`,
+      );
+    }
+    const run = async () => {
+      let endpoint = "";
+      for (let i = 0; i < 100 && !stopped; i++) {
+        try {
+          const ready = chromiumEndpoint(
+            await Deno.readTextFile(`${dir}/DevToolsActivePort`),
+          );
+          if (ready) {
+            endpoint = ready;
+            break;
+          }
+        } catch (error) {
+          if (!(error instanceof Deno.errors.NotFound)) throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      }
+      if (!endpoint || stopped) {
+        throw new Error(
+          "CHROMIUM_START_FAILED: local debugging endpoint unavailable",
+        );
+      }
+      socket = new WebSocket(endpoint);
+      await new Promise<void>((resolve, reject) => {
+        socket!.onopen = () => resolve();
+        socket!.onerror = () => reject(new Error("CHROMIUM_CONNECTION_FAILED"));
+      });
+      let id = 0;
+      const events: ChromiumClient["events"] = [];
+      socket.onmessage = (event) => {
+        const message = JSON.parse(String(event.data));
+        if (message.id) {
+          const call = pending.get(message.id);
+          pending.delete(message.id);
+          if (message.error) {
+            call?.reject(
+              new Error(`CHROMIUM_PROTOCOL: ${message.error.message}`),
+            );
+          } else call?.resolve(message.result);
+        } else if (events.length < 10_000) {
+          events.push({ method: message.method, params: message.params ?? {} });
+        }
+      };
+      const send = <R>(
+        method: string,
+        params: Record<string, unknown> = {},
+        sessionId?: string,
+      ): Promise<R> =>
+        new Promise((resolve, reject) => {
+          if (stopped) {
+            reject(new Error("CHROMIUM_CLOSED"));
+            return;
+          }
+          const callId = ++id;
+          pending.set(callId, {
+            resolve: resolve as (v: unknown) => void,
+            reject,
+          });
+          socket!.send(
+            JSON.stringify({
+              id: callId,
+              method,
+              params,
+              ...(sessionId ? { sessionId } : {}),
+            }),
+          );
+        });
+      const version = await send<{ product: string }>("Browser.getVersion");
+      const target = await send<{ targetId: string }>("Target.createTarget", {
+        url: "about:blank",
+      });
+      const session = await send<{ sessionId: string }>(
+        "Target.attachToTarget",
+        { targetId: target.targetId, flatten: true },
+      );
+      return await action({
+        send: <R>(method: string, params?: Record<string, unknown>) =>
+          send<R>(method, params, session.sessionId),
+        events,
+        version: version.product,
+      });
+    };
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        stop();
+        reject(
+          new Error(
+            "CHROMIUM_TIMEOUT: headless capture exceeded its bounded deadline",
+          ),
+        );
+      }, options.timeoutMs ?? 30_000);
+    });
+    return await Promise.race([run(), timeout]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (socket?.readyState === WebSocket.OPEN) {
+      // Graceful Browser.close lets renderer/utility children finish profile IO.
+      socket.send(JSON.stringify({ id: 2147483647, method: "Browser.close" }));
+    }
+    if (child) {
+      let grace: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([
+        child.status,
+        new Promise<void>((resolve) => {
+          grace = setTimeout(resolve, 1000);
+        }),
+      ]);
+      if (grace !== undefined) clearTimeout(grace);
+    }
+    stop();
+    if (child) await child.status;
+    await removeProfile();
+  }
+}