pw-repl 0.12.8 → 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
@@ -105,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

@@ -83,7 +83,7 @@ With `npx`, use `npx pw-repl@latest` the same way every time, so every command r
   whole tab's network.
 - **Emulate:** a phone, dark mode, a locale, a timezone, a viewport size.
 - **Run code:** `eval` any JavaScript in the page, a line or a file of it, or send a raw CDP command with
-  `cdp`.
+  `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
@@ -154,7 +154,7 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | 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 <secs>`      |
+| 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`                                |

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>]
@@ -19,7 +20,7 @@ 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]
+  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
 
@@ -56,12 +57,14 @@ serves on that same one: $PW_ENDPOINT, then $PW_SOCKET, then the default.
 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.
 
-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'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.
 
 Exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable. -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.
+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.
 
 --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
@@ -105,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);
@@ -120,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;
@@ -296,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

@@ -15,7 +15,7 @@ const NAMES = {
   '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] (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>'],

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);
   },
 };
 

package/lib/help.js

@@ -41,7 +41,7 @@ const TASKS = [
   ['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 <secs>'],
+  ['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'],
@@ -62,6 +62,8 @@ ${TASKS.map(([task, commands]) => `  ${task.padEnd(38)}  ${commands}`).join('\n'
 Modes (${MODES}) stay on until turned off; the prompt shows the selected tab's: (watch routes:1) pw>.
 Each of them on its own, and modes, shows its state and what you can run next.
 
+Times are in milliseconds, as in Playwright, or in seconds with an s: wait .done 30000, or wait .done 30s.
+
 Topics (help <topic>):
   tabs      open, select, close, navigate        network   requests, bodies, console, fakes, network off
   interact  click, fill, type, press, select     devtools  eval, CDP commands, cookie and storage names
@@ -120,7 +122,7 @@ box to point at something, and toast <text> a line of text saying what is happen
 the viewer needs to read it. After a step that loads a page, wait for text only the result shows (wait
 text ...), not a heading the page always has, and not wait load: a single-page app loads nothing.
 
-record on --steps also saves when and where each step ran, in the video's seconds and pixels, for
+record on --steps also saves when and where each step ran, in seconds into the video and its pixels, for
 editing it afterwards.
 
 The user's own screen, with their real pointer, takes a screen recorder they run (OBS, ffmpeg -f
@@ -135,7 +137,7 @@ clean browser of its own (here, its video-start is record on).`,
   devtools: {
     intro: `Cookie and storage listings omit values. eval, cdp, html, screenshots, recordings and URLs can
 still show sensitive data (cdp Network.getCookies shows cookie values).`,
-    commands: ['eval', 'cdp', 'cookies', 'storage'],
+    commands: ['eval', 'cdp', 'clipboard', 'cookies', 'storage'],
   },
   session: {
     intro: `Server: pw-repl serve also takes commands on /tmp/pw-repl.sock; they show here as [server] lines.
@@ -372,7 +374,7 @@ all.`,
       ['--grep <text>', 'only the lines containing text (role, name or a flag such as [disabled], any case), each with the named elements around it.'],
       ['--regex <pattern>', '--grep by a regular expression: snapshot --regex "Total: \\d+".'],
     ],
-    detail: `Refs: a ref (e3, or f1e3 in newer Playwright) works as a selector in any command: click e3. It belongs
+    detail: `Refs: a ref (e3; f1e3, f2e3 once the page has loaded again, when the old refs stop working) works as a selector in any command: click e3. It belongs
 to the tab whose snapshot gave it, and can change when the page changes (e102 may become f4e98): take a
 new snapshot after it does.
 
@@ -527,7 +529,7 @@ circle). That changes the page, so put it back afterwards, as it was if it had a
   eval document.querySelector("#rate-3").style.outline = ""`,
   },
   screenshot: {
-    usage: 'screenshot [<ref>] [--full] [-d <secs>] [name]',
+    usage: 'screenshot [<ref>] [--full] [-d <time>] [name]',
     summary: 'save a PNG of the viewport, --full page or an element',
     args: [
       ['[<ref>]', 'only that element, from a snapshot ref: screenshot e5.'],
@@ -535,7 +537,7 @@ circle). That changes the page, so put it back afterwards, as it was if it had a
     ],
     options: [
       ['--full', 'the whole page, not only the viewport; --full-page too.'],
-      ['-d, --delay <secs>', 'counts down out loud first, up to 60, so someone can hold a hover or open a menu.'],
+      ['-d, --delay <time>', 'counts down out loud first, in seconds, up to 60s, so someone can hold a hover or open a menu.'],
       ['--filename=<file>', 'saves it there instead (a JPEG if it ends in .jpg). Relative to the REPL\'s folder; through pw-repl send, the sender\'s. It never replaces a file.'],
     ],
     detail: `Where: $PW_SCREENSHOT_DIR (a folder that exists); without it, next to the REPL's socket when it serves on one of its own, or
@@ -603,19 +605,19 @@ the same spot, and shows in screenshots and recordings. Selectors, snapshot and
 takes no clicks, and it points at elements inside frames too.`,
   },
   record: {
-    usage: 'record [on [file] [seconds] [options] | off [file]]',
+    usage: 'record [on [file] [time] [options] | off [file]]',
     summary: 'record the selected tab\'s page to a video',
     args: [
       ['on | off', 'on starts recording the selected tab; off stops it, saves the file and says its path, length, size and bytes. Neither: says whether it is recording, and how your last recording ended.'],
       ['[file]', 'clip.webm or clip.mp4; its ending picks the format. Relative to the REPL\'s folder; through pw-repl send, the sender\'s. Default: recording-<timestamp>.webm where screenshot saves. On record off: saves it under that name instead.'],
-      ['[seconds]', 'stops by itself after them, 1 to 3600. Default: 3600.'],
+      ['[time]', 'stops by itself after it, 1s or more. Default: 1 hour (3600s).'],
     ],
     optionsFor: 'record on',
     options: [
       ['--steps', 'also save clip.steps.txt next to clip.webm: when and where each command ran (Steps, below). Default: off.'],
       ['--pause=<ms>', 'a pause after each action, and each highlight drawn, so the viewer sees it. Default: 750; 0 none.'],
-      ['--lead=<ms>', 'still page recorded before record on returns. Default: 1000; counts toward the seconds.'],
-      ['--tail=<ms>', 'still page recorded after record off, before it stops. Default: 1000; none when it stops at its seconds.'],
+      ['--lead=<ms>', 'still page recorded before record on returns. Default: 1000; counts toward its time.'],
+      ['--tail=<ms>', 'still page recorded after record off, before it stops. Default: 1000; none when it stops at its time.'],
       ['--filename=<file>', 'the file, as playwright-cli writes it.'],
     ],
     detail: `What it records: the page only, from inside the browser, at the viewport's size in CSS pixels (set
@@ -656,7 +658,7 @@ height loses a pixel), scrollbars included; a phone's under emulate mobile is it
 is 412 wide, less sharp than the phone draws it.
 
 How it ended: record on its own, or record off when nothing is recording, says how your last recording
-ended (record off, its seconds, its tab closing or the REPL stopping) with what record off would have
+ended (record off, its time, its tab closing or the REPL stopping) with what record off would have
 said. tab close says what became of a recording it ended. A REPL stopped with pw-repl stop cannot be
 asked: stop prints what became of each recording it ended, and of one that ended by itself that record
 has not shown since.
@@ -702,14 +704,14 @@ mouse, and sends no touch events. Dark, light and timezone apply at once, but wh
 drew with them (times, colors set by its script) changes only when it reloads.`,
   },
   wait: {
-    usage: 'wait [text|request] <what> [--gone] [secs]',
+    usage: 'wait [text|request] <what> [--gone] [time]',
     summary: 'wait for an element, text, a response or a load (10s)',
     args: [
       ['<selector>', 'for a matching element to be visible.'],
-      ['text <text>', 'for text to be visible: any part of an element\'s text, any case. Quote text that ends in a number, or the number is taken as the seconds: wait text "Showing 1".'],
+      ['text <text>', 'for text to be visible: any part of an element\'s text, any case. Quote text that ends in a number, or the number is taken as the time: wait text "Showing 1".'],
       ['request <part>', 'for a matching response (a URL part or a glob), counting one that finished since the previous command began, or is still under way: click, then wait request, does not miss it.'],
       ['load', 'for the page to finish loading (its load event), counting a navigation that began since the previous command began: click a link, then wait load.'],
-      ['[secs]', 'how long, up to 120. Default: 10.'],
+      ['[time]', 'how long, with no limit (give send time too: send -t). Default: 10s.'],
     ],
     options: [
       ['--gone', 'until nothing matching is visible (removed or hidden): wait .spinner --gone. Done at once if nothing matches yet, so wait for it to appear first if it may not have.'],
@@ -718,8 +720,8 @@ drew with them (times, colors set by its script) changes only when it reloads.`,
 something on the new view instead. A wait that times out is an error; the REPL carries on.`,
   },
   sleep: {
-    usage: 'sleep <ms>',
-    summary: 'wait a fixed time, in milliseconds (maximum 3600000)',
+    usage: 'sleep <time>',
+    summary: 'wait a fixed time: sleep 1500, or sleep 1.5s',
     detail: `While recording, each action is already followed by a pause (help record): a sleep adds to it.`,
   },
   requests: {
@@ -776,11 +778,11 @@ A page brought back from the back/forward cache (back, forward) reports its earl
 the time it comes back, though nothing loaded again.`,
   },
   profile: {
-    usage: 'profile on [secs] | off | reload | save <file>',
+    usage: 'profile on [time] | off | reload | save <file>',
     summary: 'what slows the tab: long tasks, layouts, input, frames',
     args: [
-      ['on', 'starts a performance trace of the selected tab, until profile off (at most 120 seconds).'],
-      ['[secs]', 'records that long (1 to 120), then prints. Other commands wait until it ends. Over 20, give send time too: pw-repl send -t 70 profile on 60.'],
+      ['on', 'starts a performance trace of the selected tab, until profile off (at most 120s; give it a time for longer).'],
+      ['[time]', 'records that long (1s or more), then prints. Other commands wait until it ends. Over 20s, give send time too: pw-repl send -t 70s profile on 60s.'],
       ['off', 'stops it and prints the summary.'],
       ['reload', 'reloads the tab and profiles its load, until its network is idle (at most 10s after load) and half a second more. For work that starts later (a timer): profile on, reload, sleep, profile off.'],
       ['save <file>', 'writes the last profile\'s trace, the tab\'s events only, as Chrome trace JSON for DevTools\' Performance panel (Load profile) or ui.perfetto.dev. It refuses a file that exists.'],
@@ -813,7 +815,7 @@ may time out, but the profile records it all; profile off once the page answers
 
 Size: a busy page fills Chrome's trace buffer in under a minute (one that restyles many elements as it
 draws, sooner), which stops the profile there, and the summary says so. Stopping a long one takes a
-while, as Chrome writes out its trace: give send time, pw-repl send -t 60 profile off. If send gives up
+while, as Chrome writes out its trace: give send time, pw-repl send -t 60s profile off. If send gives up
 first, the profile still ends, and profile shows it.
 
 One profile runs at a time, in a browser: Chrome traces one at a time, the whole browser's, so another
@@ -844,12 +846,12 @@ the trace even when its page did nothing. The trace is kept in a temporary folde
 profile, or until the REPL stops.`,
   },
   capture: {
-    usage: 'capture on [requests|console] [secs] | off',
+    usage: 'capture on [requests|console] [time] | off',
     summary: 'record requests and console together, in time order',
     args: [
       ['on', 'records both until capture off, which prints them.'],
       ['requests | console', 'records only one.'],
-      ['[secs]', 'records that long (1 to 3600), then prints. Other commands wait until it ends.'],
+      ['[time]', 'records that long (1s or more), then prints. Other commands wait until it ends.'],
       ['(none)', 'says whether one is running, or shows the last one.'],
     ],
     detail: `A timed capture suits recording what someone does in the browser; around your own commands, use
@@ -862,7 +864,7 @@ and console it keeps more than the last 200, and lists both together.`,
     args: [
       ['<glob> <status> <json>', 'answers with this status (200-599) and JSON (the rest of the line), or no body. It never reaches the network, so it still answers while the network is off.'],
       ['<glob> patch <json>', 'lets it through, then changes its JSON response: a JSON Merge Patch, where objects merge, null removes a key and anything else replaces; one that is not an object (an array) replaces the whole body.'],
-      ['<glob> delay <secs>', 'holds it for up to 120 seconds, then lets it through.'],
+      ['<glob> delay <time>', 'holds it that long, then lets it through.'],
       ['<glob> abort', 'fails it as if the connection broke.'],
       ['off <glob> | --all', 'removes one route, or all.'],
       ['(none)', 'lists the selected tab\'s routes.'],
@@ -888,11 +890,11 @@ replaces it. A glob may be quoted. Example: route **/api/cart patch {"total": 0}
       ['on', 'restores it.'],
     ],
     detail: `Per tab; lasts until network on or the REPL exits. Routes still answer while it is off or slow. To slow
-one API, use route <glob> delay <secs>. Stopping a service is not the same as network off: a dev proxy
+one API, use route <glob> delay <time>. Stopping a service is not the same as network off: a dev proxy
 in front of it usually holds the request open, so the page spins instead of failing.`,
   },
   eval: {
-    usage: 'eval [--all] <JavaScript>',
+    usage: 'eval [--all] [--timeout=<time>] <JavaScript>',
     summary: 'evaluate JavaScript in the selected tab and print the result',
     args: [
       ['<JavaScript>', 'the rest of the line. Promises are awaited, await works at the top level, and a function (() => document.title) is called.'],
@@ -900,10 +902,16 @@ in front of it usually holds the request open, so the page spins instead of fail
     ],
     options: [
       ['--file=<path>', 'the JavaScript is the file\'s text: anything the line takes, over many lines and with // comments. With a ref or a selector after the path, it is a function called with that element (the first match). Over send, a relative path is from your shell\'s current folder.'],
+      ['--timeout=<time>', 'how long the page has to answer, before --file. Default: 15s. Past 20s, give send time too, or it gives up first and cancels the eval: pw-repl send -t 70s eval --timeout=60s ...'],
       ['--all', 'the whole result, not capped.'],
     ],
     detail: `eval fetch(...) sends a new request, which can change state on the server; it cannot read one that
-already happened (requests lists those).`,
+already happened (requests lists those).
+
+Long work (--timeout): every other command waits while an eval runs, the other clients' too. For work of
+minutes, or in a browser others are using, start it without awaiting it, keep its result on window, and
+read it back: eval "window.__done = null; run().then(r => window.__done = r); 'started'", then eval
+window.__done until it is set.`,
   },
   cdp: {
     usage: 'cdp [--all] <method> <JSON object>',
@@ -917,6 +925,20 @@ already happened (requests lists those).`,
     ],
     detail: `The session is detached afterwards, so subscriptions and settings do not persist. Browser.close and
 Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog answers one.`,
+  },
+  clipboard: {
+    usage: 'clipboard [--all] [--shared-clipboard]',
+    summary: 'print the text on the clipboard, as a Copy button left it',
+    options: [
+      ['--shared-clipboard', 'reads it in a browser with a window too, whose clipboard is the computer\'s (below).'],
+      ['--all', 'the whole text, not capped.'],
+    ],
+    detail: `It reads through the selected tab, which must be a secure page (https, or http on localhost), granting
+it clipboard-read only while it reads. Check a Copy button: click it, then clipboard.
+
+A headless browser, as --launch starts, has a clipboard of its own, holding only what its pages copied.
+One with a window reads the computer's: whatever its user last copied, a password too. There it refuses
+without --shared-clipboard; ask the user before giving it.`,
   },
   cookies: {
     usage: 'cookies [--all]',
@@ -973,7 +995,11 @@ at the browser (e.g. headless), it is the only way to answer one.`,
   quit: {
     usage: 'quit',
     summary: 'disconnect, leaving Chromium running (one --launch started stops too)',
-    detail: `Runs immediately, even while another command is waiting. Only available at the prompt.`,
+    detail: `Runs immediately, even while another command is waiting. Only available at the prompt.
+
+As it stops (quit, or pw-repl stop), it says, for each client, how many of the files it wrote are still
+there, how large, and in which folders: Files left by cart-bug: 3 files, 48 MB (2 screenshots, 1 video)
+in /tmp/. pw-repl send -c <name> close lists a client's own in full.`,
   },
 };