@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/web/src/obscura/cli.ts

@@ -0,0 +1,254 @@
+/**
+ * Bounded, shell-free Obscura CLI runner for one-shot `fetch`/`scrape` operations.
+ * Child processes are killed on timeout/abort, output is capped and collected
+ * linearly, and diagnostics never echo the configured argv.
+ */
+import { type ChildProcess, spawn } from "node:child_process";
+import { isIP } from "node:net";
+import { assertSsrfAllowedUrl, type MediaHostAddress, type MediaHostnameResolver } from "@arnilo/prism";
+import { defaultResolver, normalizeHostname } from "@arnilo/prism/net";
+import { ObscuraError } from "./errors.js";
+import type { ObscuraProcessLimits } from "./limits.js";
+import { resolveObscuraProcessLimits } from "./limits.js";
+import { validateObscuraCommand } from "./process.js";
+
+export interface ObscuraCliRunResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly truncated: boolean;
+  readonly exitCode: number | null;
+}
+
+export interface ObscuraCliRunOptions {
+  readonly command: string;
+  /** Subcommand and its arguments, e.g. `["fetch", "https://example.com", "--dump", "markdown"]`. */
+  readonly args?: readonly string[];
+  /**
+   * Fixed argv placed before the subcommand — e.g. a script path for wrapped
+   * executables or `["run", "--rm", "-i", "image"]` for Docker. Never host-controlled.
+   */
+  readonly argsBefore?: readonly string[];
+  readonly env?: Readonly<Record<string, string>>;
+  readonly cwd?: string;
+  readonly limits?: Partial<ObscuraProcessLimits>;
+  readonly signal?: AbortSignal;
+  /** Wall-clock kill deadline for the child; bounded by the resolved web timeout. */
+  readonly timeoutMs?: number;
+  /** Cap on retained stdout (2 MiB default, 8 MiB hard ceiling enforced by callers). */
+  readonly maxOutputBytes?: number;
+}
+
+function collect(child: ChildProcess, stream: "stdout" | "stderr", maxBytes: number): { text: () => string; truncated: () => boolean } {
+  let size = 0;
+  let truncated = false;
+  const chunks: Buffer[] = [];
+  child[stream]!.on("data", (chunk: Buffer) => {
+    if (size >= maxBytes) {
+      truncated = true;
+      return;
+    }
+    const take = chunk.subarray(0, maxBytes - size);
+    if (take.byteLength < chunk.byteLength) truncated = true;
+    size += take.byteLength;
+    chunks.push(take);
+  });
+  return { text: () => Buffer.concat(chunks, size).toString("utf8"), truncated: () => truncated };
+}
+
+function kill(child: ChildProcess): void {
+  try {
+    child.kill("SIGKILL");
+  } catch {
+    // already gone
+  }
+}
+
+/** Run one bounded Obscura CLI operation; rejects with redacted diagnostics on any failure. */
+export async function runObscuraCli(options: ObscuraCliRunOptions): Promise<ObscuraCliRunResult> {
+  const limits = resolveObscuraProcessLimits(options.limits);
+  const args = [...(options.argsBefore ?? []), ...(options.args ?? [])];
+  validateObscuraCommand({ command: options.command, args }, limits);
+  if (options.signal?.aborted) throw new ObscuraError("ERR_OBSCURA_ABORTED", "obscura cli aborted before start");
+
+  const child = spawn(options.command, args, {
+    env: { PATH: process.env.PATH ?? "", ...(options.env ?? {}) },
+    ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  const maxOutput = options.maxOutputBytes ?? 2 * 1024 * 1024;
+  if (!Number.isFinite(maxOutput) || maxOutput <= 0 || maxOutput > 8 * 1024 * 1024) {
+    throw new ObscuraError("ERR_OBSCURA_LIMIT", "maxOutputBytes out of range");
+  }
+  const stdout = collect(child, "stdout", maxOutput);
+  const stderr = collect(child, "stderr", 64 * 1024);
+
+  return await new Promise<ObscuraCliRunResult>((resolve, reject) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+    const onAbort = () => {
+      settled = true;
+      kill(child);
+      reject(new ObscuraError("ERR_OBSCURA_ABORTED", "obscura cli aborted"));
+    };
+    const deadline = options.timeoutMs ?? 30_000;
+    timer = setTimeout(() => {
+      settled = true;
+      kill(child);
+      reject(new ObscuraError("ERR_OBSCURA_TIMEOUT", `obscura cli timed out after ${deadline}ms`));
+    }, deadline);
+    timer.unref?.();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new ObscuraError("ERR_OBSCURA_SPAWN", `obscura cli spawn failed: ${error.message}`));
+    });
+    child.once("exit", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      const stderrText = stderr.text();
+      if (code !== 0) {
+        reject(
+          new ObscuraError("ERR_OBSCURA_CLI", `obscura cli exited with code ${code}${stderrText ? `: ${stderrText.slice(0, 512)}` : ""}`),
+        );
+        return;
+      }
+      resolve({ stdout: stdout.text(), stderr: stderrText, truncated: stdout.truncated() || stderr.truncated(), exitCode: code });
+    });
+  });
+}
+
+/** First Obscura release whose HTTP client re-validates every redirect hop and resolves through `SsrfGuardResolver`. */
+export const OBSCURA_GUARDED_VERSION = "0.1.8";
+
+/**
+ * Leading semver of an `obscura --version` line, or `undefined` when it is missing or a source build
+ * (`0.1.0-dev+<sha>`), which cannot be assumed to carry the per-hop guard.
+ */
+export function parseObscuraVersion(output: string): string | undefined {
+  const line = output
+    .split(/\r?\n/u)
+    .map((part) => part.trim())
+    .find((part) => /\b\d+\.\d+\.\d+\b/u.test(part));
+  if (line === undefined || /-dev(?![\w])/iu.test(line)) return undefined;
+  const match = line.match(/\b(\d+)\.(\d+)\.(\d+)\b/u);
+  return match === null ? undefined : `${match[1]}.${match[2]}.${match[3]}`;
+}
+
+/** True when `version` is at least {@link OBSCURA_GUARDED_VERSION}. */
+export function obscuraVersionIsGuarded(version: string | undefined): boolean {
+  if (version === undefined) return false;
+  const [major = 0, minor = 0, patch = 0] = version.split(".").map(Number);
+  return major > 0 || minor > 1 || (minor === 1 && patch >= 8);
+}
+
+export interface ObscuraVersionProbeOptions {
+  readonly command: string;
+  readonly argsBefore?: readonly string[];
+  readonly env?: Readonly<Record<string, string>>;
+  readonly cwd?: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+
+export interface ObscuraVersionProbe {
+  readonly version?: string;
+  /** False when the probe failed, the output was unparseable, or the version predates the guard. */
+  readonly guarded: boolean;
+}
+
+/** One bounded `obscura --version` run per package setup; any failure is a "not guarded" result. */
+export async function probeObscuraVersion(options: ObscuraVersionProbeOptions): Promise<ObscuraVersionProbe> {
+  try {
+    const run = await runObscuraCli({
+      command: options.command,
+      ...(options.argsBefore === undefined ? {} : { argsBefore: options.argsBefore }),
+      ...(options.env === undefined ? {} : { env: options.env }),
+      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+      args: ["--version"],
+      timeoutMs: options.timeoutMs ?? 5_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    const version = parseObscuraVersion(run.stdout.trim() === "" ? run.stderr : run.stdout);
+    return { ...(version === undefined ? {} : { version }), guarded: obscuraVersionIsGuarded(version) };
+  } catch {
+    return { guarded: false };
+  }
+}
+
+export interface ValidateObscuraUrlOptions {
+  readonly allowedHostnames?: readonly string[];
+  readonly resolver?: MediaHostnameResolver;
+  readonly signal?: AbortSignal;
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value);
+}
+
+/** Public HTTP(S) URL validation and DNS pre-resolution for anything handed to the Obscura CLI. */
+export async function validateObscuraWebUrl(input: string, options?: readonly string[] | ValidateObscuraUrlOptions): Promise<string> {
+  const opts: ValidateObscuraUrlOptions = options === undefined || isStringArray(options) ? { allowedHostnames: options } : options;
+  const allowedHostnames = opts.allowedHostnames;
+  const resolver = opts.resolver ?? defaultResolver;
+  const signal = opts.signal;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(input);
+  } catch {
+    throw new ObscuraError("ERR_OBSCURA_SSRF", "URL is not a public HTTP(S) target: private, credentialed, or non-HTTP URLs are denied");
+  }
+
+  try {
+    assertSsrfAllowedUrl(input, allowedHostnames === undefined ? {} : { allowedHostnames });
+  } catch {
+    throw new ObscuraError("ERR_OBSCURA_SSRF", "URL is not a public HTTP(S) target: private, credentialed, or non-HTTP URLs are denied");
+  }
+
+  const hostname = normalizeHostname(parsed.hostname);
+  const family = isIP(hostname);
+  if (family !== 0) {
+    // Literal IP address was already validated by assertSsrfAllowedUrl.
+    return input;
+  }
+
+  if (signal?.aborted) throw new ObscuraError("ERR_OBSCURA_ABORTED", "obscura dns resolution aborted");
+
+  let addresses: readonly MediaHostAddress[];
+  try {
+    addresses = await resolver(hostname, signal ?? new AbortController().signal);
+  } catch (error) {
+    if (signal?.aborted) throw new ObscuraError("ERR_OBSCURA_ABORTED", "obscura dns resolution aborted");
+    throw new ObscuraError("ERR_OBSCURA_SSRF", `Failed to resolve hostname for Obscura target: ${hostname}`, { cause: error });
+  }
+
+  if (!addresses || addresses.length === 0) {
+    throw new ObscuraError("ERR_OBSCURA_SSRF", `Obscura target ${hostname} returned no addresses`);
+  }
+
+  for (const candidate of addresses) {
+    const candidateNormalized = normalizeHostname(candidate.address);
+    if (isIP(candidateNormalized) !== candidate.family) {
+      throw new ObscuraError("ERR_OBSCURA_SSRF", "obscura hostname resolver returned an invalid address");
+    }
+    const literal = candidate.family === 6 ? `[${candidateNormalized}]` : candidateNormalized;
+    try {
+      assertSsrfAllowedUrl(`${parsed.protocol}//${literal}`);
+    } catch {
+      throw new ObscuraError(
+        "ERR_OBSCURA_SSRF",
+        `Obscura target ${hostname} resolved to a private or denied address (${candidateNormalized})`,
+      );
+    }
+  }
+
+  return input;
+}

package/web/src/obscura/errors.ts

@@ -0,0 +1,8 @@
+export class ObscuraError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ObscuraError";
+    this.code = code;
+  }
+}

package/web/src/obscura/index.ts

@@ -0,0 +1,59 @@
+export type { ObscuraCdpSession, ObscuraChromium, ObscuraPlaywright } from "./cdp.js";
+export { connectObscuraCdp, endpointFromServeArgs, validateObscuraEndpoint } from "./cdp.js";
+export { isObscuraReadTool } from "./classify.js";
+export type {
+  ObscuraCliRunOptions,
+  ObscuraCliRunResult,
+  ObscuraVersionProbe,
+  ObscuraVersionProbeOptions,
+  ValidateObscuraUrlOptions,
+} from "./cli.js";
+export {
+  OBSCURA_GUARDED_VERSION,
+  obscuraVersionIsGuarded,
+  parseObscuraVersion,
+  probeObscuraVersion,
+  runObscuraCli,
+  validateObscuraWebUrl,
+} from "./cli.js";
+export { ObscuraError } from "./errors.js";
+export {
+  DEFAULT_OBSCURA_PROCESS_LIMITS,
+  DEFAULT_OBSCURA_WEB_LIMITS,
+  HARD_OBSCURA_PROCESS_LIMITS,
+  HARD_OBSCURA_WEB_LIMITS,
+  type ObscuraProcessLimits,
+  type ObscuraWebLimits,
+  resolveObscuraProcessLimits,
+  resolveObscuraWebLimits,
+} from "./limits.js";
+export {
+  createObscuraMcpTools,
+  DEFAULT_OBSCURA_NAME_PREFIX,
+  DEFAULT_OBSCURA_SERVER_ID,
+  ObscuraMcpError,
+  type ObscuraMcpTools,
+  type ObscuraMcpToolsOptions,
+} from "./mcp.js";
+export type {
+  PlaywrightBrowser,
+  PlaywrightBrowserContext,
+  PlaywrightCdpSession,
+  PlaywrightDialog,
+  PlaywrightDownload,
+  PlaywrightLocator,
+  PlaywrightPage,
+  PlaywrightRequest,
+  PlaywrightRoute,
+} from "./playwright.js";
+export { resolveObscuraCommand, spawnObscuraProcess, validateObscuraCommand } from "./process.js";
+export { DEFAULT_OBSCURA_SEARCH_PROFILE, type ObscuraSearchProfile, resolveObscuraSearchProfile } from "./search-profile.js";
+export type {
+  ObscuraCloseOptions,
+  ObscuraExit,
+  ObscuraProcessOptions,
+  OwnedObscuraProcess,
+} from "./types.js";
+export { createObscuraWebTools, type ObscuraWebTools, type ObscuraWebToolsOptions } from "./web.js";
+
+export const packageName = "@arnilo/prism-tools/web";

package/web/src/obscura/limits.ts

@@ -0,0 +1,92 @@
+import { ObscuraError } from "./errors.js";
+
+export interface ObscuraProcessLimits {
+  /** Bounded wait for a readiness probe before the owned process is killed. */
+  readonly startupTimeoutMs: number;
+  /** Grace period for SIGTERM before SIGKILL. */
+  readonly shutdownTimeoutMs: number;
+  /** Cap on retained stderr used for post-mortem diagnostics. */
+  readonly maxStderrBytes: number;
+  readonly maxArgvEntries: number;
+  readonly maxArgvBytes: number;
+  readonly maxEnvEntries: number;
+  readonly maxEnvValueBytes: number;
+}
+
+export const DEFAULT_OBSCURA_PROCESS_LIMITS: ObscuraProcessLimits = {
+  startupTimeoutMs: 10_000,
+  shutdownTimeoutMs: 5_000,
+  maxStderrBytes: 64 * 1024,
+  maxArgvEntries: 256,
+  maxArgvBytes: 64 * 1024,
+  maxEnvEntries: 64,
+  maxEnvValueBytes: 16 * 1024,
+};
+
+export const HARD_OBSCURA_PROCESS_LIMITS: ObscuraProcessLimits = {
+  startupTimeoutMs: 120_000,
+  shutdownTimeoutMs: 30_000,
+  maxStderrBytes: 1024 * 1024,
+  maxArgvEntries: 1_000,
+  maxArgvBytes: 1024 * 1024,
+  maxEnvEntries: 256,
+  maxEnvValueBytes: 64 * 1024,
+};
+
+export function resolveObscuraProcessLimits(input: Partial<ObscuraProcessLimits> = {}): ObscuraProcessLimits {
+  const out = {} as Record<keyof ObscuraProcessLimits, number>;
+  for (const key of Object.keys(DEFAULT_OBSCURA_PROCESS_LIMITS) as (keyof ObscuraProcessLimits)[]) {
+    const value = input[key] ?? DEFAULT_OBSCURA_PROCESS_LIMITS[key];
+    if (!Number.isFinite(value) || value < 0 || value > HARD_OBSCURA_PROCESS_LIMITS[key]) {
+      throw new ObscuraError("ERR_OBSCURA_LIMIT", `Obscura limit ${key} out of range`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Bounds for the CLI-backed web tools (search/fetch/scrape child processes). */
+export interface ObscuraWebLimits {
+  readonly maxQueryBytes: number;
+  readonly maxResults: number;
+  readonly maxUrls: number;
+  readonly maxConcurrency: number;
+  readonly maxOutputBytes: number;
+  readonly maxStderrBytes: number;
+  readonly timeoutMs: number;
+  readonly maxEvalBytes: number;
+}
+
+export const DEFAULT_OBSCURA_WEB_LIMITS: ObscuraWebLimits = {
+  maxQueryBytes: 4096,
+  maxResults: 10,
+  maxUrls: 25,
+  maxConcurrency: 5,
+  maxOutputBytes: 2 * 1024 * 1024,
+  maxStderrBytes: 64 * 1024,
+  timeoutMs: 30_000,
+  maxEvalBytes: 4096,
+};
+
+export const HARD_OBSCURA_WEB_LIMITS: ObscuraWebLimits = {
+  maxQueryBytes: 16 * 1024,
+  maxResults: 100,
+  maxUrls: 200,
+  maxConcurrency: 32,
+  maxOutputBytes: 8 * 1024 * 1024,
+  maxStderrBytes: 256 * 1024,
+  timeoutMs: 120_000,
+  maxEvalBytes: 16 * 1024,
+};
+
+export function resolveObscuraWebLimits(input: Partial<ObscuraWebLimits> = {}): ObscuraWebLimits {
+  const out = {} as Record<keyof ObscuraWebLimits, number>;
+  for (const key of Object.keys(DEFAULT_OBSCURA_WEB_LIMITS) as (keyof ObscuraWebLimits)[]) {
+    const value = input[key] ?? DEFAULT_OBSCURA_WEB_LIMITS[key];
+    if (!Number.isFinite(value) || value <= 0 || value > HARD_OBSCURA_WEB_LIMITS[key]) {
+      throw new ObscuraError("ERR_OBSCURA_LIMIT", `Obscura web limit ${key} out of range`);
+    }
+    out[key] = value;
+  }
+  return out;
+}

package/web/src/obscura/mcp.ts

@@ -0,0 +1,104 @@
+import type { ToolDefinition, ToolResult } from "@arnilo/prism";
+import type { ConnectMcpToolsOptions, McpToolBridge, McpTransportConfig } from "@arnilo/prism-extensions/mcp";
+import { isObscuraReadTool } from "./classify.js";
+import { resolveObscuraProcessLimits } from "./limits.js";
+import { validateObscuraCommand } from "./process.js";
+
+export const DEFAULT_OBSCURA_SERVER_ID = "obscura";
+export const DEFAULT_OBSCURA_NAME_PREFIX = "obscura_";
+
+export interface ObscuraMcpToolsOptions {
+  /** stdio (`obscura mcp` or a Docker argv) or Streamable HTTP transport config. */
+  readonly transport: McpTransportConfig;
+  readonly serverId?: string;
+  /** Default `obscura_` so Obscura tools coexist with `@arnilo/prism-tools/browser`; `""` keeps native Obscura names. */
+  readonly namePrefix?: string;
+  /**
+   * Streamable HTTP endpoints outside loopback require this explicit opt-in; the
+   * endpoint still needs a secure transport/auth per `@arnilo/prism-extensions/mcp` policy.
+   */
+  readonly allowRemoteHttp?: boolean;
+  readonly signal?: AbortSignal;
+  /** Test seam: replace the MCP bridge connection. Defaults to a dynamic `@arnilo/prism-extensions/mcp` import. */
+  readonly connect?: (options: ConnectMcpToolsOptions) => Promise<McpToolBridge>;
+}
+
+export interface ObscuraMcpTools {
+  readonly tools: readonly ToolDefinition[];
+  /** Re-list upstream tools (e.g. after an Obscura upgrade changes the tool set). */
+  refresh(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export class ObscuraMcpError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ObscuraMcpError";
+  }
+}
+
+function resolveTransport(options: ObscuraMcpToolsOptions): McpTransportConfig {
+  const transport = options.transport;
+  if (transport.type === "stdio") {
+    // Fail closed on the same command policy as owned processes (absolute, bounded, no insecure flags).
+    validateObscuraCommand(
+      { command: transport.command, args: transport.args, env: transport.env, cwd: transport.cwd },
+      resolveObscuraProcessLimits(),
+    );
+    return transport;
+  }
+  if (transport.type === "raw") {
+    return transport;
+  }
+  const url = new URL(transport.url);
+  const loopback = ["127.0.0.1", "::1", "[::1]", "localhost"].includes(url.hostname.toLowerCase());
+  if (!loopback && !options.allowRemoteHttp) {
+    throw new ObscuraMcpError(`non-loopback MCP HTTP endpoint ${url.hostname} requires explicit allowRemoteHttp`);
+  }
+  return transport;
+}
+
+/**
+ * Bridge the complete Obscura MCP surface into Prism tools. Every advertised tool is
+ * exposed (no static allow-list): reads are effect-free, known mutations and unknown
+ * future tools are exclusive serialized external mutations.
+ */
+export async function createObscuraMcpTools(options: ObscuraMcpToolsOptions): Promise<ObscuraMcpTools> {
+  // Dynamic import: the MCP bridge is only loaded when this surface is actually used, so importing
+  // `@arnilo/prism-tools/web` never pulls `@arnilo/prism-extensions/mcp`.
+  const connect = options.connect ?? (await import("@arnilo/prism-extensions/mcp")).connectMcpTools;
+  const bridge = await connect({
+    serverId: options.serverId ?? DEFAULT_OBSCURA_SERVER_ID,
+    transport: resolveTransport(options),
+    namePrefix: options.namePrefix ?? DEFAULT_OBSCURA_NAME_PREFIX,
+    effect: ({ remoteName }) => (isObscuraReadTool(remoteName) ? { kind: "none", idempotency: "none" } : undefined),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+  return wrapObscuraBridge(bridge);
+}
+
+function wrapObscuraBridge(bridge: McpToolBridge): ObscuraMcpTools {
+  // Obscura keeps one live page: mutating tools dispatch strictly sequentially.
+  let mutationTail: Promise<unknown> = Promise.resolve();
+  const tools = () =>
+    bridge.tools.map((tool) => {
+      if (typeof tool.effect !== "function" && tool.effect?.kind === "none") return tool;
+      const execute = tool.execute.bind(tool);
+      return {
+        ...tool,
+        exclusive: true,
+        execute: (args: Parameters<typeof execute>[0], context: Parameters<typeof execute>[1]): Promise<ToolResult> => {
+          const run = mutationTail.then(() => execute(args, context));
+          mutationTail = run.catch(() => undefined);
+          return run;
+        },
+      } satisfies ToolDefinition;
+    });
+  return {
+    get tools() {
+      return tools();
+    },
+    refresh: () => bridge.refresh(),
+    close: () => bridge.close(),
+  };
+}

package/web/src/obscura/playwright.ts

@@ -0,0 +1,133 @@
+/**
+ * Structural Playwright surface the Obscura CDP composition consumes.
+ *
+ * Mirrors the subset of `packages/tools/browser/src/types.ts` that `connectObscuraCdp` needs,
+ * so this package carries no runtime or type dependency on the browser package. The two copies
+ * are structurally identical; a later phase that consolidates browser automation can share one.
+ */
+export interface PlaywrightLocator {
+  click(options?: { timeout?: number }): Promise<void>;
+  fill(value: string, options?: { timeout?: number }): Promise<void>;
+  type?(text: string, options?: { timeout?: number; delay?: number }): Promise<void>;
+  pressSequentially?(text: string, options?: { timeout?: number; delay?: number }): Promise<void>;
+  selectOption(
+    values: string | readonly string[] | { label?: string; value?: string } | ReadonlyArray<{ label?: string; value?: string }>,
+    options?: { timeout?: number },
+  ): Promise<string[]>;
+  check(options?: { timeout?: number }): Promise<void>;
+  uncheck(options?: { timeout?: number }): Promise<void>;
+  scrollIntoViewIfNeeded?(options?: { timeout?: number }): Promise<void>;
+  setInputFiles?(
+    files: string | readonly string[] | { name: string; mimeType: string; buffer: Buffer },
+    options?: { timeout?: number },
+  ): Promise<void>;
+  count(): Promise<number>;
+  first(): PlaywrightLocator;
+  nth(index: number): PlaywrightLocator;
+}
+
+export interface PlaywrightDialog {
+  type(): string;
+  message(): string;
+  accept(promptText?: string): Promise<void>;
+  dismiss(): Promise<void>;
+}
+
+export interface PlaywrightRequest {
+  url(): string;
+  resourceType?(): string;
+  redirectedFrom?(): PlaywrightRequest | null;
+  method?(): string;
+}
+
+export interface PlaywrightRoute {
+  request(): PlaywrightRequest;
+  continue(options?: { url?: string; headers?: Record<string, string> }): Promise<void>;
+  abort(errorCode?: string): Promise<void>;
+  fulfill?(options?: { status?: number; body?: string | Buffer; contentType?: string }): Promise<void>;
+}
+
+export interface PlaywrightDownload {
+  url(): string;
+  suggestedFilename(): string;
+  createReadStream?(): Promise<NodeJS.ReadableStream | null>;
+  saveAs?(path: string): Promise<void>;
+  cancel?(): Promise<void>;
+  failure?(): Promise<string | null>;
+}
+
+export interface PlaywrightPage {
+  readonly url: () => string;
+  title(): Promise<string>;
+  goto(url: string, options?: { timeout?: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit" }): Promise<unknown>;
+  ariaSnapshot(options?: { mode?: "ai" | "default"; depth?: number; boxes?: boolean; timeout?: number }): Promise<string>;
+  screenshot?(options?: {
+    type?: "png" | "jpeg";
+    fullPage?: boolean;
+    clip?: { x: number; y: number; width: number; height: number };
+    timeout?: number;
+  }): Promise<Buffer>;
+  locator(selector: string): PlaywrightLocator;
+  getByRole(role: string, options?: { name?: string | RegExp; exact?: boolean }): PlaywrightLocator;
+  getByLabel(text: string | RegExp, options?: { exact?: boolean }): PlaywrightLocator;
+  getByTestId(testId: string | RegExp): PlaywrightLocator;
+  getByText(text: string | RegExp, options?: { exact?: boolean }): PlaywrightLocator;
+  waitForTimeout?(timeout: number): Promise<void>;
+  waitForURL?(url: string | RegExp, options?: { timeout?: number }): Promise<void>;
+  waitForSelector?(selector: string, options?: { timeout?: number }): Promise<unknown>;
+  close(): Promise<void>;
+  isClosed(): boolean;
+  on(event: "dialog", handler: (dialog: PlaywrightDialog) => void): void;
+  on(event: "popup" | "close" | "crash" | "download", handler: (page?: PlaywrightPage | PlaywrightDownload) => void): void;
+  off?(event: string, handler: (...args: never[]) => void): void;
+  once?(event: string, handler: (...args: never[]) => void): void;
+  mouse?: {
+    wheel(deltaX: number, deltaY: number): Promise<void>;
+  };
+  evaluate?<T = unknown>(pageFunction: string | ((arg: unknown) => T | Promise<T>), arg?: unknown): Promise<T>;
+}
+
+export interface PlaywrightBrowserContext {
+  newPage(): Promise<PlaywrightPage>;
+  pages(): PlaywrightPage[];
+  close(): Promise<void>;
+  on(event: "page" | "download", handler: (pageOrDownload: PlaywrightPage | PlaywrightDownload) => void): void;
+  off?(event: string, handler: (...args: never[]) => void): void;
+  route?(url: string | RegExp, handler: (route: PlaywrightRoute) => unknown): Promise<void>;
+  unroute?(url: string | RegExp, handler?: (route: PlaywrightRoute) => unknown): Promise<void>;
+  setDefaultTimeout?(timeout: number): void;
+  setDefaultNavigationTimeout?(timeout: number): void;
+  /** CDP (Chromium only): page-level Chrome DevTools Protocol session. */
+  newCDPSession?(page: PlaywrightPage): Promise<PlaywrightCdpSession>;
+}
+
+export interface PlaywrightBrowser {
+  newContext(options?: {
+    serviceWorkers?: "allow" | "block";
+    acceptDownloads?: boolean;
+    javaScriptEnabled?: boolean;
+    userAgent?: string;
+    viewport?: { width: number; height: number } | null;
+    // Host may pass storageState; Prism never returns or persists it.
+    storageState?: string | { cookies?: unknown[]; origins?: unknown[] };
+    proxy?: { server: string; bypass?: string; username?: string; password?: string };
+  }): Promise<PlaywrightBrowserContext>;
+  isConnected?(): boolean;
+  version?(): string;
+  close?(): Promise<void>;
+  /** CDP (Chromium only): browser-level Chrome DevTools Protocol session. */
+  newBrowserCDPSession?(): Promise<PlaywrightCdpSession>;
+}
+
+/**
+ * Structural Chrome DevTools Protocol session surface (playwright-core CDPSession).
+ * Hosts that want CDP tools must supply a Chromium-based Playwright Browser whose
+ * contexts expose newCDPSession(page); fakes in tests supply the same surface.
+ * No playwright import occurs at package load time.
+ */
+export interface PlaywrightCdpSession {
+  send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  on(event: string, handler: (params: Record<string, unknown>) => void): void;
+  off?(event: string, handler: (params: Record<string, unknown>) => void): void;
+  detach?(): Promise<void>;
+}