mirinjs 0.1.0-alpha.18 → 0.1.0-alpha.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirinjs",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./config": "./src/config/index.ts",
+    "./check": "./src/check/index.ts",
+    "./devtools/session": "./src/devtools/session.ts",
     "./rpc": "./src/rpc.ts",
     "./client": "./src/client.ts",
     "./codec": "./src/codec.ts",

package/src/app/facade.ts

@@ -26,19 +26,36 @@ import type {
 /** A live, typed handle to an open window. */
 export class WindowHandle extends Emitter<WindowEvents> {
   readonly id: number;
-  readonly name: string | undefined;
+  /** Always set: a window opened without a name is given one from its id. */
+  readonly name: string;
+  #url: string;
+  #title: string | undefined;
 
-  constructor(id: number, name: string | undefined) {
+  constructor(id: number, name: string, url = "", title?: string) {
     super();
     this.id = id;
     this.name = name;
+    this.#url = url;
+    this.#title = title;
+  }
+
+  /** The URL this window was last asked to load. */
+  get url(): string {
+    return this.#url;
+  }
+
+  /** The title this window was last given, if the app set one. */
+  get title(): string | undefined {
+    return this.#title;
   }
 
   async setTitle(title: string): Promise<void> {
+    this.#title = title;
     runtime().core.windowSetTitle(this.id, title);
   }
 
   async loadUrl(url: string): Promise<void> {
+    this.#url = url;
     runtime().core.windowLoadUrl(this.id, url);
   }
 
@@ -159,21 +176,24 @@ class Windows {
 
   async open(options: WindowOpenOptions | string): Promise<WindowHandle> {
     const opts = typeof options === "string" ? manifestWindow(options) : options;
+    const url = resolveUrl(opts.url);
     const id = runtime().core.windowCreate(
       JSON.stringify({
         ...opts,
-        url: resolveUrl(opts.url),
+        url,
         material: normalizeMaterial(opts.material),
       }),
     );
-    const handle = new WindowHandle(id, opts.name);
+    // Fall back to an id-derived name so every window is addressable by name, not
+    // just the ones declared in the manifest.
+    const handle = new WindowHandle(id, opts.name ?? `window-${id}`, url, opts.title);
     this.#register(handle);
     return handle;
   }
 
   #register(handle: WindowHandle): void {
     this.#byId.set(handle.id, handle);
-    if (handle.name) this.#byName.set(handle.name, handle);
+    this.#byName.set(handle.name, handle);
   }
 
   /** @internal */
@@ -185,7 +205,8 @@ class Windows {
     const handle = this.#byId.get(id);
     if (handle) {
       this.#byId.delete(id);
-      if (handle.name) this.#byName.delete(handle.name);
+      // Only if it is still the binding: a later window may have taken the name.
+      if (this.#byName.get(handle.name) === handle) this.#byName.delete(handle.name);
     }
   }
 }

package/src/check/define.ts

@@ -0,0 +1,24 @@
+import type { CheckScenario } from "./types.ts";
+
+/**
+ * Declare a `mirin check` scenario. Default-export the result from the file you
+ * pass to `mirin check --scenario`.
+ *
+ * ```ts
+ * import { defineCheck } from "mirinjs/check";
+ *
+ * export default defineCheck(async (app) => {
+ *   app.step("add a todo");
+ *   await app.click("text=add a todo");
+ *   await app.type("ship it");
+ *   await app.click("text=Add");
+ *   await app.expectText("ship it");
+ * });
+ * ```
+ *
+ * Identity at runtime — its whole job is to type the callback, so `app` is
+ * inferred without the file having to annotate it.
+ */
+export function defineCheck(scenario: CheckScenario): CheckScenario {
+  return scenario;
+}

package/src/check/index.ts

@@ -0,0 +1,2 @@
+export { defineCheck } from "./define.ts";
+export type { CheckDriver, CheckScenario, CheckWindow, WindowTarget } from "./types.ts";

package/src/check/types.ts

@@ -0,0 +1,95 @@
+/**
+ * The contract a `mirin check` scenario is written against. Types live in the
+ * runtime package so an app can import them without the CLI's internals; the
+ * implementation lives in the CLI, which holds the inspector connection.
+ */
+
+import type { DevEvent, DevEventQuery } from "../devtools/types.ts";
+
+/** A window as the scenario sees it. */
+export interface CheckWindow {
+  id: number;
+  name: string;
+  url?: string;
+  title?: string;
+}
+
+/** Which window an action targets. Omit when the app has only one. */
+export interface WindowTarget {
+  window?: number;
+}
+
+/**
+ * The app under check. Every method talks to the running app's inspector.
+ * Anything that cannot be done rejects, and an unhandled rejection fails the check.
+ */
+export interface CheckDriver {
+  /** Click an element. Selectors accept CSS or `text=Save`. */
+  click(selector: string, options?: WindowTarget & { clickCount?: number }): Promise<void>;
+  /** Type text, optionally focusing `selector` first. */
+  type(text: string, options?: WindowTarget & { selector?: string }): Promise<void>;
+  /** Press a named key, e.g. `Enter`, `Escape`, `Tab`. */
+  key(name: string, options?: WindowTarget): Promise<void>;
+  scroll(options: WindowTarget & { deltaY?: number; deltaX?: number }): Promise<void>;
+  /** Wait for a selector to match, rejecting if it never does. */
+  waitFor(selector: string, options?: WindowTarget & { timeoutMs?: number }): Promise<void>;
+  /** Wait a fixed time. Prefer `waitFor` — a sleep is a guess. */
+  sleep(ms: number): Promise<void>;
+
+  /** The accessibility tree, or the DOM with `format: "dom"`. */
+  snapshot(options?: WindowTarget & { format?: "ax" | "dom" }): Promise<string>;
+  /** Evaluate an expression in the page and return its value. */
+  evaluate<T = unknown>(expression: string, options?: WindowTarget): Promise<T>;
+  /** Capture a screenshot into the session dir; returns its path. */
+  screenshot(label?: string, options?: WindowTarget): Promise<string>;
+  windows(): Promise<CheckWindow[]>;
+  /** Slices the app published with `devtools.expose`. */
+  exposed(): Promise<Record<string, unknown>>;
+  /** The event stream so far, filtered the same way as the inspector's `/logs`. */
+  logs(query?: DevEventQuery): Promise<DevEvent[]>;
+  /**
+   * Send a raw DevTools-protocol command, for anything the methods above do not cover.
+   *
+   * ```ts
+   * const [call] = await app.logs({ type: "network.response", contains: "/api/todos" });
+   * const body = await app.cdp<{ body: string }>("Network.getResponseBody", {
+   *   requestId: call.data.requestId,
+   * });
+   * ```
+   */
+  cdp<T = Record<string, unknown>>(
+    method: string,
+    params?: Record<string, unknown>,
+    options?: WindowTarget,
+  ): Promise<T>;
+
+  /** Fail the check unless `condition` is truthy, right now. After an interaction,
+   *  prefer `waitUntil` — the RPC round trip has not landed yet. */
+  assert(condition: unknown, message: string): asserts condition;
+  /**
+   * Poll `condition` until it holds, failing the check with `message` if it never
+   * does. The general form of `expectText`.
+   *
+   * ```ts
+   * await app.waitUntil(
+   *   async () => (await app.evaluate<number>("todos.length")) > 0,
+   *   "the todo never reached the list",
+   * );
+   * ```
+   */
+  waitUntil(
+    condition: () => Promise<unknown> | unknown,
+    message: string,
+    options?: { timeoutMs?: number },
+  ): Promise<void>;
+  /** Fail the check unless the window's accessibility tree contains `text`. Polls
+   *  until the timeout (2s by default): a single read would be flaky by construction. */
+  expectText(text: string, options?: WindowTarget & { timeoutMs?: number }): Promise<void>;
+
+  /** Name the phase the scenario is in. Steps appear in the report and the event
+   *  stream, so a failure says which step it happened in. */
+  step(name: string): void;
+}
+
+/** A scenario: drive the app, throw to fail. */
+export type CheckScenario = (app: CheckDriver) => Promise<void> | void;

package/src/config/manifest.ts

@@ -176,6 +176,52 @@ export interface MirinConfig {
    * multiple instances (each gets its own CEF cache dir).
    */
   singleInstance?: boolean;
+  /**
+   * Agent-facing developer tooling: the structured event stream and the loopback
+   * inspector (docs/agent-devtools.md). Fully enabled under `mirin dev` and
+   * fully disabled in packaged builds; omit unless you need to change that.
+   */
+  devtools?: DevtoolsConfig;
+}
+
+/**
+ * Developer/agent observability settings. Under `mirin dev` every capability
+ * defaults to on; in a packaged build everything is **off** and the switches are
+ * ignored unless {@link DevtoolsConfig.production} is `true` — the inspector can
+ * evaluate JavaScript and synthesize input, so enable it only in a diagnostic
+ * build you control.
+ */
+export interface DevtoolsConfig {
+  /** Master switch for the whole subsystem. Default true where permitted. */
+  enabled?: boolean;
+  /** Bind the loopback inspector HTTP/SSE server. Default true where permitted. */
+  inspector?: boolean;
+  /** Mirror the event stream to `.mirin/dev/<session>/events.jsonl`. Default true. */
+  file?: boolean;
+  /** Events kept in memory for `/logs`. Default 2000. */
+  bufferSize?: number;
+  /**
+   * Include RPC inputs and results in traces. Default false: procedure payloads
+   * carry app data, and the stream is written to disk in plain text.
+   */
+  rpcPayloads?: boolean;
+  /**
+   * Record HTTP metadata in the stream (headers redacted; bodies never captured —
+   * fetch one via `Network.getResponseBody` through `POST /cdp`). Default true
+   * where permitted. `false` silences successful traffic only; failures and
+   * 4xx/5xx are always recorded, so `mirin check` keeps its teeth.
+   */
+  network?: boolean;
+  /**
+   * Attach to CEF's remote-debugging port, enabling `/screenshot`, `/snapshot`,
+   * `/eval`, and `/act`. Default true where permitted.
+   */
+  cdp?: boolean;
+  /**
+   * Permit devtools in a packaged (non-dev) build. Default false. Read the
+   * warning on this interface before setting it.
+   */
+  production?: boolean;
 }
 
 /** A bundled sidecar binary with optional hardened-runtime entitlements. */

package/src/devtools/devtools.ts

@@ -0,0 +1,213 @@
+/**
+ * mirin/devtools — the agent-facing observability facade (docs/agent-devtools.md).
+ * Collects every event source into one queryable stream, mirrors it to
+ * `.mirin/dev/<session>/events.jsonl`, and serves it over loopback.
+ *
+ *   devtools.event({ type: "route.change", msg: "/settings" });
+ *   devtools.expose("store", () => store.getState());
+ */
+
+import type { DevtoolsConfig } from "../config/index.ts";
+import { maybeRuntime, onNativeEvent } from "../runtime.ts";
+import { CdpBridge } from "./lib/cdp.ts";
+import { type InspectorHandle, startInspector } from "./lib/inspector.ts";
+import { recordCdpEvent } from "./lib/renderer-taps.ts";
+import { cdpRoutes } from "./lib/routes-cdp.ts";
+import { installNativeTap, installProcessTaps } from "./lib/taps.ts";
+import { devtoolsOptions, resolveDevtoolsOptions, setDevtoolsOptions } from "./options.ts";
+import {
+  DEV_CDP_PORT_ENV,
+  DEV_SESSION_ENV,
+  type SessionPaths,
+  sessionPaths,
+  writeInspectorEndpoint,
+} from "./session.ts";
+import { record, sink } from "./sink.ts";
+import type { AppDevEvent, DevEvent, DevEventQuery, InspectorEndpoint } from "./types.ts";
+
+const exposed = new Map<string, () => unknown>();
+
+let paths: SessionPaths | undefined;
+let inspector: InspectorHandle | undefined;
+let bridge: CdpBridge | undefined;
+let teardown: (() => void)[] = [];
+
+/** CEF's remote-debugging port for this run, when one was supplied. */
+function cdpPort(): number | undefined {
+  const value = Number(process.env[DEV_CDP_PORT_ENV] ?? "");
+  return Number.isSafeInteger(value) && value >= 1024 && value <= 65535 ? value : undefined;
+}
+
+/** A registered getter's current value, or an error marker if it threw. */
+function readExposed(getter: () => unknown): unknown {
+  try {
+    return getter();
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export const devtools = {
+  get enabled(): boolean {
+    return devtoolsOptions().enabled;
+  },
+
+  get session(): SessionPaths | undefined {
+    return paths;
+  },
+
+  get inspectorUrl(): string | undefined {
+    return inspector !== undefined ? `http://127.0.0.1:${inspector.port}` : undefined;
+  },
+
+  /** Publish an app-defined event into the stream. Always safe: with devtools
+   *  disabled the record lands in the in-memory buffer only. */
+  event(event: AppDevEvent): void {
+    record({
+      src: "app",
+      level: event.level ?? "info",
+      type: event.type,
+      msg: event.msg ?? event.type,
+      ...(event.window !== undefined ? { window: event.window } : {}),
+      ...(event.data !== undefined ? { data: event.data } : {}),
+    });
+  },
+
+  /** Publish a named slice of app state under the inspector's `/state`. The getter
+   *  runs on each read; one that throws is reported against its own key, not the request. */
+  expose(name: string, getter: () => unknown): void {
+    exposed.set(name, getter);
+  },
+
+  unexpose(name: string): void {
+    exposed.delete(name);
+  },
+
+  state(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [name, getter] of exposed) out[name] = readExposed(getter);
+    return out;
+  },
+
+  /** Query the in-memory event buffer. */
+  read(query: DevEventQuery = {}): DevEvent[] {
+    return sink.read(query);
+  },
+};
+
+/** Boot devtools; called from the package entry right after `boot()`. Taps install
+ *  here, not at import time; nothing is missed — native events sit in the core's
+ *  queue until the Worker's first poll. */
+export function startDevtools(override?: DevtoolsConfig): void {
+  const runtime = maybeRuntime();
+  const options = resolveDevtoolsOptions(override ?? runtime?.devtools, runtime?.isDev ?? false);
+  setDevtoolsOptions(options);
+  if (!options.enabled) return;
+
+  sink.resize(options.bufferSize);
+
+  const dir = process.env[DEV_SESSION_ENV];
+  if (dir !== undefined && dir.length > 0) {
+    paths = sessionPaths(dir);
+    if (options.file) sink.openFile(paths.events);
+  }
+
+  const port = options.cdp ? cdpPort() : undefined;
+  // Local binding: route closures must capture a definite bridge, not the
+  // reassignable module-level slot.
+  const attached = port !== undefined ? startCdpBridge(port) : undefined;
+  bridge = attached;
+
+  // `cdpCovers` is read per event, not captured now: CDP attachment completes later.
+  teardown.push(
+    installNativeTap({
+      cdpCovers: (window) =>
+        window !== undefined && (attached?.attachedWindows().includes(window) ?? false),
+    }),
+  );
+  teardown.push(installProcessTaps());
+  const screenshotDir = paths?.screenshots;
+
+  inspector = startInspector({
+    exposed: () => devtools.state(),
+    ...(attached !== undefined
+      ? {
+          extraRoutes: () =>
+            cdpRoutes({
+              bridge: attached,
+              ...(screenshotDir !== undefined ? { screenshotDir } : {}),
+            }),
+        }
+      : {}),
+  });
+  if (inspector !== undefined) {
+    publishInspectorEndpoint({
+      version: 1,
+      port: inspector.port,
+      token: inspector.token,
+      pid: process.pid,
+      startedAt: Date.now(),
+      ...(port !== undefined ? { cdpPort: port } : {}),
+    });
+  }
+
+  record({
+    src: "main",
+    level: "info",
+    type: "devtools.ready",
+    msg: "devtools attached",
+    data: {
+      file: sink.filePath ?? null,
+      inspector: inspector !== undefined ? `http://127.0.0.1:${inspector.port}` : null,
+      cdpPort: port ?? null,
+      bufferSize: options.bufferSize,
+    },
+  });
+}
+
+/** Create the CDP bridge and start attaching. Attachment is async and not awaited:
+ *  CEF binds its debugging port after the Worker is already running, and app
+ *  startup must not wait on diagnostics. */
+function startCdpBridge(port: number): CdpBridge {
+  const created = new CdpBridge(port, recordCdpEvent);
+  teardown.push(onNativeEvent("window.created", () => void created.refresh(true)));
+
+  void created.attachWhenReady().then((attached) => {
+    record({
+      src: "main",
+      level: attached ? "info" : "warn",
+      type: attached ? "devtools.cdp-attached" : "devtools.cdp-unavailable",
+      msg: attached
+        ? `attached to the DevTools protocol on port ${port}`
+        : `no webview attached on DevTools port ${port} — screenshots and snapshots are unavailable`,
+      data: { port, windows: created.attachedWindows() },
+    });
+  });
+
+  return created;
+}
+
+export function publishInspectorEndpoint(endpoint: InspectorEndpoint): void {
+  if (paths === undefined) return;
+  try {
+    writeInspectorEndpoint(paths, endpoint);
+  } catch (err) {
+    record({
+      src: "main",
+      level: "warn",
+      type: "devtools.error",
+      msg: `could not publish inspector endpoint: ${err instanceof Error ? err.message : err}`,
+    });
+  }
+}
+
+/** Flush and detach. Called on Worker shutdown paths. */
+export function stopDevtools(): void {
+  for (const off of teardown) off();
+  teardown = [];
+  void inspector?.stop();
+  inspector = undefined;
+  bridge?.close();
+  bridge = undefined;
+  sink.close();
+}

package/src/devtools/index.ts

@@ -0,0 +1,11 @@
+export { devtools, publishInspectorEndpoint, startDevtools, stopDevtools } from "./devtools.ts";
+export type { DevtoolsOptions } from "./options.ts";
+export { devtoolsOptions } from "./options.ts";
+export type {
+  AppDevEvent,
+  DevEvent,
+  DevEventLevel,
+  DevEventQuery,
+  DevEventSource,
+  InspectorEndpoint,
+} from "./types.ts";

package/src/devtools/lib/actions.ts

@@ -0,0 +1,185 @@
+/**
+ * Synthetic input over CDP (docs/agent-devtools.md). `text=Save` selectors match
+ * labels, since the AX snapshot a reader works from has no class attributes; input
+ * goes through `Input.dispatch*Event`, not `element.click()`, so a real event
+ * sequence is exercised. Selectors are untrusted and are always embedded with
+ * `JSON.stringify`, never concatenated into the script.
+ */
+
+import { asBoolean, asNumber, asRecord, asString } from "./parse.ts";
+
+/** Keys worth naming. Printable characters go through `type` instead. */
+const KEYS: Record<string, { code: string; keyCode: number; text?: string }> = {
+  Enter: { code: "Enter", keyCode: 13, text: "\r" },
+  Tab: { code: "Tab", keyCode: 9 },
+  Escape: { code: "Escape", keyCode: 27 },
+  Backspace: { code: "Backspace", keyCode: 8 },
+  Delete: { code: "Delete", keyCode: 46 },
+  ArrowLeft: { code: "ArrowLeft", keyCode: 37 },
+  ArrowUp: { code: "ArrowUp", keyCode: 38 },
+  ArrowRight: { code: "ArrowRight", keyCode: 39 },
+  ArrowDown: { code: "ArrowDown", keyCode: 40 },
+  Home: { code: "Home", keyCode: 36 },
+  End: { code: "End", keyCode: 35 },
+  PageUp: { code: "PageUp", keyCode: 33 },
+  PageDown: { code: "PageDown", keyCode: 34 },
+  Space: { code: "Space", keyCode: 32, text: " " },
+};
+
+export const KEY_NAMES: string[] = Object.keys(KEYS);
+
+/** Sends a CDP command for one page. Supplied by the bridge. */
+export type Send = (
+  method: string,
+  params?: Record<string, unknown>,
+) => Promise<Record<string, unknown>>;
+
+export interface Located {
+  x: number;
+  y: number;
+  tag: string;
+}
+
+/** The page script resolving a selector to a click point. `text=…` matches an
+ *  element's label (text, `value`, `aria-label`, `placeholder`, `title`), exact
+ *  first, then deepest, so a wrapper never wins over the button inside it. */
+export function locateScript(selector: string): string {
+  const text = selector.startsWith("text=") ? selector.slice(5) : undefined;
+  const css = selector.startsWith("css=") ? selector.slice(4) : selector;
+
+  const find =
+    text !== undefined
+      ? `(() => {
+           const want = ${JSON.stringify(text)}.trim().toLowerCase();
+           const label = (el) => (
+             el.getAttribute?.("aria-label") ||
+             el.getAttribute?.("placeholder") ||
+             el.getAttribute?.("title") ||
+             (el.value != null && typeof el.value === "string" ? el.value : "") ||
+             el.textContent || ""
+           ).trim().toLowerCase();
+           const all = Array.from(document.querySelectorAll("*"))
+             .filter((el) => !["SCRIPT","STYLE","HEAD","META","LINK","TITLE"].includes(el.tagName));
+           const exact = all.filter((el) => label(el) === want);
+           const partial = exact.length ? [] : all.filter((el) => label(el).includes(want));
+           const pool = exact.length ? exact : partial;
+           // Deepest candidate: the innermost element still carrying the label.
+           return pool.sort((a, b) => b.querySelectorAll("*").length - a.querySelectorAll("*").length).pop() || null;
+         })()`
+      : `document.querySelector(${JSON.stringify(css)})`;
+
+  return `(() => {
+    const el = ${find};
+    if (!el) return { found: false };
+    if (el.scrollIntoView) el.scrollIntoView({ block: "center", inline: "center" });
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return { found: true, visible: false, tag: el.tagName.toLowerCase() };
+    return {
+      found: true,
+      visible: true,
+      x: r.left + r.width / 2,
+      y: r.top + r.height / 2,
+      tag: el.tagName.toLowerCase(),
+    };
+  })()`;
+}
+
+export class ActionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ActionError";
+  }
+}
+
+/** Resolve a selector to a click point in the page's viewport. */
+export async function locate(send: Send, selector: string): Promise<Located> {
+  const result = await send("Runtime.evaluate", {
+    expression: locateScript(selector),
+    returnByValue: true,
+  });
+  const value = asRecord(asRecord(result.result)?.value);
+  if (asBoolean(value?.found) !== true) {
+    throw new ActionError(`no element matched ${selector}`);
+  }
+  if (asBoolean(value?.visible) !== true) {
+    throw new ActionError(`element matched ${selector} but has no visible box`);
+  }
+  const x = asNumber(value?.x);
+  const y = asNumber(value?.y);
+  if (x === undefined || y === undefined) {
+    throw new ActionError(`element matched ${selector} but has no position`);
+  }
+  return { x, y, tag: asString(value?.tag) ?? "" };
+}
+
+/** Press and release the left button at a selector's center. */
+export async function click(send: Send, selector: string, clickCount = 1): Promise<Located> {
+  const at = await locate(send, selector);
+  const base = { x: at.x, y: at.y, button: "left", clickCount, buttons: 1 };
+  await send("Input.dispatchMouseEvent", { type: "mousePressed", ...base });
+  await send("Input.dispatchMouseEvent", { type: "mouseReleased", ...base });
+  return at;
+}
+
+/** Insert text as if typed, into the selector's element when one is given. Focus
+ *  comes from a real click, not `el.focus()`, so the field sees real events. */
+export async function type(send: Send, text: string, selector?: string): Promise<void> {
+  if (selector !== undefined) await click(send, selector);
+  // insertText goes through the same IME path as real typing and handles the whole
+  // string at once, which is both faster and less flaky than per-character events.
+  await send("Input.insertText", { text });
+}
+
+/** Press a named key (see {@link KEY_NAMES}). */
+export async function key(send: Send, name: string): Promise<void> {
+  const spec = KEYS[name];
+  if (spec === undefined) {
+    throw new ActionError(`unknown key "${name}" — try one of: ${KEY_NAMES.join(", ")}`);
+  }
+  const base = {
+    key: name === "Space" ? " " : name,
+    code: spec.code,
+    windowsVirtualKeyCode: spec.keyCode,
+    nativeVirtualKeyCode: spec.keyCode,
+    ...(spec.text !== undefined ? { text: spec.text } : {}),
+  };
+  // Printable keys need `keyDown` to deliver their text; the rest use rawKeyDown.
+  await send("Input.dispatchKeyEvent", {
+    type: spec.text !== undefined ? "keyDown" : "rawKeyDown",
+    ...base,
+  });
+  await send("Input.dispatchKeyEvent", { type: "keyUp", ...base });
+}
+
+/** Scroll by a wheel delta, at a selector's center or the viewport's top-left. */
+export async function scroll(
+  send: Send,
+  deltaY: number,
+  deltaX = 0,
+  selector?: string,
+): Promise<void> {
+  const at = selector !== undefined ? await locate(send, selector) : { x: 10, y: 10 };
+  await send("Input.dispatchMouseEvent", {
+    type: "mouseWheel",
+    x: at.x,
+    y: at.y,
+    deltaX,
+    deltaY,
+  });
+}
+
+/** Poll until a selector matches, or throw when the deadline passes. */
+export async function waitFor(send: Send, selector: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = `no element matched ${selector}`;
+  while (Date.now() < deadline) {
+    try {
+      await locate(send, selector);
+      return;
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+    await Bun.sleep(100);
+  }
+  throw new ActionError(`timed out after ${timeoutMs}ms: ${lastError}`);
+}