pw-repl 0.12.7 → 0.12.8

package/skill/SKILL.md

@@ -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`:
 
@@ -136,9 +137,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 +163,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 +196,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