pw-repl 0.12.7 → 0.13.0

package/AGENTS.md

@@ -23,7 +23,7 @@ If you hit a limitation or write a workaround, consider adding the capability to
   `lib/routes.js`, `lib/network.js`, `lib/emulation.js` (and viewport), `lib/capture.js`, `lib/profile.js` (performance traces;
   `lib/trace.js` reads and sums them up), `lib/record.js`
   (video, through ffmpeg, and the steps file saved with it), `lib/dialogs.js` and `lib/modes.js`. Beneath them, `lib/tabstate.js` is the one record kept per tab, `lib/cdp.js` the CDP
-  session kept per tab, and `lib/util.js` small shared helpers. No facility requires `lib/modes.js` or
+  session kept per tab, `lib/util.js` small shared helpers, and `lib/written.js` the files written and for whom. No facility requires `lib/modes.js` or
   `lib/commands.js`, and a unit test fails on a require cycle, which CommonJS would not report.
 - `bin/pw-repl.js` is the command line; `lib/start.js` connects and runs the prompt; `lib/runner.js`
   runs commands one at a time (`quit` and `dialog` skip its queue); `lib/server.js` is the command
@@ -39,7 +39,7 @@ If you hit a limitation or write a workaround, consider adding the capability to
   accepts theirs too (`lib/cli-names.js`, `help playwright-cli`). Deviate only where it is necessary, as
   where sharing a browser with a user needs it, and say why in the help.
 - Comment the *why* when it isn't obvious from the code.
-- `npm test` runs the suite (under two minutes): a private headless Chromium, a local test site
+- `npm test` runs the suite (about two and a half minutes): a private headless Chromium, a local test site
   (`test/harness.js`), and the real REPL with its server. Nothing is mocked, and the shared browser is
   never touched. It finds Chromium through `PW_TEST_CHROME`, or where `--launch` looks (Playwright's
   browsers, then the `PATH`), and skips the browser tests if there is none. Add a test with each new
@@ -53,7 +53,9 @@ If you hit a limitation or write a workaround, consider adding the capability to
   shown by `help <command> --all` and `help --all`. An error about something in `more` ends by naming it
   (`help record --all`). Paragraphs are plain: `wrap()` lays each out at 104 columns, and keeps as written
   a paragraph with a bullet, a table or an indented example. `test/fixtures` holds the rendered help;
-  after an intended change to it, save it again (the command is in `test/units.test.js`).
+  after an intended change to it, save it again (the command is in `test/units.test.js`). The common
+  tasks and modes on help's front page (`TASKS` and `MODES`) are the README's too: change both, as a
+  unit test compares them.
 - Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`).
   Compare with the last commit that has one (`git log --grep='npm test:'`): a run that grew by more than
   a few seconds means a slow test crept in, usually one waiting out a real timeout (5s for a click).
@@ -103,10 +105,14 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 1.0, a change that breaks how the REPL is used is a minor bump (0.2.0 to 0.3.0), anything else a patch.
 
 1. `npm test` passes and the working tree is clean.
-2. `npm outdated` and `npm audit` show nothing that needs doing first. The lockfile holds playwright-core
-   at 1.63: on 1.64 (and 1.64.1), a click on a link to a 204 waits out its timeout instead of returning (the test
-   "waits for the page to load, counting a navigation that just began" fails). Update it once a version
-   passes `npm test`.
+2. `npm outdated` and `npm audit` show nothing that needs doing first. Dependencies are always the newest
+   stable release, never pinned back (user ruling). When the newest breaks a test, fix it in our code;
+   only a regression of the dependency's own, with the fix already in its next release, keeps the version
+   before it, until that release ships. playwright-core stays at 1.63 for that reason: on 1.64.1 a click
+   on a link to a 204 hangs at "waiting for scheduled navigations to finish" until its timeout, in plain
+   Playwright too (chromium.launch, a page with a link to a 204, page.click on it); 1.65's alphas fix it.
+   The test "waits for the page to load, counting a navigation that just began" shows it: move up once it
+   passes on the newest release.
 3. `npm version <patch|minor|major> -m "chore: release %s"` sets the version in `package.json` and
    `package-lock.json`, commits it as `chore: release X.Y.Z`, and tags that commit `vX.Y.Z`.
 4. `git push --follow-tags` pushes the commits and the tag.

package/README.md

@@ -24,6 +24,39 @@ pw> reload
 pw> console error                       # and see how the page copes
 ```
 
+## Quick start
+
+You need Node.js 20 or newer. pw-repl can use a Chromium-based browser you already have (Chrome,
+Chromium, ...), or Playwright's own: `npx playwright-core install chromium` downloads it.
+
+```bash
+npx pw-repl@latest run --launch https://example.com
+```
+
+`--launch` starts a private headless Chromium for the REPL, in a 1280x800 window, and stops it when
+the REPL quits. Add `--headed` to see that browser and click in it yourself. The page opens, and a
+`pw>` prompt waits:
+
+```text
+pw> help                          # common tasks and topics; help <topic>, help <command>, help --all
+pw> snapshot
+pw> click e3
+pw> screenshot
+pw> quit
+```
+
+Commands act on the selected tab. `tab` lists the tabs, with `*` on the selected one.
+
+### Install
+
+| How          | Setup                                        | Then run                       |
+| ------------ | -------------------------------------------- | ------------------------------ |
+| Without      | nothing                                      | `npx pw-repl@latest <command>` |
+| Global       | `npm install -g pw-repl`                     | `pw-repl <command>`            |
+| From a clone | `npm install` (and `npm link` for `pw-repl`) | `bin/pw-repl.js <command>`     |
+
+With `npx`, use `npx pw-repl@latest` the same way every time, so every command runs the same version.
+
 ## Why use it
 
 - **Your browser, as it is.** It connects to a running Chromium, with your tabs, logins and state, and
@@ -42,14 +75,15 @@ pw> console error                       # and see how the page copes
 
 - **Read the page:** accessibility snapshots with clickable refs, text, HTML, attributes, links, form
   controls, event listeners, screenshots (viewport, full page or one element).
-- **Act on it:** click, fill, type, press keys, select, check, upload files, move the mouse, scroll the
-  wheel, answer dialogs.
+- **Act on it:** click, double-click, fill, type, press keys, select, check, drag and drop, upload files,
+  click or drag at a point, scroll the wheel, answer dialogs.
 - **Watch the network:** every request and response body, console messages and page errors, all recorded
   as they happen.
 - **Change the network:** fake a response (`route`), patch its JSON, delay it, fail it, or cut or slow the
   whole tab's network.
 - **Emulate:** a phone, dark mode, a locale, a timezone, a viewport size.
-- **Run code:** `eval` any JavaScript in the page, or send a raw CDP command with `cdp`.
+- **Run code:** `eval` any JavaScript in the page, a line or a file of it, or send a raw CDP command with
+  `cdp`; read what a Copy button put on the clipboard (`clipboard`).
 - **Wait:** for an element, some text, a response or a page load.
 - **Record:** what someone does in a tab (`watch`), a timeline of requests and console (`capture`), or a
   video of the tab (`record`), with a virtual pointer (`cursor`), captions (`toast`) and highlights
@@ -59,42 +93,10 @@ pw> console error                       # and see how the page copes
 - **Share:** many clients on one REPL, each with its own tab; a command server on a Unix socket or a local
   port, with an HTTP+JSON protocol.
 
-## Quick start
-
-You need Node.js 20 or newer. pw-repl can use a Chromium-based browser you already have (Chrome,
-Chromium, ...), or Playwright's own: `npx playwright-core install chromium` downloads it.
-
-```bash
-npx pw-repl@latest run --launch https://example.com
-```
-
-`--launch` starts a private headless Chromium for the REPL and stops it when the REPL quits. Add
-`--headed` to see that browser and click in it yourself. The page opens in a new tab, and a `pw>`
-prompt waits:
-
-```text
-pw> help                          # common tasks and topics; help <topic>, help <command>, help --all
-pw> snapshot
-pw> click e3
-pw> screenshot
-pw> quit
-```
-
-Commands act on the selected tab. `tab` lists the tabs, with `*` on the selected one.
-
-### Install
-
-| How          | Setup                                        | Then run                       |
-| ------------ | -------------------------------------------- | ------------------------------ |
-| Without      | nothing                                      | `npx pw-repl@latest <command>` |
-| Global       | `npm install -g pw-repl`                     | `pw-repl <command>`            |
-| From a clone | `npm install` (and `npm link` for `pw-repl`) | `bin/pw-repl.js <command>`     |
-
-With `npx`, use `npx pw-repl@latest` the same way every time, so every command runs the same version.
-
 ## Use your own browser
 
-Start Chrome with remote debugging, then run the REPL without `--launch`:
+Start Chrome with remote debugging (on Linux it may be `google-chrome` or `chromium`), then run the REPL
+without `--launch`:
 
 ```bash
 chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
@@ -126,47 +128,49 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
   it. `pw-repl where` says what is running and how `send` will reach it.
 - For `send` to reach `run`, start it in tmux: `tmux new -s pw-repl`, then `pw-repl run` there.
 - A URL after the command opens in a new tab: `pw-repl serve http://localhost:3000`.
-- `--launch` works with each of them. Flags after `--` go to that Chromium (flags only; a start URL goes before `--`).
+- `--launch` works with each of them. Flags after `--` go to that Chromium (flags only; a start URL goes
+  before `--`).
 - A REPL of your own goes on a socket of its own: `-e /tmp/mine.sock` on every command, `serve`
   included, or set `PW_SOCKET`. `serve <port>` listens on TCP, on 127.0.0.1 only.
 
 ## Common tasks
 
-| I want to…                            | Commands                                                                             |
-| ------------------------------------- | ------------------------------------------------------------------------------------ |
-| see where I am                        | `tab` (it marks the tab you are looking at `(visible)`), `info`                      |
-| see what is on the page               | `snapshot`, `screenshot`                                                             |
-| do something on it                    | `click`, `fill`, `type`, `press`                                                     |
-| click what has no selector (a canvas) | `mouseclick <x> <y>`                                                                 |
-| run some JavaScript in the page       | `eval document.title`                                                                |
-| wait for a page or element            | `wait load`, `wait <selector>`, `wait <selector> --gone`, `wait text <text>`         |
-| choose a file in a file input         | `upload <selector> <file>`                                                           |
-| see it as a phone, or in dark mode    | `emulate mobile`, `emulate dark` (also `emulate locale`, `emulate timezone`)         |
-| see what the page requested           | `requests`, then `body <#>` for what one got back                                    |
-| see console messages and errors       | `console`                                                                            |
-| show an agent what I do               | `watch on`, click around in the browser, then `watch`                                |
-| see each step as I click              | `watch on --live`                                                                    |
-| replay what I clicked through         | `watch on`, click around, `watch save flow.txt`, then `pw-repl send --file flow.txt` |
-| record requests and console together  | `capture on`, then `capture off`                                                     |
-| find what makes the page slow         | `profile on`, then `profile off`; `profile reload` for a page load                   |
-| fake a backend response               | `route <glob> <status> <json>`, `route <glob> abort`                                 |
-| change or slow an API response        | `route <glob> patch <json>`, `route <glob> delay <secs>`                             |
-| cut or slow the whole network         | `network off`, `network slow`, then `network on`                                     |
-| record a video of the page            | `record on`, then `record off` (`help video` for a take with a pointer)              |
-| show a pointer where the agent acts   | `cursor on`, then `cursor off` (in screenshots and videos)                           |
-| say what is happening on screen       | `toast <text>`, then `toast off` (`--duration=3s` hides it by itself)                |
-| point something out on the page       | `highlight <ref>` draws a box; `highlight off` hides it                              |
-| clean up                              | `modes off`                                                                          |
+| I want to…                            | Commands                                                      |
+| ------------------------------------- | ------------------------------------------------------------- |
+| see where I am                        | `tab`, `info`                                                 |
+| see what is on the page               | `snapshot`, `screenshot`                                      |
+| do something on it                    | `click`, `fill`, `type`, `press`, `drag`                      |
+| click what has no selector (a canvas) | `mouseclick <x> <y>`, `mousedblclick <x> <y>`                 |
+| run some JavaScript in the page       | `eval document.title`; `eval --file=check.js` for a long one  |
+| wait for a page or element            | `wait load`, `wait <selector> [--gone]`, `wait text <text>`   |
+| choose a file in a file input         | `upload <selector> <file>`                                    |
+| see it as a phone, or in dark mode    | `emulate mobile`, `emulate dark`                              |
+| see what the page requested           | `requests`, then `body <#>` for what one got back             |
+| see console messages and errors       | `console`                                                     |
+| show an agent what I do               | `watch on`, click around, then `watch`                        |
+| see each step as I click              | `watch on --live`                                             |
+| watch a tab someone will open         | `watch on --next-tab [url-part]`                              |
+| replay what I clicked through         | `watch save flow.txt`, then `pw-repl send --file flow.txt`    |
+| record requests and console together  | `capture on`, then `capture off`                              |
+| find what makes the page slow         | `profile on`, then `profile off`; `profile reload` for a load |
+| fake a backend response               | `route <glob> <status> <json>`, `route <glob> abort`          |
+| change or slow an API response        | `route <glob> patch <json>`, `route <glob> delay <time>`      |
+| cut or slow the whole network         | `network off`, `network slow`, then `network on`              |
+| record a video of the page            | `record on`, then `record off` (`help video` for a take)      |
+| show a pointer where the agent acts   | `cursor on`, then `cursor off`                                |
+| say what is happening on screen       | `toast <text>`, then `toast off`                              |
+| point something out on the page       | `highlight <ref>`, then `highlight off`                       |
+| clean up                              | `modes off`                                                   |
 
 `help <topic>` lists the rest, and `help <command>` has usage and caveats.
 
 ### Modes
 
-Some commands turn on a mode that stays on until you turn it off: `watch`, `capture`, `profile`, `route`,
-`network off` or `slow`, `emulate`, `viewport`, `record`, `highlight`, `cursor` and `toast`. While any
-are on in the selected tab, the prompt shows them: `(watch network:off routes:2) pw>`. `modes` lists them
-for every tab, and `modes off` turns them all off. Each of these commands on its own shows its state and
-what you can run next.
+Some commands turn on a mode that stays on until you turn it off: `watch`, `capture`, `profile`,
+`record`, `route`, `network off` or `slow`, `emulate`, `viewport`, `highlight`, `cursor` and `toast`.
+While any are on in the selected tab, the prompt shows them: `(watch network:off routes:2) pw>`. `modes`
+lists them for every tab, and `modes off` turns them all off. Each of these commands on its own shows
+its state and what you can run next.
 
 ## For agents and scripts
 
@@ -204,12 +208,10 @@ each mode on, and `modes off --mine` turns off only the sender's own.
 `send --file take.txt` runs a file of commands, one per line, and stops at the first that fails: a
 repro to keep, or a video take.
 
-**Passwords:** type one as a variable: `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD
-}}"`, or the same line in a file run with `send --file`, as `watch save` writes it. `send` passes the
-value along with the command, and the REPL puts it in only as it runs the command, so the file, the
-REPL's output, its log and its history never hold it. Output that reads it back can: `snapshot`, `html`
-and `attrs` hide a password field's value, but `eval` on the field, a field that a Show password button
-made plain text, or page text that repeats it do not. Only `PW_` names are variables.
+**Passwords:** type one as a variable, so it is never in the command, a file of commands or the REPL's
+log: `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}"` (`watch save` writes them that
+way). What reads the page back can still show it: `snapshot`, `html` and `attrs` hide a password field's
+value; `eval` on the field does not.
 
 ### The HTTP protocol
 

package/bin/pw-repl.js

@@ -2,6 +2,7 @@
 // The one command: pw-repl run | serve | attach | stop | send | where | help | skill.
 
 const { looksLikeEndpoint } = require('../lib/client');
+const { longDuration } = require('../lib/util');
 
 const USAGE = `Usage:
   pw-repl run [--launch [--headed]] [start-url] [-- <chromium flags>]
@@ -9,7 +10,8 @@ const USAGE = `Usage:
 
   pw-repl serve [--background] [--launch [--headed]] [[-e] endpoint] [start-url] [-- <chromium flags>]
       the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/pw-repl.sock);
-      --background runs it detached, with its output in a log next to the socket
+      --background runs it detached, with its output in a log next to the socket; a socket's folder is
+      made if it is missing
 
   pw-repl attach [-e endpoint]
       see everything a background REPL does, and type commands to it; Ctrl-C leaves it running
@@ -18,7 +20,8 @@ const USAGE = `Usage:
       stop a background REPL, and say what became of each recording it ended; its socket is removed, its
       log stays
 
-  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] [--no-vars] <command...> | --file <file>
+  pw-repl send [-e endpoint | -s session] [-c client] [-t time] [--no-vars]
+               <command...> | --file <file>
       run one command in a running REPL and print its output; --file runs a file of them, one per line
 
   pw-repl where [-e endpoint | -s session]
@@ -30,47 +33,53 @@ const USAGE = `Usage:
   pw-repl skill
       print an agent skill (SKILL.md) that teaches an agent to use the REPL
 
-send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/pw-repl.sock) is
-there, and the tmux session (-s, $PW_TMUX_SESSION, default pw-repl) otherwise. If the socket exists but
-nothing answers, send fails rather than fall back. serve without an endpoint serves on that same one:
-$PW_ENDPOINT, then $PW_SOCKET, then the default.
+A browser: --launch starts a Chromium of the REPL's own, headless unless --headed, 1280x800, in a
+temporary profile, on a free port of its own (pw-repl where names it). It prints the command it ran, and
+stops with the REPL (Ctrl-C while it starts too); stop returns once it has exited. Flags after -- go to
+it, and only flags (a start URL goes before --); a --user-data-dir=<dir> among them is used instead of
+the temporary profile, and kept. PW_CHROME picks which Chromium.
 
-send -c <client> (or $PW_CLIENT) sends as a client of the REPL's with a selected tab of its own, so
-several agents can share one REPL; pw-repl help session has the rest.
+Without --launch, the REPL connects to a browser running with --remote-debugging-port, at $PW_CDP_URL
+(default http://localhost:9222).
 
-send's options can also follow the command, as in pw-repl send open <url> -t 30; after a -- before the
-command, every word is the command's, -t 30 included.
+send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/pw-repl.sock) is
+there, and the tmux session where pw-repl run runs otherwise (-s, $PW_TMUX_SESSION, default pw-repl).
+serve without an endpoint serves on that same socket. send exit status: 0 ok, 1 command error, 2
+completion not confirmed, 64 usage or unreachable. pw-repl send --help has the rest: clients, -t,
+--file and variables.`;
 
-send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable. send -t is
-how long send waits for the answer (default 20s); it does not lengthen a command's own limits, such as
-the 5s an action waits for its element.
+// pw-repl send --help: what send does beyond its usage line.
+const SEND_HELP = `send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/pw-repl.sock) is
+there, and the tmux session (-s, $PW_TMUX_SESSION, default pw-repl) otherwise, where pw-repl run runs.
+If the socket exists but nothing answers, send fails rather than fall back. serve without an endpoint
+serves on that same one: $PW_ENDPOINT, then $PW_SOCKET, then the default.
 
-send --file <file> runs each line of a file as a command, in order, as if typed at the REPL's prompt:
-quoted as the prompt reads it (no shell), with a file it records, uploads or saves relative to this
-folder, as on send's command line, and # comments and blank lines skipped. It stops at the first
-command that fails, saying its line, with its exit status. -t is each command's own limit. Other
-clients' commands can run between its lines, on their own tabs.
+send -c <client> (or $PW_CLIENT) sends as a client of the REPL's with a selected tab of its own, so
+several agents can share one REPL; pw-repl help session has the rest.
 
-A {{ PW_NAME }} in a command, or in a line of the file, is a variable: send takes its value from its own
-environment (PW_NAME) and passes it along with the command, not in it, e.g. a password kept out of the
-file and out of the command as the REPL logs it. In a file: fill '#password' "{{ PW_PASSWORD }}",
-run with PW_PASSWORD=... pw-repl send --file login.txt; or one command: PW_PASSWORD=... pw-repl send
-fill '#password' "{{ PW_PASSWORD }}". Only names starting PW_ are variables: any other {{ ... }}, as in a
-page's template text, is sent as written. In a file, put it in double quotes: there its value is
-escaped as they read it (in single quotes, which escape nothing, a value with a ' is refused). The REPL
-puts it in only as it runs the command, and its pane and log show the command as written. A variable that
-is not set stops the command, or the file at that line, before it is sent. --no-vars sends
-{{ PW_NAME }} as it is. Variables need the command server (pw-repl serve), not the tmux pane.
+send's options can also follow the command, as in pw-repl send open <url> -t 30s; after a -- before the
+command, every word is the command's, -t 30s included.
 
-The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
+Exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable. -t is how long
+send waits for the answer, in milliseconds or with s for seconds (default 20s: 20000); it does not
+lengthen a command's own limits, such as the 5s an action waits for its element. Over the server, giving
+up cancels the command: one still queued is never run, and one running is no longer waited for, though
+what it began in the page may go on.
 
---launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
-a temporary profile, on a free port of its own, which pw-repl where names), prints the command it ran,
-and stops it with the REPL (Ctrl-C while it starts too); stop returns once that Chromium has exited.
-Flags after -- go to it, and only flags; a --user-data-dir=<dir> among them is used instead of the temporary profile, and
-kept. PW_CHROME picks which one. To set a browser up your own way, start it yourself and use PW_CDP_URL.
+--file <file> runs each line of a file as a command, in order, as if typed at the REPL's prompt: quoted
+as the prompt reads it (no shell), with a file it records, uploads or saves relative to this folder, as
+on send's command line, and # comments and blank lines skipped. It stops at the first command that
+fails, saying its line, with its exit status. -t is each command's own limit. Other clients' commands
+can run between its lines, on their own tabs.
 
-In a tmux session named pw-repl, pw-repl send reaches pw-repl run without the server.`;
+Variables: a {{ PW_NAME }} in a command, or in a line of the file, takes its value from send's own
+environment (PW_NAME), passed along with the command, not in it, so a password stays out of the file and
+out of the REPL's log: PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}", or
+PW_PASSWORD="$(cat <file>)" to give it from a file without typing it. Only PW_ names are variables; any
+other {{ ... }} is sent as written. In a file, put one in double quotes (in single quotes, a value with
+a ' is refused). One that is not set stops the command, or the file at that line, before it is sent;
+--no-vars sends {{ PW_NAME }} as it is. Variables need the command server (pw-repl serve), not the tmux
+pane.`;
 
 const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl send help here (no REPL needed).
 
@@ -99,10 +108,10 @@ function shellLine(words) {
 }
 
 // -e, -s, -c and -t, then the command words (unquoted words are one command), and send's options again
-// at the end, as an agent types them (send open <url> -t 30); after --, every word is the command.
+// at the end, as an agent types them (send open <url> -t 30s); after --, every word is the command.
 function parseSendArgs(args, subcommand) {
   const allowCommand = subcommand === 'send';
-  const options = { endpoint: null, session: null, client: null, timeout: 20, command: '', file: null };
+  const options = { endpoint: null, session: null, client: null, timeout: 20000, command: '', file: null };
   const given = new Set();
   const take = (arg, value, after) => {
     if (value === undefined) usage(`${arg} needs a value`, subcommand);
@@ -114,8 +123,7 @@ function parseSendArgs(args, subcommand) {
     if (arg === '-s') options.session = value;
     if (arg === '-c') options.client = value;
     if (arg === '-t') {
-      if (!/^\d+$/.test(value) || Number(value) < 1) usage(`-t takes whole seconds, 1 or more (got ${value})`, subcommand);
-      options.timeout = Number(value);
+      try { options.timeout = longDuration(value, '-t'); } catch (error) { usage(error.message, subcommand); }
     }
   };
   let i = 0;
@@ -229,12 +237,28 @@ function skill() {
 
 async function main() {
   let [subcommand, ...args] = process.argv.slice(2);
+  // -h after send, where, attach or stop is a request for help, never a command to send.
+  if (['send', 'where', 'attach', 'stop'].includes(subcommand) && /^(?:-h|--help)$/.test(args[0] || '')) {
+    if (subcommand !== 'send') return console.log(`${USAGE}\n\n${REPL_HELP}`);
+    const block = USAGE.split('\n\n').find(b => b.startsWith('  pw-repl send '));
+    return console.log(`Usage:\n${block}\n\n${SEND_HELP}`);
+  }
   // Bare pw-repl explains itself rather than connect to someone's browser.
   if (subcommand === undefined) return console.log(`${USAGE}\n\n${REPL_HELP}`);
   switch (subcommand) {
     case 'run':
     case 'serve': {
       const options = startOptions(args, subcommand === 'serve');
+      // A socket of one's own is often in a folder of its own (/tmp/<name>/repl.sock): made here, before
+      // the log, the pid file or the socket go in it, whichever way serve runs. Owner-only, as the socket is.
+      const socket = subcommand === 'serve' ? require('../lib/client').parseEndpoint(options.endpoint).socket : null;
+      if (socket) {
+        const folder = require('path').dirname(socket);
+        try { require('fs').mkdirSync(folder, { recursive: true, mode: 0o700 }); } catch (error) {
+          console.error(`pw-repl: cannot create ${folder} for the socket (${error.code === 'EEXIST' ? 'a file is there' : error.code || error.message})`);
+          process.exit(64);
+        }
+      }
       if (options.background) process.exit(await require('../lib/background').start(options));
       return require('../lib/start').start(options);
     }
@@ -249,6 +273,7 @@ async function main() {
     // falls through never: process.exit above
     case 'send': {
       const options = parseSendArgs(args, 'send');
+      if (!options.command && !options.file) usage('no command given', 'send');
       // help is fixed text, so it needs no browser: answer it here.
       const asksHelp = /^help(?:\s+(.*))?$/.exec(options.command);
       if (asksHelp) return help((asksHelp[1] || '').trim());
@@ -273,7 +298,7 @@ async function main() {
     case '--help':
       return console.log(`${USAGE}\n\n${REPL_HELP}`);
     default: {
-      // An option before the subcommand (pw-repl -t 30 send ...): say where it goes, with the line fixed.
+      // An option before the subcommand (pw-repl -t 30s send ...): say where it goes, with the line fixed.
       if (subcommand.startsWith('-')) {
         const all = [subcommand, ...args];
         const named = all.find(word => SUBCOMMANDS.includes(word));

package/lib/background.js

@@ -5,7 +5,7 @@ const path = require('path');
 const readline = require('readline');
 const { spawn } = require('child_process');
 const client = require('./client');
-const { STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
+const { STOPPED_RECORDING, ENDED_UNSEEN, FILES_LEFT } = require('./util');
 
 const BIN = path.join(__dirname, '..', 'bin', 'pw-repl.js');
 const START_TIMEOUT = 20000;
@@ -162,7 +162,7 @@ async function stop(options) {
     fs.closeSync(fd);
     logged = buffer.toString('utf8');
   } catch {}
-  for (const line of logged.split('\n')) if (line.startsWith(STOPPED_RECORDING) || line.startsWith(ENDED_UNSEEN)) console.log(line);
+  for (const line of logged.split('\n')) if (line.startsWith(STOPPED_RECORDING) || line.startsWith(ENDED_UNSEEN) || line.startsWith(FILES_LEFT)) console.log(line);
   return 0;
 }
 

package/lib/capture.js

@@ -2,7 +2,7 @@
 const { state, onShutdown } = require('./state');
 const out = require('./output');
 const { printOutput } = out;
-const { numbers, MAX_EVENT_TEXT, NO_TAB, clock, hints } = require('./util');
+const { numbers, MAX_EVENT_TEXT, NO_TAB, clock, hints, TIME, longDuration, durationText } = require('./util');
 const { consoleText, requestEntries } = require('./requestlog');
 
 const MAX_CAPTURE_EVENTS = 10000;
@@ -17,16 +17,15 @@ function currentCapture() {
 }
 
 // Records the selected tab's requests and console messages together, in time
-// order, until capture off, or for a set number of seconds.
+// order, until capture off, or for a set time.
 async function startCapture(tokens) {
   if (cap) { out.log('Already capturing; capture off stops it.'); return; }
   if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
-  const usage = 'Usage: capture on [requests|console] [seconds] (seconds from 1 to 3600)';
+  const usage = 'Usage: capture on [requests|console] [time] (ms, or 30s)';
   const kinds = tokens.filter(t => t === 'requests' || t === 'console');
-  const numbers = tokens.filter(t => /^\d+$/.test(t));
-  if (kinds.length > 1 || numbers.length > 1 || kinds.length + numbers.length !== tokens.length) throw new Error(usage);
-  const seconds = numbers.length ? Number(numbers[0]) : null;
-  if (seconds !== null && (seconds < 1 || seconds > 3600)) throw new Error(usage);
+  const times = tokens.filter(t => TIME.test(t));
+  if (kinds.length > 1 || times.length > 1 || kinds.length + times.length !== tokens.length) throw new Error(usage);
+  const ms = times.length ? longDuration(times[0], 'capture on\'s time') : null;
   const label = kinds[0] || 'requests and console';
   const startedAt = Date.now();
   const events = [];
@@ -61,11 +60,11 @@ async function startCapture(tokens) {
     get shortened() { return shortened; },
   };
   cap = capture;
-  if (seconds) {
-    out.log(`Capturing ${label} for ${seconds}s...`);
+  if (ms) {
+    out.log(`Capturing ${label} for ${durationText(ms)}...`);
     // Also ends early if the capture does, e.g. because its tab closed.
     await new Promise(resolve => {
-      const timer = setTimeout(resolve, seconds * 1000);
+      const timer = setTimeout(resolve, ms);
       capture.wake = () => { clearTimeout(timer); resolve(); };
     });
     if (cap === capture) stopCapture();
@@ -120,7 +119,7 @@ const commands = {
     const [sub, ...rest] = (args || '').trim().split(/\s+/).filter(Boolean);
     if (sub === 'on') return startCapture(rest);
     if (sub === 'off' && !rest.length) return stopCapture(all);
-    if (sub) throw new Error('Usage: capture on [requests|console] [seconds] | capture off');
+    if (sub) throw new Error('Usage: capture on [requests|console] [time] | capture off');
     if (cap) {
       out.log(`Capturing ${cap.label} on ${cap.page.url()} since ${clock(cap.startedAt)} (${cap.events.length} so far)`);
       out.log(hints([['capture off', 'stop and print what it recorded']]));
@@ -132,7 +131,7 @@ const commands = {
     } else {
       out.log('Not capturing.');
     }
-    out.log(hints([['capture on [requests|console] [seconds]', 'record the selected tab\'s requests and console messages in time order']]));
+    out.log(hints([['capture on [requests|console] [time]', 'record the selected tab\'s requests and console messages in time order']]));
   },
 };
 

package/lib/cli-names.js

@@ -13,9 +13,9 @@ const NAMES = {
   'tab-select': [a => `tab-select ${a}`, 'tab <index>, by index only'],
   // By index there, by URL here: a number could match a port in another tab's URL.
   'tab-close': [a => (a ? null : 'tab close'), 'tab close [url-part], or tab <index> then tab close'],
-  open: [a => `tab new ${a}`.trim(), 'tab new [url]; --mobile or --device=<name> is emulate mobile [name]'],
+  open: [a => `tab new ${a}`.trim(), 'tab new [url] (goto <url> navigates); --mobile, --device=<name>: emulate mobile'],
   // It ends playwright-cli's own browser; this one is shared, so tabs stay open.
-  close: [() => 'close', 'modes off --mine, and tabs stay open'],
+  close: [() => 'close', 'modes off --mine; tabs stay open; lists the files you wrote'],
   'go-back': [() => 'back', 'back'],
   'go-forward': [() => 'forward', 'forward'],
   find: [a => `snapshot --grep ${a}`, 'snapshot --grep <text>'],
@@ -69,7 +69,7 @@ const NEAREST = {
   list: 'pw-repl where says which REPL is running; one REPL serves everyone using its browser',
   attach: 'pw-repl serve connects to the browser on PW_CDP_URL; pw-repl skill has the rest',
   detach: 'pw-repl stop, or quit at the prompt, disconnects and leaves the browser running',
-  drag: 'not here yet', drop: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
+  drop: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
   keydown: 'not here yet; press <key> presses and releases one', keyup: 'not here yet; press <key> presses and releases one',
   pdf: 'not here yet; screenshot --full saves the whole page as a PNG',
   'generate-locator': 'not here yet; a snapshot ref (e5) works as a selector in any command',
@@ -244,7 +244,7 @@ function translate(text) {
   if (name === 'open') {
     const { found, rest: url } = takeOptions(args, OPTIONS.open);
     const device = found.find(o => o.name === 'device');
-    if (!device && !found.length) return { text: `tab new ${url}`.trim(), as: 'tab new [url]' };
+    if (!device && !found.length) return { text: `tab new ${url}`.trim(), as: 'tab new [url], a new tab each time; goto <url> navigates the selected tab' };
     if (device && !device.value) return { refuse: 'Usage: open [url] [--mobile | --device=<name>]' };
     return {
       steps: ['tab new', `emulate mobile${device ? ` ${device.value}` : ''}`, ...(url ? [`goto ${url}`] : [])],

package/lib/commands.js

@@ -1,6 +1,7 @@
 // The REPL's commands, gathered from each facility's module, and what the prompt and the runner
 // need besides: playwright-cli's own commands, the hooks every page gets, and tab completion.
 const { state, shutdown } = require('./state');
+const { ownFilesText } = require('./written');
 const out = require('./output');
 const HELP = require('./help');
 const { tabState } = require('./tabstate');
@@ -80,6 +81,8 @@ const cliCommands = {
     await allModesOff(true);
     const own = state.browser.contexts().flatMap(c => c.pages()).filter(p => tabState(p).owner === state.client);
     if (own.length) out.log(`Tabs you opened are still open: ${own.map(p => p.url()).join(', ')}; tab close <url-part> closes one, or select it and tab close.`);
+    const files = ownFilesText(state.client);
+    if (files) out.log(files);
   },
 };