browxai 0.7.0

package/dist/engine/registry.d.ts

@@ -0,0 +1,145 @@
+import type { Locator } from "playwright-core";
+import type { EngineKind, EngineCapabilities } from "./types.js";
+import { engineCapabilities } from "./capability-registry.js";
+import type { BrowserSession, SessionOptions } from "../session/types.js";
+import type { SessionEntry } from "../session/registry.js";
+import type { ActionSubstrate } from "../page/action-substrate.js";
+import type { CaptureSubstrate } from "../page/capture-substrate.js";
+import type { StorageSubstrate } from "../page/storage-substrate.js";
+import type { ScriptSubstrate } from "../page/script-substrate.js";
+import type { EmulationSubstrate } from "../page/emulation-substrate.js";
+import type { SnapshotSubstrate } from "../page/snapshot-substrate.js";
+import type { NetworkSubstrate } from "../page/network-substrate.js";
+import type { ActionContext } from "../page/actionresult.js";
+import type { RefRegistry } from "../page/refs.js";
+import type { ScreenshotSaveResult } from "../page/screenshot-save.js";
+import type { CapabilityConfig } from "../util/capabilities.js";
+import type { ConfigStore } from "../util/config-store.js";
+import type { Workspace } from "../util/workspace.js";
+/** The per-capability substrate set a session is wired with. The five
+ *  `host-build.ts` selectors (actionsFor / captureFor / storageFor / scriptFor /
+ *  emulationFor) collapse into producing one of these, and so do the two
+ *  standalone `*-substrate-select.ts` files (`snapshotSubstrateFor` /
+ *  `networkSubstrateFor`) — the engine owns the Safari-vs-Playwright-vs-CDP
+ *  choice once, expressed here, so no engine-name dispatch survives above the
+ *  seam. Each field is a `(e) => Substrate` selector: the engine handle is
+ *  captured per-session from the `SessionEntry`, so the per-call surface carries
+ *  no engine type. (0004-03 §1.) */
+export interface SubstrateBundle {
+    actions: (e: SessionEntry) => ActionSubstrate;
+    capture: (e: SessionEntry) => CaptureSubstrate;
+    storage: (e: SessionEntry) => StorageSubstrate;
+    script: (e: SessionEntry) => ScriptSubstrate;
+    emulation: (e: SessionEntry) => EmulationSubstrate;
+    snapshot: (e: SessionEntry) => SnapshotSubstrate;
+    network: (e: SessionEntry) => NetworkSubstrate;
+}
+/** The per-server host config the `makeSubstrates` factory needs — the exact
+ *  `ctxFor` + `describeTarget` + screenshot-`save` dependencies host-build supplied
+ *  inline before the fold. These CLOSE OVER server-scoped security boundaries
+ *  (`ctxFor` carries the server's originPolicy / config.testAttributes / caps
+ *  gating; `save` writes under the server's `workspace.root`), so the composition
+ *  root threads its OWN per-server set at the `makeSubstrates(deps)` call site —
+ *  never a module-global, which would let a second `createServer()` in the same
+ *  process overwrite the first server's boundary (the in-process SDK transport
+ *  composes one server per transport). Threading explicitly keeps each server's
+ *  substrates bound to ITS deps, so cross-server contamination is impossible. */
+export interface SubstrateDeps {
+    /** Build the `ActionContext` for an action dispatch — the verbatim `ctxFor`
+     *  closure from host-build (it closes over the server's config/originPolicy/caps). */
+    ctxFor: (e: SessionEntry) => ActionContext;
+    /** The structured one-liner alongside an element screenshot. */
+    describeTarget: (loc: Locator, refs: RefRegistry, target: {
+        ref: string;
+    } | {
+        selector: string;
+    } | {
+        coords: {
+            x: number;
+            y: number;
+        };
+    }) => Promise<string>;
+    /** Persist a screenshot buffer to the server's workspace-rooted path. */
+    save: (buf: Buffer, args: {
+        path: string;
+        format: "png" | "jpeg";
+        fullPage: boolean;
+    }) => ScreenshotSaveResult;
+}
+/** The per-server host config the `postWire` step needs — the same locals
+ *  `buildSessionRegistry` owns. These too are server-scoped (`caps` is the
+ *  server's capability gate, `workspace.root` its sandbox write-root), so the
+ *  composition root threads its OWN set at the `postWire(entry, deps)` call site
+ *  rather than a module-global: a second server with different caps/workspace must
+ *  never reach across and wire THIS server's sessions. */
+export interface PostWireDeps {
+    caps: CapabilityConfig;
+    configStore: ConfigStore;
+    workspace: Workspace;
+}
+/** Everything the session layer needs from an engine, declared once in the
+ *  engine's own adapter-registration module. Adding an engine = a new module
+ *  that calls `registerEngine(record)` once; no edit to any session factory, the
+ *  session registry, or host-build. This is the single `EngineEntry` shape the
+ *  whole RFC 0004 suite standardizes on (0004-03 §1) — over the real session
+ *  types, not placeholders. */
+export interface EngineEntry {
+    readonly kind: EngineKind;
+    /** The static capability declaration (deep / sub-interfaces) — today this is
+     *  `capabilitiesFor(kind)`; the registry makes the adapter the owner of its
+     *  own row, not a central table. */
+    readonly capabilities: EngineCapabilities;
+    /** Launch + return the lifecycle session for one of the session modes. Subsumes
+     *  the per-engine launch/attach branching the three session factories carried;
+     *  the factories keep only their MODE concern (the launch mode is threaded
+     *  through `opts.launchMode`, defaulting to managed). */
+    makeAdapter(opts: SessionOptions): Promise<BrowserSession>;
+    /** Build the per-capability substrate selectors for a session of this engine.
+     *  Subsumes the five host-build.ts selectors + the two standalone selectors —
+     *  the Safari-vs-Playwright-vs-CDP choice is the engine's own concern. The
+     *  composition root passes its OWN per-server `SubstrateDeps` (originPolicy /
+     *  workspace / caps / ctxFor, threaded explicitly — NOT a module-global —
+     *  precisely to preserve per-server isolation when two servers share a process). */
+    makeSubstrates(deps: SubstrateDeps): SubstrateBundle;
+    /** Post-creation wiring previously scattered as `sess.engine !== "safari"`
+     *  guards across session-registry.ts — now owned by the engine that needs it.
+     *  The four Playwright engines attach the full console/bridge/policy/download/
+     *  stealth/device-emulation/ws-interactive/workers set; Safari attaches only its
+     *  BiDi console bridge (and the synthetic in-memory engine attaches nothing).
+     *
+     *  Takes the composition root's OWN per-server `PostWireDeps` (caps / configStore
+     *  / workspace) — threaded explicitly at the call site, NOT read from a
+     *  module-global, so a second server in the same process can never wire THIS
+     *  server's sessions with its capabilities or sandbox root.
+     *
+     *  Returns `void` OR a `Promise<void>`: the four Playwright engines AWAIT their
+     *  context attaches (so the session is fully wired before the factory returns it,
+     *  byte-identical to the pre-relocation inline awaits), while the no-op engines
+     *  return sync `void`. The session factory `await`s the result. */
+    postWire(entry: SessionEntry, deps: PostWireDeps): void | Promise<void>;
+}
+/** Add-only registration. Called once per adapter-registration module at module
+ *  load. A sixth engine is a sixth `registerEngine(...)` call in a new file — no
+ *  edit here. Re-registering an engine is a programming error, surfaced loudly so
+ *  a duplicate (e.g. a double-imported barrel) never silently shadows. */
+export declare function registerEngine(def: EngineEntry): void;
+/** The data-driven lookup the factories / selectors / post-wire call. Throws the
+ *  same structured `EngineNotYetSupportedError` the engine-select path does — a
+ *  declared-but-unregistered engine is a refusal, never a silent default. The
+ *  session-mode dispatch stays in the factories; the registry resolves only the
+ *  ENGINE. */
+export declare function engineEntry(kind: EngineKind): EngineEntry;
+/** Whether an engine has a registered entry. Lets a caller branch on
+ *  registration presence (e.g. a test) without forcing the throw. */
+export declare function hasEngine(kind: EngineKind): boolean;
+/** Non-throwing capability lookup — re-exported from the decoupled capability
+ *  side-table (`capability-registry.ts`) so callers can import it from the registry
+ *  surface. The gate imports it from the side-table directly to avoid a cycle. */
+export { engineCapabilities };
+/** Whether an engine's BYOB/attach lane requires an explicit `BROWX_ATTACH_CDP`
+ *  endpoint. Android attach is endpoint-DISCOVERED over adb (no endpoint needed);
+ *  every other engine's CDP-attach lane requires the loopback endpoint. The
+ *  session registry consults this so its attached-mode precondition stays
+ *  engine-agnostic (the one android-specific fact lives here, in the engine layer,
+ *  not as a literal branch in the session registry). */
+export declare function byobAttachNeedsEndpoint(kind: EngineKind): boolean;

package/dist/engine/registry.js

@@ -0,0 +1,67 @@
+// The EngineRegistry (RFC 0004 D1) — the one place an engine's name appears as
+// data. Each engine registers a single `EngineEntry` record (in its own
+// adapters/<engine>.engine.ts module); the session factories, the substrate
+// selection, and the post-creation wiring then resolve everything by a
+// data-driven lookup keyed on `session.engine` — no `if (engine === "literal")`
+// branch survives above the seam.
+//
+// This realizes architecture-principles §4 ("new engine = new adapter behind the
+// existing port"): a sixth engine is a sixth `registerEngine(...)` call in a new
+// file, with no edit to managed.ts / incognito.ts / byob.ts / session-registry.ts
+// / host-build.ts. The strangler-fig discipline (RFC 0004 §1.2): the registry is
+// a pure indirection over the SAME adapter instances + the SAME post-wire steps
+// the if-chains drove, so each engine's observable session is byte-identical —
+// only the dispatch MECHANISM changes.
+import { invariant } from "../util/invariant.js";
+import { EngineNotYetSupportedError } from "./select.js";
+import { setEngineCapabilities, engineCapabilities } from "./capability-registry.js";
+const REGISTRY = new Map();
+/** Add-only registration. Called once per adapter-registration module at module
+ *  load. A sixth engine is a sixth `registerEngine(...)` call in a new file — no
+ *  edit here. Re-registering an engine is a programming error, surfaced loudly so
+ *  a duplicate (e.g. a double-imported barrel) never silently shadows. */
+export function registerEngine(def) {
+    // L8: the record's own `kind` must match the capability row's `engine` — the
+    // registry keys on `def.kind` while the gate reads `def.capabilities.engine`,
+    // so a mismatch would silently gate the wrong engine. Each adapter module
+    // already wires `{ kind: K, capabilities: capabilitiesFor(K) }`, so this holds
+    // on every valid registration; the invariant catches a copy-paste swap at
+    // module load, not in production.
+    invariant(def.kind === def.capabilities.engine, `engine "${def.kind}" registered with capabilities for "${def.capabilities.engine}"`);
+    if (REGISTRY.has(def.kind)) {
+        throw new Error(`engine-registry: "${def.kind}" registered twice`);
+    }
+    REGISTRY.set(def.kind, def);
+    // Mirror the capability declaration into the decoupled side-table so the engine
+    // gate can read it without importing this module (which would form a cycle).
+    setEngineCapabilities(def.kind, def.capabilities);
+}
+/** The data-driven lookup the factories / selectors / post-wire call. Throws the
+ *  same structured `EngineNotYetSupportedError` the engine-select path does — a
+ *  declared-but-unregistered engine is a refusal, never a silent default. The
+ *  session-mode dispatch stays in the factories; the registry resolves only the
+ *  ENGINE. */
+export function engineEntry(kind) {
+    const def = REGISTRY.get(kind);
+    if (!def)
+        throw new EngineNotYetSupportedError(kind);
+    return def;
+}
+/** Whether an engine has a registered entry. Lets a caller branch on
+ *  registration presence (e.g. a test) without forcing the throw. */
+export function hasEngine(kind) {
+    return REGISTRY.has(kind);
+}
+/** Non-throwing capability lookup — re-exported from the decoupled capability
+ *  side-table (`capability-registry.ts`) so callers can import it from the registry
+ *  surface. The gate imports it from the side-table directly to avoid a cycle. */
+export { engineCapabilities };
+/** Whether an engine's BYOB/attach lane requires an explicit `BROWX_ATTACH_CDP`
+ *  endpoint. Android attach is endpoint-DISCOVERED over adb (no endpoint needed);
+ *  every other engine's CDP-attach lane requires the loopback endpoint. The
+ *  session registry consults this so its attached-mode precondition stays
+ *  engine-agnostic (the one android-specific fact lives here, in the engine layer,
+ *  not as a literal branch in the session registry). */
+export function byobAttachNeedsEndpoint(kind) {
+    return kind !== "android";
+}

package/dist/engine/select.d.ts

@@ -0,0 +1,48 @@
+import { type BrowserType } from "playwright-core";
+import type { EngineKind } from "./types.js";
+/** Engines wired today. Chromium + Firefox (Playwright's bundled Juggler build)
+ *  + WebKit (Playwright's bundled WebKit build — the WebKit-ENGINE correctness
+ *  lane, NOT Safari) + Android (real Chrome-on-Android attached over adb + CDP —
+ *  full CDP, `deep: true`) + Safari (REAL Safari.app over safaridriver — the
+ *  first non-Playwright engine, no Playwright Page, curated subset). All five
+ *  `EngineKind` members are implemented; the no-silent-no-op selection error
+ *  remains for any future engine declared before its adapter lands. */
+export declare const IMPLEMENTED_ENGINES: readonly EngineKind[];
+export declare class EngineNotYetSupportedError extends Error {
+    readonly engine: EngineKind;
+    constructor(engine: EngineKind);
+}
+/** Map an `EngineKind` to the Playwright `BrowserType` that drives it. Throws
+ *  `EngineNotYetSupportedError` for engines without an adapter yet. The mapping
+ *  is `playwright[browserType]` — the same surface every Playwright client
+ *  selects on. */
+export declare function resolveBrowserType(engine: EngineKind): BrowserType;
+/** Raised when the operator names an engine that browxai does not implement —
+ *  the top-level `BROWX_ENGINE` / `--engine` validation error. Distinct from
+ *  `EngineNotYetSupportedError` (which guards a *declared-but-unadaptered*
+ *  `EngineKind` at the launch path): this one fires on an arbitrary operator
+ *  string (a typo, an unsupported browser, …) that is not even a known engine,
+ *  BEFORE the server starts. The message lists the implemented engines so the fix
+ *  is in the error. */
+export declare class UnknownEngineError extends Error {
+    readonly value: string;
+    constructor(value: string);
+}
+/** Validate an operator-supplied engine string against `IMPLEMENTED_ENGINES`.
+ *  Returns the value narrowed to `EngineKind` on success; throws
+ *  `UnknownEngineError` (structured, listing the valid engines) otherwise. The
+ *  comparison is exact + case-sensitive: engine kinds are lowercase tokens, and
+ *  silently accepting `Firefox`/`FIREFOX` would mask a misconfiguration. */
+export declare function validateEngine(value: string): EngineKind;
+/** Resolve the operator's engine selection for the MCP server. Precedence:
+ *  an explicit `--engine <kind>` CLI flag wins over the `BROWX_ENGINE` env var,
+ *  which wins over the default `chromium`. Both inputs are validated against
+ *  `IMPLEMENTED_ENGINES`; an unknown value throws `UnknownEngineError`. Returns
+ *  `undefined` when neither is set, so the caller can omit `browserType` and let
+ *  `server.ts` apply its own default (byte-identical to never passing the option).
+ *
+ *  Pure over (argv, env) so it unit-tests without a browser. Mirrors the inline
+ *  env/flag idiom the rest of cli.ts uses (BROWX_HEADLESS, BROWX_ATTACH_CDP),
+ *  lifted into a function only because it carries validation + precedence worth
+ *  testing in isolation. */
+export declare function resolveEngineSelection(argv: readonly string[], env?: NodeJS.ProcessEnv): EngineKind | undefined;

package/dist/engine/select.js

@@ -0,0 +1,128 @@
+// Engine selection. The launch path resolves an `EngineKind` to a Playwright
+// browser-type and rejects the not-yet-implemented engines with a structured
+// error — the doctrine's no-silent-no-op rule: an unsupported engine must fail
+// loudly, naming the engines that are available, not quietly fall back to
+// Chromium.
+import { chromium, firefox, webkit } from "playwright-core";
+// `android` resolves to Playwright's `chromium` BrowserType — Chrome-on-Android
+// speaks full CDP, so the adapter attaches with `chromium.connectOverCDP(wsUrl)`
+// over an adb-forwarded socket, reusing the exact Chromium transport.
+// `safari` has NO entry: it is the first non-Playwright engine (driven over
+// safaridriver, not a Playwright BrowserType), so `resolveBrowserType` is never
+// the path for it — the SafaridriverHybridAdapter owns its own transport. The map
+// is `Partial` to make that explicit at the type level.
+const BROWSER_TYPES = {
+    chromium,
+    firefox,
+    webkit,
+    android: chromium,
+};
+/** Engines wired today. Chromium + Firefox (Playwright's bundled Juggler build)
+ *  + WebKit (Playwright's bundled WebKit build — the WebKit-ENGINE correctness
+ *  lane, NOT Safari) + Android (real Chrome-on-Android attached over adb + CDP —
+ *  full CDP, `deep: true`) + Safari (REAL Safari.app over safaridriver — the
+ *  first non-Playwright engine, no Playwright Page, curated subset). All five
+ *  `EngineKind` members are implemented; the no-silent-no-op selection error
+ *  remains for any future engine declared before its adapter lands. */
+export const IMPLEMENTED_ENGINES = [
+    "chromium",
+    "firefox",
+    "webkit",
+    "android",
+    "safari",
+];
+export class EngineNotYetSupportedError extends Error {
+    engine;
+    constructor(engine) {
+        super(`engine-not-yet-supported: "${engine}" is declared but not yet implemented — ` +
+            "chromium, firefox, webkit, android, and safari are wired today. " +
+            'Use browserType:"chromium" (the default), "firefox", "webkit", "android", or "safari".');
+        this.name = "EngineNotYetSupportedError";
+        this.engine = engine;
+    }
+}
+/** Map an `EngineKind` to the Playwright `BrowserType` that drives it. Throws
+ *  `EngineNotYetSupportedError` for engines without an adapter yet. The mapping
+ *  is `playwright[browserType]` — the same surface every Playwright client
+ *  selects on. */
+export function resolveBrowserType(engine) {
+    if (!IMPLEMENTED_ENGINES.includes(engine)) {
+        throw new EngineNotYetSupportedError(engine);
+    }
+    // chromium + firefox + webkit + android all reach here today (android maps to
+    // the chromium BrowserType — it attaches to real Chrome-on-Android over CDP).
+    // safari has no Playwright BrowserType (it is driven over safaridriver), so it
+    // is not in BROWSER_TYPES — the guard keeps this total without a fake mapping.
+    const browserType = BROWSER_TYPES[engine];
+    if (!browserType) {
+        throw new EngineNotYetSupportedError(engine);
+    }
+    return browserType;
+}
+/** Raised when the operator names an engine that browxai does not implement —
+ *  the top-level `BROWX_ENGINE` / `--engine` validation error. Distinct from
+ *  `EngineNotYetSupportedError` (which guards a *declared-but-unadaptered*
+ *  `EngineKind` at the launch path): this one fires on an arbitrary operator
+ *  string (a typo, an unsupported browser, …) that is not even a known engine,
+ *  BEFORE the server starts. The message lists the implemented engines so the fix
+ *  is in the error. */
+export class UnknownEngineError extends Error {
+    value;
+    constructor(value) {
+        super(`engine "${value}" is not available; implemented engines: ${IMPLEMENTED_ENGINES.join(", ")}`);
+        this.name = "UnknownEngineError";
+        this.value = value;
+    }
+}
+/** Validate an operator-supplied engine string against `IMPLEMENTED_ENGINES`.
+ *  Returns the value narrowed to `EngineKind` on success; throws
+ *  `UnknownEngineError` (structured, listing the valid engines) otherwise. The
+ *  comparison is exact + case-sensitive: engine kinds are lowercase tokens, and
+ *  silently accepting `Firefox`/`FIREFOX` would mask a misconfiguration. */
+export function validateEngine(value) {
+    if (IMPLEMENTED_ENGINES.includes(value)) {
+        return value;
+    }
+    throw new UnknownEngineError(value);
+}
+/** Resolve the operator's engine selection for the MCP server. Precedence:
+ *  an explicit `--engine <kind>` CLI flag wins over the `BROWX_ENGINE` env var,
+ *  which wins over the default `chromium`. Both inputs are validated against
+ *  `IMPLEMENTED_ENGINES`; an unknown value throws `UnknownEngineError`. Returns
+ *  `undefined` when neither is set, so the caller can omit `browserType` and let
+ *  `server.ts` apply its own default (byte-identical to never passing the option).
+ *
+ *  Pure over (argv, env) so it unit-tests without a browser. Mirrors the inline
+ *  env/flag idiom the rest of cli.ts uses (BROWX_HEADLESS, BROWX_ATTACH_CDP),
+ *  lifted into a function only because it carries validation + precedence worth
+ *  testing in isolation. */
+export function resolveEngineSelection(argv, env = process.env) {
+    const flag = readEngineFlag(argv);
+    if (flag !== undefined)
+        return validateEngine(flag);
+    const fromEnv = env.BROWX_ENGINE?.trim();
+    if (fromEnv)
+        return validateEngine(fromEnv);
+    return undefined;
+}
+/** Extract the `--engine <kind>` / `--engine=<kind>` value from an argv slice,
+ *  or undefined when the flag is absent. A bare trailing `--engine` with no
+ *  value throws (an obvious operator mistake, not a silent no-op). */
+function readEngineFlag(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--engine") {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error("--engine requires a value, e.g. `--engine firefox`. See BROWX_ENGINE.");
+            }
+            return next;
+        }
+        if (arg.startsWith("--engine=")) {
+            return arg.slice("--engine=".length);
+        }
+    }
+    return undefined;
+}

package/dist/engine/session-cdp.d.ts

@@ -0,0 +1,13 @@
+import type { CDPSession } from "playwright-core";
+/** A session shape carrying the optional CDP accessor + its engine tag. The
+ *  full `BrowserSession` satisfies this; the helper takes the narrow shape so
+ *  it doesn't pull the whole session interface into the engine module. */
+export interface CdpCapable {
+    readonly engine: string;
+    cdp?(): CDPSession;
+}
+/** Return the session's raw CDP handle. Throws a structured error naming the
+ *  engine when the session has no CDP escape hatch. On Chromium `cdp` is always
+ *  present, so this never throws there — keep it a direct delegate on the hot
+ *  path. */
+export declare function requireCdp(session: CdpCapable): CDPSession;

package/dist/engine/session-cdp.js

@@ -0,0 +1,22 @@
+// CDP-presence assertion for the now-optional `cdp()` member.
+//
+// `BrowserSession.cdp()` used to be mandatory; making it optional is what un-
+// gates multi-engine (the eager `newCDPSession` throws off-Chromium). The ~19
+// CDP-hard tools and the network/a11y substrate still need the raw handle on
+// Chromium — they route through `requireCdp`, which returns the handle on an
+// engine that has it (Chromium: always) and throws a structured, engine-naming
+// error on one that doesn't, rather than letting `undefined.send(...)` blow up
+// opaquely. On the Chromium hot path this is a single truthiness check and a
+// direct delegate — no allocation, no indirection.
+/** Return the session's raw CDP handle. Throws a structured error naming the
+ *  engine when the session has no CDP escape hatch. On Chromium `cdp` is always
+ *  present, so this never throws there — keep it a direct delegate on the hot
+ *  path. */
+export function requireCdp(session) {
+    if (!session.cdp) {
+        throw new Error(`engine "${session.engine}" has no CDP escape hatch — this operation needs raw CDP ` +
+            "(perf / coverage / heap / network tap / a11y substrate) and is only available on " +
+            "chromium today.");
+    }
+    return session.cdp();
+}

package/dist/engine/tool-gate.d.ts

@@ -0,0 +1,19 @@
+import type { EngineKind } from "./types.js";
+/** Record that a tool needs the raw-CDP (`deep`) escape hatch, from its colocated
+ *  `host.register({ deep: true })` metadata (RFC 0004 P2). The only writer of the
+ *  derived `DEEP_TOOLS` set. Idempotent. */
+export declare function declareDeepTool(tool: string): void;
+export declare function installDeepToolsCollector(collect: () => void): void;
+export declare const DEEP_TOOLS: ReadonlySet<string>;
+/** The structured refusal envelope an engine-gated tool returns. Mirrors
+ *  `assertPdfSupported`'s `{error, hint} | null` shape so handlers splice it in
+ *  the same way. */
+export interface EngineRefusal {
+    error: string;
+    hint: string;
+}
+/** Returns a structured refusal when `tool` cannot run on `engine`, else null.
+ *  Null is the fast path on chromium (the only engine with `deep`) and on every
+ *  cross-browser tool regardless of engine — a single Set lookup + a capability
+ *  read, no allocation on the supported path. */
+export declare function assertEngineSupports(tool: string, engine: EngineKind): EngineRefusal | null;