pw-repl 0.12.5 → 0.12.7

package/AGENTS.md

@@ -104,7 +104,7 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 
 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, a click on a link to a 204 waits out its timeout instead of returning (the test
+   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`.
 3. `npm version <patch|minor|major> -m "chore: release %s"` sets the version in `package.json` and

package/README.md

@@ -126,7 +126,7 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
   it. `pw-repl where` says what is running and how `send` will reach it.
 - For `send` to reach `run`, start it in tmux: `tmux new -s pw-repl`, then `pw-repl run` there.
 - A URL after the command opens in a new tab: `pw-repl serve http://localhost:3000`.
-- `--launch` works with each of them. Flags after `--` go to that Chromium.
+- `--launch` works with each of them. Flags after `--` go to that Chromium (flags only; a start URL goes before `--`).
 - A REPL of your own goes on a socket of its own: `-e /tmp/mine.sock` on every command, `serve`
   included, or set `PW_SOCKET`. `serve <port>` listens on TCP, on 127.0.0.1 only.
 

package/bin/pw-repl.js

@@ -38,7 +38,12 @@ $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 exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable.
+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 exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable. send -t is
+how long send waits for the answer (default 20s); it does not lengthen a command's own limits, such as
+the 5s an action waits for its element.
 
 send --file <file> runs each line of a file as a command, in order, as if typed at the REPL's prompt:
 quoted as the prompt reads it (no shell), with a file it records, uploads or saves relative to this
@@ -62,7 +67,7 @@ The browser must be running with --remote-debugging-port (default http://localho
 --launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
 a temporary profile, on a free port of its own, which pw-repl where names), prints the command it ran,
 and stops it with the REPL (Ctrl-C while it starts too); stop returns once that Chromium has exited.
-Flags after -- go to it; a --user-data-dir=<dir> among them is used instead of the temporary profile, and
+Flags after -- go to it, and only flags; a --user-data-dir=<dir> among them is used instead of the temporary profile, and
 kept. PW_CHROME picks which one. To set a browser up your own way, start it yourself and use PW_CDP_URL.
 
 In a tmux session named pw-repl, pw-repl send reaches pw-repl run without the server.`;
@@ -72,15 +77,49 @@ const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl s
 pw-repl help <topic | command [--all] | --all> shows one part of it; pw-repl help video and pw-repl
 help playwright-cli are guides.`;
 
-function usage() {
-  console.error(USAGE);
+const SUBCOMMANDS = ['run', 'serve', 'attach', 'stop', 'send', 'where', 'help', 'skill'];
+
+// What is wrong, then only the usage of the subcommand it is about: the whole of it would bury the line
+// that matters. With no message, the whole usage (-h after a subcommand).
+function usage(message, subcommand) {
+  if (!message) {
+    console.error(USAGE);
+    process.exit(64);
+  }
+  console.error(`pw-repl: ${message}`);
+  const lines = subcommand && USAGE.split('\n\n').find(block => new RegExp(`^(?:Usage:\\n)?  pw-repl ${subcommand}(?: |\\n|$)`).test(block));
+  if (lines) console.error(`Usage:\n${lines.replace(/^Usage:\n/, '')}`);
+  console.error(`pw-repl --help has the ${lines ? 'rest' : 'usage'}.`);
   process.exit(64);
 }
 
-// -e, -s, -c and -t, then the command words (unquoted words are one command).
-function parseSendArgs(args, allowCommand) {
+// A command line to copy, quoted as a shell reads it.
+function shellLine(words) {
+  return words.map(w => (/^[\w@%+=:,./-]+$/.test(w) ? w : `'${w.replace(/'/g, "'\\''")}'`)).join(' ');
+}
+
+// -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.
+function parseSendArgs(args, subcommand) {
+  const allowCommand = subcommand === 'send';
   const options = { endpoint: null, session: null, client: null, timeout: 20, command: '', file: null };
+  const given = new Set();
+  const take = (arg, value, after) => {
+    if (value === undefined) usage(`${arg} needs a value`, subcommand);
+    // Given before the command and after it, neither silently wins.
+    if (after && given.has(arg)) usage(`${arg} is given twice, ${value === true ? arg : `${arg} ${value}`} after the command; give it once`, subcommand);
+    given.add(arg);
+    if (arg === '--no-vars') options.noVars = true;
+    if (arg === '-e') options.endpoint = value;
+    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);
+    }
+  };
   let i = 0;
+  let dashes = false;
   for (; i < args.length; i++) {
     const arg = args[i];
     // playwright-cli's --raw: the output here is only the command's already.
@@ -95,22 +134,22 @@ function parseSendArgs(args, allowCommand) {
     // A file of commands, one per line, as typed at the prompt.
     if (arg.startsWith('--file=') && arg.length > 7) { options.file = require('path').resolve(arg.slice(7)); continue; }
     if (arg === '--file') {
-      if (args[i + 1] === undefined) usage();
+      if (args[i + 1] === undefined) usage('--file needs a file of commands', subcommand);
       options.file = require('path').resolve(args[++i]);
       continue;
     }
-    if (arg === '--no-vars') { options.noVars = true; continue; }
-    if (arg === '-e' || arg === '-s' || arg === '-c' || arg === '-t') {
-      const value = args[++i];
-      if (value === undefined) usage();
-      if (arg === '-e') options.endpoint = value;
-      if (arg === '-s') options.session = value;
-      if (arg === '-c') options.client = value;
-      if (arg === '-t') {
-        if (!/^\d+$/.test(value) || Number(value) < 1) usage();
-        options.timeout = Number(value);
-      }
-    } else if (arg === '--') { i++; break; } else break;
+    if (arg === '--no-vars') take(arg, true);
+    else if (arg === '-e' || arg === '-s' || arg === '-c' || arg === '-t') take(arg, args[++i]);
+    else if (arg === '--') { i++; dashes = true; break; } else break;
+  }
+  const words = args.slice(i);
+  // A word the shell kept whole ("a -t 3") is never one of these; an option with a bad value is still
+  // send's, refused, not the end of a URL or a selector.
+  while (allowCommand && !dashes) {
+    const last = words.length - 1;
+    if (last > 0 && words[last] === '--raw') words.pop();
+    else if (last > 0 && words[last] === '--no-vars') take(words.pop(), true, true);
+    else if (last > 1 && /^-[ecst]$/.test(words[last - 1])) { const value = words.pop(); take(words.pop(), value, true); } else break;
   }
   // An address that is refused (not loopback) is a usage error, said once, not a stack trace.
   const endpoint = options.endpoint || process.env.PW_ENDPOINT;
@@ -122,9 +161,9 @@ function parseSendArgs(args, allowCommand) {
       process.exit(64);
     }
   }
-  const words = args.slice(i);
-  if (!allowCommand && (words.length || options.file)) usage();
-  if (options.file && words.length) usage();
+  if (!allowCommand && options.file) usage(`--file is send's; ${subcommand} runs no commands`, subcommand);
+  if (!allowCommand && words.length) usage(`${subcommand} takes no command (got ${shellLine(words)})`, subcommand);
+  if (options.file && words.length) usage(`a command or --file, not both (got --file and ${shellLine(words)})`, subcommand);
   options.command = require('../lib/send').commandLine(words);
   return options;
 }
@@ -139,17 +178,35 @@ function startOptions(args, serve) {
   if (serve) options.background = flag('--background');
   options.launch = flag('--launch');
   options.headed = flag('--headed');
-  if ((options.headed || options.chromeArgs.length) && !options.launch) usage();
+  const subcommand = serve ? 'serve' : 'run';
+  if (options.headed && !options.launch) usage('--headed is for the Chromium --launch starts; add --launch', subcommand);
+  if (options.chromeArgs.length && !options.launch) usage('flags after -- go to the Chromium --launch starts; add --launch', subcommand);
+  // Chromium takes any word that is not a --switch as a page to open, and a headless one refuses a second.
+  const n = options.chromeArgs.findIndex(word => !word.startsWith('-'));
+  if (n !== -1) {
+    const [page, before] = [options.chromeArgs[n], options.chromeArgs[n - 1]];
+    // Most likely a switch's value given as a word of its own (--user-data-dir /tmp/p); a URL after a
+    // switch is a URL (--disable-gpu http://...).
+    if (before && /^--[^=]+$/.test(before) && !page.includes('://')) usage(`${page} after -- would go to Chromium as a page to open: it takes a switch's value as ${before}=${page}`, subcommand);
+    usage(`${page} after -- would go to Chromium as a page to open; only flags go after --. A start URL goes before --; for a browser already running, leave out --launch and set PW_CDP_URL`, subcommand);
+  }
   // -e <endpoint>, as send, attach, stop and where take it, or the endpoint as the first word.
   const e = rest.indexOf('-e');
   if (serve && e !== -1 && rest[e + 1] && looksLikeEndpoint(rest[e + 1])) {
     options.endpoint = rest.splice(e, 2)[1];
     // Two endpoints, one with -e: neither silently wins.
-    if (rest[0] && looksLikeEndpoint(rest[0])) usage();
+    if (rest[0] && looksLikeEndpoint(rest[0])) usage(`two endpoints, -e ${options.endpoint} and ${rest[0]}: give one`, subcommand);
   } else if (serve && rest[0] && looksLikeEndpoint(rest[0])) options.endpoint = rest.shift();
   // Otherwise the socket send would look for: PW_ENDPOINT, then PW_SOCKET, then the default.
   if (serve && !options.endpoint) options.endpoint = process.env.PW_ENDPOINT || process.env.PW_SOCKET || null;
-  if (rest.length > 1 || (rest[0] && rest[0].startsWith('-'))) usage();
+  const option = rest.find(word => word.startsWith('-'));
+  if (option === '-h' || option === '--help') usage();
+  if (option === '-e') {
+    usage(serve ? `-e takes an endpoint: a socket (/tmp/<name>.sock), a port, or 127.0.0.1:port (got ${rest[rest.indexOf('-e') + 1] ?? 'nothing'})` : 'run has no command server, so no endpoint; pw-repl serve has one', subcommand);
+  }
+  if (option === '--background') usage('--background is serve\'s: pw-repl serve --background', subcommand);
+  if (option) usage(`unknown option ${option}`, subcommand);
+  if (rest.length > 1) usage(`one start URL at most (got ${shellLine(rest)})`, subcommand);
   options.startUrl = rest[0] || null;
   return options;
 }
@@ -183,15 +240,15 @@ async function main() {
     }
     case 'attach':
     case 'stop': {
-      const options = parseSendArgs(args, false);
-      if (options.session) usage();
+      const options = parseSendArgs(args, subcommand);
+      if (options.session) usage(`-s is send's tmux session; ${subcommand} takes -e <endpoint>`, subcommand);
       // The same socket send would use when there is no -e: PW_ENDPOINT, then PW_SOCKET.
       const endpoint = options.endpoint || process.env.PW_ENDPOINT || process.env.PW_SOCKET || null;
       process.exit(await require('../lib/background')[subcommand]({ endpoint }));
     }
     // falls through never: process.exit above
     case 'send': {
-      const options = parseSendArgs(args, true);
+      const options = parseSendArgs(args, 'send');
       // help is fixed text, so it needs no browser: answer it here.
       const asksHelp = /^help(?:\s+(.*))?$/.exec(options.command);
       if (asksHelp) return help((asksHelp[1] || '').trim());
@@ -199,7 +256,7 @@ async function main() {
     }
     // falls through never: process.exit above
     case 'where':
-      process.exit(await require('../lib/send').where(parseSendArgs(args, false)));
+      process.exit(await require('../lib/send').where(parseSendArgs(args, 'where')));
     // falls through never
     case 'help': {
       const topic = args.join(' ').trim();
@@ -207,7 +264,7 @@ async function main() {
       return console.log(`${USAGE}\n\n${REPL_HELP}`);
     }
     case 'skill':
-      if (args.length) usage();
+      if (args.length) usage(`skill takes no arguments (got ${shellLine(args)})`, 'skill');
       return skill();
     case '-v':
     case '--version':
@@ -215,8 +272,17 @@ async function main() {
     case '-h':
     case '--help':
       return console.log(`${USAGE}\n\n${REPL_HELP}`);
-    default:
-      return usage();
+    default: {
+      // An option before the subcommand (pw-repl -t 30 send ...): say where it goes, with the line fixed.
+      if (subcommand.startsWith('-')) {
+        const all = [subcommand, ...args];
+        const named = all.find(word => SUBCOMMANDS.includes(word));
+        const fixed = named ? shellLine(['pw-repl', named, ...all.filter((word, n) => n !== all.indexOf(named))]) : `pw-repl send ${shellLine(all)} <command>`;
+        return usage(`${subcommand} is an option of a subcommand, and goes after it: ${fixed}`, named || 'send');
+      }
+      const url = /^[a-z][\w+.-]*:/i.test(subcommand) && !looksLikeEndpoint(subcommand) ? `; a start URL goes after run or serve: pw-repl run ${subcommand}` : '';
+      return usage(`${subcommand} is not a command (they are ${SUBCOMMANDS.join(', ')})${url}`);
+    }
   }
 }
 

package/lib/elements.js

@@ -5,7 +5,7 @@ const { state, onShutdown } = require('./state');
 const out = require('./output');
 const { takeOptions } = require('./cli-names');
 const { unquote, toSelector, keyName, splitSelector, REF } = require('./syntax');
-const { numbers, hints } = require('./util');
+const { numbers, hints, BUSY_PAGE } = require('./util');
 const { tabState } = require('./tabstate');
 const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
 const { recordingOf, stepTarget, pauseToShow } = require('./record');
@@ -95,8 +95,13 @@ async function onElement(selector, action, budget = 5000) {
 // or the check the element kept failing.
 function lastBlocker(log) {
   const lines = log.split('\n').map(line => line.trim().replace(/^-\s*/, ''));
+  // Its last step was the action itself: it was sent, and the page stopped answering, as when the click
+  // sets off a long task. A profile started now would miss that task: Chrome traces only what begins
+  // after it starts.
+  const sent = /^performing (\w+) action$/.exec(lines.filter(Boolean).pop() || '');
+  if (sent) return `the ${sent[1]} was sent, and may have landed, but the page stopped answering after it, likely busy with what it set off. A profile shows that only if it is on before the action: profile on, then the action again, if repeating it is safe`;
   const line = lines.reverse().find(l => /intercepts pointer events|element is not |element is outside|not attached|detached/.test(l));
-  if (!line) return 'it never became ready to act on';
+  if (!line) return `it never became ready to act on; ${BUSY_PAGE}`;
   return line.length > 240 ? `${line.slice(0, 240)}…` : line;
 }
 

package/lib/emulation.js

@@ -175,9 +175,10 @@ const commands = {
       out.log(`Viewport off: ${await viewportText()}`);
       return;
     }
-    const match = /^(\d+)x(\d+)$/.exec(arg);
+    const match = /^(\d+)x(\d+)$/i.exec(arg);
     const [w, h] = match ? [Number(match[1]), Number(match[2])] : [];
-    if (!w || !h) throw new Error('Usage: viewport [<width>x<height> | off]');
+    if (!match) throw new Error(`A size is <width>x<height>, e.g. viewport 1280x900 (got ${arg}). Usage: viewport [<width>x<height> | off]`);
+    if (!w || !h) throw new Error(`A width and a height are 1 or more (got ${arg})`);
     // Both set the screen size; whichever came last would win without saying so.
     if (tabState(state.page).emulation?.device) throw new Error('emulate mobile sets the size of the selected tab; emulate mobile off first');
     await setViewport(state.page, { width: w, height: h });

package/lib/help.js

@@ -69,7 +69,8 @@ tab on its own lists them all.`,
   interact: {
     intro: `Selectors are Playwright selectors (CSS, text=..., role=...) or snapshot refs such as e5.
 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.`,
+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'],
   },
   inspect: {
@@ -609,7 +610,11 @@ goes on recording. There is no --mp4 or --webm: the file's ending picks the form
       ['off', 'back to the window\'s size.'],
       ['(none)', 'shows the size, and whether it was set or is the window\'s.'],
     ],
-    detail: `emulate mobile sets a phone's size instead, and each refuses while the other is on.`,
+    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
+window, frame included, so the page is smaller: --window-size=1280,900 gives 1280x757 in a headless one.
+For a page of an exact size, use viewport <W>x<H>.`,
   },
   emulate: {
     usage: 'emulate [<what> [off] | off]',
@@ -734,6 +739,14 @@ each click or key press with its time to the next paint (input delay, handlers,
 burst of wheel or scroll events and each drag, with the main thread's busy time and the frames drawn and
 dropped. Times are from when it started. --all lists every long task and step, not the first ones.
 
+Long tasks read kind, what set it off, script: scripting, click event, app.js:120 handleClick. The kind
+is what most of its time went to (GC, style/layout); what set it off is the event or callback that began
+it (timer, promise callbacks); promise callbacks a click handler queued run in the click's task, so
+show as click event. No script is named when none of its code came from a page URL.
+
+A page that freezes: profile on, then do what freezes it. Your commands wait for the page meanwhile, and
+may time out, but the profile records it all; profile off once the page answers again.
+
 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
@@ -755,6 +768,13 @@ small hot function called in a loop can show as the loop's function.
 A wheel-zoom or drag the page handles in its own script (a map) shows as a step from its events; one the
 browser handles alone, with no listener, may show only as frames.
 
+A page gets scroll events for any scroll, input or not. Those next to a click or key press, with no wheel
+event (an action's scroll into view, or a handler's scrollTo), are that step's: it says the page
+scrolled. A burst of scroll events alone may also be the page's own script scrolling.
+
+A step under way when the profile began (an action still running at profile on) reads before, without
+its busy time: the trace has nothing from before it began.
+
 profile on and off each run console.timeStamp in the page, which prints nothing, so the tab is found in
 the trace even when its page did nothing. The trace is kept in a temporary folder until the next
 profile, or until the REPL stops.`,

package/lib/inspect.js

@@ -6,7 +6,7 @@ const out = require('./output');
 const { printOutput } = out;
 const { devices } = require('playwright-core');
 const { toSelector, REF, unquote } = require('./syntax');
-const { regexOf, COMMAND_TIMEOUT } = require('./util');
+const { regexOf, COMMAND_TIMEOUT, BUSY_PAGE } = require('./util');
 const { tabState } = require('./tabstate');
 const { keptSession } = require('./cdp');
 const { CDP_REFUSED } = require('./dialogs');
@@ -127,6 +127,13 @@ 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}`;
+    throw error;
+  });
+}
+
 // Each matching line (any part of it: role, name, flags such as [disabled]),
 // with the named elements it sits in, so a match can be placed without the
 // rest of the tree.
@@ -435,7 +442,12 @@ const commands = {
     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 || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
+    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 timeout = seconds * 1000;
     // Said plainly, not as Playwright's call log.
     const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };
@@ -480,7 +492,7 @@ 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 withTimeout((await el.ownerFrame()).evaluateHandle(unquote(onRef[1])), 'Page evaluation', COMMAND_TIMEOUT);
+        const fn = await evaluated((await el.ownerFrame()).evaluateHandle(unquote(onRef[1])));
         try {
           printOutput(await el.evaluate((e, f) => f(e), fn), all);
         } finally {
@@ -502,13 +514,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 withTimeout(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }), 'Page evaluation', COMMAND_TIMEOUT);
+      const { result, exceptionDetails } = await evaluated(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }));
       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 withTimeout(state.page.evaluate(expression), 'Page evaluation', COMMAND_TIMEOUT);
+    const value = await evaluated(state.page.evaluate(expression));
     // 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:

package/lib/profile.js

@@ -35,9 +35,15 @@ function workDir() {
 
 // A trace event naming the tab's frame, from its renderer, so an idle tab is still found in the trace.
 // console.timeStamp prints nothing in the console. A page held by a dialog does not answer: no wait.
-async function mark(page) {
+// At the end it waits two frames and 100ms more first: a click's timing reaches the trace only after the
+// paint that follows it, and its step takes in what the page did for 100ms after it.
+async function mark(page, { last = false } = {}) {
   if (page.isClosed()) return;
-  await Promise.race([page.evaluate(() => console.timeStamp('pw-repl profile')).catch(() => {}), new Promise(resolve => setTimeout(resolve, 1000))]);
+  const marked = page.evaluate(async settle => {
+    if (settle) await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(resolve, 100))));
+    console.timeStamp('pw-repl profile');
+  }, last).catch(() => {});
+  await Promise.race([marked, new Promise(resolve => setTimeout(resolve, 1000))]);
 }
 
 function forget(profile) {
@@ -121,7 +127,7 @@ function finishProfile() {
   clearTimeout(profile.cap);
   profile.unlisten();
   profile.finished = (async () => {
-    await mark(profile.page);
+    await mark(profile.page, { last: true });
     const endedAt = Date.now();
     const raw = path.join(workDir(), `raw-${process.pid}-${endedAt}.json`);
     try {
@@ -212,10 +218,13 @@ function printProfile(profile, all = false) {
     const steps = all ? s.steps : s.steps.slice(0, SHOWN * 2);
     for (const step of steps) {
       const span = step.latency != null
-        ? `${Math.round(step.latency)}ms to next paint (input delay ${Math.round(step.delay)}ms, handlers ${Math.round(step.handlers)}ms, presentation ${Math.round(step.presentation)}ms)`
+        ? `${Math.round(step.latency)}ms to next paint (input delay ${Math.round(step.delay)}ms, handlers ${Math.round(step.handlers)}ms, presentation ${Math.round(step.presentation)}ms)${step.scrolled ? ', the page scrolled' : ''}`
         : `${secs(step.end - step.start)}, ${step.events} event${step.events === 1 ? '' : 's'}`;
       const frames = step.frames ? `, frames ${step.frames} drawn, ${step.dropped} dropped` : '';
-      lines.push(`  ${at(step.start).padStart(8)}  ${step.kind}  ${span}; busy ${ms(step.busy)}${step.longest ? `, longest task ${ms(step.longest)}` : ''}${frames}`);
+      // One under way at profile on (an action still running): what ran before it began is not in the
+      // trace, so its busy time would be only the end of it.
+      const busy = step.start < s.t0 ? 'began before the profile: its busy time was not recorded' : `busy ${ms(step.busy)}${step.longest ? `, longest task ${ms(step.longest)}` : ''}`;
+      lines.push(`  ${(step.start < s.t0 ? 'before' : at(step.start)).padStart(8)}  ${step.kind}  ${span}; ${busy}${frames}`);
     }
     if (steps.length < s.steps.length) lines.push(`  (the first ${steps.length} of ${s.steps.length}; profile --all lists them all)`);
     if (profile.drawing && s.steps.some(step => step.frames)) {
@@ -307,4 +316,4 @@ onShutdown(async () => {
   if (dir) fs.rmSync(dir, { recursive: true, force: true });
 });
 
-module.exports = { commands, currentProfile, finishProfile };
+module.exports = { commands, currentProfile, finishProfile, printProfile };

package/lib/start.js

@@ -148,7 +148,8 @@ async function start(options) {
   rl.on('close', () => {
     if (state.stopping) return;
     endPromptLine();
-    out.error('Input ended; disconnecting.');
+    // With no terminal (an agent's shell, a pipe), input ends at once: say what runs without one.
+    out.error(process.stdin.isTTY ? 'Input ended; disconnecting.' : 'Input ended (stdin is not a terminal); disconnecting. pw-repl serve --background runs it without one.');
     runner.drained().then(() => shutdown(), () => shutdown())
       .then(beforeExit).then(() => process.exit(process.exitCode || 0));
   });

package/lib/trace.js

@@ -10,6 +10,9 @@ const BIG_REQUEST = 100 * 1024;
 const STEP_GAP = 300000;
 // A step's frames and busy time include this long after its last input, for what it drew.
 const STEP_TAIL = 100000;
+// How long before its scroll events a scroll's frame can be drawn: the compositor scrolls and draws, and
+// the page gets the scroll event in its next frame, later still when frames are being dropped.
+const SCROLL_LEAD = 50000;
 
 const BUCKETS = ['scripting', 'style/layout', 'paint', 'GC', 'other'];
 
@@ -433,8 +436,9 @@ function steps(tracks, events, { taskOf, tasks }) {
   const began = e => (e.task >= 0 ? events.ts[e.task] : e.ts);
   let burst = null;
   for (const e of dispatches.filter(d => /^(?:wheel|mousewheel|scroll)$/.test(d.type))) {
-    if (burst && e.ts - burst.end <= STEP_GAP) { burst.end = e.ts + e.dur; burst.events += 1; continue; }
-    burst = { kind: 'wheel/scroll', start: began(e), end: e.ts + e.dur, events: 1 };
+    const wheel = e.type !== 'scroll';
+    if (burst && e.ts - burst.end <= STEP_GAP) { burst.end = e.ts + e.dur; burst.events += 1; burst.wheel ||= wheel; continue; }
+    burst = { kind: 'wheel/scroll', start: began(e), end: e.ts + e.dur, events: 1, wheel };
     found.push(burst);
   }
   let down = null;
@@ -470,6 +474,16 @@ function steps(tracks, events, { taskOf, tasks }) {
       presentation: Math.max(0, latency - (processingEnd - startAt)),
     });
   }
+  // A page gets scroll events for any scroll, not only input: a click's scroll into view (dispatched in
+  // the frame after it, or before it when the click waited a frame) or its handler's scrollTo. Scroll
+  // events with no wheel event next to a click or key press are that step's.
+  for (const burst of found.filter(s => s.kind === 'wheel/scroll' && !s.wheel)) {
+    const step = found.find(s => s.latency != null && burst.start <= s.end + STEP_TAIL && burst.end >= s.start - STEP_TAIL);
+    if (!step) continue;
+    step.scrolled = true;
+    step.end = Math.max(step.end, burst.end);
+    found.splice(found.indexOf(burst), 1);
+  }
   found.sort((a, b) => a.start - b.start);
   const taskStarts = tasks.map(t => t.ts);
   const frames = tracks.frames.sort((a, b) => a.ts - b.ts);
@@ -488,7 +502,14 @@ function steps(tracks, events, { taskOf, tasks }) {
     }
     step.frames = 0;
     step.dropped = 0;
-    for (let k = lowerBound(frameTimes, step.start); k < frames.length && frames[k].ts < end; k++) {
+    let first = lowerBound(frameTimes, step.start);
+    // A scroll's own frame comes before its scroll event: the last frame before it, if close and not
+    // the step before's.
+    if (step.kind === 'wheel/scroll' && first > 0) {
+      const before = frames[first - 1].ts;
+      if (step.start - before <= SCROLL_LEAD && before > (found[i - 1]?.start ?? -Infinity)) first -= 1;
+    }
+    for (let k = first; k < frames.length && frames[k].ts < end; k++) {
       step.frames += 1;
       if (frames[k].dropped) step.dropped += 1;
     }

package/lib/util.js

@@ -7,6 +7,9 @@ const COMMAND_TIMEOUT = 15000;
 
 const MAX_EVENT_TEXT = 4000;
 
+// For a command that timed out waiting on the page.
+const BUSY_PAGE = 'a page busy with a long task does not answer meanwhile: profile on, then try again, shows what it is busy with';
+
 // For a command that needs a tab, when none is selected.
 const NO_TAB = 'No tab is selected; select one with tab <index|url-part>, or open one with tab new';
 
@@ -66,4 +69,4 @@ function playwrightBrowsersDir() {
   return path.join(cache, 'ms-playwright');
 }
 
-module.exports = { STOPPED_RECORDING, ENDED_UNSEEN, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock, playwrightBrowsersDir };
+module.exports = { BUSY_PAGE, STOPPED_RECORDING, ENDED_UNSEEN, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock, playwrightBrowsersDir };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-repl",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
   "keywords": [
     "playwright",

package/skill/SKILL.md

@@ -54,12 +54,12 @@ run one; each takes an optional start URL, which opens in a new tab.
 - Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
   own instead of connecting to one: headless unless `--headed`, in a temporary profile, on a free port
   of its own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns
-  once it has exited. It prints the command it ran; flags after `--` are passed to that Chromium, and a
-  `--user-data-dir=<dir>` among them is used instead of the temporary profile, and kept. Started again
-  in a kept profile, Chromium picks up where it left off, as it would for the user, headless too: its
-  tabs come back, and session cookies with them, so a login stays. They start loading before the REPL is
-  attached, so `requests` and `console` have only what came after, often nothing: `reload` for a full
-  record.
+  once it has exited. It prints the command it ran; flags after `--` are passed to that Chromium (only
+  flags: a start URL goes before `--`), and a `--user-data-dir=<dir>` among them is used instead of the
+  temporary profile, and kept. Started again in a kept profile, Chromium picks up where it left off, as
+  it would for the user, headless too: its tabs come back, and session cookies with them, so a login
+  stays. They start loading before the REPL is attached, so `requests` and `console` have only what
+  came after, often nothing: `reload` for a full record.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
   the tmux session `pw-repl`:
 
@@ -112,8 +112,9 @@ of a REPL of your own, which `send` refuses. The words after `send` are the comm
 `select`, `press`, `upload` and `wait`, a word quoted in your shell stays one word
 (`pw-repl send fill "text=Your name" Ada`, `pw-repl send wait text "Showing 1"`); other commands get the words as they are, joined by
 spaces (`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the
-whole line, spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL was
-started:
+whole line, spaces and all: `pw-repl send click "text=Your name"`. `send`'s own options (`-t`, `-c`, `-e`,
+`-s`, `--no-vars`) go before the command or after it (`pw-repl send open <url> -t 30`); after `--`, every
+word is the command's. It works however the REPL was started:
 
 - `run` (in tmux): `send` types the command into the tmux pane and reads the result back off the screen.
   It types only when the pane's last line is a bare prompt, so nothing lands in a shell or in the middle