pw-repl 0.12.8 → 0.14.0

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.
@@ -214,6 +216,7 @@ afresh.`,
       ['--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.'],
+      ['--force', 'skips Playwright\'s actionability checks (enabled, stable, not covered), as Playwright\'s force. For an element marked aria-disabled, which Playwright counts as disabled, that a page keeps clickable (a greyed menu item that says why). Several matches are still chosen from as below; a covered ref or single match is clicked where it is, so what covers it gets the click.'],
     ],
     detail: `Several matches: hidden ones and ones covered by something else (a dialog's overlay) are passed over,
 and it says which it used: Clicked: text=Buy (match 3 of 4; ...), or names the first when it was the
@@ -221,8 +224,10 @@ one: (the first of 2 matches: <h1> Buy), as it may not be the one meant. If none
 says why for each and does nothing. A ref, or a single match, is clicked as it is, waiting up to 5s for
 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.`,
+Timed out, it says what stopped it, and Playwright's full call log goes to the REPL's pane or log. Stopped by
+one of Playwright's checks before the click is sent, it did nothing: the element is not visible, enabled
+or stable, or <div class="overlay"> intercepts pointer events (something covers it). Stopped after it was
+sent, as when the page stops answering, the outcome is unknown.`,
   },
   dblclick: {
     usage: 'dblclick <selector> [button]',
@@ -372,7 +377,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,15 +532,15 @@ 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.'],
-      ['[name]', 'saved as screenshot-<name>.png; letters, digits, underscores and hyphens. Default: a timestamp.'],
+      ['[name]', 'saved as screenshot-<name>.png; letters, digits, underscores and hyphens. Default: a timestamp. A word with a / or ending in .png, .jpg or .jpeg is a file instead, as --filename: x.png is the file x.png, not screenshot-x.png. At the prompt, a path with a space goes in --filename="<file>"; through pw-repl send, either works.'],
     ],
     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 +608,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 +661,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 +707,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 +723,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 +781,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 +818,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 +849,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 +867,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 +893,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,14 +905,20 @@ 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>',
-    summary: 'send one CDP command through a temporary session',
+    summary: 'send one CDP command to the selected tab',
     args: [
       ['<method>', 'a CDP method: Network.getCookies.'],
       ['<JSON object>', 'its parameters: {} for none.'],
@@ -915,8 +926,35 @@ already happened (requests lists those).`,
     options: [
       ['--all', 'the whole result, not capped.'],
     ],
-    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.`,
+    detail: `A command goes through a temporary session, detached afterwards, so subscriptions and settings do not
+persist (input aside, below). Browser.close and Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog
+answers one.
+
+Input (Input.dispatchTouchEvent, dispatchMouseEvent, the synthesize gestures): through a session kept for
+the tab, so a sequence sent one call at a time stays one sequence (Chrome drops it when the session that
+began it detaches). End one before other commands (touchEnd, or touchCancel to drop it): left open, the
+next click lands mid-touch. Input.setIgnoreInputEvents and setInterceptDrags go through a temporary session,
+as they would otherwise stay on and break later clicks.
+
+Touch (under emulate mobile, for pointerType touch): touchStart and touchEnd sent this way make a tap, with
+click, and two in a row a dblclick; held, it is still a tap, with no contextmenu. Chrome takes a tap sent
+soon after another gesture as part of it, with no click: up to a few seconds after a drag (sleep 3s). The synthesize gestures
+(Input.synthesizeTapGesture, synthesizePinchGesture, synthesizeScrollGesture) send pointer and touch events
+but no click, dblclick or contextmenu.`,
+  },
+  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 +1011,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.`,
   },
 };
 

package/lib/inspect.js

@@ -5,16 +5,17 @@ const { state, withTimeout } = require('./state');
 const out = require('./output');
 const { printOutput } = out;
 const { devices } = require('playwright-core');
-const { toSelector, REF, unquote } = require('./syntax');
-const { regexOf, COMMAND_TIMEOUT, BUSY_PAGE } = require('./util');
+const { toSelector, REF, SCREENSHOT_FILE, unquote } = require('./syntax');
+const { regexOf, COMMAND_TIMEOUT, BUSY_PAGE, TIME, parseDuration, durationText } = require('./util');
 const { tabState } = require('./tabstate');
-const { keptSession } = require('./cdp');
+const { noteWritten } = require('./written');
+const { keptSession, keepDrawing } = require('./cdp');
 const { CDP_REFUSED } = require('./dialogs');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
 const { deviceMetrics, viewportMetrics, reapplyMetrics } = require('./emulation');
 
-const SCREENSHOT_DELAY_MAX = 60;
+const SCREENSHOT_DELAY_MAX = 60000;
 // What inputs lists: native form controls, and elements that are one by their ARIA role.
 const INPUTS = ['input', 'select', 'textarea', ...['checkbox', 'radio', 'switch', 'combobox', 'listbox', 'textbox', 'searchbox', 'slider', 'spinbutton'].map(role => `[role=${role}]`)].join(', ');
 
@@ -111,15 +112,14 @@ function compactSnapshot(text) {
   return lines.join('\n');
 }
 
-const WAIT_DEFAULT = 10;
-const WAIT_MAX = 120;
+const WAIT_DEFAULT = 10000;
 
 // Gone once no match is visible, whether it was removed or hidden.
 async function waitGone(locator, what, timeout) {
   try {
     await locator.filter({ visible: true }).first().waitFor({ state: 'detached', timeout });
   } catch (error) {
-    if (/Timeout \d+ms exceeded/.test(error.message)) throw new Error(`Still visible after ${timeout / 1000}s: ${what}`);
+    if (/Timeout \d+ms exceeded/.test(error.message)) throw new Error(`Still visible after ${durationText(timeout)}: ${what}`);
     throw error;
   }
   out.log(`Gone: ${what}`);
@@ -127,9 +127,9 @@ async function waitGone(locator, what, timeout) {
 
 const SNAPSHOT_HINT_LINES = 60;
 
-function evaluated(promise) {
-  return withTimeout(promise, 'Page evaluation', COMMAND_TIMEOUT).catch(error => {
-    if (error.message === 'Page evaluation timed out') error.message += ` after ${COMMAND_TIMEOUT / 1000}s; ${BUSY_PAGE}`;
+function evaluated(promise, timeout = COMMAND_TIMEOUT) {
+  return withTimeout(promise, 'Page evaluation', timeout).catch(error => {
+    if (error.message === 'Page evaluation timed out') error.message += ` after ${durationText(timeout)}: eval --timeout=<time> waits longer (and send -t with it), but ${BUSY_PAGE}`;
     throw error;
   });
 }
@@ -316,7 +316,7 @@ const commands = {
   },
 
   async screenshot(args) {
-    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <seconds>] [name | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens.';
+    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <time>] [name | <file> | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens; a word with a / or ending in .png, .jpg or .jpeg is a file.';
     // The file first: a path may be quoted, with spaces in it.
     let file = null;
     const rest = (args || '').replace(/(?:^|\s)--filename(?:=|\s+)("(?:[^"\\]|\\.)*"|'[^']*'|\S+)/, (_, value) => { file = unquote(value); return ' '; });
@@ -334,9 +334,14 @@ const commands = {
       if (token === '--delay' || token === '-d') {
         const value = tokens[++i];
         // Capped low on purpose: a timed shot is human-in-the-loop, and a typo
-        // like `-d 300` would otherwise park the serialized command queue.
-        if (!value || !/^\d+$/.test(value) || Number(value) > SCREENSHOT_DELAY_MAX) throw new Error(`Usage: screenshot --delay <seconds> (maximum ${SCREENSHOT_DELAY_MAX})`);
-        delay = Number(value);
+        // like `-d 300s` would otherwise park the serialized command queue.
+        delay = parseDuration(value);
+        if (delay === null || delay > SCREENSHOT_DELAY_MAX) throw new Error(`Usage: screenshot --delay <time> (ms, or 5s; at most ${durationText(SCREENSHOT_DELAY_MAX)})`);
+        continue;
+      }
+      if (SCREENSHOT_FILE.test(token)) {
+        if (file) throw new Error(usage);
+        file = token;
         continue;
       }
       names.push(token);
@@ -345,9 +350,11 @@ const commands = {
     const name = names[0] || null;
     // Counted down out loud so a watcher can time a hover or menu state, and so
     // the wait is distinguishable from a hung command in a tmux capture.
-    for (let remaining = delay; remaining > 0; remaining--) {
-      out.log(`${remaining}...`);
-      await state.page.waitForTimeout(1000);
+    for (let left = delay; left > 0;) {
+      out.log(`${Math.ceil(left / 1000)}...`);
+      const step = left % 1000 || 1000;
+      await state.page.waitForTimeout(step);
+      left -= step;
     }
     // Named after the countdown so a default filename timestamps the capture.
     // A file given is relative to the REPL's folder; pw-repl send makes it the sender's.
@@ -388,6 +395,7 @@ const commands = {
       if (error.code === 'EEXIST') throw new Error(`Screenshot already exists: ${filepath}`);
       throw error;
     }
+    noteWritten(filepath, 'screenshot');
     out.log(`Saved: ${filepath}`);
   },
 
@@ -433,22 +441,22 @@ const commands = {
   },
 
   async wait(args) {
-    const usage = 'Usage: wait <selector> | wait text <text> | wait request <url-part|glob> | wait load, with optional [seconds]; --gone for a selector or text';
+    const usage = 'Usage: wait <selector> | wait text <text> | wait request <url-part|glob> | wait load, with an optional [time] (ms, or 30s); --gone for a selector or text';
     let tokens = (args || '').trim().split(/\s+/).filter(Boolean);
     const gone = tokens.includes('--gone');
     tokens = tokens.filter(t => t !== '--gone');
-    let seconds = WAIT_DEFAULT;
-    // A number last is the seconds, unless it is all there is to wait for: wait text 990.
+    // A time last is how long, unless it is all there is to wait for: wait text 990.
     const onlyWhat = (tokens[0] === 'text' || tokens[0] === 'request') && tokens.length === 2;
-    const tookSeconds = tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1]);
-    if (tookSeconds) seconds = Number(tokens.pop());
-    if (!tokens.length) throw new Error(`${usage} (1-${WAIT_MAX})`);
-    if (seconds < 1 || seconds > WAIT_MAX) {
-      // Most likely text that ends in a number, not seconds at all.
-      const text = tokens[0] === 'text' && !/^["']/.test(tokens[1]) ? `; for text that ends in a number, quote it: wait text "${tokens.slice(1).join(' ')} ${seconds}"` : '';
-      throw new Error(`wait takes 1-${WAIT_MAX} seconds (got ${seconds})${text}`);
+    const tookTime = tokens.length > 1 && !onlyWhat && TIME.test(tokens[tokens.length - 1]);
+    const given = tookTime ? tokens.pop() : null;
+    const timeout = given ? parseDuration(given) : WAIT_DEFAULT;
+    if (!tokens.length) throw new Error(usage);
+    if (!timeout) {
+      // Most likely text that ends in a number, not a time at all.
+      const text = tokens[0] === 'text' && !/^["']/.test(tokens[1]) ? `; for text that ends in a number, quote it: wait text "${tokens.slice(1).join(' ')} ${given}"` : '';
+      throw new Error(`wait takes a time over 0 (got ${given})${text}`);
     }
-    const timeout = seconds * 1000;
+    const within = durationText(timeout);
     // Said plainly, not as Playwright's call log.
     const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };
     const kind = tokens[0];
@@ -464,26 +472,36 @@ const commands = {
       }
       if (gone) return waitGone(state.page.getByText(what), what, timeout);
       // Text that ends in a number gives it up as the seconds, unless quoted: said when it times out.
-      const quote = tookSeconds && !/^["']/.test(tokens[1]) ? ` (${seconds} was taken as the seconds: wait text "${what} ${seconds}" waits for that text)` : '';
-      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${seconds}s${quote}`));
+      const quote = tookTime && !/^["']/.test(tokens[1]) ? ` (${given} was taken as the time: wait text "${what} ${given}" waits for that text)` : '';
+      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${within}${quote}`));
       out.log(`Visible: ${what}`);
       return;
     }
     const selector = toSelector(unquote(tokens.join(' ')));
     if (gone) return waitGone(state.page.locator(selector), tokens.join(' '), timeout);
-    await state.page.waitForSelector(selector, { state: 'visible', timeout }).catch(plainly(`No visible element matches ${tokens.join(' ')} within ${seconds}s`));
+    await state.page.waitForSelector(selector, { state: 'visible', timeout }).catch(plainly(`No visible element matches ${tokens.join(' ')} within ${within}`));
     out.log(`Visible: ${tokens.join(' ')}`);
   },
 
   async sleep(args) {
-    if (!args || !/^\d+$/.test(args) || Number(args) > 3600000) throw new Error('Usage: sleep <ms> (maximum 3600000)');
-    await state.page.waitForTimeout(Number(args));
+    const ms = parseDuration(args);
+    if (ms === null) throw new Error('Usage: sleep <time> (ms, or 3s)');
+    await state.page.waitForTimeout(ms);
     // sleep 3 is easily meant as seconds.
-    out.log(Number(args) < 100 ? `Slept ${args}ms (sleep takes milliseconds: sleep ${args}000 is ${args}s)` : `Slept ${args}ms`);
+    out.log(/^\d+$/.test(args) && ms < 100 ? `Slept ${args}ms (sleep takes milliseconds: sleep ${args}s for ${args}s)` : `Slept ${durationText(ms)}`);
   },
 
   async eval(args, all) {
     if (!args) throw new Error('Usage: eval <js-expression>');
+    // eval --timeout=<time> [--file=...] <JavaScript>: how long the page has to answer.
+    let timeout = COMMAND_TIMEOUT;
+    const timed = /^--timeout(?:=|\s+)(\S+)(?:\s+([\s\S]*))?$/.exec(args.trim());
+    if (/^--timeout(?:[=\s]|$)/.test(args.trim())) {
+      timeout = parseDuration(timed?.[1]);
+      if (!timeout) throw new Error('Usage: eval --timeout=<time> <JavaScript>, a time in ms or with s: eval --timeout=60s ...');
+      args = timed[2] || '';
+      if (!args.trim()) throw new Error('Usage: eval --timeout=<time> <JavaScript>');
+    }
     let ref = null;
     // eval --file=<path> [<ref or selector>]: the file's text is what the line would be, over as many lines as
     // it likes. The rest of the line can only be the element, so any selector goes there, not only a ref.
@@ -509,9 +527,9 @@ const commands = {
       try {
         // Made from its text by the debugger, as eval is, so a page's CSP cannot
         // refuse it, and in the element's own frame, which may be an iframe.
-        const fn = await evaluated((await el.ownerFrame()).evaluateHandle(args));
+        const fn = await evaluated((await el.ownerFrame()).evaluateHandle(args), timeout);
         try {
-          printOutput(await el.evaluate((e, f) => f(e), fn), all);
+          printOutput(await evaluated(el.evaluate((e, f) => f(e), fn), timeout), all);
         } finally {
           await fn.dispose().catch(() => {});
         }
@@ -531,13 +549,13 @@ const commands = {
     const call = `const value = (${args}\n); return typeof value === 'function' ? value() : value;`;
     if (awaits && !single && compiles(AsyncFunction, args)) {
       const session = await keptSession(state.page);
-      const { result, exceptionDetails } = await evaluated(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }));
+      const { result, exceptionDetails } = await evaluated(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }), timeout);
       if (exceptionDetails) throw new Error(exceptionDetails.exception?.description || exceptionDetails.text);
       printOutput(result.value !== undefined ? result.value : result.description ?? 'undefined', all);
       return;
     }
     const expression = single ? `(${awaits ? 'async ' : ''}() => { ${call} })()` : args;
-    const value = await evaluated(state.page.evaluate(expression));
+    const value = await evaluated(state.page.evaluate(expression), timeout);
     // An empty string is shown as one, not as no output at all.
     printOutput(value === '' ? '""' : value, all);
     // Quotes around the whole of it, as a shell's quoting sent on, make it a string, not code to run:
@@ -547,6 +565,38 @@ const commands = {
     }
   },
 
+  // Read through the selected tab, granted clipboard-read for that moment only. A browser with a
+  // window reads the system's clipboard, the user's, so only with --shared-clipboard.
+  async clipboard(args, all) {
+    const words = (args || '').trim().split(/\s+/).filter(Boolean);
+    if (words.some(w => w !== '--shared-clipboard')) throw new Error('Usage: clipboard [--shared-clipboard]');
+    const browser = await state.browser.newBrowserCDPSession();
+    try {
+      // Headless says so in its user agent (its product name says Chrome either way).
+      const { userAgent } = await browser.send('Browser.getVersion');
+      if (!/\bHeadlessChrome\//.test(userAgent) && !words.length) {
+        throw new Error('This browser has a window, so its clipboard is the computer\'s: whatever its user last copied, a password too. clipboard --shared-clipboard reads it anyway; ask them first. A headless browser (--launch, without --headed) has a clipboard of its own.');
+      }
+      const p = state.page;
+      const origin = await evaluated(p.evaluate(() => (isSecureContext && location.origin !== 'null' ? location.origin : null)));
+      if (!origin) throw new Error(`The selected tab (${p.url()}) is not a secure page, and only one can read the clipboard: https, or http on localhost`);
+      const permission = { name: 'clipboard-read' };
+      const before = await p.evaluate(() => navigator.permissions.query({ name: 'clipboard-read' }).then(s => s.state));
+      // readText also needs the page focused: a tab the REPL uses is told it is (help tab).
+      await keepDrawing(p);
+      await browser.send('Browser.setPermission', { permission, setting: 'granted', origin });
+      try {
+        const granted = await p.evaluate(() => navigator.permissions.query({ name: 'clipboard-read' }).then(s => s.state));
+        if (granted !== 'granted') throw new Error('The browser did not let the selected tab read the clipboard: a tab in a private window, or in a browser context of its own, does not take the grant');
+        printOutput(await evaluated(p.evaluate(() => navigator.clipboard.readText())), all);
+      } finally {
+        await browser.send('Browser.setPermission', { permission, setting: before, origin }).catch(() => {});
+      }
+    } finally {
+      await browser.detach().catch(() => {});
+    }
+  },
+
   async cdp(args, all) {
     const match = /^(\S+)\s+([\s\S]+)$/.exec(args || '');
     if (!match) throw new Error('Usage: cdp <method> <JSON object>');
@@ -554,6 +604,13 @@ const commands = {
     if (match[1] === 'Page.handleJavaScriptDialog') throw new Error(CDP_REFUSED);
     const params = JSON.parse(match[2]);
     if (!params || Array.isArray(params) || typeof params !== 'object') throw new Error('Parameters must be a JSON object');
+    // Input sent through the tab's kept session: Chrome drops a touch or mouse sequence when the session
+    // that began it detaches. Not Input's two switches, which would stay on and break later clicks.
+    if (/^Input\./.test(match[1]) && !['Input.setIgnoreInputEvents', 'Input.setInterceptDrags'].includes(match[1])) {
+      const kept = await keptSession(state.page);
+      printOutput(await withTimeout(kept.send(match[1], params), 'CDP operation', COMMAND_TIMEOUT), all);
+      return;
+    }
     const operation = async () => {
       const cdp = await state.page.context().newCDPSession(state.page);
       try {

package/lib/output.js

@@ -4,14 +4,21 @@ const OUTPUT_LIMIT = 12000;
 
 let sink = null;
 
+// A cancelled command still running prints to the pane only, never into the next command's answer.
+let cancelled = () => false;
+
+function onCancelled(fn) {
+  cancelled = fn;
+}
+
 function log(text) {
   console.log(text);
-  if (sink) sink.push(String(text));
+  if (sink && !cancelled()) sink.push(String(text));
 }
 
 function error(text) {
   console.error(text);
-  if (sink) sink.push(String(text));
+  if (sink && !cancelled()) sink.push(String(text));
 }
 
 // Commands run one at a time, so a single sink is enough. Lines printed by
@@ -86,4 +93,4 @@ function printOutput(value, all = false, footer = '') {
   log(footer ? `${text}\n${footer}` : text);
 }
 
-module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, onSelectedTab, printOutput };
+module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, onSelectedTab, onCancelled, printOutput };