patchrome 0.1.0

package/dist/wait.d.ts

@@ -0,0 +1,24 @@
+import type { Page } from "patchright";
+import { type CommandArgs } from "./protocol.ts";
+import { type ElementLocator } from "./targets.ts";
+export declare const loadStates: readonly ["load", "domcontentloaded", "networkidle"];
+export type LoadState = (typeof loadStates)[number];
+export type WaitCondition = {
+    kind: "element";
+    locator: ElementLocator;
+    isGone: boolean;
+} | {
+    kind: "url";
+    glob: string;
+    isGone: boolean;
+} | {
+    kind: "title";
+    text: string;
+    isGone: boolean;
+} | {
+    kind: "load";
+    state: LoadState;
+};
+export declare function parseWaitCondition(args: CommandArgs): WaitCondition;
+export declare function describeWaitCondition(condition: WaitCondition): string;
+export declare function waitForCondition(page: Page, condition: WaitCondition, timeoutMs: number): Promise<void>;

package/dist/wait.js

@@ -0,0 +1,88 @@
+import { urlGlobMatches } from "./glob.js";
+import { CommandError } from "./protocol.js";
+import { describeElementLocator, elementLocator, parseElementLocator } from "./targets.js";
+export const loadStates = ["load", "domcontentloaded", "networkidle"];
+const titlePollMs = 250;
+const waitHint = "wait --selector <css> | --role <role> [--name <name>] | --text <text> | --label <text> | --url <glob> | --title <text> [--gone], or wait --load load|domcontentloaded|networkidle";
+export function parseWaitCondition(args) {
+    const isGone = args.gone === true;
+    const pageConditions = ["url", "title", "load"].filter((name) => typeof args[name] === "string");
+    const elementConditions = ["selector", "role", "text", "label"].filter((name) => typeof args[name] === "string");
+    const given = [...elementConditions, ...pageConditions];
+    if (given.length !== 1) {
+        throw new CommandError("bad_args", given.length === 0
+            ? "wait needs a condition"
+            : `wait takes one condition, got ${given.map((option) => `--${option}`).join(" ")}`, waitHint);
+    }
+    const locator = parseElementLocator(args, waitHint);
+    if (locator !== undefined)
+        return { kind: "element", locator, isGone };
+    const [name] = pageConditions;
+    if (name === undefined)
+        throw new CommandError("bad_args", "wait needs a condition", waitHint);
+    const value = String(args[name]);
+    if (value === "")
+        throw new CommandError("bad_args", `wait --${name} needs a non-empty value`);
+    switch (name) {
+        case "url":
+            return { kind: "url", glob: value, isGone };
+        case "title":
+            return { kind: "title", text: value, isGone };
+        case "load":
+            if (isGone)
+                throw new CommandError("bad_args", "wait --load does not take --gone");
+            if (!loadStates.includes(value))
+                throw new CommandError("bad_args", `wait --load must be one of ${loadStates.join(", ")}, got ${value}`);
+            return { kind: "load", state: value };
+    }
+}
+export function describeWaitCondition(condition) {
+    switch (condition.kind) {
+        case "element":
+            return `${condition.isGone ? "no visible" : "a visible"} ${describeElementLocator(condition.locator)}`;
+        case "url":
+            return `url ${condition.isGone ? "leaving" : "matching"} ${condition.glob}`;
+        case "title":
+            return `title ${condition.isGone ? "without" : "with"} "${condition.text}"`;
+        case "load":
+            return `load state ${condition.state}`;
+    }
+}
+// Element and URL conditions use Patchright's own waits, which query from an isolated world: a probe page that
+// wrapped querySelector, getClientRects and requestAnimationFrame saw no calls from them. waitForFunction
+// does run in the page's realm (the probe saw its requestAnimationFrame polling), so the title is polled
+// from here instead. Throws Playwright's TimeoutError when the time runs out.
+export async function waitForCondition(page, condition, timeoutMs) {
+    switch (condition.kind) {
+        case "load":
+            return page.waitForLoadState(condition.state, { timeout: timeoutMs });
+        case "element": {
+            const locator = elementLocator(page, condition.locator);
+            // On a macOS CI runner waitFor took over a second to report an element that was already visible.
+            // One direct read answers that case at once; a bad locator falls through so waitFor reports it.
+            const isVisible = await locator.isVisible().catch(() => undefined);
+            if (isVisible !== undefined && isVisible !== condition.isGone)
+                return;
+            return locator.waitFor({
+                state: condition.isGone ? "hidden" : "visible",
+                timeout: timeoutMs,
+            });
+        }
+        case "url":
+            await page.waitForURL((url) => urlGlobMatches(condition.glob, url.href) !== condition.isGone, {
+                timeout: timeoutMs,
+                waitUntil: "commit",
+            });
+            return;
+        case "title": {
+            const deadlineMs = Date.now() + timeoutMs;
+            // A read that lands mid-navigation throws; it counts as not yet.
+            while ((await page.title().then((title) => title.includes(condition.text), () => condition.isGone)) === condition.isGone) {
+                if (Date.now() >= deadlineMs)
+                    throw new CommandError("timeout", `no ${describeWaitCondition(condition)} within ${timeoutMs} ms`);
+                await new Promise((resolve) => setTimeout(resolve, titlePollMs));
+            }
+            return;
+        }
+    }
+}

package/examples/go/go.mod

@@ -0,0 +1,3 @@
+module patchrome.example/hn
+
+go 1.22

package/examples/go/main.go

@@ -0,0 +1,104 @@
+// Top stories on Hacker News from Go, over one `patchrome pipe`. Run with `go run .`.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"os/exec"
+)
+
+type response struct {
+	ID     int             `json:"id"`
+	OK     bool            `json:"ok"`
+	Data   json.RawMessage `json:"data"`
+	Stream json.RawMessage `json:"stream"`
+	Error  *struct {
+		Code    string `json:"code"`
+		Message string `json:"message"`
+	} `json:"error"`
+}
+
+type patchrome struct {
+	stdin  io.WriteCloser
+	stdout *bufio.Scanner
+	nextID int
+	cmd    *exec.Cmd
+}
+
+func start(session string) (*patchrome, error) {
+	cmd := exec.Command("patchrome", "pipe")
+	cmd.Env = append(os.Environ(), "PATCHROME_SESSION="+session)
+	cmd.Stderr = os.Stderr
+	stdin, err := cmd.StdinPipe()
+	if err != nil {
+		return nil, err
+	}
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return nil, err
+	}
+	scanner := bufio.NewScanner(stdout)
+	scanner.Buffer(make([]byte, 1<<20), 64<<20)
+	return &patchrome{stdin: stdin, stdout: scanner, cmd: cmd}, cmd.Start()
+}
+
+// run sends the words you would type after `patchrome` and decodes the response's data into out.
+func (p *patchrome) run(out any, words ...string) error {
+	p.nextID++
+	request, _ := json.Marshal(map[string]any{"id": p.nextID, "argv": words})
+	if _, err := fmt.Fprintf(p.stdin, "%s\n", request); err != nil {
+		return err
+	}
+	for p.stdout.Scan() {
+		var message response
+		if err := json.Unmarshal(p.stdout.Bytes(), &message); err != nil {
+			return err
+		}
+		if message.ID != p.nextID || message.Stream != nil {
+			continue
+		}
+		if !message.OK {
+			return fmt.Errorf("patchrome %s: %s", message.Error.Code, message.Error.Message)
+		}
+		if out == nil {
+			return nil
+		}
+		return json.Unmarshal(message.Data, out)
+	}
+	return fmt.Errorf("patchrome pipe exited: %v", p.stdout.Err())
+}
+
+func (p *patchrome) close() {
+	_ = p.run(nil, "session", "close")
+	_ = p.stdin.Close()
+	_ = p.cmd.Wait()
+}
+
+func main() {
+	browser, err := start(fmt.Sprintf("hn-go-%d", os.Getpid()))
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer browser.close()
+
+	if err := browser.run(nil, "open", "https://news.ycombinator.com/"); err != nil {
+		log.Fatal(err)
+	}
+	schema := `{"rows": "tr.athing", "fields": {"rank": ".rank", "title": ".titleline > a"}, "limit": 10}`
+	var extracted struct {
+		Rows []struct {
+			Rank  string `json:"rank"`
+			Title string `json:"title"`
+		} `json:"rows"`
+	}
+	if err := browser.run(&extracted, "extract", schema, "--inline"); err != nil {
+		log.Fatal(err)
+	}
+	for _, story := range extracted.Rows {
+		fmt.Println(story.Rank, story.Title)
+	}
+}

package/examples/hn-front-page.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# Top stories on Hacker News as JSON rows, one patchrome command per step.
+# Needs patchrome on PATH and jq for reading --json output.
+set -eu
+export PATCHROME_SESSION="${PATCHROME_SESSION:-hn-sh-$$}"
+trap 'patchrome session close >/dev/null' EXIT
+
+patchrome open https://news.ycombinator.com/ >/dev/null
+patchrome wait --selector 'tr.athing' >/dev/null
+patchrome --json extract '{
+  "rows": "tr.athing",
+  "fields": {
+    "rank": ".rank",
+    "title": ".titleline > a",
+    "url": {"selector": ".titleline > a", "attr": "href"}
+  },
+  "limit": 10
+}' --inline | jq -c '.data.rows[]'

package/examples/hn-front-page.ts

@@ -0,0 +1,24 @@
+// Top stories on Hacker News with the Node library. Run with `node hn-front-page.ts` after
+// `npm i patchrome` in your project, or from a checkout after `npm run build`.
+import { CommandError, connect } from "patchrome";
+
+const browser = connect({ session: `hn-ts-${process.pid}` });
+try {
+  await browser.run("open", "https://news.ycombinator.com/");
+  const { rows } = (await browser.run(
+    "extract",
+    JSON.stringify({
+      rows: "tr.athing",
+      fields: { rank: ".rank", title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } },
+      limit: 10,
+    }),
+    "--inline",
+  )) as { rows: Array<{ rank: string; title: string; url: string }> };
+  for (const story of rows) console.log(story.rank, story.title, story.url);
+} catch (err) {
+  if (err instanceof CommandError) console.error(`patchrome ${err.code}: ${err.message}`);
+  throw err;
+} finally {
+  await browser.run("session", "close");
+  browser.close();
+}

package/examples/hn_front_page.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Two pages of Hacker News stories, over one `patchrome pipe`."""
+
+import itertools
+import json
+import os
+import subprocess
+
+
+class PatchromeError(Exception):
+    def __init__(self, error):
+        super().__init__(f"{error['code']}: {error['message']}")
+        self.code = error["code"]
+        self.hint = error.get("hint")
+
+
+class Patchrome:
+    """Sends CLI words to `patchrome pipe` and returns the `data` of each response."""
+
+    def __init__(self, session):
+        env = {**os.environ, "PATCHROME_SESSION": session}
+        self._process = subprocess.Popen(["patchrome", "pipe"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True, env=env)
+        self._ids = itertools.count(1)
+
+    def run(self, *words):
+        request_id = next(self._ids)
+        self._process.stdin.write(json.dumps({"id": request_id, "argv": list(words)}) + "\n")
+        self._process.stdin.flush()
+        for line in self._process.stdout:
+            message = json.loads(line)
+            # Stream events from `watch` carry the same id and come before the response.
+            if message["id"] != request_id or "stream" in message:
+                continue
+            if not message["ok"]:
+                raise PatchromeError(message["error"])
+            return message["data"]
+        raise PatchromeError({"code": "daemon_unreachable", "message": "patchrome pipe exited"})
+
+    def close(self):
+        self.run("session", "close")
+        self._process.stdin.close()
+        self._process.wait()
+
+
+browser = Patchrome(session=f"hn-py-{os.getpid()}")
+try:
+    browser.run("open", "https://news.ycombinator.com/")
+    schema = json.dumps({"rows": "tr.athing", "fields": {"rank": ".rank", "title": ".titleline > a"}})
+    for page in (1, 2):
+        if page > 1:
+            browser.run("click", "--role", "link", "--name", "More", "--exact")
+            browser.run("wait", "--url", f"*?p={page}")
+        for story in browser.run("extract", schema, "--inline")["rows"]:
+            print(story["rank"], story["title"])
+finally:
+    browser.close()

package/extension/tab-groups/manifest.json

@@ -0,0 +1,8 @@
+{
+  "manifest_version": 3,
+  "name": "patchrome tab groups",
+  "description": "Groups each patchrome session's tabs under the session name.",
+  "version": "0.1.0",
+  "permissions": ["tabs", "tabGroups", "debugger"],
+  "background": { "service_worker": "service-worker.js" }
+}

package/extension/tab-groups/service-worker.js

@@ -0,0 +1,41 @@
+// The daemon calls these through its service worker handle. The extension injects nothing into pages.
+// chrome.debugger.getTargets only lists targets, it attaches to none, so Chrome shows no debugging bar.
+
+async function tabsOfTargets(targetIds) {
+  const tabIdByTarget = new Map((await chrome.debugger.getTargets()).map((target) => [target.id, target.tabId]));
+  const tabIds = targetIds.map((targetId) => tabIdByTarget.get(targetId)).filter((tabId) => tabId !== undefined);
+  return Promise.all(tabIds.map((tabId) => chrome.tabs.get(tabId)));
+}
+
+// A group cannot span windows, and isolated sessions open in their own window, so each window gets a group.
+// A tab already in a group keeps that group, so a new tab joins its session's group instead of starting one.
+globalThis.patchromeGroupTabs = async ({ targetIds, title, color }) => {
+  const tabsByWindow = new Map();
+  for (const tab of await tabsOfTargets(targetIds))
+    tabsByWindow.set(tab.windowId, [...(tabsByWindow.get(tab.windowId) ?? []), tab]);
+  for (const tabs of tabsByWindow.values()) {
+    const existingGroupId = tabs.find((tab) => tab.groupId !== chrome.tabGroups.TAB_GROUP_ID_NONE)?.groupId;
+    const groupId = await chrome.tabs.group({
+      tabIds: tabs.map((tab) => tab.id),
+      ...(existingGroupId === undefined ? {} : { groupId: existingGroupId }),
+    });
+    await chrome.tabGroups.update(groupId, { title, color });
+  }
+};
+
+globalThis.patchromeDescribeTabGroups = async ({ targetIds }) => {
+  const tabCountByGroup = new Map();
+  for (const tab of await tabsOfTargets(targetIds)) {
+    if (tab.groupId === chrome.tabGroups.TAB_GROUP_ID_NONE) continue;
+    tabCountByGroup.set(tab.groupId, (tabCountByGroup.get(tab.groupId) ?? 0) + 1);
+  }
+  return Promise.all(
+    [...tabCountByGroup].map(async ([groupId, tabCount]) => {
+      const group = await chrome.tabGroups.get(groupId);
+      return { title: group.title ?? "", color: group.color, tabCount };
+    }),
+  );
+};
+
+// Tab events wake the worker if Chrome ever suspends it.
+chrome.tabs.onCreated.addListener(() => {});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "patchrome",
+  "version": "0.1.0",
+  "description": "Stealth shared-browser CLI for coding agents: one Patchright Chrome, a tab set per agent session",
+  "homepage": "https://github.com/akaike-byob/patchrome#readme",
+  "bugs": {
+    "url": "https://github.com/akaike-byob/patchrome/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akaike-byob/patchrome.git"
+  },
+  "bin": {
+    "patchrome": "bin/patchrome.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "extension",
+    "skills",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "lint": "oxlint --type-aware --deny-warnings",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check"
+  },
+  "dependencies": {
+    "patchright": "^1.63.0",
+    "zod": "^4.6.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=24.2"
+  }
+}

package/skills/patchrome/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: patchrome
+description: Drives a real, stealth, headed Google Chrome from the shell through the `patchrome` CLI - opens tabs, reads pages as accessibility snapshots with @refs, clicks, fills, extracts text and rows, reads network responses, signs in once and reuses the login, and exports a working flow as a script. Many agent sessions share one Chrome and one logged-in profile, each on its own tabs. Use whenever a task needs a real browser - a page behind a bot wall or login, JS-rendered content that curl cannot see, scraping, clicking through a web app, a repeatable scrape script, or checking what a site shows.
+allowed-tools: Bash(patchrome:*)
+---
+
+# Browser from the CLI (`patchrome`)
+
+One daemon owns one headed Chrome per profile. Every `patchrome` call is a short client; the first
+starts Chrome. Other agent sessions browse the same Chrome at once, and you see only your own tabs.
+If `patchrome` is not on PATH: `npm i -g patchrome`.
+
+## The loop
+
+```bash
+patchrome session label "compare laptop prices"   # first: the user sees it on your Chrome tab group
+patchrome open https://example.com                # new background tab, becomes your current tab
+patchrome snapshot                                # accessibility tree to a file; prints its path
+# grep the file for the node: - button "Sign in" [ref=f1e6]
+patchrome fill @f1e5 "alice@example.com"
+patchrome click @f1e6
+patchrome wait --url '*/dashboard*'               # click returns before the next page loads
+patchrome snapshot                                # refs from before a navigation are stale
+```
+
+Copy refs exactly from the latest snapshot, from a line that has `[ref=...]`. A locator works anywhere
+a ref does and survives page changes: `--role button --name "Sign in"` (role and name as on the
+snapshot line), `--text <text>`, `--label <form label>` or `--selector <css>`, with `--exact`,
+`--nth <n>` and `--frame <iframe-css>`.
+
+## Read the reference for the task
+
+| Task | Read |
+|---|---|
+| Any flag or command not shown here | [references/commands.md](references/commands.md) |
+| Scraping: JSON API responses, `extract` rows, globs, HAR, blocking or mocking requests | [references/scraping.md](references/scraping.md) |
+| A repeatable script, `session history`, `pipe`, the Node library, sh/Python/Go callers | [references/scripting.md](references/scripting.md) |
+| A site needs sign-in: `login`, `state import`, `state save`/`load`, a separate account | [references/logins.md](references/logins.md) |
+| iframes, closed shadow roots, canvas, CAPTCHAs, bot-wall interstitials | [references/hard-pages.md](references/hard-pages.md) |
+| Debugging your own localhost app: console, page errors, traces, CDP | [references/debugging.md](references/debugging.md) |
+
+## Rules
+
+- Never close, switch to or act on tabs you did not open. `tabs --all` is for looking only.
+- Read snapshot and text files with your file tools and grep them; never `cat` a large one whole.
+- Wait for a condition (`wait --url`, `wait --text`, `wait --selector`), never `sleep`. Quote globs:
+  zsh expands `*` and `?` itself.
+- A bot wall's interstitial ("Just a moment") often clears by itself. Only a
+  `wait --title "<interstitial title>" --gone` that times out means blocked.
+- Never solve a CAPTCHA yourself. When `challenge` reports `pending`, tell the user and run
+  `challenge --handoff`.
+- Logins are shared by every session in the profile: never log out of a site another agent may use.
+- Never run `daemon stop` or `session close <other session>` unless the user asks; both end other
+  agents' work.
+- Keep request volume low on protected sites: no tight loops of `goto`.
+- Session name comes from `--session`, `$PATCHROME_SESSION`, `$CLAUDE_CODE_SESSION_ID`, the tty, then
+  the parent process. If `patchrome session` prints a new name on each call, export
+  `PATCHROME_SESSION` for the whole task.
+
+## Errors
+
+Exit code 0 ok, 1 command error, 2 bad usage. `--json` errors carry a `code`:
+
+| Code | Do |
+|---|---|
+| `tab_gone` | current tab closed or none yet: `patchrome open <url>`; never grab another session's tab |
+| `ref_stale` | page changed since the snapshot: `patchrome snapshot`, pick the ref again, or use a locator |
+| `timeout` | snapshot to see the page state; raise `--timeout-ms` if the site is slow |
+| `navigation_failed` | DNS, TLS or connection failure: check the URL, retry once |
+| `daemon_unreachable` | `patchrome daemon logs`; the next command restarts the daemon |
+| `daemon_outdated` | tell the user; `daemon stop` closes Chrome for every session |
+| `bad_args` | wrong usage, a JS error in `eval`, a bad schema or selector: read the message and hint |
+| `unsupported_in_stealth` | the command needs `--profile debug`, which is only for your own apps |
+| `copy_denied` | the user refused a login copy: tell them, do not retry, never copy cookies another way |

package/skills/patchrome/references/commands.md

@@ -0,0 +1,130 @@
+# Command reference
+
+## Contents
+- Global flags and output
+- Elements: refs and locators
+- Tabs and navigation
+- Reading the page
+- Acting
+- Waiting and watching
+- Network
+- Logins and state
+- Scripting
+- Debug profile
+- Sessions, profiles and the daemon
+
+## Global flags and output
+
+Global flags go before the command: `--json` (one object, `{ok, data}` or `{ok: false, error}`),
+`--timeout-ms <n>` (default 30000; `login`, `watch`, `challenge --handoff` and `console --follow`
+default to 10 min), `--session <name>`, `--profile <name>` (default `stealth`).
+
+Plain output is a few lines. A value over 2 KB goes to a file in the session folder and stdout carries
+the path. `--inline` always prints the value; `--out <file>` always writes that file.
+
+## Elements: refs and locators
+
+`<element>` is one of:
+
+- `@e12` or `@f1e12`, a ref from the latest snapshot (`--ref <ref>` on commands that read one)
+- `--role <role> [--name <name>]`, the role and accessible name on a snapshot line
+- `--text <text>`, visible text, case-insensitive substring
+- `--label <text>`, a form field's label
+- `--selector <css>`, which also pierces closed shadow roots
+
+Modifiers: `--exact` matches the whole name or text, `--nth <n>` picks match n from 0 instead of the
+first, `--frame <iframe-css>` looks inside that iframe.
+
+## Tabs and navigation
+
+| Command | Does |
+|---|---|
+| `open [url] [--wait load\|domcontentloaded\|networkidle] [--isolated]` | new background tab, becomes current; `--isolated` on your first tab gives your session its own cookies |
+| `goto <url> [--wait ...]` | navigate the current tab |
+| `tabs [--all]` | your tabs, `*` marks current; `--all` lists every session's, read-only |
+| `switch <tab>`, `close [tab]` | tab ids look like `t3`; only your own tabs |
+
+## Reading the page
+
+| Command | Does |
+|---|---|
+| `snapshot [--inline \| --out <file>]` | accessibility tree with refs, iframes included; `--inline` only for small pages |
+| `text [<element>] [--inline \| --out <file>]` | visible text of the page or one element |
+| `screenshot [--full] [<element>] [--out <file>]` | PNG to a file |
+| `eval <js> [--main-world] [--inline \| --out <file>]` | JS expression, prints JSON; `--json` puts it under `value` |
+| `extract <schema> [<element>] [--inline \| --out <file>]` | CSS selectors to JSON rows: `{"rows": "li.item", "fields": {"name": "h2", "url": {"selector": "a", "attr": "href"}}}` |
+
+`eval` runs in an isolated world: the DOM works, page globals (`window.myApp`) read as undefined.
+`--main-world` sees them but runs inside the page's own realm, which a protected site can notice.
+
+## Acting
+
+| Command | Does |
+|---|---|
+| `click <ref> \| <element>` | click |
+| `click --at <x>,<y>` | trusted click at viewport pixels read off a screenshot |
+| `fill <ref> \| <element> <text>` | replace a field's value |
+| `type <text>` | trusted keystrokes into whatever has focus; click the field first |
+| `press <key>` | Playwright key names: `Enter`, `Tab`, `Control+a` |
+| `challenge [--handoff]` | CAPTCHA state (`none`, `pending`, `solved`); `--handoff` raises the tab for the user |
+
+## Waiting and watching
+
+| Command | Does |
+|---|---|
+| `wait <element> \| --url <glob> \| --title <text> [--gone]` | block until the page shows it, or with `--gone` stops showing it; a condition already true returns at once |
+| `wait --load load\|domcontentloaded\|networkidle` | block until the tab reaches a load state |
+| `watch [--events navigation,load,response,console,error] [--url <glob>] [--count <n>]` | stream your tabs' events, one line each; `console` and `error` need a debug profile |
+
+## Network
+
+| Command | Does |
+|---|---|
+| `network list [--url <glob>] [--type xhr,fetch] [--status 4xx] [--inline \| --out <file>]` | your requests, newest last, ids like `n17`; last 1000 kept |
+| `network get <id> \| --url <glob> [--body] [--inline \| --out <file>]` | headers, post data, and with `--body` the response body; `--url` takes the newest match |
+| `network har start\|stop [--out <file>]` | record your requests; `stop` writes a HAR with text bodies |
+| `route block <glob>`, `route mock <glob> <file>` | abort, or answer from a file, matching requests on your tabs |
+| `route list\|clear` | your rules; the newest matching rule wins |
+
+## Logins and state
+
+| Command | Does |
+|---|---|
+| `login <url> [--until <url-glob>]` | a visible tab for a person to sign in |
+| `cookies [--domain <domain>] [--inline \| --out <file>]` | cookies with values |
+| `state save <file>`, `state load <file>` | cookies and localStorage, Playwright storageState format |
+| `state import <site> [--from <chrome-profile>]` | one site's login from the user's everyday Chrome |
+| `audit [--count <n>]` | recent login copies and who approved them |
+
+## Scripting
+
+| Command | Does |
+|---|---|
+| `session history [--format sh\|jsonl] [--out <file>]` | your session's working commands, refs rewritten as locators |
+| `session history clear` | empty the recording |
+| `pipe [--bail]` | JSON requests on stdin, one JSON response per line |
+
+## Debug profile
+
+| Command | Does |
+|---|---|
+| `console [--level debug\|info\|warning\|error] [--follow]` | your tabs' console, that level and above |
+| `errors` | uncaught page errors with stacks |
+| `trace start\|stop [--out <file>]` | Playwright trace zip of every tab in the profile; one session at a time |
+| `cdp <Domain.method> [params-json]` | raw CDP on your current tab |
+| `cdp help [Domain\|Domain.method]` | the CDP domains, commands and params this Chrome implements |
+| `devtools-url` | debugging URL for chrome-devtools, Lighthouse or heap snapshots |
+
+## Sessions, profiles and the daemon
+
+| Command | Does |
+|---|---|
+| `session`, `session close` | your session name, label and tabs; close all your tabs |
+| `session label <text>` | what you are doing, shown on your Chrome tab group |
+| `sessions [pattern]`, `session close <session\|pattern>` | list sessions; close others by name or glob (`'work-*'`), only when the user asks |
+| `profile create <name> --mode stealth\|debug` | a profile's mode is fixed once made |
+| `daemon status\|stop\|logs` | `stop` closes Chrome for every session |
+| `completions zsh` | zsh completion script, for people |
+
+If the daemon restarts, your tabs come back on your next command under the same ids, reloaded at
+their last URL. Typed input and refs are gone: take a fresh snapshot.

package/skills/patchrome/references/debugging.md

@@ -0,0 +1,20 @@
+# Debugging your own app
+
+For localhost apps you are building, use the debug profile: a separate Chrome with console capture,
+page errors, tracing, raw CDP and a `127.0.0.1` debugging port. Never use it for third-party sites:
+all of that is detectable. Stealth profiles refuse these commands with `unsupported_in_stealth`.
+
+```bash
+patchrome --profile debug open http://localhost:3000
+patchrome --profile debug console --level warning   # c4 t1 error Failed to load user (http://localhost:3000/app.js:88)
+patchrome --profile debug console --follow          # streams until --timeout-ms (default 10 min)
+patchrome --profile debug errors                    # uncaught exceptions with stacks
+patchrome --profile debug trace start               # covers every tab in the profile; one session at a time
+patchrome --profile debug trace stop                # prints the zip; npx playwright show-trace <file>
+patchrome --profile debug cdp Performance.getMetrics
+patchrome --profile debug cdp help Network          # what this Chrome implements
+patchrome --profile debug devtools-url              # for chrome-devtools-mcp --browserUrl <url>, Lighthouse, heap snapshots
+```
+
+`watch --events console,error` streams the same events alongside navigation and responses.
+`profile create <name> --mode debug` makes another debug profile; `debug` is one by default.