pw-repl 0.12.7 → 0.13.0

package/lib/help.js

@@ -22,36 +22,52 @@ function wrap(text, width = WIDTH) {
   }).join('\n\n');
 }
 
+// The common tasks, as the README's table lists them too (a unit test keeps the two the same).
+const TASKS = [
+  ['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'],
+];
+
+// The commands that turn on a mode, as the README lists them too.
+const MODES = 'watch, capture, profile, record, route, network off or slow, emulate, viewport, highlight, cursor and toast';
+
 const OVERVIEW = wrap(`pw-repl drives Chromium over CDP. Commands act on the selected tab (\`tab\` shows which).
 The browser may be a shared session, with other users' tabs open in it.
 
 Common tasks:
-  where am I?                       tab, info
-  what is on the page?              snapshot, screenshot
-  do something on it                click, fill, press
-  wait for a page or element        wait load, wait <selector>, wait <selector> --gone
-  choose a file in a file input     upload <selector> <file>
-  see it as a phone, or dark        emulate mobile, emulate dark
-  what did the page request?        requests, then body <#> for what one got back
-  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]
-  requests and console together     capture on, then capture off
-  a video of what I do              help video
-  break the backend on purpose      route <glob> <status> <json>, route <glob> abort, network off
-  change or slow an API response    route <glob> patch <json>, route <glob> delay <secs>
-  slow the whole network            network slow
-  clean up                          modes off
-
-Modes (watch, capture, record, route, network off or slow, emulate, viewport) stay on until turned off;
-the prompt shows the selected tab's: (watch routes:1) pw>. tab, watch, capture, record, route, network,
-emulate and modes on their own show their state and what you can run next.
+${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
-  inspect   snapshot, watch, text, screenshots   session   modes, markers, server, quitting
+  inspect   snapshot, watch, wait, screenshots   session   modes, server, clients, quitting
   video     record a take, with a pointer
 
 help <command> for usage and caveats (e.g. help route), help <command> --all for all of it; help --all
@@ -71,7 +87,7 @@ tab on its own lists them all.`,
 Commands use the first match (click, dblclick and hover the first they can use: help click); see help
 fill for selectors with spaces. mousemove and the other mouse commands act at a point instead. An action
 scrolls its element into view first, as Playwright does; profile counts that scroll in the action's step.`,
-    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mousemove', 'mouseclick', 'mousedown', 'mouseup', 'mousewheel'],
+    commands: ['click', 'dblclick', 'hover', 'drag', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mousemove', 'mouseclick', 'mousedblclick', 'mousedown', 'mouseup', 'mousewheel'],
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
@@ -106,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
@@ -121,15 +137,10 @@ 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: `Completion: @<id> <command> makes the REPL print [[pw-done:<id>:ok|error]] when it finishes.
-
-Unknown outcome: a command that timed out after it began acting on the page may or may not have done
-it. It says so (pw-repl send exits 2), and the REPL carries on.
-
-Server: pw-repl serve also takes commands on /tmp/pw-repl.sock; they show here as [server] lines.
+    intro: `Server: pw-repl serve also takes commands on /tmp/pw-repl.sock; they show here as [server] lines.
 
 Clients: pw-repl send -c <name> (or $PW_CLIENT) sends as a client of its own. It has a selected tab of
 its own, so clients do not move each other's; its commands show as [server:<name>] lines. modes and tab
@@ -143,7 +154,12 @@ selected tab, if any: (watch network:off routes:2 capture) pw>. modes lists them
 
 Times (requests, console, watch) are local, with their UTC offset: 18:16:15.721-06:00.
 
-Dialogs are reported and never answered on their own; dialog accept or dismiss answers one, from any client, whoever opened it.`,
+Dialogs are reported and never answered on their own; dialog accept or dismiss answers one, from any client, whoever opened it.
+
+Unknown outcome: a command that timed out after it began acting on the page may or may not have done
+it. It says so (pw-repl send exits 2), and the REPL carries on.
+
+Completion: @<id> <command> makes the REPL print [[pw-done:<id>:ok|error]] when it finishes.`,
     commands: ['modes', 'dialog', 'help', 'quit'],
   },
 };
@@ -197,6 +213,8 @@ afresh.`,
       ['[button]', 'left, right or middle, after a ref or a quoted selector: click e5 right. Default: left.'],
     ],
     options: [
+      ['--button=<button>', 'the button, after any selector: click #menu --button=right. Over send, the shell takes the quotes, so pw-repl send click \'#menu\' right clicks a selector "#menu right": use --button, or quote it twice (\'"#menu"\').'],
+      ['--click-count=<n>', 'clicks this many times at once, as Playwright\'s clickCount: 2 is a double-click (as dblclick), 3 a triple-click, which selects a line of text or all of a field\'s. 1 to 3. Default: 1.'],
       ['--modifiers=<keys>', 'keys held down meanwhile, comma-separated: Alt, Control, ControlOrMeta, Meta, Shift.'],
     ],
     detail: `Several matches: hidden ones and ones covered by something else (a dialog's overlay) are passed over,
@@ -208,8 +226,23 @@ it to be ready.
 Timed out after it began acting, it says what stopped it (e.g. <div class="overlay"> intercepts pointer
 events) and that the outcome is unknown; Playwright's full call log goes to the REPL's pane or log.`,
   },
-  dblclick: { usage: 'dblclick <selector> [button]', summary: 'double-click, choosing the match as click does' },
+  dblclick: {
+    usage: 'dblclick <selector> [button]',
+    summary: 'double-click, as click does, with its options',
+    detail: `click --click-count=2, as Playwright's dblclick is. For a triple-click: click --click-count=3.`,
+  },
   hover: { usage: 'hover <selector>', summary: 'hover, choosing the match as click does' },
+  drag: {
+    usage: 'drag <from> <to>',
+    summary: 'drag one element onto another',
+    args: [
+      ['<from> <to>', 'selectors or snapshot refs, each quoted if it has spaces: drag e5 e9, drag "text=Item 1" "#done ul".'],
+    ],
+    detail: `As Playwright's dragTo: it hovers the first match of <from>, presses the left button, hovers the
+first match of <to>, and releases, waiting up to 5s in all for each to be ready. An HTML5 drag (a
+draggable element) gets dragstart, dragover and drop; any other gets pointer and mouse events. A drag
+through points of its own: mousemove, mousedown, mousemove, mouseup.`,
+  },
   mousemove: {
     usage: 'mousemove <x> <y>',
     summary: 'move the mouse to a point in the viewport',
@@ -220,7 +253,7 @@ events) and that the outcome is unknown; Playwright's full call log goes to the
 eval (r => [r.x + r.width / 2, r.y + r.height / 2])(document.querySelector("#map")
   .getBoundingClientRect())
 
-A click at a point: mouseclick <x> <y>. A drag: mousedown, then mousemove to another point, then mouseup.`,
+A click at a point: mouseclick <x> <y>; a double-click: mousedblclick <x> <y>. A drag: mousedown, then mousemove to another point, then mouseup.`,
   },
   mouseclick: {
     usage: 'mouseclick <x> <y> [button]',
@@ -230,14 +263,30 @@ A click at a point: mouseclick <x> <y>. A drag: mousedown, then mousemove to ano
       ['[button]', 'left, right or middle. Default: left.'],
     ],
     options: [
+      ['--button=<button>', 'the button, as click\'s: mouseclick 400 300 --button=right.'],
+      ['--click-count=<n>', 'as click\'s: 2 is a double-click (as mousedblclick), 3 a triple-click. 1 to 3. Default: 1.'],
       ['--delay=<ms>', 'holds the button down this long between press and release, as Playwright\'s mouse.click delay. Default: 0.'],
     ],
     detail: `For what has no selector, such as a marker drawn on a canvas; anything a selector finds is better
 clicked with click, which waits for it. help mousemove shows how to find a point. The mouse stays at the point, for a mousewheel or mousedown after
 it. The cursor (help cursor) moves there first and shows a ring at the press.`,
   },
-  mousedown: { usage: 'mousedown [button]', summary: 'press a mouse button at the mouse (left, right, middle)' },
-  mouseup: { usage: 'mouseup [button]', summary: 'release a mouse button where the mouse is' },
+  mousedblclick: {
+    usage: 'mousedblclick <x> <y> [button]',
+    summary: 'double-click at a point in the viewport',
+    args: [
+      ['<x> <y>', 'CSS pixels from the top left of the tab\'s viewport, as for mousemove.'],
+      ['[button]', 'left, right or middle. Default: left.'],
+    ],
+    options: [
+      ['--button=<button>', 'the button, as click\'s.'],
+    ],
+    detail: `mouseclick --click-count=2, as Playwright's mouse.dblclick is: the page gets two clicks and a
+dblclick. Two mouseclicks are two single clicks, which fire no dblclick. For a triple-click: mouseclick
+<x> <y> --click-count=3.`,
+  },
+  mousedown: { usage: 'mousedown [button]', summary: 'press a mouse button at the mouse (left, right, middle)', detail: 'The button is a word or --button=<button>, as for mouseclick.' },
+  mouseup: { usage: 'mouseup [button]', summary: 'release a mouse button where the mouse is', detail: 'The button is a word or --button=<button>, as for mouseclick.' },
   mousewheel: {
     usage: 'mousewheel <dx> <dy>',
     summary: 'turn the wheel where the mouse is',
@@ -259,14 +308,19 @@ scrolled or redrawn. While recording, it scrolls in eased steps over up to 1s (h
       ['--submit', 'at the end: presses Enter in it afterwards.'],
     ],
     detail: `Examples: fill #name Ada Lovelace, fill "text=Your name" Ada, fill e7 Ada. It sets the whole value at
-once, even while recording: type shows it being typed.`,
+once, even while recording: type shows it being typed.
+
+At the prompt and in a send --file line, \\n, \\t and \\r in double quotes are a newline, a tab and a
+carriage return (fill #notes "line 1\\nline 2"), and \\\\ is a backslash. Over send, the shell's quoting comes
+first, and its "a\\nb" is a literal \\n, typed as a backslash and an n: give it a real newline, as
+$'line 1\\nline 2'.`,
   },
   type: {
     usage: 'type [--delay=<ms>] [<selector>] <text> [--submit]',
     summary: 'type key by key after what the field holds',
     args: [
       ['[<selector>]', 'as for fill. Without it (one word, or one quoted), into what has focus: type "garden hose".'],
-      ['<text>', 'the rest of the line, as fill\'s value.'],
+      ['<text>', 'the rest of the line, as fill\'s value: a newline in it presses Enter, which in a textarea starts a new line (help fill says how to give one).'],
     ],
     options: [
       ['--delay=<ms>', 'right after type: the gap between keys. Default: none, or 60 while the tab records.'],
@@ -320,10 +374,13 @@ 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.
 
+Quotes: some names and text are quoted, YAML-style, as one with a quote mark in it is, and their quotes
+are escaped: paragraph: "Say \\"hi\\"" is the text Say "hi" on the page, with no backslashes.
+
 --grep: a hit with no named element around it prints without a path. A hit on text (a label) keeps the
 ref of the element holding it, so snapshot <that ref> shows what sits beside it, such as the value next
 to the label.
@@ -381,7 +438,14 @@ one no selector finds alone) stays a comment saying why, and the save says how m
 ends with the last step, not with what it brought: to end on a result that comes later (search results
 loading), add a wait for it at the end (wait text ...).
 
-Shared: every client sees the same steps, and watch new's place is shared.`,
+Watching someone: read a response body over 100 KB that matters as soon as it shows in requests, since
+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.
+
+Shared: every client sees the same steps, and watch new's place is shared: when another client watches
+the tab too, read it with watch <n>, since each one's watch new would hide steps from the other.`,
     moreAbout: 'bodies kept, --live timing, what --changes misses, one --next-tab at a time, and what watch save leaves out',
     more: `From its first watch on, a tab keeps response bodies of up to 100 KB, so body <#> still shows one
 after the tab navigates, even when the page navigates as soon as the request answers.
@@ -465,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.'],
@@ -473,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
@@ -526,9 +590,9 @@ shows in screenshots and recordings. Selectors, snapshot and text don't see it,
     ],
     detail: `The REPL's clicks and typing don't move a pointer on screen, so a recording shows things happening
 with nothing pointing at them. With the cursor on, these commands move it smoothly to their element or
-point before they act: click, dblclick, hover, fill, type <selector>, press <selector>, select, check,
-uncheck, upload, mousemove and mouseclick. Each move takes 150 to 600ms by distance (300 to 1000ms while the tab
-records), and the command waits for it. Clicks (click, dblclick, check, uncheck, mouseclick, mousedown, and upload
+point before they act: click, dblclick, hover, drag (to each end), fill, type <selector>, press <selector>, select, check,
+uncheck, upload, mousemove, mouseclick and mousedblclick. Each move takes 150 to 600ms by distance (300 to 1000ms while the tab
+records), and the command waits for it. Clicks (click, dblclick, check, uncheck, mouseclick, mousedblclick, mousedown, and upload
 when it clicks a button) show a ring where they land.
 
 Only the drawing moves: no mouse events are sent along the way, so the page gets the same input as with
@@ -541,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
@@ -594,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.
@@ -607,13 +671,15 @@ goes on recording. There is no --mp4 or --webm: the file's ending picks the form
     summary: 'show, set or unset the viewport size',
     args: [
       ['<W>x<H>', 'sets the selected tab\'s page to that size, until viewport off, modes off or the REPL exits. The window is not resized.'],
-      ['off', 'back to the window\'s size.'],
-      ['(none)', 'shows the size, and whether it was set or is the window\'s.'],
+      ['off', 'back to the window\'s page area.'],
+      ['(none)', 'shows the size, and whether it was set or is the window\'s page area.'],
     ],
     detail: `emulate mobile sets a phone's size instead, and each refuses while the other is on.
 
-The window's size here is the size of the page in it. Chromium's --window-size flag sizes the whole
+The window's page area is the page's size without a viewport set. Chromium's --window-size flag sizes the whole
 window, frame included, so the page is smaller: --window-size=1280,900 gives 1280x757 in a headless one.
+--launch starts its Chromium at --window-size=1280,800 (a page of 1280x657 headless), unless the flags
+after -- give one; a profile it was given and has used before may keep its own last size.
 For a page of an exact size, use viewport <W>x<H>.`,
   },
   emulate: {
@@ -638,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.'],
@@ -654,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: {
@@ -712,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.'],
@@ -749,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
@@ -780,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
@@ -798,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.'],
@@ -824,21 +890,28 @@ 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.'],
-      ['<function> <ref>', 'calls it with that element: eval "el => el.textContent" e5.'],
+      ['<function> <ref>', 'calls it with that element: eval "el => el.textContent" e5. Quoted, its \\n is a newline and its \\" a quote: write \\\\n for a JS string\'s \\n.'],
     ],
     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>',
@@ -852,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]',
@@ -908,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.`,
   },
 };
 
@@ -990,9 +1081,11 @@ Different on purpose, since the browser may be someone else's too:
   if (Object.hasOwn(TOPICS, topicOrCommand)) {
     const topic = TOPICS[topicOrCommand];
     const text = [topic.intro, '', ...commandLines(topic.commands)].join('\n');
-    // A topic can share its name with a command (network); both are shown.
-    return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${renderCommand(topicOrCommand)}` : text;
+    // A topic can share its name with a command (network): the topic, and where the command's help is.
+    return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${topicOrCommand} is also a command: help ${topicOrCommand} --command` : text;
   }
+  const asCommand = /^(\S+)\s+--command$/.exec(topicOrCommand);
+  if (asCommand && Object.hasOwn(COMMANDS, asCommand[1])) return renderCommand(asCommand[1]);
   if (Object.hasOwn(COMMANDS, topicOrCommand)) return renderCommand(topicOrCommand);
   // Not a topic: the mouse commands are in interact, with the others that act on the page.
   if (topicOrCommand === 'mouse') {
@@ -1020,4 +1113,4 @@ function notFound(topic) {
   return `No help for ${topic}. Topics: ${Object.keys(TOPICS).join(', ')}`;
 }
 
-module.exports = { render, notFound, TOPICS, COMMANDS };
+module.exports = { render, notFound, TOPICS, COMMANDS, TASKS, MODES };