pi-browser-harness 0.10.2 → 0.12.0

package/src/daemon/spawn.ts

@@ -1,17 +1,7 @@
-/**
- * Daemon lifecycle helpers — spawn detection and lazy launch.
- *
- * The daemon is a standalone long-lived process that owns the single WebSocket
- * to Chrome. pi instances connect to it via a Unix domain socket. This module
- * provides the plumbing to detect a running daemon and spawn one if needed.
- *
- * Reference:
- *   - child_process.spawn detached: https://nodejs.org/docs/latest-v22.x/api/child_process.html#optionsdetached
- */
-
 import { spawn, type ChildProcess } from "node:child_process";
+import { accessSync } from "node:fs";
 import { access, unlink } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { createConnection } from "node:net";
@@ -19,36 +9,31 @@ import { DAEMON_SOCKET_PATH, serialize, type WireControl } from "./protocol";
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 
+const requireFromHere = createRequire(import.meta.url);
+
 const isWindows = process.platform === "win32";
 
-/**
- * Remove a stale POSIX socket file. On Windows the daemon endpoint is a named
- * pipe, which is not a filesystem entry and is torn down automatically when the
- * owning process exits — so there is nothing to unlink, and calling unlink on a
- * pipe path throws. This is a no-op on Windows.
- */
+// No-op on Windows: a named pipe is not a filesystem entry and unlinking a pipe path throws.
 const cleanupStaleSocket = (): void => {
   if (isWindows) return;
   unlink(DAEMON_SOCKET_PATH).catch(() => {});
 };
 
-/**
- * Check whether the daemon is running by probing its Unix socket.
- * A file-existence check is unreliable — a crashed daemon leaves a stale socket.
- * We connect, send a register, wait for the registered ack, then disconnect.
- * On failure, clean up the stale socket so ensureDaemon can spawn a fresh one.
- */
-export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
-  // On POSIX, a missing socket file means the daemon definitely isn't running,
-  // so we can short-circuit. Windows named pipes are not filesystem entries —
-  // access() always fails there — so skip the pre-check and probe directly.
-  if (!isWindows) {
-    try {
-      await access(DAEMON_SOCKET_PATH);
-    } catch {
-      return false;
-    }
+export const daemonSocketMayExist = async (
+  platform: NodeJS.Platform = process.platform,
+  socketPath: string = DAEMON_SOCKET_PATH,
+): Promise<boolean> => {
+  if (platform === "win32") return true;
+  try {
+    await access(socketPath);
+    return true;
+  } catch {
+    return false;
   }
+};
+
+export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
+  if (!(await daemonSocketMayExist())) return false;
 
   return new Promise((resolve) => {
     let settled = false;
@@ -61,7 +46,6 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
     const sock = createConnection(DAEMON_SOCKET_PATH);
     const timer = setTimeout(() => {
       sock.destroy();
-      // ponytail: stale socket cleanup; ENOENT = already gone, fine
       cleanupStaleSocket();
       done(false);
     }, timeoutMs);
@@ -75,7 +59,6 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
       const text = chunk.toString();
       if (text.includes('"registered"')) {
         clearTimeout(timer);
-        // Send deregister so the probe doesn't hog a slot
         const deregMsg: WireControl = { type: "control", action: "deregister", clientId: "_liveness_probe" };
         try { sock.write(serialize(deregMsg) + "\n"); } catch {}
         sock.destroy();
@@ -86,13 +69,11 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
     sock.on("error", () => {
       clearTimeout(timer);
       sock.destroy();
-      // ponytail: connection refused = daemon dead, clean up stale socket
       cleanupStaleSocket();
       done(false);
     });
 
-    // close without 'registered' ack = daemon alive but rejected us (e.g. max clients);
-    // don't unlink — the daemon is still using that socket.
+    // Closed without a 'registered' ack: the daemon is alive but rejected us, so do NOT unlink its socket.
     sock.on("close", () => {
       clearTimeout(timer);
       done(false);
@@ -100,66 +81,93 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
   });
 };
 
-/**
- * Spawn the daemon as a detached child process. The daemon will continue
- * running after the parent pi process exits.
- *
- * The daemon entry point is resolved relative to this module. When running
- * from source (tsx), the entry is src/daemon/index.ts. When running compiled,
- * it's dist/daemon/index.js.
- *
- * Returns the child process handle (caller should call child.unref()).
- */
-export const spawnDaemon = (): ChildProcess | null => {
-  // Resolve the daemon entry point and tsx binary.
+// Walks upward like Node's own node_modules lookup. Exported with an injectable start so the
+// hoisted layout pi uses can be exercised against a fixture instead of this checkout.
+export const resolveTsxCliFromFilesystem = (startDir: string = moduleDir): string | null => {
+  let dir = startDir;
+
+  while (true) {
+    const candidate = join(dir, "node_modules", "tsx", "dist", "cli.mjs");
+    try {
+      accessSync(candidate);
+      return candidate;
+    } catch {
+      // Keep walking toward the filesystem root. This mirrors Node's node_modules lookup
+      // without relying on createRequire().resolve(), which is broken for external modules
+      // loaded through jiti/static inside a Bun-compiled executable such as pi.exe.
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+};
+
+const resolveTsxCli = (): string | null => {
+  try {
+    const resolved = requireFromHere.resolve("tsx/cli");
+    // A compiled runtime may theoretically return a virtual path that a separately spawned
+    // Node process cannot read. Only accept a resolver result that exists on the host FS.
+    accessSync(resolved);
+    return resolved;
+  } catch {
+    return resolveTsxCliFromFilesystem();
+  }
+};
+
+export const daemonNodeExecutable = (
+  env: NodeJS.ProcessEnv = process.env,
+  versions: Readonly<Record<string, string | undefined>> = process.versions,
+  platform: NodeJS.Platform = process.platform,
+  execPath: string = process.execPath,
+): string => {
+  const override = env["PI_BROWSER_NODE"];
+  if (override) return override;
+
+  // Under normal Node keep the exact executable that launched pi/the extension. Under Bun,
+  // process.execPath is bun/pi.exe, not Node, so run the tsx CLI with the required Node runtime.
+  if ("bun" in versions) return platform === "win32" ? "node.exe" : "node";
+
+  return execPath;
+};
+
+export const daemonSpawnCommand = (): { readonly command: string; readonly args: ReadonlyArray<string> } | null => {
   const daemonScript = join(moduleDir, "index.ts");
+  const tsxCli = resolveTsxCli();
+  if (!tsxCli) return null;
+
+  return {
+    command: daemonNodeExecutable(),
+    args: [tsxCli, daemonScript],
+  };
+};
 
-  // On Windows, npm installs binaries as `.cmd` shims, not bare executables,
-  // and the npx fallback is `npx.cmd`. A `.cmd` file can only be launched
-  // through a shell (spawning it directly yields EINVAL), so set shell: true
-  // whenever we invoke one.
-  const tsxBinBase = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
-  const tsxBin = isWindows ? `${tsxBinBase}.cmd` : tsxBinBase;
-  const hasLocalTsx = existsSync(tsxBin);
-
-  // Use the local tsx binary to run the daemon TypeScript source directly.
-  // The spawned process inherits the parent's env so module resolution works.
-  // Fall back to `npx tsx` if the local binary isn't available.
-  const cmd = hasLocalTsx ? tsxBin : isWindows ? "npx.cmd" : "npx";
-  const args = hasLocalTsx ? [daemonScript] : ["tsx", daemonScript];
-
-  // With shell: true, Node passes the command line to the shell verbatim
-  // without quoting, so any path containing spaces (e.g. C:\Users\Some Name)
-  // would be split into multiple tokens. Wrap each token in double quotes on
-  // Windows to keep space-containing paths intact.
-  const quote = (s: string): string => (isWindows ? `"${s}"` : s);
-
-  const child = spawn(quote(cmd), args.map(quote), {
+export const spawnDaemon = (): ChildProcess | null => {
+  const spec = daemonSpawnCommand();
+  if (!spec) return null;
+
+  const child = spawn(spec.command, [...spec.args], {
     detached: true,
     stdio: "ignore",
     env: { ...process.env },
-    // `.cmd` shims (local tsx or npx.cmd on Windows) must run via a shell.
-    shell: isWindows,
-    windowsVerbatimArguments: isWindows,
+    windowsHide: true,
   });
 
+  // `spawn` reports a missing executable (a bare `node` that is not on PATH under a Bun host)
+  // asynchronously via `error`; without a listener that is an uncaught exception in pi.
+  // ensureDaemon's poll loop reports the failure as a timeout, which is what the user sees.
+  child.on("error", () => {});
+
   child.unref();
   return child;
 };
 
-/**
- * Ensure the daemon is running. If not, spawn it and wait (up to timeoutMs)
- * for the socket file to appear.
- *
- * Returns true if the daemon is running (or was successfully spawned).
- */
 export const ensureDaemon = async (timeoutMs = 10_000): Promise<boolean> => {
   if (await isDaemonRunning()) return true;
 
   const child = spawnDaemon();
   if (!child) return false;
 
-  // Poll for the socket file to appear
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await isDaemonRunning()) return true;

package/src/{cdp/daemon-transport.ts → daemon/transport.ts}

@@ -1,34 +1,19 @@
-/**
- * DaemonTransport — CdpTransport backed by a Unix socket to the browser daemon.
- *
- * Satisfies the exact CdpTransport interface so BrowserClient, CdpSession, and
- * all domain tools work without changes. Internally uses newline-delimited JSON
- * over a Unix domain socket instead of a WebSocket to Chrome.
- *
- * References:
- *   - CdpTransport interface: src/cdp/transport.ts
- *   - net.createConnection IPC: https://nodejs.org/docs/latest-v22.x/api/net.html#netcreateconnection
- *   - readline.createInterface: https://nodejs.org/docs/latest-v22.x/api/readline.html#readlinecreateinterfaceoptions
- */
-
 import { createConnection, type Socket } from "node:net";
 import { createInterface } from "node:readline";
 import { type Result, err, ok } from "../util/result";
-import { type CdpError, cdpError } from "../cdp/errors";
-import type { CdpTransport } from "../cdp/transport";
+import { type CdpError, cdpError, classifyRemoteError } from "../cdp/errors";
+import { DEFAULT_TIMEOUT_MS, type CdpTransport } from "../cdp/types";
 import type { CdpEvent } from "../cdp/types";
-import { type Pending, makeEventQueue, makeOnClose, rejectAllPending, sendWithTimeout } from "./event-queue";
+import { type Pending, makeEventQueue, makeOnClose, rejectAllPending, sendWithTimeout } from "./queue";
 import {
   DAEMON_SOCKET_PATH,
   type WireRequest,
   type WireControl,
   deserialize,
   serialize,
-} from "../daemon/protocol";
-
-// ── Implementation ─────────────────────────────────────────────────────────────
+} from "./protocol";
 
-export const createDaemonTransport = (clientId: string): CdpTransport => {
+export const createDaemonTransport = (clientId: string, socketPath: string = DAEMON_SOCKET_PATH): CdpTransport => {
   let socket: Socket | null = null;
   let rl: ReturnType<typeof createInterface> | null = null;
   let queue = makeEventQueue();
@@ -49,10 +34,7 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
     for (const cb of closeListeners) cb();
   };
 
-  // ── Connect ────────────────────────────────────────────────────────────
-
   const connect = (_url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>> => {
-    // url is ignored — we always connect to the daemon socket
     const timeoutMs = opts?.timeoutMs ?? 10_000;
 
     if (socket && !socket.destroyed && registered) {
@@ -67,21 +49,28 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
         resolve(r);
       };
 
+      let sock: Socket;
       try {
-        socket = createConnection(DAEMON_SOCKET_PATH);
+        sock = createConnection(socketPath);
       } catch (e) {
         settle(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
         return;
       }
+      socket = sock;
+      // The client is kept connected across sessions on purpose (index.ts session_shutdown), so this
+      // socket must not be what keeps the process alive: in `pi -p` it was the last handle standing
+      // and pi never exited (#39). In-flight requests hold their own ref'd timers, so nothing a
+      // caller is awaiting can be dropped by this.
+      sock.unref();
 
       const connectTimer = setTimeout(() => {
         cleanup("Connection timeout");
         settle(err(cdpError("timeout", `Daemon connection timed out after ${timeoutMs}ms`)));
       }, timeoutMs);
 
-      socket.on("connect", () => {
+      sock.on("connect", () => {
         clearTimeout(connectTimer);
-        rl = createInterface({ input: socket!, crlfDelay: Infinity });
+        rl = createInterface({ input: sock, crlfDelay: Infinity });
 
         rl.on("line", (line: string) => {
           const msg = deserialize(line);
@@ -107,13 +96,7 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
             clearTimeout(p.timer);
 
             if (msg.error) {
-              p.resolve(err(cdpError(
-                msg.error.message.includes("Session with given id not found")
-                  ? "session_not_found"
-                  : "remote_error",
-                msg.error.message,
-                p.method,
-              )));
+              p.resolve(err(cdpError(classifyRemoteError(msg.error.message), msg.error.message, p.method)));
             } else {
               p.resolve(ok(msg.result));
             }
@@ -130,23 +113,19 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
           }
         });
 
-        socket!.on("error", () => {
-          // Errors are surfaced via 'close'
-        });
+        sock.on("error", () => {});
 
-        socket!.on("close", () => {
+        sock.on("close", () => {
           clearTimeout(connectTimer);
           cleanup("Daemon socket closed");
-          // If connect hasn't settled yet, settle with error
           settle(err(cdpError("transport_closed", "Daemon socket closed before registration")));
         });
 
-        // Send registration
         const regMsg: WireControl = { type: "control", action: "register", clientId };
-        socket!.write(serialize(regMsg) + "\n");
+        sock.write(serialize(regMsg) + "\n");
       });
 
-      socket.on("error", (e: NodeJS.ErrnoException) => {
+      sock.on("error", (e: NodeJS.ErrnoException) => {
         clearTimeout(connectTimer);
         const msg = e.code === "ENOENT"
           ? "Daemon not running — socket not found"
@@ -156,8 +135,6 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
     });
   };
 
-  // ── Close ──────────────────────────────────────────────────────────────
-
   const close = async (): Promise<void> => {
     if (registered && socket && !socket.destroyed) {
       const dereg: WireControl = { type: "control", action: "deregister", clientId };
@@ -166,17 +143,16 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
     cleanup("close() called");
   };
 
-  // ── Request ────────────────────────────────────────────────────────────
-
   const request = (
     method: string,
     params: Record<string, unknown>,
     opts?: { sessionId?: string | null; timeoutMs?: number },
   ): Promise<Result<unknown, CdpError>> => {
-    const timeoutMs = opts?.timeoutMs ?? 15_000;
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const sessionId = opts?.sessionId ?? null;
 
-    if (!socket || socket.destroyed || !registered) {
+    const sock = socket;
+    if (sock === null || sock.destroyed || !registered) {
       return Promise.resolve(err(cdpError("transport_closed", "Daemon not connected", method)));
     }
 
@@ -189,15 +165,11 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
       ...(sessionId !== null && sessionId !== undefined ? { sessionId } : {}),
     };
 
-    return sendWithTimeout(pending, id, method, timeoutMs, "Daemon", () => socket!.write(serialize(req) + "\n"));
+    return sendWithTimeout(pending, id, method, timeoutMs, "Daemon", () => sock.write(serialize(req) + "\n"));
   };
 
-  // ── Events ─────────────────────────────────────────────────────────────
-
   const events = (): AsyncIterable<CdpEvent> => queue.iter;
 
-  // ── State ──────────────────────────────────────────────────────────────
-
   const state = (): "open" | "closed" | "connecting" => {
     if (!socket) return "closed";
     if (!registered) return "connecting";

package/src/domains/ax-tree.ts

@@ -0,0 +1,179 @@
+import type { AxNodeResult } from "../cdp/commands";
+import type { BrowserClient } from "../client";
+import type { Box } from "./box";
+import { cdpCall } from "./cdp-call";
+
+export type RawAxNode = AxNodeResult;
+type AxValue = NonNullable<RawAxNode["role"]>;
+
+export type SlimNode = {
+  role: string;
+  name?: string;
+  value?: string;
+  description?: string;
+  state?: string;
+  children: SlimNode[];
+  _backendId?: number;
+  ref?: string;
+  box?: Box;
+};
+
+export const INTERACTIVE_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "menuitem",
+  "tab",
+  "switch",
+  "slider",
+  "searchbox",
+  "spinbutton",
+]);
+
+// The AX `value` is stale for freshly-typed or controlled inputs, so for these roles the live DOM property is read instead.
+export const VALUE_ROLES = new Set([
+  "textbox",
+  "searchbox",
+  "spinbutton",
+  "combobox",
+  "checkbox",
+  "radio",
+  "switch",
+  "slider",
+]);
+
+const stringOf = (v: AxValue | undefined): string | undefined => {
+  const x = v?.value;
+  if (typeof x === "string" && x !== "") return x;
+  if (typeof x === "number") return String(x);
+  return undefined;
+};
+
+const collectState = (props: RawAxNode["properties"]): string | undefined => {
+  if (!props || props.length === 0) return undefined;
+  const flags: string[] = [];
+  for (const p of props) {
+    const name = p.name;
+    if (!name) continue;
+    const raw = p.value?.value;
+    if (raw === true && (name === "focused" || name === "required" || name === "disabled" || name === "checked" || name === "expanded" || name === "selected" || name === "pressed" || name === "modal")) {
+      flags.push(name);
+    }
+    if (typeof raw === "number" && name === "level") flags.push(`level ${raw}`);
+  }
+  return flags.length > 0 ? flags.join(", ") : undefined;
+};
+
+export const buildTree = (
+  rawNodes: ReadonlyArray<RawAxNode>,
+  opts: { interestingOnly: boolean; maxNodes: number },
+): SlimNode[] => {
+  const byId = new Map<string, RawAxNode>();
+  for (const n of rawNodes) byId.set(n.nodeId, n);
+
+  const rootIds: string[] = [];
+  for (const n of rawNodes) {
+    if (!n.parentId || !byId.has(n.parentId)) rootIds.push(n.nodeId);
+  }
+
+  let budget = opts.maxNodes;
+
+  const slim = (node: RawAxNode): SlimNode | undefined => {
+    if (budget <= 0) return undefined;
+    if (opts.interestingOnly && node.ignored) {
+      // Chrome often ignores wrapper divs while their descendants remain meaningful, so recurse through an ignored node's children.
+      const out: SlimNode[] = [];
+      for (const cid of node.childIds ?? []) {
+        const child = byId.get(cid);
+        if (!child) continue;
+        const slimChild = slim(child);
+        if (slimChild) out.push(slimChild);
+      }
+      return out.length > 0 ? { role: "_hoist", children: out } : undefined;
+    }
+    budget--;
+    const role = stringOf(node.role) ?? "unknown";
+    const name = stringOf(node.name);
+    const value = stringOf(node.value);
+    const description = stringOf(node.description);
+    const state = collectState(node.properties);
+    const children: SlimNode[] = [];
+    for (const cid of node.childIds ?? []) {
+      const child = byId.get(cid);
+      if (!child) continue;
+      const slimChild = slim(child);
+      if (!slimChild) continue;
+      if (slimChild.role === "_hoist") children.push(...slimChild.children);
+      else children.push(slimChild);
+    }
+    const out: SlimNode = { role, children };
+    if (name !== undefined) out.name = name;
+    if (value !== undefined) out.value = value;
+    if (description !== undefined) out.description = description;
+    if (state !== undefined) out.state = state;
+    if (node.backendDOMNodeId !== undefined) out._backendId = node.backendDOMNodeId;
+    return out;
+  };
+
+  const result: SlimNode[] = [];
+  for (const rid of rootIds) {
+    const root = byId.get(rid);
+    if (!root) continue;
+    const s = slim(root);
+    if (!s) continue;
+    if (s.role === "_hoist") result.push(...s.children);
+    else result.push(s);
+  }
+  return result;
+};
+
+export const countNodes = (nodes: ReadonlyArray<SlimNode>): number => {
+  let n = 0;
+  for (const node of nodes) n += 1 + countNodes(node.children);
+  return n;
+};
+
+export const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
+  nodes.map((n) => {
+    const { _backendId: _bid, ...rest } = n;
+    return { ...rest, children: stripInternals(n.children) };
+  });
+
+export const collectInteractiveTargets = (
+  nodes: ReadonlyArray<SlimNode>,
+): Array<{ node: SlimNode; backendId: number }> => {
+  const out: Array<{ node: SlimNode; backendId: number }> = [];
+  const walk = (ns: ReadonlyArray<SlimNode>): void => {
+    for (const n of ns) {
+      if (n._backendId !== undefined && INTERACTIVE_ROLES.has(n.role)) {
+        out.push({ node: n, backendId: n._backendId });
+      }
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return out;
+};
+
+export const liveValue = async (client: BrowserClient, backendId: number): Promise<string | undefined> => {
+  const resolved = await cdpCall(client, "DOM.resolveNode", { backendNodeId: backendId });
+  if (!resolved.success) return undefined;
+  const objectId = resolved.data.object.objectId;
+  if (!objectId) return undefined;
+  const fn = `function () {
+    if (this.type === "checkbox" || this.type === "radio") return this.checked ? "checked" : "unchecked";
+    if (typeof this.value === "string") return this.value;
+    return null;
+  }`;
+  const r = await cdpCall(client, "Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: fn,
+    returnByValue: true,
+  });
+  if (!r.success) return undefined;
+  const value = r.data.result.value;
+  return typeof value === "string" ? value : undefined;
+};

package/src/domains/box.ts

@@ -0,0 +1,51 @@
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+
+export type Box = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly cx: number;
+  readonly cy: number;
+};
+
+type BoxModel = {
+  readonly content: ReadonlyArray<number>;
+  readonly width: number;
+  readonly height: number;
+};
+
+export const centreOf = (model: BoxModel): Box => {
+  const x = model.content[0] ?? 0;
+  const y = model.content[1] ?? 0;
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    width: Math.round(model.width),
+    height: Math.round(model.height),
+    cx: Math.round(x + model.width / 2),
+    cy: Math.round(y + model.height / 2),
+  };
+};
+
+export const boxOf = async (
+  client: BrowserClient,
+  backendNodeId: number,
+): Promise<Result<Box, ToolErr>> => {
+  const r = await cdpCall(client, "DOM.getBoxModel", { backendNodeId });
+  if (!r.success) return r;
+  const model = r.data.model;
+  if (model.content.length < 8) {
+    return err({ kind: "invalid_state", message: "DOM.getBoxModel returned an incomplete content quad" });
+  }
+  if (model.width <= 0 || model.height <= 0) {
+    return err({
+      kind: "invalid_state",
+      message: "element has a zero-size box and cannot be clicked",
+    });
+  }
+  return ok(centreOf(model));
+};