patchrome 0.1.0

package/skills/patchrome/references/hard-pages.md

@@ -0,0 +1,49 @@
+# Hard pages: iframes, shadow roots, CAPTCHAs, bot walls
+
+## iframes
+
+Snapshots include iframes, cross-site ones too; their refs carry a different frame prefix, like
+`@f2e4`. Locators need the frame: `click --role checkbox --name Verify --frame 'iframe[title*=widget]'`.
+
+## Closed shadow roots
+
+A widget inside a closed shadow root shows up empty in the snapshot. CSS selectors pierce it:
+
+```bash
+patchrome click --selector '#cb' --frame 'iframe[src*="challenges"]'
+patchrome fill --selector 'input#code' --frame 'iframe' 123456
+```
+
+## Canvas and anything without an element
+
+Take a screenshot, read the pixel position, then:
+
+```bash
+patchrome click --at 120,340     # trusted click at viewport pixels, into whatever iframe is under it
+patchrome type "hello"           # trusted keystrokes into the focused element
+```
+
+## CAPTCHAs
+
+Never solve one yourself: not by clicking its checkbox, reading its images or typing its characters.
+
+```bash
+patchrome challenge              # none | pending | solved, with vendor and box
+patchrome challenge --handoff    # raises the tab for the user, waits up to 10 min
+```
+
+When `challenge` reports `pending`, tell the user, run `challenge --handoff`, and carry on once it
+prints `solved` or `none`.
+
+## Bot-wall interstitials
+
+"Just a moment", "Prove your humanity" and similar pages often clear by themselves within seconds. One
+early read reports a block that is not there:
+
+```bash
+patchrome open https://www.reddit.com/r/programming/
+patchrome wait --title "Prove your humanity" --gone --timeout-ms 20000
+patchrome snapshot
+```
+
+Only a wait that times out means blocked. Then run `challenge`, and hand off if it reports `pending`.

package/skills/patchrome/references/logins.md

@@ -0,0 +1,46 @@
+# Logins and state
+
+Cookies and logins are shared by every session in a profile: sign in once and every agent is signed
+in. Never log out of a site another agent may be using.
+
+## Pick the way in
+
+1. The user says they are signed in to the site in their everyday Chrome: `state import <site>`.
+2. Otherwise, a person signs in: `login <url> --until <url-glob>`.
+3. A saved state file from earlier: `state load <file>`.
+4. A different account, or a clean cookie jar: `open --isolated` as your session's first tab.
+
+## `state import`
+
+```bash
+patchrome state import github.com --from "Profile 1"
+```
+
+`--from` takes the name in Chrome's profile menu, the folder (`Default`, `Profile 1`) or the signed-in
+email; without it, the last used profile. Ask which profile when the user has several; a wrong
+`--from` lists them. The site covers its subdomains. Google accounts use device-bound sessions and
+may refuse an imported login; use `login` for those.
+
+## `login`
+
+A visible tab for a person. Tell the user a Chrome window is waiting, and pass `--until` with a URL
+the site reaches after sign-in. Without `--until` it returns when the user closes the tab. It waits
+up to 10 minutes.
+
+## Approvals
+
+`state import` and `state load` wait up to a minute for the user to approve with Touch ID (Windows
+Hello on WSL). Tell the user a prompt is coming before you run one. `copy_denied` means they refused:
+do not retry, and never copy cookies or profile files another way. `audit` lists past copies.
+
+## `state save` and `state load`
+
+`state save <file>` writes cookies and localStorage for the sites your session visited, in
+Playwright's storageState format. The file holds live session tokens: keep it out of git.
+`state load <file>` adds to the shared profile without clearing it, so every session sees the cookies.
+
+## Isolated sessions
+
+`open --isolated` on your session's first tab gives it an in-memory cookie jar. Its cookies vanish
+when the session closes or the daemon restarts, and its tabs are not grouped in Chrome. `state load`
+and `state import` in an isolated session fill only its own jar.

package/skills/patchrome/references/scraping.md

@@ -0,0 +1,51 @@
+# Scraping
+
+## Read the API response first
+
+Most shops and apps render from JSON. The response the page already fetched beats parsing HTML:
+
+```bash
+patchrome open https://shop.example/product/42 --wait networkidle
+patchrome network list --type xhr,fetch        # n17 t2 200 fetch GET https://shop.example/api/product/42 88ms
+patchrome network get n17 --body               # JSON inline, or a file path past 2 KB
+patchrome network get --url '*/api/product/*' --body --inline   # by URL: the newest match
+```
+
+A response body lives only as long as its page. Read it before navigating away, or `tab_gone` follows.
+
+## Rows from HTML
+
+```bash
+patchrome extract '{"rows": "li.product", "fields": {"name": "h2", "url": {"selector": "a", "attr": "href"}, "tags": {"selector": ".tag", "all": true}}, "limit": 50}'
+```
+
+- A field is a selector string (its visible text), or `{selector, attr, all}`.
+- No `selector` means the row itself. `href` and `src` come back absolute. A missing element is `null`.
+- Pass a file path instead of inline JSON for long schemas.
+- `--role`, `--selector` or `--ref` limits rows to inside one element.
+
+## Globs
+
+Globs match the whole URL: `*` is any run of characters, `?` one character. `*/api/items` does not
+match `/api/items?page=2`; write `*/api/items*`. Quote them in the shell.
+
+## Recording and shaping traffic
+
+```bash
+patchrome network har start
+# ... browse ...
+patchrome network har stop --out traffic.har     # your session's requests, with text bodies
+patchrome route block '*/analytics/*'
+patchrome route mock '*/api/flags*' flags.json
+patchrome route clear
+```
+
+Routes intercept every request on your tabs while any rule exists, which turns off the cache. Clear
+them when done.
+
+## Pages that change after load
+
+- `click` returns once the click lands; `wait --url` or `wait --text` for the next page before reading.
+- Paginate with a locator: `click --role link --name Next --exact`, then `wait --url '*page=2*'`.
+- Keep volume low on protected sites: one page at a time, no tight `goto` loops.
+- For a scrape the user will rerun, pass `--inline` or `--out <file>` so output keeps one shape.

package/skills/patchrome/references/scripting.md

@@ -0,0 +1,79 @@
+# Scripting a flow
+
+## Contents
+- Export what worked
+- Output that keeps its shape
+- `patchrome pipe`
+- The Node library
+- Sessions in scripts
+
+## Export what worked
+
+Explore with refs, then export the successful commands as a script. The daemon rewrites each ref as
+the role and name from the snapshot it came from.
+
+```bash
+patchrome session history clear                     # before exploring
+# ... open, snapshot, fill @e5, click @e6, extract ...
+patchrome session history --out scrape.sh           # runnable sh
+patchrome session history --format jsonl --out scrape.jsonl
+sh scrape.sh                                        # or: patchrome pipe --bail < scrape.jsonl
+```
+
+History leaves out snapshots, tabs, session commands and failed commands. Read every `# check:` line
+before handing the script over:
+
+- a repeated role and name got `--nth` from its position on the recorded page
+- a ref inside an iframe needs `--frame <iframe-css>`
+- text typed into a password field became `$PATCHROME_SECRET` (sh) or `<secret>` (jsonl)
+- tab ids and `login`, `challenge --handoff`, `state import` steps need a person or may differ
+
+Run the export once in a fresh session (`PATCHROME_SESSION=try-1 sh scrape.sh`) before calling it done.
+
+## Output that keeps its shape
+
+Without flags, `text`, `eval`, `extract`, `cookies`, `network list` and `network get --body` print a
+value up to 2 KB and a path past that. Scripts pass `--inline` (always the value) or `--out <file>`
+(always the file). With `--json`, values keep their JSON type: `eval` answers `{"value": ...}`,
+`extract` answers `{"count", "rows": [...]}`. Use `network get --url <glob>`, not request ids.
+
+## `patchrome pipe`
+
+One request per line on stdin: the words after `patchrome` as a JSON array, or
+`{"id": ..., "argv": [...]}`. One response per line on stdout: the `--json` object plus `id` (the line
+number when none was given).
+
+```bash
+printf '%s\n' '["open", "https://news.ycombinator.com"]' \
+  '{"id": "top", "argv": ["extract", "{\"rows\": \"tr.athing\", \"fields\": {\"title\": \".titleline > a\"}}", "--inline"]}' \
+  | patchrome pipe
+# {"id":1,"ok":true,"data":{"tab":"t1","url":"https://news.ycombinator.com/","title":"Hacker News"}}
+# {"id":"top","ok":true,"data":{"count":30,"rows":[{"title":"..."}]}}
+```
+
+- Requests for one session run in order; `--session` inside `argv` runs other sessions at once.
+- `watch` and `console --follow` send `{"id", "stream"}` lines first and do not block later requests.
+- `--bail` stops at the first failure. Exit code 0 when every request succeeded, 1 otherwise.
+- Kept open as a coprocess, one pipe serves a whole Python or Go program with no process per step.
+
+A Python caller writes `json.dumps({"id": n, "argv": [...]})` to the pipe's stdin and reads lines
+until one has that `id` and no `stream` key. The package's `examples/` folder has sh, Python, Node and
+Go versions.
+
+## The Node library
+
+```ts
+import { CommandError, connect } from "patchrome";
+
+const browser = connect({ session: "prices" });
+await browser.run("open", "https://shop.example");
+const { rows } = await browser.run("extract", "schema.json", "--inline");
+await browser.stream(["watch", "--events", "response", "--count", "3"], (event) => console.log(event));
+```
+
+`run` resolves to the `--json` `data` and throws `CommandError` with `code`.
+
+## Sessions in scripts
+
+A script started from your shell shares your session and tabs. Give each run its own:
+`PATCHROME_SESSION=scrape-$$` in sh, `connect({ session })` in Node. End with `session close`.