pw-repl 0.12.7 → 0.13.0

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, recording what the user does, profiling what makes a page slow (long tasks, forced layouts, input delay, dropped frames), and recording a video of a tab, with a pointer and on-screen captions. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
+description: Inspect and drive a Chromium browser, possibly one the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, what a page copied to the clipboard, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, recording what the user does, profiling what makes a page slow (long tasks, forced layouts, input delay, dropped frames), and recording a video of a tab, with a pointer and on-screen captions. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
 allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 ---
 
@@ -43,7 +43,8 @@ and check the skill it names against the top of this file. It says whether a REP
 `send` reaches it, or that one is still starting (retry shortly; it exits 64 until the REPL serves, as
 when none is running). Right after you start one, for a moment before its process is up, it can still
 say none is there: retry for a few seconds before taking that as a failed start. There are three ways to
-run one; each takes an optional start URL, which opens in a new tab.
+run one; each takes an optional start URL, which opens in a new tab (with `--launch`, in its browser's
+first tab).
 
 - `pw-repl serve --background` runs it detached, with a command server on `/tmp/pw-repl.sock`
   (owner-only) and its output in `/tmp/pw-repl.log`. `pw-repl attach` shows everything it does and
@@ -52,14 +53,14 @@ run one; each takes an optional start URL, which opens in a new tab.
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
   `pw[serve]>`. It stops at that prompt (`quit`, or Ctrl-C); `pw-repl stop` is for a background one.
 - Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
-  own instead of connecting to one: headless unless `--headed`, in a temporary profile, on a free port
-  of its own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns
-  once it has exited. It prints the command it ran; flags after `--` are passed to that Chromium (only
-  flags: a start URL goes before `--`), and a `--user-data-dir=<dir>` among them is used instead of the
-  temporary profile, and kept. Started again in a kept profile, Chromium picks up where it left off, as
-  it would for the user, headless too: its tabs come back, and session cookies with them, so a login
-  stays. They start loading before the REPL is attached, so `requests` and `console` have only what
-  came after, often nothing: `reload` for a full record.
+  own instead of connecting to one: headless unless `--headed`, in a 1280x800 window, in a temporary
+  profile, on a free port of its own (never 9222). It stops with the REPL, Ctrl-C while it starts
+  included, and `stop` returns once it has exited. It prints the command it ran; flags after `--` are
+  passed to that Chromium (only flags: a start URL goes before `--`), and a `--user-data-dir=<dir>`
+  among them is used instead of the temporary profile, and kept. Started again in a kept profile,
+  Chromium picks up where it left off, as it would for the user, headless too: its tabs come back, and
+  session cookies with them, so a login stays. They start loading before the REPL is attached, so
+  `requests` and `console` have only what came after, often nothing: `reload` for a full record.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
   the tmux session `pw-repl`:
 
@@ -92,7 +93,7 @@ client of your own: `PW_CLIENT=<name>` (or `send -c <name>`), with a name that s
   as `[server:<name>]` lines.
 - `modes` and `tab` say which client turned each mode on and opened each tab. `modes off --mine` turns
   off only what you turned on; `tab close <url-part>` closes a tab you opened.
-- Commands run one at a time, from every client: a long one (`capture on 60`, `sleep`) holds the rest.
+- Commands run one at a time, from every client: a long one (`capture on 60s`, `sleep`) holds the rest.
 
 A REPL of your own, on a socket of its own, is for a browser of your own (`--launch`), or when you are
 asked for one. Several REPLs on one browser each see every tab but list only their own modes, and can
@@ -104,16 +105,19 @@ A REPL in a terminal stops at its prompt (`quit`, or Ctrl-C); `send quit` is ref
 
 ```bash
 pw-repl send tab
-pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
+pw-repl send -t 90s 'screenshot -d 60s'   # wait longer than the 20s default
 ```
 
+Times, in send's `-t` and in every command, are in milliseconds, as in Playwright, or in seconds with an
+`s`: `-t 90000` or `-t 90s`.
+
 Always send commands with `pw-repl send`; don't type into the pane yourself, except `quit` at the prompt
 of a REPL of your own, which `send` refuses. The words after `send` are the command. For `fill`, `type`,
 `select`, `press`, `upload` and `wait`, a word quoted in your shell stays one word
 (`pw-repl send fill "text=Your name" Ada`, `pw-repl send wait text "Showing 1"`); other commands get the words as they are, joined by
 spaces (`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the
 whole line, spaces and all: `pw-repl send click "text=Your name"`. `send`'s own options (`-t`, `-c`, `-e`,
-`-s`, `--no-vars`) go before the command or after it (`pw-repl send open <url> -t 30`); after `--`, every
+`-s`, `--no-vars`) go before the command or after it (`pw-repl send open <url> -t 30s`); after `--`, every
 word is the command's. It works however the REPL was started:
 
 - `run` (in tmux): `send` types the command into the tmux pane and reads the result back off the screen.
@@ -136,9 +140,10 @@ line, not in it; the REPL puts it in only as it runs the line, and its pane and
 written, so neither the file nor the line as logged holds the secret. Only `PW_` names are variables;
 any other `{{ ... }}` (a page's template text) is sent as written. One that is not set stops the file;
 `--no-vars` sends it as written. A single `send` takes them too: `PW_PASSWORD=... pw-repl send fill
-'#password' "{{ PW_PASSWORD }}"` types a password without it in the command. What reads it back can
-still show it: `snapshot`, `html` and `attrs` hide a password field's value, `eval` on the field does
-not.
+'#password' "{{ PW_PASSWORD }}"` types a password without it in the command. Give the value without
+typing it, from a file only you can read: `PW_PASSWORD="$(cat <file>)" pw-repl send ...`. What reads it
+back can still show it: `snapshot`, `html` and `attrs` hide a password field's value, `eval` on the
+field does not.
 
 `send` takes one command; chain several in your shell. Use `&&` when a step only makes sense if the one
 before it worked: it stops at any exit status but 0, a failure and an outcome not confirmed included.
@@ -161,40 +166,24 @@ background REPL (server commands as `[server]` lines), so whoever looks there se
 shows REPL commands only, not what was clicked in the browser (unless `watch on --live` is on); for
 that, look at the browser itself: `tab` and `info` for where things are, `requests` for the requests the
 clicks made (`body <#>` for what one returned), `console` for console messages and page errors.
-`watch on` records each step someone takes in a tab, with the requests it caused (`watch on --changes`
-adds what each step changed on the page); `watch` reads it back, and `watch new` only what it has not
-shown yet. For a tab they have not opened yet, `watch on --next-tab [url-part]` waits for it and
-watches it from its first page. `watch save <file>` writes the steps as commands that `send --file`
-runs again, a repro to keep. What is typed is recorded, except in password fields; `watch on
---no-values` leaves it out. The file has a `{{ PW_PASSWORD }}` variable where a password was typed,
-set when it runs (`PW_PASSWORD=... pw-repl send --file login.txt`), so the file can be shared without
-it.
-
-When watching someone:
-
-- A watched tab keeps response bodies of up to 100 KB, so `body <#>` still has them after the tab
-  navigates. Read a bigger one that matters as soon as it shows up in `requests`: the browser drops it
-  once the tab navigates.
-- `watch` leaves out images and other static files, failed ones too; `console error` and
-  `requests --all` show what failed.
-- Without a url-part, `--next-tab` takes the first tab anyone opens; check `tab` and `info` once it
-  fires, since another tab opening later does not show in `watch`.
-- A watch belongs to the tab: when another client watches it too, read it with `watch <n>`, since
-  `watch new`'s place is shared and each one's would hide steps from the other.
+`watch on` records each step someone takes in a tab, with the requests it caused; `watch` reads it back,
+and `watch save <file>` writes the steps as commands that `send --file` runs again, a repro to keep.
+Before you watch someone, read `help watch`: what it keeps and leaves out, passwords, and sharing a watch
+with another client.
 
 When a page is slow or feels laggy, `requests` shows a slow response; for what the page itself is busy
-with, `profile on` and `profile off` around what you do, or while the user uses it, sum up a performance
-trace of the tab: long tasks and the function behind each, forced layouts, each click's time to the next
-paint, and frames dropped while scrolling or dragging. `profile reload` profiles a load. `help profile`.
+with, `profile on` and `profile off` around what you do, or while the user uses it (`help profile`).
 
 Exit status: `0` ok, `1` the command failed, `2` completion not confirmed (outcome unknown: do not
-blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --help` has the options.
+blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --help` has the options, and
+`pw-repl send --help` the rest of send's.
 
 ## Learn the commands
 
 Run `pw-repl send help`. It lists seven topics; `help <topic>` lists their commands, `help <command>`
-gives usage and caveats: read it before you use a command, since this file does not repeat them. `help
---all` prints everything at once. pw-repl answers help itself: it needs no running REPL, and never
+gives usage and caveats: read it before you use a command, since this file does not repeat them. When a
+command fails or does something you did not expect, read its `help <command>` before working around it.
+`help --all` prints everything at once. pw-repl answers help itself: it needs no running REPL, and never
 reaches one. If you know playwright-cli, its command names work too (`help playwright-cli` lists them).
 
 ### Coming from playwright-cli
@@ -210,8 +199,9 @@ pw-repl send -c <name> click e5
 pw-repl send -c <name> close                        # your modes off; tab close <url-part> closes yours
 ```
 
-- There is no browser of your own to open or close: `open` opens a tab in the one the REPL uses, and
-  `close` turns off the modes you turned on and leaves every tab open.
+- There is no browser of your own to open or close: `open` opens a new tab in the one the REPL uses,
+  each time, so use it once and `goto <url>` after that, which navigates the selected tab. `close` turns
+  off the modes you turned on and leaves every tab open.
 - Instead of `-s=<session>`, send as a client: `-c <name>`, with a selected tab of its own, in a browser
   whose cookies and storage are shared.
 - `upload <selector> <file>` names the file input or the button that opens it; do not click a file
@@ -240,6 +230,9 @@ pw-repl send -c <name> close                        # your modes off; tab close
   lists what is on in every tab (the prompt shows the selected tab's, e.g. `(watch routes:1) pw>`);
   `modes off` turns off every mode in every tab.
 - Someone may be attached to the REPL's tmux session; killing the session ends it for them too.
+- What a page copied (a Copy button): click it, then `clipboard` prints it. In a headless browser
+  (`--launch`) that is the browser's own clipboard. In one with a window it is the user's, which may
+  hold a password, so `clipboard` refuses there without `--shared-clipboard`: ask the user first.
 - To point something out, to the user or in a screenshot, `highlight <ref|selector>` draws a box over it
   without changing the page (`--style=<css>` restyles it; `highlight off` hides them), without
   Playwright's locator label unless `highlight --labels on`.
@@ -262,6 +255,8 @@ pw-repl send -c <name> close                        # your modes off; tab close
   not by `send`. Without it, a REPL on a socket of its own saves them next to its socket, and any other
   in `/tmp`. `screenshot` prints each file's path; other REPLs may save theirs in the same place. Remove
   only your own, and keep those too if they are needed, e.g. as evidence or as something to hand over.
+  `close` (as a client, `-c <name>`) lists every file you wrote that is still there: screenshots,
+  videos, saved profiles and watches.
 - `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `serve`
   serves on and `send` looks for when neither is given (default `/tmp/pw-repl.sock`).