@nativedesktop/test 0.1.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@nativedesktop/test",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
+  "bugs": "https://github.com/FormalSnake/NativeDesktop/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FormalSnake/NativeDesktop.git",
+    "directory": "packages/test"
+  },
+  "publishConfig": {
+  "access": "public"
+},
+"files": ["src"],
+"main": "./src/index.ts",
+"types": "./src/index.ts",
+"exports": {
+  ".": "./src/index.ts"
+},
+"dependencies": {
+  "@nativedesktop/host": "0.1.0",
+  "@nativedesktop/react": "0.1.0"
+}
+}

package/src/client.ts

@@ -0,0 +1,38 @@
+// Wraps socket.ts's AutomationClient (reused, not forked — same framing, same
+// generated RpcMethods map) so every call in the harness carries a timeout: a
+// hung host (deadlock, crashed reader thread) fails a test in rpcTimeoutMs
+// instead of the whole run hanging forever.
+import { AutomationClient } from "./socket.ts";
+import type { RpcMethodName, RpcParams, RpcResult } from "@nativedesktop/react/rpc";
+
+export class TimedClient {
+  constructor(
+    private readonly inner: AutomationClient,
+    private timeoutMs: number,
+    private readonly stderrTail: (lines: number) => string,
+  ) {}
+
+  setTimeoutMs(ms: number): void {
+    this.timeoutMs = ms;
+  }
+
+  call<M extends RpcMethodName>(
+    method: M,
+    ...params: RpcParams<M> extends undefined ? [] : [RpcParams<M>]
+  ): Promise<RpcResult<M>> {
+    const ms = this.timeoutMs;
+    let timer: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(`${method} timed out after ${ms}ms\n--- last 40 stderr lines ---\n${this.stderrTail(40)}`));
+      }, ms);
+    });
+    return Promise.race([this.inner.call(method, ...params), timeout]).finally(() => clearTimeout(timer)) as Promise<
+      RpcResult<M>
+    >;
+  }
+
+  close(): void {
+    this.inner.close();
+  }
+}

package/src/dialogs.ts

@@ -0,0 +1,25 @@
+// §1.5's ND_AUTOMATION_DIALOG_SCRIPT: typed builder for the per-method FIFO
+// consumed by src/automation_dialogs.zig. Entry shapes mirror the real
+// systemRequest/widgetCommand results verbatim (verified against
+// packages/react/src/system.ts's `dialog` object and
+// packages/react/src/dialogs.ts's Window-scoped helpers) — NOT the
+// {paths:[...]}/{button:0} shapes sketched in the design doc, which predate
+// the landed result types:
+//   - dialog.openFile resolves to a raw string[] (system.ts: `Promise<string[]>`)
+//   - dialog.saveFile resolves to a raw string | null
+//   - dialog.showMessage resolves to a raw number (button index)
+//   - window.showAlert / .openFile / .saveFile settle dialogs.ts's
+//     AlertResult / OpenFileResult / SaveFileResult objects
+export interface DialogScript {
+  "dialog.openFile"?: string[][];
+  "dialog.saveFile"?: (string | null)[];
+  "dialog.showMessage"?: number[];
+  "window.showAlert"?: { buttonId: string }[];
+  "window.openFile"?: { canceled: boolean; paths: string[] }[];
+  "window.saveFile"?: { canceled: boolean; path: string | null }[];
+}
+
+/** Serializes a DialogScript to the inline-JSON form of ND_AUTOMATION_DIALOG_SCRIPT. */
+export function dialogScriptEnv(script: DialogScript): string {
+  return JSON.stringify(script);
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// @nativedesktop/test — §1.4: launchApp/AppHandle over the automation socket.
+// socket.ts's AutomationClient is the repo's ONE copy of the wire framing;
+// packages/mcp and the drive scripts import it from here rather than forking.
+export { AutomationClient } from "./socket.ts";
+export { launchApp, AppHandle, killAll } from "./launch.ts";
+export type { LaunchOptions } from "./launch.ts";
+
+export { TimedClient } from "./client.ts";
+
+export { resolveTarget, findNode, findAllNodes, findMatchingNode } from "./query.ts";
+export type { Target } from "./query.ts";
+
+export { poll, renderWaitValue } from "./wait.ts";
+export type { WaitOpts } from "./wait.ts";
+
+export { takeScreenshot } from "./screenshot.ts";
+export type { ScreenshotOptions } from "./screenshot.ts";
+
+export { dialogScriptEnv } from "./dialogs.ts";
+export type { DialogScript } from "./dialogs.ts";
+
+export { pngSize } from "./png.ts";
+export type { PngSize } from "./png.ts";
+
+// Tree types a caller needs to type find()/tree() results, re-exported so
+// nothing outside this package has to import @nativedesktop/react/rpc itself.
+export type { GetTreeResult, JsonNode } from "@nativedesktop/react/rpc";

package/src/launch.ts

@@ -0,0 +1,488 @@
+// §1.4's launchApp/AppHandle: spawns a host binary with NATIVE_AUTOMATION=1,
+// waits for the ready markers on stderr, and connects socket.ts's
+// AutomationClient (wrapped in client.ts's TimedClient) over the parsed
+// socket path. One AppHandle owns exactly one host process at a time;
+// restart() tears it down and relaunches in place.
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Backend } from "@nativedesktop/host";
+import { resolveBackend, resolveHostBinary } from "@nativedesktop/host";
+import { AutomationClient } from "./socket.ts";
+import type {
+  DragParams,
+  DragResult,
+  ClickResult,
+  GetTreeResult,
+  JsonNode,
+  KeysResult,
+  ScreenshotResult,
+  ScrollResult,
+  SetValueResult,
+  TypeResult,
+  WaitCondition,
+  WaitForResult,
+  WindowsResult,
+} from "@nativedesktop/react/rpc";
+import { TimedClient } from "./client.ts";
+import { type DialogScript, dialogScriptEnv } from "./dialogs.ts";
+import { findAllNodes, findMatchingNode, findNode, resolveTarget, type Target } from "./query.ts";
+import { registerProcess, unregisterProcess } from "./registry.ts";
+import { type ScreenshotOptions, takeScreenshot } from "./screenshot.ts";
+import { poll, renderWaitValue, type WaitOpts } from "./wait.ts";
+
+export interface LaunchOptions {
+  /** Entry file, e.g. "src/main.tsx" -> ND_SCRIPT. */
+  entry: string;
+  cwd?: string;
+  backend?: Backend;
+  env?: Record<string, string | undefined>;
+  /** ND_DEV=1. Default false. */
+  dev?: boolean;
+  /** -> ND_ACL_GRANTS JSON. */
+  acl?: Record<string, string[]>;
+  /** -> ND_AUTOMATION_DIALOG_SCRIPT (§1.5). */
+  dialogScript?: DialogScript;
+  readyMarkers?: string[];
+  readyTimeoutMs?: number;
+  rpcTimeoutMs?: number;
+  /** Relaunch attempts on ready failure / early exit, on top of the first try. Default 2. */
+  retries?: number;
+  logPath?: string;
+  onStderr?: (line: string) => void;
+}
+
+const DEFAULT_READY_MARKERS = ["ND_AUTOMATION_LISTENING", "ND_COMMIT_APPLIED"];
+const DEFAULT_READY_TIMEOUT_MS = 20_000;
+const DEFAULT_RPC_TIMEOUT_MS = 8_000;
+const DEFAULT_RETRIES = 2;
+const MAX_STDERR_LINES = 5000;
+const SOCKET_PATH_RE = /ND_AUTOMATION_LISTENING path=(\S+)/;
+
+function buildEnv(opts: LaunchOptions): Record<string, string> {
+  const merged: Record<string, string | undefined> = {
+    ...process.env,
+    NATIVE_AUTOMATION: "1",
+    ND_SCRIPT: opts.entry,
+  };
+  if (opts.dev) merged.ND_DEV = "1";
+  if (opts.acl) merged.ND_ACL_GRANTS = JSON.stringify(opts.acl);
+  if (opts.dialogScript) merged.ND_AUTOMATION_DIALOG_SCRIPT = dialogScriptEnv(opts.dialogScript);
+  Object.assign(merged, opts.env);
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(merged)) {
+    if (value !== undefined) env[key] = value;
+  }
+  // The GTK host (including GTK-via-Quartz on macOS) hard-fails during
+  // startup (ND_RUNTIME_ERROR nd_start_runtime failed) when XDG_RUNTIME_DIR
+  // is unset or points at a directory that doesn't exist. Every hand-written
+  // bash driver works around this with `mktemp -d`; do it here once so no
+  // caller has to remember the quirk.
+  if (!env.XDG_RUNTIME_DIR || !existsSync(env.XDG_RUNTIME_DIR)) {
+    env.XDG_RUNTIME_DIR = mkdtempSync(join(tmpdir(), "nd-test-xdg-"));
+  }
+  return env;
+}
+
+/** Splits a byte stream into lines, decoding across chunk boundaries. */
+async function pumpStderr(
+  stream: ReadableStream<Uint8Array>,
+  onLine: (line: string) => void,
+  onChunk?: (chunk: Uint8Array) => void,
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    onChunk?.(value);
+    buf += decoder.decode(value, { stream: true });
+    let idx: number;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      onLine(buf.slice(0, idx));
+      buf = buf.slice(idx + 1);
+    }
+  }
+  if (buf.length) onLine(buf);
+}
+
+interface ResolvedConfig {
+  binary: string;
+  cwd: string;
+  env: Record<string, string>;
+  readyMarkers: string[];
+  readyTimeoutMs: number;
+  rpcTimeoutMs: number;
+  retries: number;
+  backend: Backend;
+  logPath?: string;
+  onStderr?: (line: string) => void;
+}
+
+interface LineSink {
+  write(chunk: Uint8Array): number;
+  end(): void;
+}
+
+interface LiveHost {
+  proc: import("bun").Subprocess<"ignore", "ignore", "pipe">;
+  pid: number;
+  stderrLines: string[];
+  seenMarkers: Set<string>;
+  socketPath: string | undefined;
+  exited: boolean;
+  exitCode: number | null;
+  pumpDone: Promise<void>;
+  exitedPromise: Promise<number>;
+}
+
+export class AppHandle {
+  private live?: LiveHost;
+  private client?: TimedClient;
+
+  private constructor(private readonly config: ResolvedConfig) {}
+
+  static async launch(config: ResolvedConfig): Promise<AppHandle> {
+    const handle = new AppHandle(config);
+    await handle.launchWithRetries();
+    return handle;
+  }
+
+  private async launchWithRetries(): Promise<void> {
+    let lastErr: Error | undefined;
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      try {
+        await this.spawnOnce();
+        await this.connectRpc();
+        return;
+      } catch (e) {
+        lastErr = e as Error;
+      }
+    }
+    throw new Error(`launchApp: failed after ${this.config.retries + 1} attempt(s): ${lastErr?.message}`);
+  }
+
+  private async spawnOnce(): Promise<void> {
+    const proc = Bun.spawn([this.config.binary], {
+      cwd: this.config.cwd,
+      env: this.config.env,
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "pipe",
+    });
+    registerProcess(proc);
+
+    const logSink: LineSink | undefined = this.config.logPath ? Bun.file(this.config.logPath).writer() : undefined;
+    const live: LiveHost = {
+      proc,
+      pid: proc.pid,
+      stderrLines: [],
+      seenMarkers: new Set(),
+      socketPath: undefined,
+      exited: false,
+      exitCode: null,
+      pumpDone: Promise.resolve(),
+      exitedPromise: Promise.resolve(0),
+    };
+    this.live = live;
+
+    const onLine = (line: string): void => {
+      live.stderrLines.push(line);
+      if (live.stderrLines.length > MAX_STDERR_LINES) live.stderrLines.shift();
+      for (const marker of this.config.readyMarkers) {
+        if (line.includes(marker)) live.seenMarkers.add(marker);
+      }
+      const match = SOCKET_PATH_RE.exec(line);
+      if (match?.[1]) live.socketPath = match[1];
+      this.config.onStderr?.(line);
+    };
+
+    live.pumpDone = pumpStderr(proc.stderr, onLine, logSink ? (chunk) => void logSink.write(chunk) : undefined).finally(
+      () => logSink?.end(),
+    );
+    live.exitedPromise = proc.exited.then((code) => {
+      live.exited = true;
+      live.exitCode = code;
+      unregisterProcess(proc);
+      return code;
+    });
+
+    try {
+      await this.waitUntilReady(live);
+    } catch (e) {
+      if (!live.exited) proc.kill("SIGKILL");
+      await live.exitedPromise.catch(() => {});
+      throw e;
+    }
+  }
+
+  private async waitUntilReady(live: LiveHost): Promise<void> {
+    const deadline = Date.now() + this.config.readyTimeoutMs;
+    for (;;) {
+      if (this.config.readyMarkers.every((m) => live.seenMarkers.has(m))) return;
+      if (live.exited) {
+        throw new Error(
+          `host exited before ready markers were seen (code ${live.exitCode})\n` +
+            `--- last 40 stderr lines ---\n${tail(live.stderrLines, 40)}`,
+        );
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `ready markers not seen within ${this.config.readyTimeoutMs}ms: ${this.config.readyMarkers.join(", ")}\n` +
+            `--- last 40 stderr lines ---\n${tail(live.stderrLines, 40)}`,
+        );
+      }
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+
+  private async connectRpc(): Promise<void> {
+    const live = this.live;
+    if (!live) throw new Error("connectRpc: no live host");
+    if (!live.socketPath) {
+      throw new Error(
+        `no automation socket path parsed from stderr (ND_AUTOMATION_LISTENING line missing)\n` +
+          `--- last 40 stderr lines ---\n${tail(live.stderrLines, 40)}`,
+      );
+    }
+    const inner = await AutomationClient.connect(live.socketPath);
+    this.client = new TimedClient(inner, this.config.rpcTimeoutMs, (n) => this.stderrTail(n));
+  }
+
+  private async teardown(): Promise<void> {
+    this.client?.close();
+    this.client = undefined;
+    const live = this.live;
+    if (!live) return;
+    if (!live.exited) {
+      live.proc.kill("SIGTERM");
+      const exited = await Promise.race([
+        live.exitedPromise.then(() => true),
+        new Promise<boolean>((r) => setTimeout(() => r(false), 3000)),
+      ]);
+      if (!exited && !live.exited) live.proc.kill("SIGKILL");
+    }
+    await live.exitedPromise.catch(() => {});
+    await live.pumpDone.catch(() => {});
+  }
+
+  // --- identity ------------------------------------------------------------
+
+  get pid(): number {
+    if (!this.live) throw new Error("AppHandle: host not running");
+    return this.live.pid;
+  }
+
+  get logPath(): string | undefined {
+    return this.config.logPath;
+  }
+
+  get socketPath(): string {
+    if (!this.live?.socketPath) throw new Error("AppHandle: no automation socket connected");
+    return this.live.socketPath;
+  }
+
+  get backend(): Backend {
+    return this.config.backend;
+  }
+
+  get rpc(): TimedClient {
+    if (!this.client) throw new Error("AppHandle: not connected");
+    return this.client;
+  }
+
+  stderr(): string {
+    return (this.live?.stderrLines ?? []).join("\n");
+  }
+
+  stderrTail(n = 40): string {
+    return tail(this.live?.stderrLines ?? [], n);
+  }
+
+  // --- tree queries ----------------------------------------------------------
+
+  async tree(window?: number): Promise<GetTreeResult> {
+    return this.rpc.call("getTree", { window });
+  }
+
+  async find(testId: string, opts: { window?: number } = {}): Promise<JsonNode | null> {
+    const t = await this.tree(opts.window);
+    return findNode(t.root, testId);
+  }
+
+  async findAll(testId: string, opts: { window?: number } = {}): Promise<JsonNode[]> {
+    const t = await this.tree(opts.window);
+    return findAllNodes(t.root, testId);
+  }
+
+  async mustFind(testId: string, opts: { window?: number } = {}): Promise<JsonNode> {
+    const node = await this.find(testId, opts);
+    if (!node) throw new Error(`${testId} not found in tree`);
+    return node;
+  }
+
+  async findMatching(pred: (n: JsonNode) => boolean, opts: { window?: number } = {}): Promise<JsonNode | null> {
+    const t = await this.tree(opts.window);
+    return findMatchingNode(t.root, pred);
+  }
+
+  // --- actions (single RPC, host-side resolution, no retry loops) ------------
+
+  click(t: Target): Promise<ClickResult> {
+    return this.rpc.call("click", resolveTarget(t));
+  }
+
+  setValue(t: Target, value: unknown): Promise<SetValueResult> {
+    return this.rpc.call("setValue", { ...resolveTarget(t), value });
+  }
+
+  type(t: Target, text: string): Promise<TypeResult> {
+    return this.rpc.call("type", { ...resolveTarget(t), text });
+  }
+
+  scroll(t: Target, opts: { dx?: number; dy?: number } = {}): Promise<ScrollResult> {
+    return this.rpc.call("scroll", { ...resolveTarget(t), ...opts });
+  }
+
+  hover(t: Target): Promise<ClickResult> {
+    return this.rpc.call("hover", resolveTarget(t));
+  }
+
+  doubleClick(t: Target): Promise<ClickResult> {
+    return this.rpc.call("doubleClick", resolveTarget(t));
+  }
+
+  rightClick(t: Target): Promise<ClickResult> {
+    return this.rpc.call("rightClick", resolveTarget(t));
+  }
+
+  keys(spec: string, opts: { window?: number } = {}): Promise<KeysResult> {
+    return this.rpc.call("keys", { keys: spec, ...opts });
+  }
+
+  drag(opts: DragParams): Promise<DragResult> {
+    return this.rpc.call("drag", opts);
+  }
+
+  // --- waitFor + sugar (thin pass-throughs; the host does the polling) -------
+
+  waitFor(condition: WaitCondition, opts: WaitOpts = {}): Promise<WaitForResult> {
+    return this.rpc.call("waitFor", { condition, timeoutMs: opts.timeoutMs, window: opts.window });
+  }
+
+  waitForText(text: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ textContains: text }, opts);
+  }
+
+  waitForPresent(testId: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, state: "present" }, opts);
+  }
+
+  waitForGone(testId: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, state: "gone" }, opts);
+  }
+
+  waitForEnabled(testId: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, state: "enabled" }, opts);
+  }
+
+  waitForDisabled(testId: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, state: "disabled" }, opts);
+  }
+
+  waitForFocused(testId: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, state: "focused" }, opts);
+  }
+
+  waitForCount(testId: string, count: number, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, countAtLeast: count }, opts);
+  }
+
+  waitForValue(testId: string, value: string | number | boolean, opts: WaitOpts & { contains?: boolean } = {}): Promise<WaitForResult> {
+    const { contains, ...rest } = opts;
+    const rendered = renderWaitValue(value);
+    return this.waitFor(contains ? { testId, valueContains: rendered } : { testId, valueEquals: rendered }, rest);
+  }
+
+  async waitForMarker(marker: string, timeoutMs = 5000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      if (this.live?.stderrLines.some((l) => l.includes(marker))) return;
+      if (Date.now() >= deadline) {
+        throw new Error(`marker "${marker}" not seen within ${timeoutMs}ms\n--- last 40 stderr lines ---\n${this.stderrTail(40)}`);
+      }
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+
+  windows(): Promise<WindowsResult> {
+    return this.rpc.call("windows");
+  }
+
+  async waitForWindows(count: number, timeoutMs = 3000): Promise<number> {
+    const result = await poll(() => this.windows(), (r) => r.windows.length === count, { timeoutMs }).catch((e: Error) => {
+      throw new Error(`waitForWindows(${count}): ${e.message}`);
+    });
+    return result.windows.length;
+  }
+
+  // --- screenshot --------------------------------------------------------------
+
+  screenshot(path: string, opts: ScreenshotOptions = {}): Promise<ScreenshotResult> {
+    return takeScreenshot(
+      {
+        callScreenshot: (p, window) => this.rpc.call("screenshot", { path: p, window }),
+        pid: this.pid,
+        backend: this.backend,
+      },
+      path,
+      opts,
+    );
+  }
+
+  // --- lifecycle ---------------------------------------------------------------
+
+  async restart(): Promise<void> {
+    await this.teardown();
+    await this.launchWithRetries();
+  }
+
+  async close(): Promise<void> {
+    await this.teardown();
+  }
+
+  kill(): void {
+    this.client?.close();
+    this.client = undefined;
+    if (this.live && !this.live.exited) this.live.proc.kill("SIGKILL");
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close();
+  }
+}
+
+function tail(lines: string[], n: number): string {
+  return lines.slice(-n).join("\n");
+}
+
+export async function launchApp(opts: LaunchOptions): Promise<AppHandle> {
+  const backend = resolveBackend({ backend: opts.backend });
+  const binary = await resolveHostBinary({ backend });
+  const config: ResolvedConfig = {
+    binary,
+    cwd: opts.cwd ?? process.cwd(),
+    env: buildEnv(opts),
+    readyMarkers: opts.readyMarkers ?? DEFAULT_READY_MARKERS,
+    readyTimeoutMs: opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+    rpcTimeoutMs: opts.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+    retries: opts.retries ?? DEFAULT_RETRIES,
+    backend,
+    logPath: opts.logPath,
+    onStderr: opts.onStderr,
+  };
+  return AppHandle.launch(config);
+}
+
+export { killAll } from "./registry.ts";

package/src/png.ts

@@ -0,0 +1,22 @@
+// PNG dimension reader: parses the 8-byte signature + IHDR chunk (width/height,
+// big-endian u32 at bytes 16/20) without pulling in an image-decoding
+// dependency. Every drive script used to hand-roll this; this is the one copy.
+
+export interface PngSize {
+  width: number;
+  height: number;
+}
+
+const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+export async function pngSize(path: string): Promise<PngSize> {
+  const bytes = new Uint8Array(await Bun.file(path).slice(0, 24).arrayBuffer());
+  if (bytes.length < 24) throw new Error(`${path}: too short to be a PNG (${bytes.length} bytes)`);
+  for (let i = 0; i < SIGNATURE.length; i++) {
+    if (bytes[i] !== SIGNATURE[i]) throw new Error(`${path}: not a PNG (bad signature)`);
+  }
+  const chunkType = String.fromCharCode(bytes[12]!, bytes[13]!, bytes[14]!, bytes[15]!);
+  if (chunkType !== "IHDR") throw new Error(`${path}: first chunk is "${chunkType}", want "IHDR"`);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { width: view.getUint32(16, false), height: view.getUint32(20, false) };
+}

package/src/query.ts

@@ -0,0 +1,39 @@
+// Tree-walking helpers factored out of the four consumer drive scripts, which
+// each hand-rolled the same find/mustFind pair. resolveTarget() is the
+// client-side half of §1.2a's targeting: a caller passes a testID, a raw ref,
+// or an explicit {testId?, ref?, window?}, and every action RPC accepts
+// exactly one of ref/testId (validated host-side).
+import type { JsonNode } from "@nativedesktop/react/rpc";
+
+export function findNode(node: JsonNode, testId: string): JsonNode | null {
+  if (node.testID === testId) return node;
+  for (const child of node.children) {
+    const found = findNode(child, testId);
+    if (found) return found;
+  }
+  return null;
+}
+
+export function findAllNodes(node: JsonNode, testId: string, out: JsonNode[] = []): JsonNode[] {
+  if (node.testID === testId) out.push(node);
+  for (const child of node.children) findAllNodes(child, testId, out);
+  return out;
+}
+
+export function findMatchingNode(node: JsonNode, pred: (n: JsonNode) => boolean): JsonNode | null {
+  if (pred(node)) return node;
+  for (const child of node.children) {
+    const found = findMatchingNode(child, pred);
+    if (found) return found;
+  }
+  return null;
+}
+
+/** A widget reference for the action RPCs: a bare testID, a bare ref, or an explicit descriptor. */
+export type Target = string | number | { testId?: string; ref?: number; window?: number };
+
+export function resolveTarget(t: Target): { testId?: string; ref?: number; window?: number } {
+  if (typeof t === "string") return { testId: t };
+  if (typeof t === "number") return { ref: t };
+  return { ...t };
+}

package/src/registry.ts

@@ -0,0 +1,41 @@
+// Process-lifetime registry of launched host binaries. A thrown assertion in
+// a drive script (or a test runner's own SIGINT) must not orphan a native
+// window — killAll() is wired to fire on every exit path exactly once.
+
+const live = new Set<import("bun").Subprocess>();
+let wired = false;
+
+export function registerProcess(proc: import("bun").Subprocess): void {
+  live.add(proc);
+  wireSignalHandlers();
+}
+
+export function unregisterProcess(proc: import("bun").Subprocess): void {
+  live.delete(proc);
+}
+
+/** Kills every still-registered host process. Safe to call more than once. */
+export function killAll(): void {
+  for (const proc of live) {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // already dead
+    }
+  }
+  live.clear();
+}
+
+function wireSignalHandlers(): void {
+  if (wired) return;
+  wired = true;
+  process.on("exit", killAll);
+  process.on("SIGINT", () => {
+    killAll();
+    process.exit(130);
+  });
+  process.on("SIGTERM", () => {
+    killAll();
+    process.exit(143);
+  });
+}

package/src/screenshot.ts

@@ -0,0 +1,74 @@
+// screenshot() with retries + floor checks — subsumes every drive script's
+// hand-rolled screenshotRetrying loop (notes-drive, tabs-drive, m6-drive: a
+// screenshot right after a mutation/animation can race frame invalidation
+// and answer -32603 or a blank frame; poll rather than treat one bad shot as
+// final). `via: "ndshot"` shells out to tools/ndshot (macOS/AppKit only) for
+// the ScreenCaptureKit capture path documented in automation-socket.md, for
+// callers hitting the offscreen-render TextInput/TextArea blanking bug.
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import type { Backend } from "@nativedesktop/host";
+import type { ScreenshotResult } from "@nativedesktop/react/rpc";
+import { pngSize } from "./png.ts";
+
+export interface ScreenshotOptions {
+  window?: number;
+  retries?: number;
+  minHeight?: number;
+  minBytes?: number;
+  via?: "rpc" | "ndshot";
+}
+
+export interface ScreenshotDeps {
+  callScreenshot: (path: string, window?: number) => Promise<ScreenshotResult>;
+  pid: number;
+  backend: Backend;
+}
+
+const NDSHOT_BIN = resolvePath(import.meta.dir, "..", "..", "..", "tools", "ndshot", "bin", "ndshot");
+
+export async function takeScreenshot(
+  deps: ScreenshotDeps,
+  path: string,
+  opts: ScreenshotOptions = {},
+): Promise<ScreenshotResult> {
+  const retries = opts.retries ?? 5;
+  let lastErr: Error | undefined;
+  for (let attempt = 0; attempt < retries; attempt++) {
+    try {
+      const shot =
+        opts.via === "ndshot" ? await captureViaNdshot(deps, path) : await deps.callScreenshot(path, opts.window);
+      if (shot.width <= 0 || shot.height <= 0) {
+        throw new Error(`screenshot has no dimensions (${shot.width}x${shot.height})`);
+      }
+      if (opts.minHeight !== undefined && shot.height < opts.minHeight) {
+        throw new Error(`screenshot height ${shot.height} below floor ${opts.minHeight}`);
+      }
+      if (opts.minBytes !== undefined) {
+        const size = Bun.file(path).size;
+        if (size < opts.minBytes) throw new Error(`screenshot ${size} bytes below floor ${opts.minBytes}`);
+      }
+      return shot;
+    } catch (e) {
+      lastErr = e as Error;
+      if (attempt < retries - 1) await new Promise((r) => setTimeout(r, 150));
+    }
+  }
+  throw new Error(`screenshot failed after ${retries} attempts: ${lastErr?.message}`);
+}
+
+async function captureViaNdshot(deps: ScreenshotDeps, path: string): Promise<ScreenshotResult> {
+  if (deps.backend !== "appkit") throw new Error(`via: "ndshot" is macOS/AppKit-only (backend=${deps.backend})`);
+  if (!existsSync(NDSHOT_BIN)) throw new Error(`ndshot binary missing at ${NDSHOT_BIN} — run tools/ndshot/build.sh`);
+  const proc = Bun.spawn([NDSHOT_BIN, "capture", "--out", path, "--pid", String(deps.pid)], {
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const status = await proc.exited;
+  if (status !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`ndshot capture failed (exit ${status}): ${err.trim()}`);
+  }
+  const { width, height } = await pngSize(path);
+  return { path, width, height };
+}

package/src/socket.ts

@@ -0,0 +1,100 @@
+// Framed JSON-RPC 2.0 client for the NativeDesktop automation socket.
+// Wire format matches NDP: u32 LE length prefix + UTF-8 JSON (runtime/ndp.ts),
+// but the payload here is a JSON-RPC 2.0 request/response, not an NDP message.
+// Method names and params/result shapes are GENERATED from schema/rpc.json
+// (the single source of truth shared with the Zig host, src/automation.zig via
+// src/generated/rpc.zig) — `call` is constrained by the generated RpcMethods
+// map, so a schema change is a compile error here, tRPC-style.
+
+import type { RpcMethodName, RpcParams, RpcResult } from "@nativedesktop/react/rpc";
+
+interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+export class AutomationClient {
+  private socket!: import("bun").Socket;
+  private inbox = new Uint8Array(0);
+  private nextId = 1;
+  private pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+
+  static async connect(path = process.env.ND_AUTOMATION_SOCKET): Promise<AutomationClient> {
+    if (!path) throw new Error("ND_AUTOMATION_SOCKET not set");
+    let self!: AutomationClient;
+    const socket = await Bun.connect({
+      unix: path,
+      socket: {
+        data(_sock, chunk) {
+          self.onData(chunk);
+        },
+        close() {
+          self.onClose();
+        },
+      },
+    });
+    self = new AutomationClient(socket);
+    return self;
+  }
+
+  private constructor(socket: import("bun").Socket) {
+    this.socket = socket;
+  }
+
+  private onClose(): void {
+    for (const p of this.pending.values()) p.reject(new Error("automation socket closed"));
+    this.pending.clear();
+  }
+
+  private onData(chunk: Uint8Array): void {
+    const merged = new Uint8Array(this.inbox.length + chunk.length);
+    merged.set(this.inbox, 0);
+    merged.set(chunk, this.inbox.length);
+    this.inbox = merged;
+    // Drain complete frames; a chunk may contain zero, one, or many frames,
+    // and the last frame may be split across the next read.
+    while (this.inbox.length >= 4) {
+      const view = new DataView(this.inbox.buffer, this.inbox.byteOffset, 4);
+      const len = view.getUint32(0, true);
+      if (this.inbox.length < 4 + len) break;
+      const json = new TextDecoder().decode(this.inbox.subarray(4, 4 + len));
+      this.inbox = this.inbox.subarray(4 + len);
+      this.dispatch(JSON.parse(json) as JsonRpcResponse);
+    }
+  }
+
+  private dispatch(msg: JsonRpcResponse): void {
+    const pending = this.pending.get(msg.id);
+    if (!pending) return; // unknown/stale id — drop
+    this.pending.delete(msg.id);
+    if (msg.error) pending.reject(new Error(`${msg.error.message} (${msg.error.code})`));
+    else pending.resolve(msg.result);
+  }
+
+  call<M extends RpcMethodName>(
+    method: M,
+    ...params: RpcParams<M> extends undefined ? [] : [RpcParams<M>]
+  ): Promise<RpcResult<M>> {
+    const id = this.nextId++;
+    const json = new TextEncoder().encode(JSON.stringify({ jsonrpc: "2.0", id, method, params: params[0] }));
+    const frame = new Uint8Array(4 + json.length);
+    new DataView(frame.buffer).setUint32(0, json.length, true);
+    frame.set(json, 4);
+    return new Promise<RpcResult<M>>((resolve, reject) => {
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      this.socket.write(frame);
+    });
+  }
+
+  close(): void {
+    this.socket.end();
+  }
+}

package/src/wait.ts

@@ -0,0 +1,32 @@
+// §1.4's waitFor sugar is a thin pass-through to the `waitFor` RPC: the host
+// polls its own retained tree at ~50ms (§1.1) and this client never
+// re-implements that loop. poll() below is the one piece of genuine
+// client-side polling in the harness, for conditions the waitFor vocabulary
+// can't express (window count).
+export interface WaitOpts {
+  timeoutMs?: number;
+  window?: number;
+}
+
+/** Generic poll: calls `fn` until `pred` holds or `timeoutMs` elapses. */
+export async function poll<T>(
+  fn: () => Promise<T>,
+  pred: (value: T) => boolean,
+  opts: { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<T> {
+  const timeoutMs = opts.timeoutMs ?? 3000;
+  const intervalMs = opts.intervalMs ?? 100;
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const value = await fn();
+    if (pred(value)) return value;
+    if (Date.now() >= deadline) throw new Error(`poll: predicate never held within ${timeoutMs}ms`);
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
+/** Renders a value the same way the host stringifies `value` for
+ * valueEquals/valueContains: numbers stringified, bools "true"/"false". */
+export function renderWaitValue(value: string | number | boolean): string {
+  return typeof value === "string" ? value : String(value);
+}