patchrome 0.1.0

package/dist/session-name.js

@@ -0,0 +1,50 @@
+import { execFileSync } from "node:child_process";
+const shellCommands = new Set([
+    "sh",
+    "bash",
+    "zsh",
+    "fish",
+    "dash",
+    "ksh",
+    "nu",
+    "env",
+    "node",
+    "npx",
+    "npm",
+    "pnpm",
+    "bun",
+]);
+// Claude Code and Codex run each tool call in a fresh shell, so the direct parent pid changes per command.
+// The first ancestor that is not a shell or a Node launcher is the agent or terminal, and outlives the call.
+export function resolveSessionName(env, startPid, lookup) {
+    if (env.PATCHROME_SESSION)
+        return env.PATCHROME_SESSION;
+    if (env.CLAUDE_CODE_SESSION_ID)
+        return `claude-${env.CLAUDE_CODE_SESSION_ID}`;
+    let pid = startPid;
+    for (let depth = 0; depth < 32 && pid > 1; depth++) {
+        const info = lookup(pid);
+        if (!info)
+            break;
+        const commandName = info.command.split("/").pop()?.replace(/^-/, "") ?? "";
+        const hasTty = info.tty !== "" && info.tty !== "??" && info.tty !== "?";
+        if (hasTty)
+            return `tty-${info.tty.replace(/^\/dev\//, "")}`;
+        if (!shellCommands.has(commandName))
+            return `pid-${info.pid}`;
+        pid = info.ppid;
+    }
+    return `pid-${startPid}`;
+}
+export function lookupProcess(pid) {
+    try {
+        const line = execFileSync("ps", ["-o", "pid=,ppid=,tty=,comm=", "-p", String(pid)], { encoding: "utf8" }).trim();
+        const match = line.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+        if (!match)
+            return undefined;
+        return { pid: Number(match[1]), ppid: Number(match[2]), tty: match[3] ?? "", command: match[4] ?? "" };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/session-store.d.ts

@@ -0,0 +1,5 @@
+import type { SavedSession } from "./sessions.ts";
+export declare const sessionRetentionMs: number;
+export declare function loadSavedSessions(path: string, nowMs: number): Promise<SavedSession[]>;
+export declare function saveSessions(path: string, sessions: SavedSession[], nowMs: number): Promise<void>;
+export declare function pruneSessionFolders(sessionsDir: string, nowMs: number): Promise<string[]>;

package/dist/session-store.js

@@ -0,0 +1,58 @@
+import { readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+// Session folders and saved sessions untouched this long are dropped when the daemon starts.
+export const sessionRetentionMs = 7 * 24 * 60 * 60 * 1000;
+const savedSessionSchema = z.object({
+    name: z.string(),
+    isIsolated: z.boolean(),
+    label: z.string().optional(),
+    currentTabId: z.string().optional(),
+    tabs: z.array(z.object({ id: z.string().regex(/^t\d+$/), url: z.string() })),
+});
+// One bad entry drops that session, not the whole file.
+const sessionsFileSchema = z.object({
+    savedAtMs: z.number(),
+    sessions: z.array(z.unknown()),
+});
+// A missing, stale or unreadable file restores nothing: restore is best-effort and never blocks a start.
+export async function loadSavedSessions(path, nowMs) {
+    const raw = await readFile(path, "utf8").catch(() => undefined);
+    if (raw === undefined)
+        return [];
+    try {
+        const parsed = sessionsFileSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success || nowMs - parsed.data.savedAtMs > sessionRetentionMs)
+            return [];
+        return parsed.data.sessions.flatMap((entry) => {
+            const session = savedSessionSchema.safeParse(entry);
+            if (!session.success)
+                return [];
+            const { label, currentTabId } = session.data;
+            return [{ ...session.data, label, currentTabId }];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+// Writes through a temp file and a rename, so a daemon killed mid-write leaves the previous file intact.
+export async function saveSessions(path, sessions, nowMs) {
+    const body = { savedAtMs: nowMs, sessions };
+    const partialPath = `${path}.partial`;
+    await writeFile(partialPath, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 });
+    await rename(partialPath, path);
+}
+export async function pruneSessionFolders(sessionsDir, nowMs) {
+    const names = await readdir(sessionsDir).catch(() => []);
+    const pruned = [];
+    for (const name of names) {
+        const folder = join(sessionsDir, name);
+        const info = await stat(folder).catch(() => undefined);
+        if (!info?.isDirectory() || nowMs - info.mtimeMs <= sessionRetentionMs)
+            continue;
+        await rm(folder, { recursive: true, force: true });
+        pruned.push(name);
+    }
+    return pruned;
+}

package/dist/sessions.d.ts

@@ -0,0 +1,47 @@
+import type { Page } from "patchright";
+import { SnapshotGenerations } from "./refs.ts";
+export interface Tab {
+    id: string;
+    session: string;
+    page: Page;
+    generations: SnapshotGenerations;
+    isClosed: boolean;
+}
+export interface SavedSession {
+    name: string;
+    isIsolated: boolean;
+    label: string | undefined;
+    currentTabId: string | undefined;
+    tabs: Array<{
+        id: string;
+        url: string;
+    }>;
+}
+export interface TabSummary {
+    id: string;
+    session: string;
+    url: string;
+    isCurrent: boolean;
+}
+export type TrackedPage = Pick<Page, "on" | "url" | "mainFrame">;
+export declare class SessionRegistry {
+    #private;
+    constructor(onTabAdopted?: (tab: Tab) => void, onChanged?: () => void);
+    adoptPage(sessionName: string, page: TrackedPage, makeCurrent: boolean, restoredTabId?: string): Tab;
+    currentTab(sessionName: string): Tab;
+    ownedTab(sessionName: string, tabId: string): Tab;
+    switchTo(sessionName: string, tabId: string): Tab;
+    tabsOf(sessionName: string): TabSummary[];
+    allTabs(): TabSummary[];
+    openTabsOf(sessionName: string): Tab[];
+    forget(sessionName: string): void;
+    reserveTabIds(tabIds: string[]): void;
+    hasSession(sessionName: string): boolean;
+    browserContextOf(sessionName: string): string | undefined;
+    isolate(sessionName: string, browserContextId: string): void;
+    labelOf(sessionName: string): string | undefined;
+    setLabel(sessionName: string, label: string | undefined): void;
+    savedSessions(): SavedSession[];
+    originsOf(sessionName: string): string[];
+    sessionNames(): string[];
+}

package/dist/sessions.js

@@ -0,0 +1,171 @@
+import { CommandError } from "./protocol.js";
+import { SnapshotGenerations } from "./refs.js";
+export class SessionRegistry {
+    #sessions = new Map();
+    #tabs = new Map();
+    #nextTabNumber = 1;
+    #onTabAdopted;
+    #onChanged;
+    // The daemon hangs network recording and routes off onTabAdopted, so popups get them too, and saves
+    // sessions.json on onChanged.
+    constructor(onTabAdopted = () => { }, onChanged = () => { }) {
+        this.#onTabAdopted = onTabAdopted;
+        this.#onChanged = onChanged;
+    }
+    // A restored tab keeps the id it had before the daemon restarted, so an agent's `switch t3` still works.
+    adoptPage(sessionName, page, makeCurrent, restoredTabId) {
+        const session = this.#sessionFor(sessionName);
+        const restoredNumber = restoredTabId === undefined ? undefined : Number(restoredTabId.slice(1));
+        if (restoredNumber !== undefined)
+            this.#nextTabNumber = Math.max(this.#nextTabNumber, restoredNumber + 1);
+        const tab = {
+            id: restoredTabId ?? `t${this.#nextTabNumber++}`,
+            session: sessionName,
+            page: page,
+            generations: new SnapshotGenerations(),
+            isClosed: false,
+        };
+        this.#tabs.set(tab.id, tab);
+        session.tabIds.add(tab.id);
+        if (makeCurrent)
+            session.currentTabId = tab.id;
+        page.on("close", () => {
+            tab.isClosed = true;
+            session.tabIds.delete(tab.id);
+            this.#tabs.delete(tab.id);
+            this.#onChanged();
+        });
+        page.on("framenavigated", (frame) => {
+            if (frame !== page.mainFrame())
+                return;
+            tab.generations.recordNavigation();
+            const origin = originOf(page.url());
+            if (origin !== undefined)
+                session.origins.add(origin);
+            this.#onChanged();
+        });
+        // A popup belongs to the session whose page opened it, and does not become current by itself.
+        page.on("popup", (popup) => {
+            this.adoptPage(sessionName, popup, false);
+        });
+        this.#onTabAdopted(tab);
+        this.#onChanged();
+        return tab;
+    }
+    currentTab(sessionName) {
+        const session = this.#sessions.get(sessionName);
+        const tabId = session?.currentTabId;
+        if (!session || tabId === undefined) {
+            throw new CommandError("tab_gone", `session ${sessionName} has no current tab`, "run `patchrome open <url>`");
+        }
+        const tab = this.#tabs.get(tabId);
+        if (!tab || tab.isClosed) {
+            throw new CommandError("tab_gone", `tab ${tabId} was closed`, "run `patchrome open <url>` for a new tab");
+        }
+        return tab;
+    }
+    ownedTab(sessionName, tabId) {
+        const tab = this.#tabs.get(tabId);
+        if (!tab || tab.isClosed) {
+            throw new CommandError("tab_gone", `no open tab ${tabId}`, "run `patchrome tabs` to list this session's tabs");
+        }
+        if (tab.session !== sessionName) {
+            throw new CommandError("bad_args", `tab ${tabId} belongs to another session`, "a session only acts on tabs it opened");
+        }
+        return tab;
+    }
+    switchTo(sessionName, tabId) {
+        const tab = this.ownedTab(sessionName, tabId);
+        this.#sessionFor(sessionName).currentTabId = tab.id;
+        this.#onChanged();
+        return tab;
+    }
+    tabsOf(sessionName) {
+        const session = this.#sessions.get(sessionName);
+        if (!session)
+            return [];
+        return [...session.tabIds].map((id) => this.#summarize(id, session.currentTabId));
+    }
+    allTabs() {
+        return [...this.#sessions.values()].flatMap((session) => [...session.tabIds].map((id) => this.#summarize(id, session.currentTabId)));
+    }
+    openTabsOf(sessionName) {
+        const session = this.#sessions.get(sessionName);
+        if (!session)
+            return [];
+        return [...session.tabIds]
+            .map((id) => this.#tabs.get(id))
+            .filter((tab) => tab !== undefined && !tab.isClosed);
+    }
+    forget(sessionName) {
+        for (const tabId of this.#sessions.get(sessionName)?.tabIds ?? [])
+            this.#tabs.delete(tabId);
+        this.#sessions.delete(sessionName);
+        this.#onChanged();
+    }
+    // Tab ids saved before a restart stay reserved, so a new tab never takes the id of one still to be restored.
+    reserveTabIds(tabIds) {
+        for (const tabId of tabIds)
+            this.#nextTabNumber = Math.max(this.#nextTabNumber, Number(tabId.slice(1)) + 1);
+    }
+    hasSession(sessionName) {
+        return this.#sessions.has(sessionName);
+    }
+    browserContextOf(sessionName) {
+        return this.#sessions.get(sessionName)?.browserContextId;
+    }
+    isolate(sessionName, browserContextId) {
+        this.#sessionFor(sessionName).browserContextId = browserContextId;
+    }
+    labelOf(sessionName) {
+        return this.#sessions.get(sessionName)?.label;
+    }
+    setLabel(sessionName, label) {
+        this.#sessionFor(sessionName).label = label;
+        this.#onChanged();
+    }
+    savedSessions() {
+        return [...this.#sessions.values()].map((session) => ({
+            name: session.name,
+            isIsolated: session.browserContextId !== undefined,
+            label: session.label,
+            currentTabId: session.currentTabId,
+            tabs: [...session.tabIds].map((id) => ({ id, url: this.#tabs.get(id)?.page.url() ?? "" })),
+        }));
+    }
+    // Web origins the session's tabs have loaded, which is what `state save` keeps.
+    originsOf(sessionName) {
+        return [...(this.#sessions.get(sessionName)?.origins ?? [])];
+    }
+    sessionNames() {
+        return [...this.#sessions.keys()];
+    }
+    #sessionFor(name) {
+        let session = this.#sessions.get(name);
+        if (!session) {
+            session = {
+                name,
+                tabIds: new Set(),
+                currentTabId: undefined,
+                origins: new Set(),
+                browserContextId: undefined,
+                label: undefined,
+            };
+            this.#sessions.set(name, session);
+        }
+        return session;
+    }
+    #summarize(tabId, currentTabId) {
+        const tab = this.#tabs.get(tabId);
+        return { id: tabId, session: tab?.session ?? "", url: tab?.page.url() ?? "", isCurrent: tabId === currentTabId };
+    }
+}
+function originOf(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/tab-groups.d.ts

@@ -0,0 +1,9 @@
+export declare const tabGroupColors: readonly ["grey", "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"];
+export type TabGroupColor = (typeof tabGroupColors)[number];
+export interface TabGroupSummary {
+    title: string;
+    color: TabGroupColor;
+    tabCount: number;
+}
+export declare function tabGroupTitleFor(sessionName: string, label: string | undefined): string;
+export declare function tabGroupColorFor(sessionName: string): TabGroupColor;

package/dist/tab-groups.js

@@ -0,0 +1,13 @@
+// Chrome's fixed tab group palette.
+export const tabGroupColors = ["grey", "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"];
+// The session name leads, so a glance at the tab strip says which agent owns the tabs.
+export function tabGroupTitleFor(sessionName, label) {
+    return label === undefined || label === "" ? sessionName : `${sessionName}: ${label}`;
+}
+// A session keeps its colour across restarts and relabels, because the colour comes from the name alone.
+export function tabGroupColorFor(sessionName) {
+    let hash = 0;
+    for (const char of sessionName)
+        hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+    return tabGroupColors[hash % tabGroupColors.length] ?? "grey";
+}

package/dist/targets.d.ts

@@ -0,0 +1,43 @@
+import type { Locator, Page } from "patchright";
+import { type CommandArgs } from "./protocol.ts";
+export declare const ariaRoles: readonly ["alert", "alertdialog", "application", "article", "banner", "blockquote", "button", "caption", "cell", "checkbox", "code", "columnheader", "combobox", "complementary", "contentinfo", "definition", "deletion", "dialog", "directory", "document", "emphasis", "feed", "figure", "form", "generic", "grid", "gridcell", "group", "heading", "img", "insertion", "link", "list", "listbox", "listitem", "log", "main", "marquee", "math", "meter", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "navigation", "none", "note", "option", "paragraph", "presentation", "progressbar", "radio", "radiogroup", "region", "row", "rowgroup", "rowheader", "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton", "status", "strong", "subscript", "superscript", "switch", "tab", "table", "tablist", "tabpanel", "term", "textbox", "time", "timer", "toolbar", "tooltip", "tree", "treegrid", "treeitem"];
+export type AriaRole = (typeof ariaRoles)[number];
+export declare function isAriaRole(value: string): value is AriaRole;
+export interface LocatorScope {
+    frame: string | undefined;
+    nth: number | undefined;
+}
+export type ElementLocator = ({
+    kind: "selector";
+    selector: string;
+} & LocatorScope) | ({
+    kind: "role";
+    role: AriaRole;
+    name: string | undefined;
+    isExact: boolean;
+} & LocatorScope) | ({
+    kind: "text";
+    text: string;
+    isExact: boolean;
+} & LocatorScope) | ({
+    kind: "label";
+    label: string;
+    isExact: boolean;
+} & LocatorScope);
+export type Target = {
+    kind: "ref";
+    ref: string;
+} | ElementLocator | {
+    kind: "point";
+    x: number;
+    y: number;
+};
+export declare function parseTarget(args: CommandArgs, { allowsPoint }: {
+    allowsPoint: boolean;
+}): Target;
+export declare function parseElementLocator(args: CommandArgs, hint: string): ElementLocator | undefined;
+export declare function elementLocator(page: Page, target: ElementLocator): Locator;
+export declare function describeTarget(target: Target): string;
+export declare function describeElementLocator(target: ElementLocator): string;
+export declare function clickPoint(page: Page, x: number, y: number): Promise<void>;
+export declare function typeLikeAPerson(page: Page, text: string): Promise<void>;

package/dist/targets.js

@@ -0,0 +1,229 @@
+import { CommandError } from "./protocol.js";
+// Roles Playwright's getByRole accepts, which are also the roles a snapshot line starts with.
+export const ariaRoles = [
+    "alert",
+    "alertdialog",
+    "application",
+    "article",
+    "banner",
+    "blockquote",
+    "button",
+    "caption",
+    "cell",
+    "checkbox",
+    "code",
+    "columnheader",
+    "combobox",
+    "complementary",
+    "contentinfo",
+    "definition",
+    "deletion",
+    "dialog",
+    "directory",
+    "document",
+    "emphasis",
+    "feed",
+    "figure",
+    "form",
+    "generic",
+    "grid",
+    "gridcell",
+    "group",
+    "heading",
+    "img",
+    "insertion",
+    "link",
+    "list",
+    "listbox",
+    "listitem",
+    "log",
+    "main",
+    "marquee",
+    "math",
+    "meter",
+    "menu",
+    "menubar",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "navigation",
+    "none",
+    "note",
+    "option",
+    "paragraph",
+    "presentation",
+    "progressbar",
+    "radio",
+    "radiogroup",
+    "region",
+    "row",
+    "rowgroup",
+    "rowheader",
+    "scrollbar",
+    "search",
+    "searchbox",
+    "separator",
+    "slider",
+    "spinbutton",
+    "status",
+    "strong",
+    "subscript",
+    "superscript",
+    "switch",
+    "tab",
+    "table",
+    "tablist",
+    "tabpanel",
+    "term",
+    "textbox",
+    "time",
+    "timer",
+    "toolbar",
+    "tooltip",
+    "tree",
+    "treegrid",
+    "treeitem",
+];
+export function isAriaRole(value) {
+    return ariaRoles.includes(value);
+}
+const targetHint = "pass a ref from the latest snapshot, --role <role> [--name <name>], --text <text>, --label <text>, --selector <css>, or --at <x>,<y>";
+const locatorKinds = ["selector", "role", "text", "label"];
+export function parseTarget(args, { allowsPoint }) {
+    const ref = typeof args.ref === "string" ? args.ref : undefined;
+    const at = typeof args.at === "string" ? args.at : undefined;
+    const locatorNames = locatorKinds.filter((name) => typeof args[name] === "string");
+    const given = [ref, at].filter((value) => value !== undefined).length + locatorNames.length;
+    if (given !== 1)
+        throw new CommandError("bad_args", given === 0 ? "no target given" : "give one target, not several", targetHint);
+    if (ref !== undefined || at !== undefined) {
+        const stray = ["frame", "nth", "name"].find((name) => args[name] !== undefined) ??
+            (args.exact === true ? "exact" : undefined);
+        if (stray !== undefined)
+            throw new CommandError("bad_args", `--${stray} goes with --role, --text, --label or --selector`, targetHint);
+    }
+    if (ref !== undefined)
+        return { kind: "ref", ref };
+    if (at === undefined)
+        return parseElementLocator(args, targetHint) ?? unreachable();
+    if (!allowsPoint)
+        throw new CommandError("bad_args", "--at works with click only", "click the field with --at first, then run `patchrome type <text>`");
+    const match = at.match(/^(\d+(?:\.\d+)?),(\d+(?:\.\d+)?)$/);
+    if (!match?.[1] || !match[2])
+        throw new CommandError("bad_args", `--at takes <x>,<y> in viewport pixels, got ${at}`, "for example --at 120,340");
+    return { kind: "point", x: Number(match[1]), y: Number(match[2]) };
+}
+// Reads one of --selector, --role, --text, --label with --name, --exact, --nth and --frame. Undefined when
+// none is given; wait also takes --url, --title and --load, so absence is not an error here.
+export function parseElementLocator(args, hint) {
+    const given = locatorKinds.filter((name) => typeof args[name] === "string");
+    const [kind] = given;
+    const name = typeof args.name === "string" ? args.name : undefined;
+    const isExact = args.exact === true;
+    const frame = typeof args.frame === "string" ? args.frame : undefined;
+    if (kind === undefined) {
+        const stray = frame !== undefined
+            ? "frame"
+            : name !== undefined
+                ? "name"
+                : args.nth !== undefined
+                    ? "nth"
+                    : isExact
+                        ? "exact"
+                        : undefined;
+        if (stray !== undefined)
+            throw new CommandError("bad_args", `--${stray} goes with --role, --text, --label or --selector`, hint);
+        return undefined;
+    }
+    if (given.length > 1)
+        throw new CommandError("bad_args", `give one of ${given.map((option) => `--${option}`).join(" ")}, not several`, hint);
+    const value = String(args[kind]);
+    if (value === "" || frame === "")
+        throw new CommandError("bad_args", `--${kind}${frame === "" ? " and --frame" : ""} need a non-empty value`, hint);
+    if (name !== undefined && kind !== "role")
+        throw new CommandError("bad_args", "--name goes with --role", "for example --role button --name 'Sign in'");
+    if (isExact && (kind === "selector" || (kind === "role" && name === undefined)))
+        throw new CommandError("bad_args", "--exact goes with --name, --text or --label", hint);
+    const scope = { frame, nth: parseNth(args.nth) };
+    switch (kind) {
+        case "selector":
+            return { kind, selector: value, ...scope };
+        case "role":
+            if (!isAriaRole(value))
+                throw new CommandError("bad_args", `--role ${value} is not an ARIA role`, `roles: ${ariaRoles.join(" ")}`);
+            return { kind, role: value, name, isExact, ...scope };
+        case "text":
+            return { kind, text: value, isExact, ...scope };
+        case "label":
+            return { kind, label: value, isExact, ...scope };
+    }
+}
+function parseNth(raw) {
+    if (raw === undefined)
+        return undefined;
+    const nth = Number(raw);
+    if (!Number.isInteger(nth) || nth < 0)
+        throw new CommandError("bad_args", `--nth must be a whole number from 0, got ${String(raw)}`);
+    return nth;
+}
+function unreachable() {
+    throw new CommandError("bad_args", "no target given", targetHint);
+}
+export function elementLocator(page, target) {
+    const root = target.frame === undefined ? page : page.frameLocator(target.frame);
+    const matches = (() => {
+        switch (target.kind) {
+            case "selector":
+                return root.locator(target.selector);
+            case "role":
+                return root.getByRole(target.role, target.name === undefined ? {} : { name: target.name, exact: target.isExact });
+            case "text":
+                return root.getByText(target.text, { exact: target.isExact });
+            case "label":
+                return root.getByLabel(target.label, { exact: target.isExact });
+        }
+    })();
+    return target.nth === undefined ? matches.first() : matches.nth(target.nth);
+}
+export function describeTarget(target) {
+    switch (target.kind) {
+        case "ref":
+            return target.ref;
+        case "point":
+            return `${target.x},${target.y}`;
+        case "selector":
+        case "role":
+        case "text":
+        case "label":
+            return describeElementLocator(target);
+    }
+}
+export function describeElementLocator(target) {
+    const what = (() => {
+        switch (target.kind) {
+            case "selector":
+                return target.selector;
+            case "role":
+                return target.name === undefined ? target.role : `${target.role} "${target.name}"`;
+            case "text":
+                return `text "${target.text}"`;
+            case "label":
+                return `label "${target.label}"`;
+        }
+    })();
+    return `${what}${target.nth === undefined ? "" : ` #${target.nth}`}${target.frame === undefined ? "" : ` in ${target.frame}`}`;
+}
+// A person's pointer travels to the spot, and their keys land tens of milliseconds apart.
+export async function clickPoint(page, x, y) {
+    await page.mouse.move(x, y, { steps: 12 });
+    await page.mouse.click(x, y, { delay: jitterMs(40, 110) });
+}
+export async function typeLikeAPerson(page, text) {
+    for (const character of text) {
+        await page.keyboard.type(character);
+        await new Promise((resolve) => setTimeout(resolve, jitterMs(45, 140)));
+    }
+}
+function jitterMs(minMs, maxMs) {
+    return Math.round(minMs + Math.random() * (maxMs - minMs));
+}

package/dist/validate.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+export declare function parseJsonInput<T extends z.ZodType>(schema: T, raw: string, what: string, hint?: string): z.infer<T>;
+export declare function parseInput<T extends z.ZodType>(schema: T, value: unknown, what: string, hint?: string): z.infer<T>;

package/dist/validate.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { CommandError } from "./protocol.js";
+// Parses JSON input against a schema. The first problem becomes a bad_args error that names the input and
+// the path inside it, such as `extract schema: fields.a has unknown keys selecter`.
+export function parseJsonInput(schema, raw, what, hint) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new CommandError("bad_args", `${what} is not JSON: ${err instanceof Error ? err.message : String(err)}`, hint);
+    }
+    return parseInput(schema, parsed, what, hint);
+}
+export function parseInput(schema, value, what, hint) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return result.data;
+    throw new CommandError("bad_args", `${what}: ${describeIssue(result.error.issues[0])}`, hint);
+}
+function describeIssue(issue) {
+    if (issue === undefined)
+        return "is invalid";
+    const where = issue.path.length === 0 ? "" : `${issue.path.join(".")} `;
+    switch (issue.code) {
+        case "unrecognized_keys":
+            return `${where}has unknown keys ${issue.keys.join(", ")}`;
+        default:
+            return `${where}${issue.message}`;
+    }
+}