pw-repl 0.8.2 → 0.10.0

package/AGENTS.md

@@ -41,9 +41,14 @@ If you hit a limitation or write a workaround, consider adding the capability to
   command or behaviour. In `test/repl.test.js` each test starts in a fresh tab of its own, and every mode
   is turned off after it; a test whose REPL quits, times out or is killed goes in
   `test/repl-alone.test.js`, with a Chromium of its own.
-- Help entries (`lib/help.js`) are plain paragraphs: `wrap()` lays each out at 104 columns, and keeps as
-  written a paragraph with a bullet, a table or an indented example. `test/fixtures` holds the rendered
-  help; after an intended change to it, save it again (the command is in `test/units.test.js`).
+- A command's help (`lib/help.js`) follows playwright-cli's layout: `usage` and `summary`; `args` and
+  `options`, one `[name, text]` each, with the default in its text (`Default: 750; 0 none.`); `detail`,
+  short paragraphs on what most callers need, a paragraph on one theme starting with a label (`Steps
+  (--steps):`); and `more`, with `moreAbout` naming what is in it, for what only goes wrong now and then,
+  shown by `help <command> --all` and `help --all`. An error about something in `more` ends by naming it
+  (`help record --all`). Paragraphs are plain: `wrap()` lays each out at 104 columns, and keeps as written
+  a paragraph with a bullet, a table or an indented example. `test/fixtures` holds the rendered help;
+  after an intended change to it, save it again (the command is in `test/units.test.js`).
 - Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`).
   Compare with the last commit that has one (`git log --grep='npm test:'`): a run that grew by more than
   a few seconds means a slow test crept in, usually one waiting out a real timeout (5s for a click).

package/README.md

@@ -78,8 +78,8 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 - For `send` to reach `run`, start it in tmux: `tmux new -s playwright-repl`, then `pw-repl run` there.
 - A URL after the command opens in a new tab: `pw-repl run http://localhost:3000`.
 - `--launch` works with each of them; flags after `--` go to that Chromium.
-- `serve` takes a socket of its own (`pw-repl serve --background /tmp/mine.sock`; then `-e /tmp/mine.sock`
-  for `send`, `attach`, `stop` and `where`), or `serve <port>` for TCP on 127.0.0.1.
+- A socket of its own: `-e /tmp/mine.sock` on every command, `serve` included (`pw-repl serve --background
+  -e /tmp/mine.sock`), or `PW_SOCKET`; `serve <port>` listens on TCP on 127.0.0.1.
 - A background REPL cannot be brought back like a Ctrl-Z job; `attach` is how you get back to it, from
   any terminal.
 
@@ -98,9 +98,9 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | show an agent what I do              | `watch on`, click around in the browser, then `watch`                                 |
 | see each step as I click             | `watch on --live`                                                                     |
 | record requests and console together | `capture on`, then `capture off`                                                      |
-| record a video of the page           | `record on`, then `record off` (`help video` for the other ways)                      |
+| record a video of the page           | `record on`, then `record off` (`help video` for a take with a pointer)               |
 | show a pointer where the agent acts  | `cursor on`, then `cursor off` (in screenshots and videos)                            |
-| point something out on the page      | `highlight <ref>` (`--style=<css>` to restyle it), then `highlight off`               |
+| point something out on the page      | `highlight <ref>`: a box, unlabelled unless `--labels on`; `highlight off` hides it   |
 | break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `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`                                                                        |
@@ -112,8 +112,8 @@ Everything else is in `help <topic>`; `help <command>` has usage and caveats.
 
 `watch`, `capture`, `route`, `network off` or `slow`, `emulate`, `viewport`, `record`, `highlight` and `cursor`
 stay on until you turn them off: `watch on|off`, `capture on|off`, `route ...|route off`, `network off|slow|on`,
-`emulate ...|emulate off`, `viewport <WxH>|viewport off`, `record on|off`, `highlight <selector>|highlight off`,
-`cursor on|off`.
+`emulate ...|emulate off`, `viewport <WxH>|viewport off`, `record on|off`, `highlight <selector>|highlight off`
+(and `highlight --labels on|off`), `cursor on|off`.
 While any are on in the selected tab, the prompt shows them: `(watch network:off routes:2) pw>`. `modes`
 lists them for every tab, and `modes off` turns them all off.
 
@@ -125,7 +125,7 @@ their own show their state and what you can run next.
 [playwright-cli](https://github.com/microsoft/playwright-cli) is Microsoft's command line for agents. It
 gives each agent a browser session of its own; pw-repl shares one browser between a person and agents.
 Its command names and most of their options work here too (`help playwright-cli` lists them), and where
-pw-repl differs, it is because someone else may be using the browser:
+pw-repl differs, it is mostly because someone else may be using the browser:
 
 - `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
 - Routes, network and emulation apply to one tab, not the whole browser.
@@ -133,6 +133,8 @@ pw-repl differs, it is because someone else may be using the browser:
 - There is no snapshot after every command, since a person reads the REPL too; `snapshot` shows one.
 - Instead of `-s=<session>`, an agent is a client of its own (`send -c <name>`).
 - `watch` records what a person does as steps with their requests, not as generated code.
+- `highlight` draws its box without Playwright's locator label, which covers what is below it and puts
+  selectors in screenshots and videos; `highlight --labels on` shows it.
 
 For a browser of its own per agent, isolated sessions, traces, video, PDFs or generated test code,
 playwright-cli is the better fit. `record on` records a tab's page, and `cursor on` draws a pointer where the

package/bin/pw-repl.js

@@ -7,7 +7,7 @@ const USAGE = `Usage:
   pw-repl run [--launch [--headed]] [start-url] [-- <chromium flags>]
       connect to the browser and open the prompt
 
-  pw-repl serve [--background] [--launch [--headed]] [endpoint] [start-url] [-- <chromium flags>]
+  pw-repl serve [--background] [--launch [--headed]] [[-e] endpoint] [start-url] [-- <chromium flags>]
       the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/playwright-repl.sock);
       --background runs it detached, with its output in a log next to the socket
 
@@ -17,8 +17,8 @@ const USAGE = `Usage:
   pw-repl stop [-e endpoint]
       stop a background REPL, and say what became of each recording it ended
 
-  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] <command...>
-      run one command in a running REPL and print its output
+  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] <command...> | --file <file>
+      run one command in a running REPL and print its output; --file runs a file of them, one per line
 
   pw-repl where [-e endpoint | -s session]
       say which REPL send would reach
@@ -31,13 +31,20 @@ const USAGE = `Usage:
 
 send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/playwright-repl.sock)
 is there, and the tmux session (-s, $PW_TMUX_SESSION, default playwright-repl) otherwise. If the socket
-exists but nothing answers, send fails rather than fall back.
+exists but nothing answers, send fails rather than fall back. serve without an endpoint serves on that
+same one: $PW_ENDPOINT, then $PW_SOCKET, then the default.
 
 send -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 --file <file> runs each line of a file as a command, in order, as if typed at the REPL's prompt:
+quoted as the prompt reads it (no shell), with a file it records, uploads or saves relative to this
+folder, as on send's command line, and # comments and blank lines skipped. It stops at the first
+command that fails, saying its line, with its exit status. -t is each command's own limit. Other
+clients' commands can run between its lines, on their own tabs.
+
 The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
 
 --launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
@@ -50,8 +57,8 @@ In a tmux session named playwright-repl, pw-repl send reaches pw-repl run withou
 
 const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl send help here (no REPL needed).
 
-pw-repl help <topic | command | --all> shows one part of it; pw-repl help video and pw-repl help
-playwright-cli are guides.`;
+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);
@@ -60,7 +67,7 @@ function usage() {
 
 // -e, -s, -c and -t, then the command words (unquoted words are one command).
 function parseSendArgs(args, allowCommand) {
-  const options = { endpoint: null, session: null, client: null, timeout: 20, command: '' };
+  const options = { endpoint: null, session: null, client: null, timeout: 20, command: '', file: null };
   let i = 0;
   for (; i < args.length; i++) {
     const arg = args[i];
@@ -73,6 +80,13 @@ function parseSendArgs(args, allowCommand) {
       console.error('browser it shares, cookies, storage and modes and all.');
       process.exit(64);
     }
+    // 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();
+      options.file = require('path').resolve(args[++i]);
+      continue;
+    }
     if (arg === '-e' || arg === '-s' || arg === '-c' || arg === '-t') {
       const value = args[++i];
       if (value === undefined) usage();
@@ -96,39 +110,9 @@ function parseSendArgs(args, allowCommand) {
     }
   }
   const words = args.slice(i);
-  if (!allowCommand && words.length) usage();
-  // For a command that reads a quoted selector (fill "text=Your name" Ada), a
-  // word the shell kept whole is quoted again so it stays one word. Any other
-  // command takes the rest of its line as it is (eval, route's JSON), so its
-  // words are joined as they are.
-  const { SELECTOR_FIRST } = require('../lib/syntax');
-  // So does playwright-cli's storage key (localstorage-set "my key" v).
-  // And record's file, which may have spaces in it.
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0]));
-  // An empty word (fill #name "") is the empty value.
-  // upload's files are read by the REPL, whose folder may not be this one.
-  // So are the files upload reads and screenshot --filename writes.
-  const resolve = require('path').resolve;
-  let resolved = words[0] === 'upload' ? words.map((w, n) => (n > 1 ? resolve(w) : w)) : words;
-  // record on <file> writes it too.
-  if (words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0])) {
-    resolved = words.map((w, n) => {
-      if (n < (words[0] === 'record' ? 2 : 1)) return w;
-      if (w.startsWith('--filename=') && w.length > 11) return `--filename=${resolve(w.slice(11))}`;
-      return words[n - 1] === '--filename' || !/^(?:\d+|-.*)$/.test(w) ? resolve(w) : w;
-    });
-  }
-  if (words[0] === 'screenshot') {
-    resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : w));
-  }
-  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
-  // An option's value the shell kept whole stays whole too: --device='iPhone 15'.
-  // Single quotes escape nothing, so a backslash (a regexp's \d) reaches it as typed.
-  for (const [n, w] of quoted.entries()) {
-    const option = /^(--[A-Za-z][\w-]*=)([\s\S]*\s[\s\S]*)$/.exec(w);
-    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? JSON.stringify(option[2]) : `'${option[2]}'`}`;
-  }
-  options.command = quoted.join(' ').trim();
+  if (!allowCommand && (words.length || options.file)) usage();
+  if (options.file && words.length) usage();
+  options.command = require('../lib/send').commandLine(words);
   return options;
 }
 
@@ -143,7 +127,15 @@ function startOptions(args, serve) {
   options.launch = flag('--launch');
   options.headed = flag('--headed');
   if ((options.headed || options.chromeArgs.length) && !options.launch) usage();
-  if (serve && rest[0] && looksLikeEndpoint(rest[0])) options.endpoint = rest.shift();
+  // -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();
+  } 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();
   options.startUrl = rest[0] || null;
   return options;

package/lib/cli-names.js

@@ -91,9 +91,10 @@ for (const what of ['reduced-motion', 'forced-colors', 'contrast', 'media']) {
   NEAREST[`clear-${what}`] = 'not here yet; emulate dark|light sets the color scheme';
 }
 for (const name of ['request-headers', 'response-headers', 'request-body']) NEAREST[name] = 'not here yet; body <#> shows the response body';
-for (const name of ['video-chapter', 'video-show-actions', 'video-hide-actions']) {
-  NEAREST[name] = 'not here: record on|off records a video, without chapters or action labels';
-}
+NEAREST['video-chapter'] = 'not here: record on|off records a video, without chapters';
+// Theirs labels each action and pauses on it; the cursor is a pointer that moves to each action instead.
+NEAREST['video-show-actions'] = 'not here; cursor on draws a pointer that moves to each action, without labels';
+NEAREST['video-hide-actions'] = 'not here; cursor off hides the pointer cursor on draws';
 for (const name of ['pause-at', 'resume', 'step-over']) NEAREST[name] = 'not here: they step through a Playwright test';
 
 const NAME_LIST = Object.keys(NAMES);

package/lib/client.js

@@ -69,6 +69,9 @@ function request(endpoint, command, timeoutMs, client = null) {
       ...target(endpoint),
       path: '/run',
       method: 'POST',
+      // A connection of its own each time: on one kept alive from an earlier command (send --file),
+      // 'connect' never fires, and a drop would be taken for a command never sent.
+      agent: false,
       headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
     }, res => {
       let text = '';

package/lib/cursor.js

@@ -9,7 +9,7 @@ const { unquote, toSelector } = require('./syntax');
 const { recordingOf, stepTarget, cursorStep } = require('./record');
 
 // Scaled with the distance, so a short hop is quick and a long one does not drag. Slower while the tab
-// records, so a video (and a zoom that follows the cursor) can be followed.
+// records, so a viewer can follow it.
 const DWELL_MS = 300;
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -80,8 +80,8 @@ function pageCursor({ x, y, action, ms, count, fade, box, items, index }) {
     cursor.y = y;
     place(cursor.arrow, x, y);
     if (!ms) return;
-    // Smoothstep, exactly (x = t with these control points, and y = 3t² - 2t³): the easing a zoom that
-    // follows the cursor uses, so it knows where the cursor is on every frame.
+    // Smoothstep, exactly (x = t with these control points, and y = 3t² - 2t³), so a tool editing the
+    // video can work out from the steps file where the cursor is on every frame.
     const glide = cursor.arrow.animate([{ transform: from }, { transform: to }], { duration: ms, easing: 'cubic-bezier(0.3333, 0, 0.6667, 1)' });
     // A hidden tab draws no frames, and its animation may never finish: not waited on past its time.
     return Promise.race([glide.finished, new Promise(resolve => setTimeout(resolve, ms + 300))]).then(() => {}, () => {});
@@ -158,19 +158,52 @@ async function glideTo(p, x, y) {
   const cursor = cursorOf(p);
   if (!cursor) return;
   const ms = glideTime(Math.hypot(x - cursor.x, y - cursor.y), !!recordingOf(p));
-  // A recording notes where the pointer went and when, for a zoom to follow it.
+  // A recording with --steps notes where the pointer went and when, for whoever edits the video.
   if (ms) cursorStep(p, `(cursor from ${cursor.x} ${cursor.y})`, { x, y }, ms);
   cursor.x = x;
   cursor.y = y;
   await p.evaluate(pageCursor, { x, y, action: 'move', ms }).catch(() => {});
 }
 
-// Whether a command should find its element first: to glide the cursor there, or to note it in a
-// recording's steps.
+// Whether a command should find its element first: to glide the cursor there, or, while recording, to
+// scroll to it smoothly and note it in the steps (record on --steps).
 function aiming(p) {
   return !!(cursorOf(p) || recordingOf(p));
 }
 
+// While recording, an element out of view is scrolled to smoothly, to the middle, rather than jumped to
+// as Playwright's own scroll would. The page scrolls itself, so no input is sent and a scrollable box
+// it is in scrolls too. One larger than the view is scrolled to only if its centre, where Playwright
+// acts, is out of view. Done when it has held still for a few frames: a nested box ends its scroll on
+// its own, and nothing ends one that never started.
+async function scrollSmoothly(target) {
+  // Chrome slows a background tab's timers too, so the REPL bounds the wait as well.
+  await Promise.race([sleep(2000), target.evaluate(async (el, cap) => {
+    const r = el.getBoundingClientRect();
+    const cx = r.left + r.width / 2;
+    const cy = r.top + r.height / 2;
+    const inView = r.width > innerWidth || r.height > innerHeight
+      ? cx >= 0 && cy >= 0 && cx <= innerWidth && cy <= innerHeight
+      : r.left >= 0 && r.top >= 0 && r.right <= innerWidth && r.bottom <= innerHeight;
+    if (inView) return;
+    el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'center' });
+    // A tab that is not drawing (behind another, minimised) has no frames: the timer keeps the cap.
+    const frame = () => new Promise(resolve => { requestAnimationFrame(resolve); setTimeout(resolve, 100); });
+    const started = performance.now();
+    const from = `${r.left},${r.top}`;
+    let last = from;
+    let still = 0;
+    // A smooth scroll can take a frame or two to start: longer to wait while nothing has moved yet.
+    while (performance.now() - started < cap && still < (last === from ? 10 : 3)) {
+      await frame();
+      const b = el.getBoundingClientRect();
+      const at = `${b.left},${b.top}`;
+      still = at === last ? still + 1 : 0;
+      last = at;
+    }
+  }, 1500).catch(() => {})]);
+}
+
 // Finds the centre of an element (a locator or a handle), where Playwright clicks, after scrolling it
 // into view as Playwright would, and glides the cursor there if it is on: the pointer is there before
 // the click, not after. A recording notes the element in its steps.
@@ -182,6 +215,7 @@ async function aimAt(p, target, timeout) {
   if (target.waitFor) await target.waitFor({ state: 'attached', timeout });
   try {
     if (!await target.isVisible()) return null;
+    if (recordingOf(p)) await scrollSmoothly(target);
     await target.scrollIntoViewIfNeeded({ timeout: 2000 });
     const box = await target.boundingBox({ timeout: 1000 });
     if (!box) return null;
@@ -270,10 +304,11 @@ const commands = {
     const usage = 'Usage: cursor [on [<selector> | <x> <y>] | off]';
     const on = /^on(?:\s+([\s\S]+))?$/.exec(arg);
     if (!on) throw new Error(usage);
-    if (cursor) { out.log(`The cursor is already on in the selected tab, at ${cursor.x}, ${cursor.y}; mousemove or a command on an element moves it`); return; }
     // Where it is asked to appear (a video's first element, say), or where the mouse last went, if the
     // REPL knows; otherwise the middle of the viewport.
     const where = (on[1] || '').trim();
+    if (cursor && !where) { out.log(`The cursor is already on in the selected tab, at ${cursor.x}, ${cursor.y}; cursor on <selector> or <x> <y> moves it`); return; }
+    const still = cursor ? 'the cursor stays where it was' : 'the cursor is still off';
     let at;
     if (/^-?\d+(?:\.\d+)?\s+-?\d+(?:\.\d+)?$/.test(where)) {
       const [x, y] = where.split(/\s+/).map(n => Math.round(Number(n)));
@@ -281,16 +316,34 @@ const commands = {
     } else if (where) {
       const target = p.locator(toSelector(unquote(where))).first();
       try {
-        await target.scrollIntoViewIfNeeded({ timeout: 5000 });
+        await target.waitFor({ state: 'visible', timeout: 5000 });
       } catch {
-        throw new Error(`No element matches ${where} that can be shown (waited 5s); the cursor is still off`);
+        throw new Error(`No element matches ${where} that can be shown (waited 5s); ${still}`);
       }
-      const box = await target.boundingBox();
-      if (!box) throw new Error(`${where} is not on the page to show the cursor at; the cursor is still off`);
-      at = { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) };
+      // Only pointing: an element partly in view is pointed at where it shows, not scrolled, so that
+      // one the page cuts off still looks cut off (a bug in a video). One wholly out of view is scrolled to.
+      const view = await p.evaluate(() => ({ width: innerWidth, height: innerHeight }));
+      const inView = b => b && b.x < view.width && b.y < view.height && b.x + b.width > 0 && b.y + b.height > 0;
+      let box = await target.boundingBox();
+      if (!inView(box)) {
+        await target.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => {});
+        box = await target.boundingBox();
+      }
+      if (!box) throw new Error(`${where} is not on the page to show the cursor at; ${still}`);
+      const left = Math.max(box.x, 0);
+      const top = Math.max(box.y, 0);
+      const right = Math.min(box.x + box.width, view.width);
+      const bottom = Math.min(box.y + box.height, view.height);
+      at = { x: Math.round((left + right) / 2), y: Math.round((top + bottom) / 2) };
     } else {
       at = tabState(p).mouseAt || await p.evaluate(() => ({ x: Math.round(innerWidth / 2), y: Math.round(innerHeight / 2) }));
     }
+    // Already on: the drawing glides there, and the real mouse stays put, as with fill.
+    if (cursor) {
+      await glideTo(p, at.x, at.y);
+      out.log(`The cursor moved to ${at.x}, ${at.y}`);
+      return;
+    }
     await p.evaluate(pageCursor, { x: at.x, y: at.y, action: 'draw', fade: true });
     tabState(p).cursor = { owner: state.client, x: at.x, y: at.y };
     cursorStep(p, '(cursor on)', at, 0);

package/lib/elements.js

@@ -9,6 +9,7 @@ const { numbers, hints } = require('./util');
 const { tabState } = require('./tabstate');
 const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
 const { recordingOf, stepTarget } = require('./record');
+const { settled } = require('./emulation');
 
 // The type a page sees for a file it is given, from its extension.
 const MIME_TYPES = {
@@ -66,8 +67,9 @@ function selectorAndValue(args, usage, example) {
 // An element that never appeared is said plainly, not as Playwright's call
 // log, and so is one that timed out: its call log (dozens of lines of retries) goes
 // to the REPL's pane and log only. A ref that no longer matches usually means the page
-// changed since the snapshot it came from.
-async function onElement(selector, action) {
+// changed since the snapshot it came from. It says the command's whole budget: Playwright's own
+// timeout is what was left of it for the last call, after a glide say, and can read 4999ms for 5000.
+async function onElement(selector, action, budget = 5000) {
   try {
     return await action();
   } catch (error) {
@@ -77,12 +79,12 @@ async function onElement(selector, action) {
     const staleRef = ref ? `\n${ref} is a snapshot ref; if the page changed since that snapshot, take a new one.` : '';
     const timeout = /Timeout (\d+)ms exceeded/.exec(message);
     if (timeout && /waiting for locator/.test(message) && !/resolved to/.test(message)) {
-      throw new Error(`No element matches ${ref || selector} (waited ${timeout[1] / 1000}s)${staleRef}`);
+      throw new Error(`No element matches ${ref || selector} (waited ${budget / 1000}s)${staleRef}`);
     }
     if (!timeout) { error.message += staleRef; throw error; }
     console.error(`Playwright's call log:\n${message}`);
     // Found, so the ref is not stale: no hint.
-    const summary = new Error(`Timed out after ${timeout[1] / 1000}s on ${ref || selector}: ${lastBlocker(message)} (its call log is in the REPL's pane or log)`);
+    const summary = new Error(`Timed out after ${budget / 1000}s on ${ref || selector}: ${lastBlocker(message)} (its call log is in the REPL's pane or log)`);
     // Worked out from the whole log: the summary no longer says whether the element was found.
     summary.uncertain = !/waiting for locator/.test(message) || /resolved to/.test(message);
     throw summary;
@@ -281,7 +283,7 @@ async function hideHighlights(p, mine = false) {
   if (!highlights?.size) return 0;
   const hidden = [...highlights].filter(([, h]) => !mine || (h.owner ?? null) === (state.client ?? null));
   if (hidden.length === highlights.size) await p.hideHighlight();
-  else for (const [selector] of hidden) await p.locator(selector).hideHighlight();
+  else for (const [selector, h] of hidden) await (h.drawn || p.locator(selector)).hideHighlight();
   for (const [selector] of hidden) highlights.delete(selector);
   return hidden.length;
 }
@@ -292,6 +294,67 @@ onShutdown(async () => {
   await Promise.all(pages.map(p => hideHighlights(p).catch(() => {})));
 });
 
+// Playwright's highlight labels each box with its locator, which covers what is below it, and has
+// no option not to; highlights are drawn without it unless highlight --labels on. Its overlay is an
+// x-pw-glass element with a closed shadow root, which only CDP reaches: a stylesheet adopted there
+// hides the labels, under any CSP, and stays as Playwright redraws them. Playwright removes the
+// overlay with its last highlight, and the sheet with it, so it is applied again after each one.
+const LABELS_OFF = 'x-pw-tooltip:not([data-pw-repl])';
+// The clients told that the labels could not be hidden, each once.
+const labelsWarned = new Set();
+
+// Adds or removes the sheet in the main document's overlay, and says whether it worked: false when
+// there is an overlay but its labels are not hidden. Null when there is no overlay.
+async function applyLabels(p, hide) {
+  const session = await p.context().newCDPSession(p);
+  try {
+    const { root } = await session.send('DOM.getDocument', { depth: 0 });
+    const { nodeId } = await session.send('DOM.querySelector', { nodeId: root.nodeId, selector: 'x-pw-glass' });
+    if (!nodeId) return null;
+    const { node } = await session.send('DOM.describeNode', { nodeId, pierce: true });
+    const shadow = node.shadowRoots?.[0];
+    if (!shadow) return false;
+    const { object } = await session.send('DOM.resolveNode', { backendNodeId: shadow.backendNodeId });
+    const call = (fn, args) => session.send('Runtime.callFunctionOn', { objectId: object.objectId, functionDeclaration: fn.toString(), arguments: args.map(value => ({ value })), returnByValue: true });
+    await call(function (rule, hidden) {
+      const sheets = [...this.adoptedStyleSheets].filter(s => ![...s.cssRules].some(r => r.selectorText === rule));
+      if (hidden) {
+        const sheet = new CSSStyleSheet();
+        sheet.replaceSync(`${rule} { display: none !important; }`);
+        sheets.push(sheet);
+      }
+      this.adoptedStyleSheets = sheets;
+    }, [LABELS_OFF, hide]);
+    if (!hide) return true;
+    // Playwright draws its labels on a later frame.
+    await settled(p);
+    const { result } = await call(function (rule) {
+      const ours = [...this.adoptedStyleSheets].some(s => [...s.cssRules].some(r => r.selectorText === rule));
+      return ours && [...this.querySelectorAll('x-pw-tooltip')].every(t => getComputedStyle(t).display === 'none');
+    }, [LABELS_OFF]);
+    return result.value === true;
+  } finally {
+    await session.detach().catch(() => {});
+  }
+}
+
+// Hides the tab's labels unless they are on; says so once if that failed, and the highlight is drawn
+// with its label as Playwright draws it. A CDP call that fails, as one does when the tab navigates or
+// closes, says nothing of Playwright's overlay: only the check finding the labels shown does.
+async function keepLabels(p) {
+  if (tabState(p).labelsOn) return;
+  const worked = await applyLabels(p, true).catch(() => null);
+  const client = state.client ?? null;
+  if (worked !== false || labelsWarned.has(client)) return;
+  labelsWarned.add(client);
+  out.log(`highlight: could not hide the labels; Playwright's highlight has changed (playwright-core ${require('playwright-core/package.json').version}). The boxes are drawn with their labels.`);
+}
+
+async function setLabels(p, on) {
+  if (on) tabState(p).labelsOn = { owner: state.client }; else delete tabState(p).labelsOn;
+  if (on) await applyLabels(p, false); else await keepLabels(p);
+}
+
 const commands = {
   async click(args) {
     const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
@@ -312,15 +375,27 @@ const commands = {
   },
 
   async highlight(args) {
-    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | off]';
-    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag' });
+    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | --labels off|on | off]';
+    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag', labels: 'value' });
     const style = found.find(o => o.name === 'style');
     const hide = found.some(o => o.name === 'hide');
+    const labels = found.find(o => o.name === 'labels');
     const highlights = highlightsOf(state.page);
+    // For the whole tab, with a highlight to draw or on its own.
+    if (labels) {
+      if (hide || rest === 'off' || !['off', 'on'].includes(labels.value)) throw new Error(usage);
+      await setLabels(state.page, labels.value === 'on');
+      out.log(labels.value === 'on'
+        ? 'Labels on in the selected tab: each highlight is labelled with its locator; highlight --labels off hides them'
+        : 'Labels off in the selected tab');
+      if (!rest) return;
+    }
     if (!rest && !found.length) {
       if (!highlights.size) { out.log(`Nothing is highlighted in the selected tab.\n${hints([['highlight <selector>', 'draw a box around it']])}`); return; }
-      for (const [selector, h] of highlights) out.log(`${selector}${h.style ? `  --style=${JSON.stringify(h.style)}` : ''}${h.owner ? `  (by ${h.owner})` : ''}`);
-      out.log(hints([['highlight --hide [<selector>]', 'hide one, or all']]));
+      for (const [selector, h] of highlights) out.log(`${selector}${h.drawn?.toString() !== state.page.locator(selector).toString() ? `  as ${h.drawn}` : ''}${h.style ? `  --style=${JSON.stringify(h.style)}` : ''}${h.owner ? `  (by ${h.owner})` : ''}`);
+      const on = tabState(state.page).labelsOn;
+      if (on) out.log(`Labels are on${on.owner ? ` (by ${on.owner})` : ''}.`);
+      out.log(hints([['highlight --hide [<selector>]', 'hide one, or all'], on ? ['highlight --labels off', 'hide their labels'] : ['highlight --labels on', 'label each with its locator']]));
       return;
     }
     if (rest === 'off' && !found.length || hide && !rest) {
@@ -333,7 +408,7 @@ const commands = {
     const locator = state.page.locator(selector);
     if (hide) {
       if (!highlights.has(selector)) throw new Error(`${rest} is not highlighted; highlight lists what is`);
-      await locator.hideHighlight();
+      await (highlights.get(selector).drawn || locator).hideHighlight();
       highlights.delete(selector);
       out.log(`Hid the highlight on ${rest}`);
       return;
@@ -341,9 +416,13 @@ const commands = {
     const count = await locator.count();
     if (!count) throw new Error(`No element matches ${rest}; nothing was highlighted`);
     // Drawn again, with its new style, rather than twice.
-    if (highlights.has(selector)) await locator.hideHighlight();
-    await locator.highlight(style ? { style: style.value } : {});
-    highlights.set(selector, { owner: state.client, style: style?.value || null });
+    if (highlights.has(selector)) await (highlights.get(selector).drawn || locator).hideHighlight();
+    // Playwright labels a box with the locator it is given, and a snapshot ref's (aria-ref=e5) finds
+    // nothing in the page's code: one is drawn with the locator Playwright makes for its element.
+    const drawn = REF.test(rest) ? await locator.normalize().catch(() => locator) : locator;
+    await drawn.highlight(style ? { style: style.value } : {});
+    await keepLabels(state.page);
+    highlights.set(selector, { owner: state.client, style: style?.value || null, drawn });
     out.log(`Highlighted ${rest}${count > 1 ? ` (all ${count} matches)` : ''}; highlight --hide ${rest} hides it`);
   },
 
@@ -510,4 +589,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, soleSelector, onElement, hideHighlights };
+module.exports = { commands, soleSelector, onElement, hideHighlights, setLabels };

package/lib/emulation.js

@@ -66,6 +66,18 @@ function settled(p) {
   ]);
 }
 
+// Bringing a tab to the front can leave Chrome capturing it at the window's size after its next
+// navigation, although the page is still laid out at its viewport's or phone's: sending the same
+// metrics again, on the kept session, has it draw at them.
+async function reapplyMetrics(p) {
+  const tab = tabState(p);
+  if (!tab.viewport && !tab.emulation?.device) return;
+  const session = await keptSession(p);
+  if (tab.viewport) await viewportMetrics(session, tab.viewport);
+  else if (tab.emulation?.device) await deviceMetrics(session, tab.emulation.device);
+  await settled(p);
+}
+
 async function setViewport(p, size) {
   const session = await keptSession(p);
   if (size) {
@@ -220,4 +232,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, viewportMetrics, setEmulation, setViewport, settled };
+module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, viewportMetrics, setEmulation, setViewport, settled, reapplyMetrics };