pw-repl 0.3.1 → 0.4.0

package/skill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: pw-repl
 description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, 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, and recording what the person does. 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:*)
 ---
 
 # pw-repl
@@ -44,10 +45,21 @@ one; each takes an optional start URL, which opens in a new tab.
 (`/tmp/mine.log`); `tail -f` on it follows along without a terminal to attach from. `serve <port>`
 listens on TCP 127.0.0.1 instead of a socket, with no access control.
 
-Several REPLs can run at once, each on its own socket, e.g. one per agent. Each has its own selected tab,
-command queue and modes, so they do not wait on or select for each other. They share the browser,
-though: each sees every tab, `modes` lists only its own REPL's modes, and two REPLs acting on the same
-tab can undo each other's routes, network or emulation settings.
+### One REPL, many clients
+
+One REPL serves everyone using its browser: the person at its prompt and any number of agents. When
+`pw-repl where` finds one running for the browser you need, use it rather than start another, as a
+client of your own: `PW_CLIENT=<name>` (or `send -c <name>`), with a name that says who you are.
+
+- A client has its own selected tab, so clients do not move each other's. Its commands show in the pane
+  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.
+
+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
+undo each other's routes, network or emulation settings.
 
 A REPL in a terminal stops at its prompt (`quit`, or Ctrl-C); `send quit` is refused.
 
@@ -59,9 +71,10 @@ pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
 ```
 
 Always send commands with `pw-repl send`; don't type into the pane yourself. The words after `send`
-are the command. For `fill`, `type`, `select` and `press`, a word quoted in your shell stays one word
-(`pw-repl send fill "text=Your name" Ada`); other commands get the words as they are
-(`pw-repl send eval "document.title + ' x'"`). It works however the REPL was started:
+are the command. For `fill`, `type`, `select`, `press` and `upload`, a word quoted in your shell stays
+one word (`pw-repl send fill "text=Your name" Ada`); 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"`. 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.
   It types only when the pane's last line is a bare prompt, so nothing lands in a shell or in the middle
@@ -81,7 +94,19 @@ that, look at the browser itself: `tab` and `info` for where things are, `reques
 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.
+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.
+
+When watching someone:
+
+- Read `body <#>` for any request that matters as soon as it shows up: the browser drops a body once
+  its 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.
 
 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.
@@ -90,7 +115,29 @@ blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --hel
 
 Run `pw-repl send help`. It lists six topics; `help <topic>` lists their commands, `help <command>`
 gives usage and caveats, and `help --all` prints everything at once. It needs no running REPL. The
-help is the command reference; this file does not repeat it.
+help is the command reference; this file does not repeat it. If you know playwright-cli, its command
+names work too (`help playwright-cli` lists them).
+
+### Coming from playwright-cli
+
+Its command names and most of their options work, and each says the first time what it is here. What
+differs comes from the browser being shared. With `<name>` a client name of your own, e.g. from your
+task (`cart-bug`), since two agents with one name are one client:
+
+```bash
+pw-repl send -c <name> open http://localhost:3000   # a tab of your own in the shared browser
+pw-repl send -c <name> snapshot                     # no snapshot after each command; ask for one
+pw-repl send -c <name> click e5
+pw-repl send -c <name> close                        # your modes off; tab close <url-part> closes your tab
+```
+
+- 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.
+- 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
+  input first, since the file picker is not caught.
+- Routes, network and emulation apply to one tab, not to the whole browser.
 
 ## Sharing the browser
 
@@ -114,8 +161,10 @@ help is the command reference; this file does not repeat it.
   one works too (`--headless=new`); nobody answers its dialogs but `dialog`.
 - `PW_CHROME` — the Chromium `--launch` starts (default: Playwright's own, then one on the `PATH`).
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
-- `PW_SCREENSHOT_DIR` — where screenshots go (default `/tmp`). They are all named `screenshot-*.png`,
-  so `rm /tmp/screenshot-*.png` cleans up.
+- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots, read when it starts, 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.
 - `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `send`
   looks for when neither is given (default `/tmp/playwright-repl.sock`).