cdp-toolkit 1.0.0 → 1.1.0

package/src/tools/dialogs.ts

@@ -1,236 +0,0 @@
-/**
- * dialogs.ts — JavaScript dialog handling (alert / confirm / prompt / beforeunload).
- *
- * Replicates chrome-devtools-mcp's `handle_dialog`. A JS dialog opened by the
- * page (alert/confirm/prompt/beforeunload) blocks the renderer until the
- * embedder responds via Page.handleJavaScriptDialog. Over raw CDP we:
- *   1. Page.enable
- *   2. subscribe to Page.javascriptDialogOpening
- *   3. on fire, respond with Page.handleJavaScriptDialog({ accept, promptText })
- *
- * Two modes are supported per CONTRACT:
- *   - "wait for next dialog then handle" (default): arm the listener and resolve
- *     when the next dialog is handled, or time out if none appears.
- *   - "auto-handle for N ms" ({ autoMs }): handle every dialog that opens during
- *     a fixed window, then resolve with the list handled.
- *
- * Because a dialog blocks the renderer, the code that *triggers* the dialog
- * (e.g. a Runtime.evaluate of `confirm("x")`) must NOT be awaited before the
- * dialog is handled — otherwise it deadlocks. `handleDialogForExpression` arms
- * the listener, fires the expression WITHOUT awaiting, waits for the dialog to
- * be handled, then awaits the now-unblocked evaluate result.
- */
-import type { CdpConnection } from "../client.ts";
-import { CdpError, openPage } from "../client.ts";
-import type { TargetSelector } from "../types.ts";
-
-/** Raw shape of the Page.javascriptDialogOpening event params. */
-interface JavascriptDialogOpening {
-  url: string;
-  message: string;
-  type: "alert" | "confirm" | "prompt" | "beforeunload" | string;
-  hasBrowserHandler: boolean;
-  defaultPrompt?: string;
-}
-
-/** A single handled dialog. */
-export interface HandledDialog {
-  type: string;
-  message: string;
-  url: string;
-  defaultPrompt?: string;
-  accept: boolean;
-  promptText?: string;
-  handled: true;
-}
-
-export interface HandleDialogArgs {
-  target?: TargetSelector;
-  /** Whether to accept (OK) or dismiss (Cancel) the dialog. */
-  accept: boolean;
-  /** Text to enter for a prompt() dialog when accepting. */
-  promptText?: string;
-  /** How long to wait for the next dialog (default 15000ms). */
-  timeoutMs?: number;
-  /**
-   * Auto-handle mode: keep handling every dialog that opens for this many ms,
-   * then resolve. When set, the return value is a list of handled dialogs and
-   * the function never throws on "no dialog" (an empty list is a valid result).
-   */
-  autoMs?: number;
-}
-
-/**
- * Arm a dialog handler on a live page connection. Returns a disarm function and
- * a promise that resolves with each dialog as it is handled (via the onHandled
- * callback). This is the low-level primitive used by both public modes and by
- * the expression helper.
- */
-function armDialogHandler(
-  conn: CdpConnection,
-  accept: boolean,
-  promptText: string | undefined,
-  onHandled: (d: HandledDialog) => void,
-): () => void {
-  return conn.on("Page.javascriptDialogOpening", (params) => {
-    const ev = params as unknown as JavascriptDialogOpening;
-    void (async () => {
-      try {
-        await conn.send("Page.handleJavaScriptDialog", {
-          accept,
-          ...(promptText !== undefined ? { promptText } : {}),
-        });
-        onHandled({
-          type: ev.type,
-          message: ev.message,
-          url: ev.url,
-          ...(ev.defaultPrompt !== undefined ? { defaultPrompt: ev.defaultPrompt } : {}),
-          accept,
-          ...(promptText !== undefined ? { promptText } : {}),
-          handled: true,
-        });
-      } catch {
-        /* connection may have raced closed; the awaiter will time out */
-      }
-    })();
-  });
-}
-
-/**
- * handle_dialog — wait for the next JS dialog on a page and respond to it.
- *
- * Default mode: opens a persistent connection, enables Page, arms the listener,
- * and resolves with the first handled dialog (or throws on timeout). Auto mode
- * ({ autoMs }): handles every dialog for the window and resolves with the list.
- *
- * The caller is expected to trigger the dialog out-of-band (e.g. by clicking a
- * button on the page). To trigger-and-handle in one call, use
- * handleDialogForExpression.
- */
-export async function handleDialog(
-  args: HandleDialogArgs,
-): Promise<HandledDialog | { handled: HandledDialog[]; count: number }> {
-  const { target, accept, promptText, timeoutMs = 15_000, autoMs } = args;
-  const { conn } = await openPage(target);
-  try {
-    await conn.send("Page.enable");
-
-    if (autoMs !== undefined) {
-      const handled: HandledDialog[] = [];
-      const disarm = armDialogHandler(conn, accept, promptText, (d) => handled.push(d));
-      await new Promise<void>((resolve) => setTimeout(resolve, autoMs));
-      disarm();
-      return { handled, count: handled.length };
-    }
-
-    return await new Promise<HandledDialog>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        disarm();
-        reject(new CdpError(`handle_dialog: no dialog opened within ${timeoutMs}ms`));
-      }, timeoutMs);
-      const disarm = armDialogHandler(conn, accept, promptText, (d) => {
-        clearTimeout(timer);
-        disarm();
-        resolve(d);
-      });
-    });
-  } finally {
-    conn.close();
-  }
-}
-
-export interface HandleDialogForExpressionArgs {
-  target?: TargetSelector;
-  /** A JS expression that opens a dialog, e.g. `confirm("ok?")` or `prompt("name?")`. */
-  expression: string;
-  accept: boolean;
-  promptText?: string;
-  timeoutMs?: number;
-}
-
-/**
- * Arm a dialog handler, evaluate an expression that OPENS a dialog (without
- * awaiting it — a blocking dialog would otherwise deadlock the evaluate), wait
- * for the dialog to be handled, then await the now-unblocked evaluate result.
- *
- * Returns both the handled-dialog metadata and the value the expression
- * resolved to (e.g. `true` for an accepted confirm, the entered text for an
- * accepted prompt, `false`/`null` for a dismissed one). This is the
- * trigger-and-handle helper used by the live smoke test.
- */
-export async function handleDialogForExpression(
-  args: HandleDialogForExpressionArgs,
-): Promise<{ dialog: HandledDialog; value: unknown }> {
-  const { target, expression, accept, promptText, timeoutMs = 15_000 } = args;
-  const { conn } = await openPage(target);
-  try {
-    await conn.send("Page.enable");
-    await conn.send("Runtime.enable");
-
-    let resolveDialog!: (d: HandledDialog) => void;
-    let rejectDialog!: (e: Error) => void;
-    const dialogPromise = new Promise<HandledDialog>((res, rej) => {
-      resolveDialog = res;
-      rejectDialog = rej;
-    });
-    const timer = setTimeout(
-      () => rejectDialog(new CdpError(`handle_dialog: expression opened no dialog within ${timeoutMs}ms`)),
-      timeoutMs,
-    );
-    const disarm = armDialogHandler(conn, accept, promptText, (d) => {
-      clearTimeout(timer);
-      resolveDialog(d);
-    });
-
-    // Fire the dialog-opening expression WITHOUT awaiting: a blocking dialog
-    // holds the evaluate open until we handle it. We capture the promise so we
-    // can await its (now-unblocked) value after the dialog is handled.
-    const evalPromise = conn
-      .send<{ result: { value?: unknown }; exceptionDetails?: { text?: string } }>("Runtime.evaluate", {
-        expression,
-        returnByValue: true,
-        awaitPromise: true,
-        // The evaluate itself must not time out before we handle the dialog.
-        userGesture: true,
-      })
-      .catch((e: unknown) => {
-        // Surface as an exception-shaped result so the await below can decide.
-        return { result: {}, __error: e } as { result: { value?: unknown }; __error: unknown };
-      });
-
-    const dialog = await dialogPromise;
-    disarm();
-
-    const evalResult = (await evalPromise) as {
-      result: { value?: unknown };
-      exceptionDetails?: { text?: string };
-      __error?: unknown;
-    };
-    if (evalResult.__error) throw evalResult.__error;
-    if (evalResult.exceptionDetails) {
-      throw new CdpError(`expression threw: ${evalResult.exceptionDetails.text ?? "unknown error"}`);
-    }
-
-    return { dialog, value: evalResult.result?.value };
-  } finally {
-    conn.close();
-  }
-}
-
-/* ----------------------------------------------------------------------------
- * CDP methods / domains used:
- *   - Page.enable
- *   - Page.javascriptDialogOpening   (event, subscribed)
- *   - Page.handleJavaScriptDialog    ({ accept, promptText })
- *   - Runtime.enable                 (helper only)
- *   - Runtime.evaluate               (helper only — fires the dialog-opening expr)
- *
- * Parity gaps vs chrome-devtools-mcp `handle_dialog`:
- *   - MCP auto-handles the single pending dialog tracked by its Page object;
- *     here the caller arms first and triggers out-of-band, OR uses the
- *     handleDialogForExpression helper to trigger-and-handle atomically.
- *   - MCP returns its standard page/snapshot envelope after handling; this
- *     returns just the handled-dialog metadata (type/message/url/accept/...).
- *   - beforeunload dialogs are handled the same way but are only emitted when a
- *     real navigation/close is attempted; arming alone does not provoke them.
- * -------------------------------------------------------------------------- */

package/src/tools/emulation.ts

@@ -1,212 +0,0 @@
-/**
- * emulation tools — `emulate` and `resize_page` over raw CDP.
- *
- * `emulate` is a one-call switchboard over Chrome's emulation overrides:
- * device metrics (size / DPR / mobile), user-agent, CPU throttling, emulated
- * media (type + features like prefers-color-scheme), and network conditions.
- * `resize_page` is the narrow case of setting just the device-metrics size.
- * A `clearOverrides` path resets every override back to the browser default.
- *
- * NOTE on persistence: these overrides live on the DevTools *session*. The
- * toolkit's stateless one-shot model (withPage opens then closes the
- * connection) means an override applied in one call is gone once that
- * connection closes — except device metrics, which Chrome keeps applied to the
- * target until explicitly cleared or the renderer navigates/reloads. We
- * therefore re-assert metrics in resize_page and document this in the footer.
- */
-import type { CdpConnection } from "../client.ts";
-import { CdpError, withPage } from "../client.ts";
-import type { Target, TargetSelector } from "../types.ts";
-
-export interface NetworkConditions {
-  /** true = simulate offline. */
-  offline?: boolean;
-  /** additional round-trip latency, ms. */
-  latency?: number;
-  /** max download throughput, bytes/sec (-1 = no limit). */
-  downloadThroughput?: number;
-  /** max upload throughput, bytes/sec (-1 = no limit). */
-  uploadThroughput?: number;
-  /** "none" | "cellular2g" | "cellular3g" | "cellular4g" | "bluetooth" | "ethernet" | "wifi" | "wimax" | "other" */
-  connectionType?: string;
-}
-
-export interface EmulateArgs {
-  target?: TargetSelector;
-  width?: number;
-  height?: number;
-  deviceScaleFactor?: number;
-  mobile?: boolean;
-  userAgent?: string;
-  /** 1 = no throttle; 2 = 2x slower; etc. */
-  cpuThrottlingRate?: number;
-  /** Emulated CSS media type: "screen" | "print" | "" (clear). */
-  media?: string;
-  /** Emulated media features, e.g. [{ name:"prefers-color-scheme", value:"dark" }]. */
-  mediaFeatures?: Array<{ name: string; value: string }>;
-  networkConditions?: NetworkConditions;
-  /** Reset every override to the browser default; ignores all other fields. */
-  clearOverrides?: boolean;
-}
-
-export interface EmulateResult {
-  target: { id: string; url: string; title: string };
-  applied: string[];
-  cleared?: boolean;
-}
-
-export interface ResizeArgs {
-  target?: TargetSelector;
-  width: number;
-  height: number;
-  deviceScaleFactor?: number;
-  mobile?: boolean;
-}
-
-export interface ResizeResult {
-  target: { id: string; url: string; title: string };
-  width: number;
-  height: number;
-  /** window.innerWidth/innerHeight observed after the override is applied. */
-  innerWidth: number;
-  innerHeight: number;
-}
-
-async function clearAll(conn: CdpConnection): Promise<void> {
-  // Order doesn't matter; each is independent. Tolerate per-domain absence.
-  await conn.send("Emulation.clearDeviceMetricsOverride").catch(() => undefined);
-  await conn.send("Emulation.setUserAgentOverride", { userAgent: "" }).catch(() => undefined);
-  await conn.send("Emulation.setCPUThrottlingRate", { rate: 1 }).catch(() => undefined);
-  await conn.send("Emulation.setEmulatedMedia", { media: "", features: [] }).catch(() => undefined);
-  await conn.send("Network.enable").catch(() => undefined);
-  await conn
-    .send("Network.emulateNetworkConditions", {
-      offline: false,
-      latency: 0,
-      downloadThroughput: -1,
-      uploadThroughput: -1,
-    })
-    .catch(() => undefined);
-}
-
-/**
- * emulate — apply any subset of device-metrics / UA / CPU / media / network
- * overrides in a single call, or clear them all with { clearOverrides:true }.
- */
-export async function emulate(args: EmulateArgs = {}): Promise<EmulateResult> {
-  const { target } = args;
-  return withPage(target, async (conn: CdpConnection, t: Target) => {
-    if (args.clearOverrides) {
-      await clearAll(conn);
-      return {
-        target: { id: t.id, url: t.url, title: t.title },
-        applied: [],
-        cleared: true,
-      };
-    }
-
-    const applied: string[] = [];
-
-    if (args.width != null || args.height != null) {
-      if (args.width == null || args.height == null) {
-        throw new CdpError("emulate device metrics require both width and height");
-      }
-      await conn.send("Emulation.setDeviceMetricsOverride", {
-        width: args.width,
-        height: args.height,
-        deviceScaleFactor: args.deviceScaleFactor ?? 0,
-        mobile: args.mobile ?? false,
-      });
-      applied.push("deviceMetrics");
-    }
-
-    if (args.userAgent != null) {
-      await conn.send("Emulation.setUserAgentOverride", { userAgent: args.userAgent });
-      applied.push("userAgent");
-    }
-
-    if (args.cpuThrottlingRate != null) {
-      if (args.cpuThrottlingRate < 1) throw new CdpError("cpuThrottlingRate must be >= 1");
-      await conn.send("Emulation.setCPUThrottlingRate", { rate: args.cpuThrottlingRate });
-      applied.push("cpuThrottlingRate");
-    }
-
-    if (args.media != null || args.mediaFeatures != null) {
-      await conn.send("Emulation.setEmulatedMedia", {
-        media: args.media ?? "",
-        features: args.mediaFeatures ?? [],
-      });
-      applied.push("emulatedMedia");
-    }
-
-    if (args.networkConditions != null) {
-      const n = args.networkConditions;
-      await conn.send("Network.enable").catch(() => undefined);
-      await conn.send("Network.emulateNetworkConditions", {
-        offline: n.offline ?? false,
-        latency: n.latency ?? 0,
-        downloadThroughput: n.downloadThroughput ?? -1,
-        uploadThroughput: n.uploadThroughput ?? -1,
-        ...(n.connectionType ? { connectionType: n.connectionType } : {}),
-      });
-      applied.push("networkConditions");
-    }
-
-    if (applied.length === 0) {
-      throw new CdpError("emulate: no overrides specified (pass clearOverrides:true to reset)");
-    }
-
-    return { target: { id: t.id, url: t.url, title: t.title }, applied };
-  });
-}
-
-/**
- * resize_page — set the page's device-metrics width/height. Verifies by reading
- * back window.innerWidth/innerHeight after the override is applied.
- */
-export async function resizePage(args: ResizeArgs): Promise<ResizeResult> {
-  const { target, width, height } = args;
-  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
-    throw new CdpError("resize_page requires positive numeric width and height");
-  }
-  return withPage(target, async (conn: CdpConnection, t: Target) => {
-    await conn.send("Emulation.setDeviceMetricsOverride", {
-      width,
-      height,
-      deviceScaleFactor: args.deviceScaleFactor ?? 0,
-      mobile: args.mobile ?? false,
-    });
-    await conn.send("Runtime.enable").catch(() => undefined);
-    const { result } = await conn.send<{ result: { value?: { w: number; h: number } } }>("Runtime.evaluate", {
-      expression: "({ w: window.innerWidth, h: window.innerHeight })",
-      returnByValue: true,
-    });
-    const v = result.value;
-    return {
-      target: { id: t.id, url: t.url, title: t.title },
-      width,
-      height,
-      innerWidth: v?.w ?? width,
-      innerHeight: v?.h ?? height,
-    };
-  });
-}
-
-/*
- * CDP methods/domains used:
- *   - Emulation.setDeviceMetricsOverride   (resize + emulate metrics)
- *   - Emulation.clearDeviceMetricsOverride (clearOverrides)
- *   - Emulation.setUserAgentOverride
- *   - Emulation.setCPUThrottlingRate
- *   - Emulation.setEmulatedMedia           (media type + features)
- *   - Network.enable / Network.emulateNetworkConditions
- *   - Runtime.enable / Runtime.evaluate    (resize_page read-back verification)
- * Parity gaps vs chrome-devtools-mcp emulate/resize_page:
- *   - Override lifetime: toolkit is stateless (connection closes after each call). Device-metrics
- *     overrides persist on the target until cleared/navigated; UA/CPU/media/network overrides are
- *     session-scoped and reset when the per-call connection closes. The MCP keeps one long-lived
- *     session so its non-metrics overrides persist across subsequent MCP calls; ours do not.
- *   - No named device-descriptor presets (e.g. "iPhone 15"); caller passes raw metrics + UA.
- *   - No touch-emulation / screen-orientation override (Emulation.setTouchEmulationEnabled,
- *     setDeviceMetricsOverride.screenOrientation) — out of the assigned arg surface.
- */