sourcemonkey 0.0.0-stage → 0.5.0

package/skills/SourceMonkey-dev/references/cdp.md

@@ -0,0 +1,293 @@
+# Raw CDP alongside a run
+
+sm-dev drives tabs over CDP (Chrome DevTools Protocol). For what it has
+no command for, send raw calls to the same tab while the run goes on.
+
+- Protocol reference: https://chromedevtools.github.io/devtools-protocol/
+- Afterwards, `$R wait` lets the page settle, and `$R eval` or
+  `$R logs` shows the effect in sm-dev's terms.
+
+## The `cdp` command
+
+One call, its result printed as JSON:
+
+```sh
+$R cdp Runtime.evaluate '{"expression": "document.title", "returnByValue": true}'
+$R cdp T2 Page.reload                              # another tab
+$R cdp Browser.getVersion                          # browser-level domains work too
+```
+
+- It acts on the current tab, or the one named first (`T2`,
+  `targetId=...`).
+- Several calls go in a `{{` block, one per line, run in order on one
+  session. It stops at the first that fails, and says why:
+
+  ```sh
+  $R --stdin <<'EOF'
+  cdp T2 {{
+  Page.enable
+  Page.getNavigationHistory
+  }}
+  EOF
+  ```
+
+- `cdp --file calls.txt` reads the calls from a file, one per line.
+- In a block or file, blank lines and lines starting with `#` are skipped.
+- Params go on the method's line: bare, or in single quotes (which may
+  hold `'` in the JSON's strings).
+- `Browser.*` and `Target.*` work from the tab's session, and default
+  to its tab: `Browser.getWindowForTarget` with no params gives the
+  tab's window.
+- Each call gets 10 seconds. One that never answers (a paused page)
+  fails with a message. One cut off by the page navigating (a
+  navigating `Runtime.evaluate`) says so, and counts as done.
+- `cdp` doesn't wait for the page to settle. Run `wait` after it.
+- **Session state ends with the command.** `Emulation.*` overrides,
+  enabled domains and event subscriptions last only as long as its
+  session: one command, or one block.
+  - To use one across sm-dev commands, hold a connection open in your
+    own script (below), and clear what you set before it exits.
+  - So a call that sets something up for a later navigation
+    (`Page.addScriptToEvaluateOnNewDocument`) goes in the same block as
+    the `Page.navigate`.
+- **A call can't use an earlier call's result.** An `objectId` from
+  `Runtime.evaluate` can't be passed to the next call in a block. For
+  chains like that, write a script.
+- `cdp` can't listen for events. For that, write a script.
+
+## Your own script
+
+sm-dev's connection doesn't own the browser: its CDP port accepts other
+clients at the same time.
+
+- The port: a temp browser (the default) picks a random one, or uses
+  `--browser`'s. With `--open-browser` or `--existing-browser`, 9233
+  by default, or the `--browser` / `$SM_DEV_BROWSER` sm-dev uses. `status`
+  shows it on its first line (`browser 127.0.0.1:9233`).
+- The tab: its `targetId`. The run prints it when it opens the tab
+  (`Opening <url> in T1 [targetId=...]`), and `tabs` lists them all.
+  Never pick a tab by URL.
+- Or read it from the tab itself, with no text to scrape:
+  `$R cdp T2 Target.getTargetInfo` gives `targetInfo.targetId`.
+
+Node 22+ has a built-in `WebSocket`, so a script needs no dependencies:
+
+```js
+const port = 9233, targetId = process.argv[2];
+const tabs = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
+const ws = new WebSocket(tabs.find((t) => t.id === targetId).webSocketDebuggerUrl);
+await new Promise((r) => { ws.onopen = r; });
+let id = 0; const waiting = new Map();
+ws.onmessage = ({ data }) => {
+  const m = JSON.parse(data);
+  if (m.id) waiting.get(m.id)?.(m); else console.log('event', m.method, JSON.stringify(m.params));
+};
+const send = (method, params = {}) => new Promise((r) => {
+  waiting.set(++id, r); ws.send(JSON.stringify({ id, method, params }));
+});
+```
+
+- `GET /json/version` gives the browser-level socket
+  (`webSocketDebuggerUrl`).
+- Or use Playwright: `chromium.connectOverCDP('http://127.0.0.1:9233')`,
+  then find the page whose `Target.getTargetInfo` (from
+  `context.newCDPSession(page)`) has the `targetId`. Connect with
+  `noDefaults: true`, or Playwright changes the person's browser
+  (focus emulation, color scheme, downloads).
+- Put a script that imports the repo's own dependencies (Playwright)
+  inside the repo, in a git-ignored folder: Node looks for imports
+  from the script's own directory, so one in `/tmp` can't find them.
+- A `Runtime.evaluate` that navigates the page never gets its reply
+  (the document is gone). Use `Page.navigate`, or `$R open`.
+
+## Recipes
+
+### Back and forward
+
+No CDP needed:
+
+```sh
+$R eval 'history.back()' -- wait
+```
+
+Or by history entry: `Page.getNavigationHistory` lists `entries` with
+ids and the `currentIndex`, then
+`Page.navigateToHistoryEntry '{"entryId": N}'`.
+
+### Where an element is
+
+Input events take viewport coordinates in CSS pixels. Get them from the
+page:
+
+```sh
+$R eval '(r => [Math.round(r.x + r.width / 2), Math.round(r.y + r.height / 2)])(document.querySelector(".target").getBoundingClientRect())'
+```
+
+The element must be on screen: `$R eval 'document.querySelector(".target").scrollIntoView({block: "center"})'`
+first.
+
+### Mouse wheel
+
+Real wheel input, which the page sees differently from a synthetic
+`WheelEvent` (targeting, default scrolling, passive listeners):
+
+```sh
+$R cdp Input.dispatchMouseEvent '{"type": "mouseWheel", "x": 400, "y": 300, "deltaX": 0, "deltaY": 600}' -- wait -- eval scrollY
+```
+
+- Pinch zoom on a trackpad arrives as a wheel event with `ctrlKey`: add
+  `"modifiers": 2`.
+
+### Clicks at a point
+
+**On an element, don't use CDP.** Use sm-dev's `click`, which finds
+the element's center (or the point `--at` gives), scrolls to it, and
+checks nothing covers it:
+
+```sh
+$R click e14 --button right            # or middle
+$R click '.item' --modifiers Shift     # Control+Alt, etc.
+$R click '.word' --count 2             # double-click
+$R click '.row' --at 300,12            # a point in it, from its top left
+```
+
+Raw CDP is only needed for a point `click` can't aim at: one on no
+element it can find, or where its checks (covered, moving) get in the
+way. Move there first (pages that react to hover need it), then press
+and release at the same point:
+
+```sh
+$R --stdin <<'EOF'
+cdp {{
+Input.dispatchMouseEvent {"type": "mouseMoved", "x": 50, "y": 50}
+Input.dispatchMouseEvent {"type": "mousePressed", "x": 50, "y": 50, "button": "right", "clickCount": 1}
+Input.dispatchMouseEvent {"type": "mouseReleased", "x": 50, "y": 50, "button": "right", "clickCount": 1}
+}}
+EOF
+```
+
+- `button`: `left`, `middle`, `right`, `back`, `forward`.
+- `modifiers` is a bitmask: Alt 1, Ctrl 2, Meta (Cmd) 4, Shift 8. So
+  Shift-click is `"modifiers": 8` on both events; Ctrl-Shift is 10.
+- Double-click: a press/release with `clickCount: 1`, then another with
+  `clickCount: 2`.
+- Get the point from the page (see [Where an element is](#where-an-element-is)).
+
+Either way:
+
+- A right-click gives the page `contextmenu` and `auxclick` events.
+  Chrome's own context menu can't be driven over CDP, so its entries
+  (an extension's included) can't be picked; fire userscript menu
+  commands with `$R menu`.
+- A Ctrl- or middle-click on a link opens a tab that the run follows
+  (it has an opener), as `T2`.
+
+### Drag
+
+Press, move in steps, release:
+
+```sh
+$R --stdin <<'EOF'
+cdp {{
+Input.dispatchMouseEvent {"type": "mousePressed", "x": 100, "y": 100, "button": "left", "clickCount": 1}
+Input.dispatchMouseEvent {"type": "mouseMoved", "x": 150, "y": 100, "button": "left", "buttons": 1}
+Input.dispatchMouseEvent {"type": "mouseMoved", "x": 200, "y": 100, "button": "left", "buttons": 1}
+Input.dispatchMouseEvent {"type": "mouseReleased", "x": 200, "y": 100, "button": "left", "clickCount": 1}
+}}
+wait
+EOF
+```
+
+- This drives pointer and mouse listeners (sliders, canvas, most
+  custom drag code).
+- Native HTML5 drag-and-drop (`draggable`, `dragstart`/`drop`) needs
+  `Input.setInterceptDrags` and `Input.dispatchDragEvent` in a script
+  that listens for `Input.dragIntercepted`.
+
+### Window size
+
+In a browser with a window (`--open-browser`, or the person's own):
+
+```sh
+W=$($R cdp Browser.getWindowForTarget | grep -o '"windowId": [0-9]*' | grep -o '[0-9]*$')
+$R cdp Browser.setWindowBounds "{\"windowId\": $W, \"bounds\": {\"windowState\": \"normal\", \"width\": 900, \"height\": 700}}"
+$R wait -- eval '[innerWidth, innerHeight]'
+```
+
+- It's a real resize: it lasts, affects the window's other tabs, and
+  fires `resize` in the page. Put it back when done.
+- A headless browser (a temp browser, unless headed) ignores it. There, use
+  `Emulation.setDeviceMetricsOverride` from a script that keeps its
+  connection open, and `Emulation.clearDeviceMetricsOverride` before it
+  exits. An override left set confuses later measurements.
+
+### Fullscreen
+
+- Enter it as a person would: `$R key f`, or `$R click` the site's
+  button. Both count as a user action, so `requestFullscreen()` is
+  allowed.
+- Check it:
+  `$R eval '[document.fullscreenElement?.outerHTML.slice(0, 200), innerWidth, innerHeight]'`.
+  In real fullscreen the size is the screen's.
+- Exit with `$R eval document.exitFullscreen()`. `key Escape` reaches
+  the page but doesn't exit: Escape leaving fullscreen is a browser
+  shortcut, and CDP keys go straight to the page.
+- Switching tabs exits fullscreen, as does a `GM_openInTab` with
+  `active`.
+- **Force it off** when the page won't exit: set the window back to
+  normal with `Browser.setWindowBounds` and
+  `{"windowState": "normal"}`, as above. This works even when the page
+  is stuck.
+- **Don't call `Emulation.setFocusEmulationEnabled`.** With it on,
+  `requestFullscreen` only fills the tab, and the page lays out at the
+  window's size. sm-dev leaves it off.
+
+### Tracing a transition per frame
+
+Screenshots are too slow to catch a flash, a gap or a jump. Record
+what's on top at chosen points on every frame, then trigger the
+change, then read the record. This runs in the page (`eval --page`);
+change `points` to spots in the image or video:
+
+```sh
+$R --stdin <<'EOF'
+eval --page {{
+window.smTrace = [];
+const points = [[400, 300], [20, 20]];
+const t0 = performance.now();
+let last = '';
+const name = (el) => !el ? 'nothing'
+  : el.tagName.toLowerCase() + (el.id ? `#${el.id}` : '') + [...el.classList].slice(0, 2).map((c) => `.${c}`).join('');
+(function frame() {
+  const now = (document.fullscreenElement ? 'fullscreen: ' : '') + points.map(([x, y]) => name(document.elementFromPoint(x, y))).join(' | ');
+  if (now !== last) window.smTrace.push(`${Math.round(performance.now() - t0)}ms ${now}`);
+  last = now;
+  if (performance.now() - t0 < 3000) requestAnimationFrame(frame);
+  else console.log('[trace] done');
+})();
+}}
+key ArrowRight
+wait log '[trace] done' --timeout-seconds 10
+eval --page window.smTrace
+EOF
+```
+
+- It keeps only the frames where something changed, for 3 seconds.
+- Frames don't run in a background tab: trace the visible one
+  (`$R focus`).
+- To follow an image or video's source, add `el.currentSrc` to `name`.
+
+### Other things worth knowing
+
+- **Dark mode, reduced motion, print**: `Emulation.setEmulatedMedia`
+  with `features` (`prefers-color-scheme: dark`). Session-scoped: set
+  it and check the page (`Runtime.evaluate`, `Page.captureScreenshot`)
+  in one `cdp {{` block, or from a script that stays connected.
+- **Network**: `Network.enable` in a script, then
+  `Network.requestWillBeSent` / `Network.responseReceived` events;
+  `Network.getResponseBody` for a body. The script's own
+  `GM_xmlhttpRequest`s don't need this: the run's stream prints each
+  one's method, URL and outcome.
+- **A background tab's screenshot** renders WebGL canvases (maps)
+  blank. Bring it forward first: `$R focus T2`.
+- **Closing the last tab quits Chromium on Linux.** Leave one open.

package/skills/SourceMonkey-dev/references/commands.md

@@ -0,0 +1,297 @@
+# sm-dev commands by task
+
+A summary. `pnpm sm-dev help` lists the help topics, and
+`help <topic>` shows one. `help <command>` (or `<command> --help`)
+shows a command's exact options, and `help script save` (or
+`script save --help`) one subcommand's; `help commands` lists the
+commands, and `help all` everything.
+
+## Shape of a command line
+
+```sh
+sm-dev [global options] <command> [args] [-- <command> ...]
+```
+
+- Global options go first: `--run ID`,
+  `--open-browser`, `--existing-browser`, `--browser URL|PORT`,
+  `--manager sm|tm|vm`, `--headed`, `--headless`, `--mute`, `--nomute`,
+  `--stdin`, `--interactive`,
+  `--root DIR`, `--local DIR`, `--json`.
+- Read the text output by default: it's shorter, and says what an
+  empty answer means and where to look next.
+- Add `--json` when you'll parse the output, with `jq` or a script:
+  `$R --json scripts | jq -r '.scripts[] | select(.status == "invalid") | .name'`.
+  - `--json` works for `list`, `status`, `scripts`, `tabs`, `frames`,
+    `values`, `get`, `match`, `validate`, `menu`, `logs`, `probe`, and every
+    `collection` and `script` verb (`script list`, `script show`, ...).
+    Each prints one JSON object; other commands print text as usual.
+  - Other messages and failures stay text, on stderr, with the usual
+    exit code.
+  - An empty list means nothing was found.
+  - A script's `state` on a tab: `running`, `not-running`, or
+    `manual` (a `@run-at context-menu` script not run yet); for a
+    SourceMonkey-managed script (E1, ...) also `kept-out` (the run
+    keeps it out of its tabs), `not-started`, `error` (it threw),
+    `refused` (Chrome refused it), `unexpected` (running though it
+    doesn't match), `changed` (changed since it started) and `unknown`
+    (the page loaded before SourceMonkey started).
+  - Every field:
+    https://github.com/jshute96/SourceMonkey/blob/main/docs/sm-dev-json.md
+- `--` separates commands. They run in order and stop at the first
+  failure (a `match` or `validate` miss excepted).
+- Exit codes: 0 success, 1 a command failed (a check missed, no
+  element, an `eval` threw, a `wait` gave up), 2 invalid command
+  (`ERROR:`). A few commands still exit 0 when they fail, and `probe`
+  reports a missing selector without failing: read the output.
+- Flags take a value after a space or `=` (`--out f.txt`,
+  `--out=f.txt`). An unknown flag's error lists the flags the command
+  takes; stray arguments are refused, with the command's usage.
+- Quotes: in `--stdin` lines, most commands take off one level of
+  quotes around an argument. `eval` and `cdp` don't: their quotes are
+  JavaScript's and JSON's. A quoted word is never a flag.
+- Flags can go anywhere, also after or inside `eval`'s JavaScript or
+  `wait log`'s text (`eval 'await x()' --timeout-seconds 45`). A word
+  there shaped like a flag (`--name`) is taken as one, and an unknown
+  one is an error. To keep one as text, quote the text as a whole
+  (`type #q 'a --b'`), or in JavaScript write it so the `--` isn't a
+  word of its own (`a = '--b'`, `(--n)`).
+
+## Names
+
+| Thing | Written | Notes |
+| --- | --- | --- |
+| Run | `D1`, or `Dname` from `--run` | `list` shows them |
+| Script | `1`, its path, file name, `@name`, or a unique piece | `T2.3`: script 3 on tab T2 |
+| Tab | `T1`, `targetId=<id>` (or 6+ chars of it) | Page commands take one first: `click T2 .x` |
+| Installed script | `E1` | SourceMonkey's own number, the same in every run |
+| Collection | `C1`, its name or a unique piece, `id=<id>` | A run's test collection: its run, `D1` |
+| Menu command | `M1`, `T2.M1`, or its label | |
+| Element | CSS or Playwright selector, or a ref (`e4`, `f2e6`) | Refs from the latest `snapshot`. A selector in an iframe: `--frame F2` |
+| Frame | `F2`, `T1.F2`, `frameId=<id>`; the top frame is its tab, `T1` | From `frames`; kept across the frame's reloads |
+| Page | URL, file, glob, or script number (its default page) | Scheme optional for hosts |
+
+## Browsers
+
+| Command | Use |
+| --- | --- |
+| `sm-dev start ...` | The default: a temp, throwaway browser for this run, with SourceMonkey loaded. Good for pages with no login. Headed when the line goes to a prompt |
+| `sm-dev --open-browser` | Start a lasting, visible browser on port 9233 (kept profile, so logins persist). A no-op if one is up |
+| `sm-dev --existing-browser ...` | Connect to the browser already on port 9233 |
+| `--browser 9300` | With `--open-browser` or `--existing-browser`: the browser on another port. With a temp browser: the port to launch it on |
+| `--headed`, `--headless`, `--nomute` | When sm-dev launches the browser: show or hide its window; sound on (a temp browser is muted otherwise) |
+
+- A run pushes its scripts into SourceMonkey in that browser. With
+  `--open-browser` or `--existing-browser`, it must be loaded there with
+  Allow User Scripts on: `manager install` does both.
+- Commands for a browser with no run (`manager install`, `collection`,
+  `script`) need `--existing-browser` or `--open-browser`.
+
+### Managers
+
+`--manager` picks SourceMonkey (`sm`, the default), Tampermonkey (`tm`)
+or Violentmonkey (`vm`). A run keeps the one it started with. How to
+test a script under VM or TM:
+[other-managers.md](other-managers.md).
+
+| Command | Does |
+| --- | --- |
+| `--manager tm manager fetch` | Download or update TM (or VM) from the Chrome Web Store into `~/.cache/sm-dev/managers` |
+| `[--manager tm] manager install` | Load the manager into the browser unpacked, with Allow User Scripts on. No run needed |
+| `[--manager tm] manager enable` / `disable` | Turn it on or off in the browser. Not SourceMonkey while a run uses it |
+| `--manager vm start <script> <url>` | A run under VM (or `tm`): its scripts are installed in the manager, and removed when it ends. `values`, `get`, `set`, `menu`, `connect` and `--values` are refused |
+| `--manager vm script list`, `script E3 show`, ... | The manager's scripts, by E-ids, in one collection, `C0`. `collection C0 disable` is its switch for all scripts |
+
+- A manager enabled beside the chosen one runs its scripts in the run's
+  tabs too: the run's first lines and `status` warn of it.
+- Under VM or TM, `scripts` and `status` show which scripts each tab
+  is expected to run, by their match rules (`Expected on tab T1 using
+  match rules:`), not what ran. A run's script shows its E-id there
+  too: `1: Hello (hello.user.js), E6 in Violentmonkey`.
+- Under VM or TM, a run never replaces a script the manager already
+  has by the same name and namespace: `start` refuses, naming it.
+
+## Runs
+
+| Command | Does |
+| --- | --- |
+| `start [script]... [url]... --detach` | Start a run in the background; returns once pages settle |
+| `start ... --watch` | Re-push and reload on each save of a script or local `@require` |
+| `start ... --values '<json>'` | Seed GM storage first |
+| `start ... --values-file <path>` | Seed GM storage first, from a JSON file |
+| `start ... --log-source all` | Also stream the site's own lines and errors (sources: `sm`, `event`, `script`, `page`) |
+| `start ... --lang zh-CN,en` | Tabs prefer these languages |
+| `start ... --all` | Open each script's default page, a tab each |
+| `start [url]...` | No scripts: just a browser to drive (`load` adds them later) |
+| `start ... --notab` | No tab at first; `newtab` later |
+| `start ... --detach --new` | Start another detached run, keeping earlier ones |
+| `list` | The active runs |
+| `status` | The run, its log file, tabs, and each script's state. With no run picked: every active run; with `--existing-browser`, also that browser and its managers |
+| `attach [ID]` | Follow a run's stream (Ctrl-C leaves it going) |
+| `stop [ID]`, `stop --all` | End a run |
+| `exit` | End this sm-dev (at a prompt or on stdin); runs it started without `--detach` stop |
+| `start --stop-after-idle-seconds N` | Idle timeout (default 30 minutes; `0` never) |
+
+## Scripts
+
+| Command | Does |
+| --- | --- |
+| `validate <path>...` | Header, `@require` and syntax checks, plus warnings, e.g. an `@icon` that can't be shown (files, dirs, globs) |
+| `match <script>... <url>...` | Would it run there; which rules matched or excluded it |
+| `match`, `match all` | In a run: the selected script on the current tab; all scripts on all tabs. `--frames`: each of the tab's iframes too |
+| `scripts`, `script <script>` | List; pick the one `get`/`set`/`match` use. It also lists SourceMonkey-managed scripts on the tab as E1, ...; `scripts E1` picks one for `get`/`set`, any installed script (`script list` lists them), on the tab or not (`set key --force <json>` outside a temp browser) |
+| `load <script>...` | Add scripts to the run |
+| `update [script]` | Re-read changed scripts and reload affected tabs |
+| `collection list` (or `collections`) | SourceMonkey's collections (C1, ...), with kind, script count, enabled. No run needed |
+| `script list [collection]` | Every installed script (E1, ...) under its collection, or one collection's. No run needed |
+| `script [script] show`, `script [script] print` | One script in full (rules, status, files, values count, and in a run its state on each tab); its installed text. No run needed |
+| `script [script] print --file <name> [--out <file>]` | One of its `@require` / `@resource` / `@icon` files as installed, by a `@resource`'s name, part of its URL, or `icon`. `--out` writes it to a file |
+| `script [script] save <dir> [--include <parts>] [--flat] [--force]` | Save the script and its files as installed into a directory, in folders by URL (`--flat`: all in one). `--force` replaces existing files |
+| `collection <collection> show` | One collection and its scripts. No run needed |
+
+### Changing what's installed
+
+The script or collection comes before the verb: `script E4 disable`,
+`collection C3 refresh`; quote a name of several words. In a run, a
+script left out is the selected one, except for `uninstall`.
+
+These change SourceMonkey's real collections and scripts, as its pages
+do, and need no run (with no run, they need `--existing-browser`).
+Outside a temp browser they're the person's own: change them only when
+asked to.
+
+| Command | What it does |
+| --- | --- |
+| `script [script] enable` / `disable` | Turn one on or off. In a run, one of its own too |
+| `script [script] refresh` | Re-read it from its location; a run's own from disk, as `update` does |
+| `script install <file\|url>` | Install for every tab, to stay (`load` is for the run only). `--collection <C>`. Under VM, replacing the person's script of the same name needs `--force`: ask first |
+| `script <script> uninstall`, `script [script] move <C>` | Remove one from, or move it between, container collections |
+| `collection <C> enable` / `disable` / `refresh`, `collection <C> rename <name>` | The same for a whole collection |
+
+- `script uninstall` needs `--force` outside a temp browser.
+- A run's test collection and other runs' scripts are refused, as is
+  uninstalling or moving a script that a directory or manifest
+  collection lists.
+- The listings mark a local file changed since it loaded: `(modified
+  on disk)`, and a collection's `Refresh pending: ...`. `script
+  refresh` / `collection refresh` load it.
+- Installing, moving or enabling a script turns off its other running
+  copies, as SourceMonkey does, and lists each one. Enabling a
+  collection does the same without listing them, and disabling it
+  turns back on what it turned off. A new file a `collection refresh`
+  finds lands disabled when its script already has an enabled copy. An
+  enabled script in a disabled collection is said not to run.
+
+## Tabs
+
+| Command | Does |
+| --- | --- |
+| `tabs`, `tab T2` | List (with targetIds); pick the current tab. `--frames`: each tab's iframes too |
+| `frames [T2\|F3\|all]` | A tab's iframes (`F1`, ...) as a tree, with the scripts running in each, `(hidden)` ones marked, each one's CDP `frameId`, and the `targetId` of one from another site |
+| `newtab [page...]` | Open a controlled tab (becomes current) |
+| `newtab --noscript <url>` | A tab the scripts stay out of (sticky) |
+| `closetab [T2 T3...\|all]` | Close the current tab, the ones named, or all. A page's "Leave site?" dialog waits for `accept`/`dismiss`; `--force` skips it |
+| `open [tab] [page]` | Navigate the current tab, or the one named |
+| `reload [T2\|all]` | Reload |
+| `focus [tab]` | Bring to the front |
+| `--from-saved [--offline] [--url U]` | On `newtab`/`open`/`start`: serve `.html` files at their recorded URL |
+| `--timeout-seconds S` | On `newtab`/`open`/`reload`: give a slow page S seconds to load (default 30) and settle (default 5) |
+
+## Reading the page
+
+| Command | Does |
+| --- | --- |
+| `snapshot [sel] [--visible] [--out F]` | Accessibility tree with refs |
+| `snapshot [sel] --find <text>` | Only elements containing the text (case insensitive), within `sel`'s matches |
+| `snapshot ... [--up N] [--context] [--limit N]` | For each match of `sel` or `--find`: N levels up, or with wrapper divs and small containers; first 5 matches (0: all) |
+| `probe <sel>... [--css] [--html]` | Which match and how many; selector / HTML of the first 10 |
+| `eval <js>` | Evaluate inside the selected script, where its `GM_*` APIs, `@require` libraries, top-level declarations and IIFE locals are visible; prints JSON (promises awaited). In the page when no script is selected or it hasn't run there |
+| `eval --page <js>` | Evaluate in the page, where the page's own globals are |
+| `eval --script=<script> <js>` | Evaluate inside the named script |
+| `eval --frame F2 <js>` | Evaluate in an iframe: in the script instance there, or in its page with `--page`. Cross-origin frames too |
+| `eval --file <path>` | Evaluate a JavaScript file |
+| `eval --out FILE <js>` | Write the result to a file; printed results are cut past 10,000 characters |
+| `cdp <Method> [json]` | A raw CDP call on the tab; the result as JSON. A `{{` block or `--file` holds several, one per line (see [cdp.md](cdp.md)) |
+| `cdp --frame F2 <Method> [json]` | The same on the target an iframe is in: its own (one from another site), else its page's |
+| `screenshot [sel] [--full] <file>` | PNG of the view, the page, or an element |
+| `savehtml <file>` | Save the DOM for `--from-saved` / `serveHtml` |
+| `logs [T2\|all] [script]` | The run's log for the tab (its scripts' lines and events), timestamped and whole (the stream cuts a line past 1000 characters) |
+| `logs ... --log-source all` | The site's own lines too; or a list, e.g. `sm` for SourceMonkey's Log entries alone |
+| `logs ... --find <text\|/re/>`, `--tail 50`, `--tail 30s` | Only matching lines; the last N, or the last stretch of time |
+| `logs ... --since <position>` | Only lines after a log ID (`Logs up to` gives the last), an ISO 8601 time, or a time of day (`14:05:12`) |
+
+## Driving the page
+
+| Command | Does |
+| --- | --- |
+| `click <sel>`, `hover <sel>` | Real mouse input, scrolled into view. A failure names the check that failed (hidden, disabled, moving, covered by what) |
+| `click <sel> --button right --modifiers Shift --count 2` | Right or middle button, keys held (`Control+Alt`), double or triple click |
+| `click <sel> --at 300,12`, `hover <sel> --at 4,4` | At that point in the element (pixels from its top left), not its center |
+| `hover <sel> --modifiers Alt` | Keys held during the hover |
+| `type <sel> <text>` | Type key by key |
+| `type <sel> {{` | Type several lines exactly (line breaks are Enter; the final one before `}}` isn't typed) |
+| `type <sel> --file <path>` | Type a file's text exactly, including a final line break |
+| `type <sel> --clear [text]` | Empty the field first, then type the text if given |
+| `key <keys>...` | `key j Shift+ArrowRight ctrl+end esc` |
+| `accept [tab] [text]`, `dismiss [tab]` | Answer an open dialog |
+| `connect once\|cancel\|allow\|deny\|allow-all [host]` | Answer SourceMonkey's prompt for a host the selected script's `@connect` doesn't cover |
+| `--nowait` | On any of these: don't wait for the page to settle |
+| `--timeout-seconds S` | On any command that waits (these, `start`, `eval`, `snapshot`, `probe`, `screenshot`, `closetab`, `load`, `update`, `menu`): S seconds for each wait, in place of its default. On `cdp`, for each call (default 10) |
+
+## Waiting
+
+| Command | Waits for |
+| --- | --- |
+| `wait [T2\|all]` | The tab to settle |
+| `wait selector <css>`, `wait selector-gone <css>` | An element to appear / disappear |
+| `wait log <text>`, `wait log /regex/` | A log line since the previous command began (or `--since`). `--find <text>` works too |
+| `wait 500ms`, `wait 2s` | Time (last resort) |
+| `--timeout-seconds S` | Give up after S seconds (default 5). On a delay, it may be given if not shorter |
+
+- A tab goes before the form: `wait T2 selector '.x'`.
+- `wait log` sees every log source, the site's own lines too, unless
+  `--log-source` narrows it. Each is matched in the form the run
+  would print it: `[page log] KEYUP 143`.
+- It ends with `Found at <log ID>`, or `Searched up to <log ID>` when
+  it gives up.
+
+Settled means: loaded, scripts started, no requests (under 3 seconds
+old) or DOM changes for 200ms. Timers aren't waited for.
+
+## Scripts' GM state
+
+| Command | Does |
+| --- | --- |
+| `menu`, `menu all` | List menu commands (`M1`...) |
+| `menu <label or M1>` | Fire one. Piped in, waits up to 5 s for it to be registered; `--timeout-seconds S` for longer |
+| `values [script\|T2\|E1]` | Stored values (`E1`: a SourceMonkey-managed script) |
+| `get <key>`, `set <key> <json>` | One value; `set` fires change listeners |
+| `set <key> --file <path>` | The value from a JSON file (or a `{{` block, as `eval` takes) |
+
+## eval
+
+- The rest of the line is JavaScript: `eval document.title`. Quote it
+  for the shell when it has spaces or special characters.
+- The value is the last expression, as in the DevTools console. A
+  top-level `return` works too (the code runs as a function body).
+  Its `const`/`let` then stay in that function, not kept for later
+  evals.
+- In the page (`--page`), a top-level `const` or `let` can clash with
+  a name the page's own scripts declare ("Identifier 'a' has already
+  been declared"). Wrap the code in `{ ... }`.
+- `eval --file probe.js` runs a file's JavaScript, with no shell
+  quoting: handy for a probe you run more than once.
+- Several lines, on stdin or at a prompt:
+
+  ```
+  eval {{
+  const rows = [...document.querySelectorAll('.row')];
+  rows.map((r) => r.id)
+  }}
+  ```
+
+  `{{` ends the first line; a line of just `}}` closes it. A tab and
+  flags go before the `{{`.
+- Elements print as DevTools describes them; return
+  `el.outerHTML` or specific fields for more.
+- An expression that navigates prints a note instead of a value;
+  follow it with `wait`.

package/skills/SourceMonkey-dev/references/other-managers.md

@@ -0,0 +1,63 @@
+# Testing under other managers
+
+A run can load its scripts into **Tampermonkey** (TM) or
+**Violentmonkey** (VM) instead of SourceMonkey: to check a script is
+portable across managers, or to debug something that works in one but
+not another. Both work the same way; the examples use VM, and
+`--manager tm` does the same under TM. Runs under each can go side by
+side, with different `--run` ids, to compare.
+
+```sh
+pnpm sm-dev --manager vm manager fetch     # once: download VM into sm-dev's cache
+R="pnpm sm-dev --manager vm --run Dvm"
+
+$R start sites/x/y.user.js https://x.com/ --detach
+$R scripts                                 # each tab's expected scripts, with their VM ids
+$R logs                                    # the script's console lines and errors
+$R stop                                    # removes the run's scripts from VM
+```
+
+- `--manager vm` goes before the command, and the run keeps it: later
+  commands to the run work without it.
+- A temp browser (the default) loads the fetched manager, fetching it
+  the first time, and lets scripts run on local `file://` pages:
+  - VM blocks them by default, and sm-dev clears that in a temp
+    browser;
+  - TM needs Chrome's file access, which is on for the unpacked copy a
+    temp browser loads, but off by default for one from the Chrome
+    Web Store.
+- For a site that needs a login, the person's `--open-browser` browser
+  needs VM: `pnpm sm-dev --existing-browser --manager vm manager
+  install`. Ask first, and about turning SourceMonkey off there
+  (`--existing-browser --manager sm manager disable`), since every
+  enabled manager runs its scripts.
+- The run's scripts go into the manager as ordinary scripts, marked by
+  a last line `// sm-dev: run=...`, and are removed when the run ends.
+  - Under TM, local `@require` lines show rewritten to
+    `https://sm-dev.invalid/...` in TM's editor: TM can't resolve them
+    otherwise. `script print` shows them as written.
+  - Each keeps its run number, with its VM id beside it: `1: Hello
+    (hello.user.js), E6 in Violentmonkey`. Either names it.
+  - `start` refuses a script VM already has by the same name and
+    namespace, naming it. Ask the person before
+    `script E<n> uninstall --force` to make room.
+
+What differs from SourceMonkey:
+
+- **Nothing reports what ran.** `scripts` and `status` list the run's
+  scripts under `Expected on tab T1 using match rules:` and `Not
+  expected on tab T1:`, from their headers. Check the page itself
+  (`snapshot`, `eval --page`) to see a script worked.
+- **Every script in the manager runs in every tab**, the person's own and other
+  runs' too: nothing keeps them out of the run's tabs.
+- **No reach into a script:** `values`, `get`, `set`, `menu`,
+  `connect` and `--values` are refused, and `eval` runs in the page,
+  not inside the script.
+- **A script's uncaught error** is a `[script error]` log line, not a
+  `threw` event.
+- `collection` and `script` work on the manager's scripts, in one
+  collection, `C0`, whose `disable` turns all its scripts off.
+- Under TM, saving needs its "Easy save" setting on, as it is by
+  default; sm-dev says so when it's off.
+- More: [sm-dev-violentmonkey.md](https://github.com/jshute96/SourceMonkey/blob/main/docs/sm-dev-violentmonkey.md)
+  and [sm-dev-tampermonkey.md](https://github.com/jshute96/SourceMonkey/blob/main/docs/sm-dev-tampermonkey.md).