pw-repl 0.7.0 → 0.8.0

package/AGENTS.md

@@ -13,10 +13,11 @@ If you hit a limitation or write a workaround, consider adding the capability to
   needs no tab, only reads, or takes `--all` is also listed in `lib/runner.js`'s `NO_TAB_NEEDED`,
   `READ_ONLY` or `INSPECTION`, and one that takes fixed words in `complete` (`lib/commands.js`).
 - The modules, one per facility, each with its commands: `lib/tabs.js` (tabs, navigating),
-  `lib/elements.js` (choosing a match; the interact and mouse commands), `lib/inspect.js` (reading the
+  `lib/elements.js` (choosing a match; the interact and mouse commands; highlight), `lib/cursor.js` (the pointer
+  drawn over the page, which the element and mouse commands glide first), `lib/inspect.js` (reading the
   page, screenshots, eval, CDP, waits), `lib/watch.js`, `lib/requestlog.js` (requests, bodies, console),
   `lib/routes.js`, `lib/network.js`, `lib/emulation.js` (and viewport), `lib/capture.js`, `lib/record.js`
-  (video, through ffmpeg), `lib/dialogs.js` and `lib/modes.js`. Beneath them, `lib/tabstate.js` is the one record kept per tab, `lib/cdp.js` the CDP
+  (video, through ffmpeg, and the steps file saved with it), `lib/dialogs.js` and `lib/modes.js`. Beneath them, `lib/tabstate.js` is the one record kept per tab, `lib/cdp.js` the CDP
   session kept per tab, and `lib/util.js` small shared helpers. No facility requires `lib/modes.js` or
   `lib/commands.js`, and a unit test fails on a require cycle, which CommonJS would not report.
 - `bin/pw-repl.js` is the command line; `lib/start.js` connects and runs the prompt; `lib/runner.js`
@@ -27,10 +28,11 @@ If you hit a limitation or write a workaround, consider adding the capability to
   names to these; `lib/state.js` holds the session state, with each client's selected tab;
   `lib/output.js` routes all output so the server can return it; `lib/skill.js` stamps the skill
   `pw-repl skill` prints, and gives `where` its hash.
-- Match playwright-cli (Microsoft's CLI for agents) where it is reasonable: agents are likelier to be
-  trained on it. A new command, option or output that does what one of its does takes its name and form,
-  or accepts them too (`lib/cli-names.js`, `help playwright-cli`). Differ where sharing a browser with a
-  person needs it, and say why in the help.
+- Match Playwright and playwright-cli (Microsoft's CLI for agents) as closely as is reasonable: agents are
+  likelier to be trained on them. A new command, option or output that does what one of theirs does takes
+  its name, form and API style (an option named as Playwright's API names it, e.g. type's `delay`), or
+  accepts theirs too (`lib/cli-names.js`, `help playwright-cli`). Deviate only where it is necessary, as
+  where sharing a browser with a user needs it, and say why in the help.
 - Comment the *why* when it isn't obvious from the code.
 - `npm test` runs the suite (under two minutes): a private headless Chromium, a local test site
   (`test/harness.js`), and the real REPL with its server. Nothing is mocked, and the shared browser is
@@ -60,7 +62,10 @@ If you hit a limitation or write a workaround, consider adding the capability to
 
 Work goes in waves, and each one ends with a release that is ready to push.
 
-1. Build what was asked, with tests, and try it in a running REPL.
+1. Build what was asked, with tests, and try it in a running REPL. For anything the user will look at
+   (a cursor, an overlay, a video), show them a demo while it is still a prototype (a recording or
+   screenshots they can open) and get their go-ahead on how it looks before writing tests or
+   building on it.
 2. Try it on a fresh agent that has not seen the code or the change (a guinea pig), on something real: a
    small local page whose planted bugs need the change to find.
    - Brief it with goals only: what to find out or do in the browser, never the commands.

package/README.md

@@ -99,6 +99,8 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | 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)                      |
+| 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`               |
 | 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`                                                                        |
@@ -108,13 +110,15 @@ Everything else is in `help <topic>`; `help <command>` has usage and caveats.
 
 ### Modes
 
-`watch`, `capture`, `route`, `network off` or `slow`, and `emulate` stay on until you turn them off:
-`watch on|off`, `capture on|off`, `route ...|route off`, `network off|slow|on`, `emulate ...|emulate off`.
+`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`.
 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.
 
-`tab`, `watch`, `capture`, `route`, `network`, `emulate` and `modes` on their own show their state and what
-you can run next.
+`tab`, `watch`, `capture`, `route`, `network`, `emulate`, `viewport`, `record`, `highlight`, `cursor` and `modes` on
+their own show their state and what you can run next.
 
 ## How it differs from playwright-cli
 
@@ -131,8 +135,9 @@ pw-repl differs, it is because someone else may be using the browser:
 - `watch` records what a person does as steps with their requests, not as generated code.
 
 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, without the pointer; for the shared
-browser as you see it, use a screen recorder (`ffmpeg -f x11grab`, macOS `screencapture -v`, OBS).
+playwright-cli is the better fit. `record on` records a tab's page, and `cursor on` draws a pointer where the
+agent acts; for the shared browser as you see it, use a screen recorder (`ffmpeg -f x11grab`, macOS
+`screencapture -v`, OBS).
 
 ## From scripts and agents
 

package/bin/pw-repl.js

@@ -15,7 +15,7 @@ const USAGE = `Usage:
       see everything a background REPL does, and type commands to it; Ctrl-C leaves it running
 
   pw-repl stop [-e endpoint]
-      stop a background REPL
+      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
@@ -41,10 +41,10 @@ send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or
 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
-a temporary profile, on a free port of its own), 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 kept. PW_CHROME picks
-which one. To set a browser up your own way, start it yourself and use PW_CDP_URL.
+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
+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 playwright-repl, pw-repl send reaches pw-repl run without the server.`;
 
@@ -103,7 +103,8 @@ function parseSendArgs(args, allowCommand) {
   // words are joined as they are.
   const { SELECTOR_FIRST } = require('../lib/syntax');
   // So does playwright-cli's storage key (localstorage-set "my key" v).
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]));
+  // 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.

package/lib/background.js

@@ -5,6 +5,7 @@ const path = require('path');
 const readline = require('readline');
 const { spawn } = require('child_process');
 const client = require('./client');
+const { STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
 
 const BIN = path.join(__dirname, '..', 'bin', 'pw-repl.js');
 const START_TIMEOUT = 20000;
@@ -132,12 +133,26 @@ async function stop(options) {
   const { pidFile } = filesFor(endpoint);
   const pid = runningPid(pidFile);
   if (!pid) return fail(`no background REPL is serving on ${client.describe(endpoint)}`);
+  // What it logs as it stops, from here on, holds what became of each recording it ended.
+  const { logFile } = filesFor(endpoint);
+  let logFrom = 0;
+  try { logFrom = fs.statSync(logFile).size; } catch {}
   // Like Ctrl-C: a command still running is answered, and the socket is removed.
   process.kill(pid, 'SIGTERM');
   const deadline = Date.now() + STOP_TIMEOUT;
   while (alive(pid) && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 100));
   if (alive(pid)) return fail(`the background REPL (pid ${pid}) has not stopped after ${STOP_TIMEOUT / 1000}s`);
-  console.log(`Stopped the background REPL (pid ${pid}) on ${client.describe(endpoint)}; its log stays at ${filesFor(endpoint).logFile}`);
+  console.log(`Stopped the background REPL (pid ${pid}) on ${client.describe(endpoint)}; its log stays at ${logFile}`);
+  // The REPL is gone, so record can no longer say where a recording it ended went, or that it was lost.
+  let logged = '';
+  try {
+    const fd = fs.openSync(logFile, 'r');
+    const buffer = Buffer.alloc(Math.max(0, fs.fstatSync(fd).size - logFrom));
+    fs.readSync(fd, buffer, 0, buffer.length, logFrom);
+    fs.closeSync(fd);
+    logged = buffer.toString('utf8');
+  } catch {}
+  for (const line of logged.split('\n')) if (line.startsWith(STOPPED_RECORDING) || line.startsWith(ENDED_UNSEEN)) console.log(line);
   return 0;
 }
 

package/lib/cli-names.js

@@ -69,7 +69,7 @@ const NEAREST = {
   list: 'pw-repl where says which REPL is running; one REPL serves everyone using its browser',
   attach: 'pw-repl serve connects to the browser on PW_CDP_URL; pw-repl skill has the rest',
   detach: 'pw-repl stop, or quit at the prompt, disconnects and leaves the browser running',
-  drag: 'not here yet', drop: 'not here yet', highlight: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
+  drag: 'not here yet', drop: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
   keydown: 'not here yet; press <key> presses and releases one', keyup: 'not here yet; press <key> presses and releases one',
   pdf: 'not here yet; screenshot --full saves the whole page as a PNG',
   'generate-locator': 'not here yet; a snapshot ref (e5) works as a selector in any command',

package/lib/commands.js

@@ -6,6 +6,7 @@ const HELP = require('./help');
 const { tabState } = require('./tabstate');
 const { commands: dialogsCommands, ensureDialogHandler } = require('./dialogs');
 const { commands: elementsCommands } = require('./elements');
+const { commands: cursorCommands } = require('./cursor');
 const { commands: requestlogCommands, ensureRecentLog } = require('./requestlog');
 const { commands: routesCommands, routesFor } = require('./routes');
 const { commands: networkCommands } = require('./network');
@@ -21,6 +22,7 @@ const { commands: modesCommands, allModesOff } = require('./modes');
 const commands = {
   ...tabsCommands,
   ...elementsCommands,
+  ...cursorCommands,
   ...inspectCommands,
   ...watchCommands,
   ...requestlogCommands,
@@ -113,6 +115,7 @@ function complete(line) {
     if (command === 'watch') return match(['on', 'off', 'new', '--all']);
     if (command === 'capture') return match(['on', 'off']);
     if (command === 'record') return match(['on', 'off']);
+    if (command === 'cursor') return match(['on', 'off']);
     if (command === 'viewport') return match(['off']);
     if (command === 'route') return match(['off']);
   }

package/lib/cursor.js

@@ -0,0 +1,302 @@
+// A pointer drawn over the page, for videos: the REPL's input moves no pointer on screen. With it on,
+// the commands that act on an element or at a point glide it there first and then act, and a
+// click shows where it landed. It shows the REPL's own input only: the user's pointer is theirs.
+// The REPL moves it, not the page's own mouse events, which the user's mouse fires as well.
+const { state, onShutdown } = require('./state');
+const out = require('./output');
+const { tabState } = require('./tabstate');
+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.
+const DWELL_MS = 300;
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+const glideTime = (distance, recording) => {
+  if (distance < 2) return 0;
+  const [min, max, base, perPixel] = recording ? [300, 1000, 200, 0.8] : [150, 600, 100, 0.5];
+  return Math.round(Math.min(max, Math.max(min, base + distance * perPixel)));
+};
+
+// Runs in the page. Its own element under <html>, not <body>, which frameworks replace, with a closed
+// shadow root, so the page's selectors, the snapshot and text do not find what is in it. It takes no
+// pointer events, so what is under it is clicked, and it is built with the DOM and inline styles,
+// which a page's Trusted Types or style-src rules do not block. It is shown as a popover, in the top
+// layer, above the page's own dialogs, as Playwright's highlight is. Kept on the document under a
+// symbol, so each call finds it again, and one the page removed is drawn again.
+function pageCursor({ x, y, action, ms, count, fade, box, items, index }) {
+  const KEY = Symbol.for('pw-repl-cursor');
+  // Important on the element in the page, whose own rules could reach it; inside, the page's cannot,
+  // and an important transform would win over the glide's animation.
+  const set = (el, styles, important = '') => { for (const [name, value] of Object.entries(styles)) el.style.setProperty(name, value, important); };
+  const place = (el, px, py) => set(el, { transform: `translate(${px}px, ${py}px)` });
+  let cursor = document[KEY];
+  if (action === 'remove') {
+    if (!cursor) return;
+    delete document[KEY];
+    if (!fade || !cursor.host.isConnected) { cursor.host.remove(); return; }
+    // Waited on, as a glide is, but not past its time in a tab that draws no frames.
+    const fading = cursor.arrow.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 200, fill: 'forwards' });
+    return Promise.race([fading.finished, new Promise(resolve => setTimeout(resolve, 500))]).then(() => cursor.host.remove(), () => cursor.host.remove());
+  }
+  if (!cursor || !cursor.host.isConnected) {
+    const host = document.createElement('pw-repl-cursor');
+    host.setAttribute('aria-hidden', 'true');
+    host.setAttribute('popover', 'manual');
+    set(host, {
+      display: 'block', position: 'fixed', inset: '0', width: '100%', height: '100%', 'max-width': 'none',
+      'max-height': 'none', margin: '0', padding: '0', border: 'none', background: 'transparent',
+      overflow: 'visible', 'pointer-events': 'none', 'z-index': '2147483647',
+    }, 'important');
+    const root = host.attachShadow({ mode: 'closed' });
+    const NS = 'http://www.w3.org/2000/svg';
+    const arrow = document.createElementNS(NS, 'svg');
+    arrow.setAttribute('width', '20');
+    arrow.setAttribute('height', '28');
+    arrow.setAttribute('viewBox', '0 0 15 21');
+    set(arrow, { position: 'absolute', left: '0', top: '0', overflow: 'visible', filter: 'drop-shadow(0 1px 1.5px rgba(0,0,0,.4))' });
+    const shape = document.createElementNS(NS, 'path');
+    // The tip at 0,0 is the point.
+    shape.setAttribute('d', 'M0 0 L0 17 L4.2 13.2 L7 19.6 L9.8 18.4 L7.1 12.1 L12.6 12.1 Z');
+    shape.setAttribute('fill', '#111');
+    shape.setAttribute('stroke', '#fff');
+    shape.setAttribute('stroke-width', '1.4');
+    shape.setAttribute('stroke-linejoin', 'round');
+    arrow.append(shape);
+    root.append(arrow);
+    document.documentElement.append(host);
+    cursor = document[KEY] = { host, root, arrow, x, y };
+    place(arrow, x, y);
+    // Faded in when turned on; drawn again on a new page, it is there at once, as it was.
+    if (fade) arrow.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 200 });
+  }
+  // Shown again, so it is above a dialog the page opened since.
+  try { cursor.host.hidePopover(); cursor.host.showPopover(); } catch {}
+  if (action === 'move') {
+    const from = `translate(${cursor.x}px, ${cursor.y}px)`;
+    const to = `translate(${x}px, ${y}px)`;
+    cursor.x = x;
+    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.
+    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(() => {}, () => {});
+  }
+  // A select's list, drawn under it: a native one opens outside the page, where no recording sees it.
+  if (action === 'pickerOpen') {
+    cursor.picker?.remove();
+    const list = document.createElement('div');
+    const rowHeight = 28;
+    set(list, {
+      position: 'absolute', left: `${box.x}px`, top: `${box.y + box.height + 2}px`, 'min-width': `${Math.max(box.width, 120)}px`,
+      background: '#fff', border: '1px solid #9aa0a6', 'border-radius': '4px', 'box-shadow': '0 4px 14px rgba(0,0,0,.25)',
+      font: '15px system-ui, sans-serif', color: '#202124', padding: '4px 0', 'box-sizing': 'border-box', overflow: 'hidden',
+    });
+    const rows = items.slice(0, 10).map(text => {
+      const row = document.createElement('div');
+      row.textContent = text;
+      set(row, { height: `${rowHeight}px`, 'line-height': `${rowHeight}px`, padding: '0 12px', 'white-space': 'nowrap' });
+      list.append(row);
+      return row;
+    });
+    cursor.picker = list;
+    cursor.pickerRows = rows;
+    cursor.root.insertBefore(list, cursor.arrow);
+    const mark = i => rows.forEach((row, j) => set(row, { background: j === i ? '#1a73e8' : 'transparent', color: j === i ? '#fff' : '#202124' }));
+    cursor.pickerMark = mark;
+    mark(index);
+    list.animate([{ opacity: 0, transform: 'translateY(-4px)' }, { opacity: 1, transform: 'none' }], { duration: 150 });
+    // Where the chosen row will be, for the cursor to go to.
+    return { rowY: box.y + box.height + 2 + 4 + rowHeight / 2, rowHeight };
+  }
+  if (action === 'pickerChoose') {
+    cursor.pickerMark?.(index);
+    return;
+  }
+  if (action === 'pickerClose') {
+    const list = cursor.picker;
+    if (!list) return;
+    cursor.picker = null;
+    return Promise.race([list.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 150, fill: 'forwards' }).finished, new Promise(resolve => setTimeout(resolve, 400))])
+      .then(() => list.remove(), () => list.remove());
+  }
+  if (action === 'click') {
+    // A ring that grows and fades where the click landed, one for each click of a double-click.
+    for (let i = 0; i < count; i += 1) {
+      const ring = document.createElement('div');
+      set(ring, {
+        position: 'absolute', left: `${x - 14}px`, top: `${y - 14}px`, width: '28px', height: '28px', 'box-sizing': 'border-box',
+        'border-radius': '50%', border: '2px solid rgba(230, 40, 40, .9)', background: 'rgba(230, 40, 40, .3)', opacity: '0',
+      });
+      cursor.root.insertBefore(ring, cursor.arrow);
+      ring.animate([{ transform: 'scale(.3)', opacity: 1 }, { transform: 'scale(1.5)', opacity: 0 }], { duration: 450, delay: i * 140, easing: 'ease-out' })
+        .finished.then(() => ring.remove(), () => ring.remove());
+    }
+  }
+}
+
+function cursorOf(p) {
+  return tabState(p).cursor || null;
+}
+
+// A new document drops the cursor: it is drawn again where it was.
+function keepAcrossPages(p) {
+  if (tabState(p).cursorKept) return;
+  tabState(p).cursorKept = true;
+  p.on('domcontentloaded', () => {
+    const cursor = cursorOf(p);
+    if (cursor) p.evaluate(pageCursor, { x: cursor.x, y: cursor.y, action: 'draw' }).catch(() => {});
+  });
+}
+
+// Glides the tab's cursor to a point, if it is on, and waits for it to get there.
+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.
+  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.
+function aiming(p) {
+  return !!(cursorOf(p) || recordingOf(p));
+}
+
+// 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.
+// It waits for a locator's element to be there, as the command would, and throws Playwright's timeout
+// if none comes, for the command to report as its own: the command does not wait all over again. One
+// there but hidden (a file input under its button) is not glided to, and the command says why.
+async function aimAt(p, target, timeout) {
+  if (!aiming(p)) return null;
+  if (target.waitFor) await target.waitFor({ state: 'attached', timeout });
+  try {
+    if (!await target.isVisible()) return null;
+    await target.scrollIntoViewIfNeeded({ timeout: 2000 });
+    const box = await target.boundingBox({ timeout: 1000 });
+    if (!box) return null;
+    const point = { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) };
+    stepTarget(p, box, point);
+    await glideTo(p, point.x, point.y);
+    // While recording, a moment on the element before acting on it, for the viewer to see where it is.
+    if (cursorOf(p) && recordingOf(p)) await sleep(DWELL_MS);
+    return point;
+  } catch {
+    return null;
+  }
+}
+
+// Shows a click where the cursor is; the input has landed by then. A click that loads a new page
+// may take the ring with it.
+async function showClick(p, count = 1) {
+  const cursor = cursorOf(p);
+  if (!cursor) return;
+  await p.evaluate(pageCursor, { x: cursor.x, y: cursor.y, action: 'click', count }).catch(() => {});
+}
+
+// select with the cursor on: a native select's list opens outside the page, where no recording (or
+// headless Chrome) shows it, so its list is drawn over the page instead. It opens under the select with
+// the current option marked, the mark moves to the option to be chosen (by value or label, as
+// Playwright's selectOption matches it), the cursor clicks it and the choice is made (act), and the list
+// closes. Drawn only: the page gets the same input as without the cursor.
+async function showSelect(p, target, value, act) {
+  const cursor = cursorOf(p);
+  const box = cursor && await target.boundingBox().catch(() => null);
+  // Not drawn for a disabled select or option, which selectOption refuses: the video would show a choice
+  // that was never made.
+  const before = box && await target.evaluate((el, v) => {
+    if (el.tagName !== 'SELECT' || el.multiple || el.size > 1 || el.disabled) return null;
+    const chosen = [...el.options].findIndex(o => o.value === v || o.label === v);
+    if (chosen >= 0 && (el.options[chosen].disabled || el.options[chosen].parentElement.disabled)) return null;
+    return { items: [...el.options].map(o => o.label || o.text), index: el.selectedIndex, chosen };
+  }, value).catch(() => null);
+  if (!before || before.chosen < 0 || before.chosen >= 10) return act();
+  const pace = recordingOf(p) ? 1 : 0.5;
+  await showClick(p);
+  const opened = await p.evaluate(pageCursor, { action: 'pickerOpen', box, items: before.items, index: before.index }).catch(() => null);
+  if (!opened) return act();
+  await sleep(350 * pace);
+  await glideTo(p, Math.round(cursor.x), Math.round(opened.rowY + before.chosen * opened.rowHeight));
+  await p.evaluate(pageCursor, { action: 'pickerChoose', index: before.chosen }).catch(() => {});
+  await showClick(p);
+  try {
+    return await act();
+  } finally {
+    await sleep(250 * pace);
+    await p.evaluate(pageCursor, { action: 'pickerClose' }).catch(() => {});
+  }
+}
+
+async function cursorOff(p) {
+  if (!cursorOf(p)) return false;
+  const { x, y } = cursorOf(p);
+  delete tabState(p).cursor;
+  cursorStep(p, '(cursor off)', { x, y }, 0);
+  await p.evaluate(pageCursor, { action: 'remove', fade: true }).catch(() => {});
+  return true;
+}
+
+onShutdown(async () => {
+  if (!state.browser || state.connectionLost) return;
+  const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => !p.isClosed());
+  await Promise.all(pages.map(p => cursorOff(p).catch(() => {})));
+});
+
+const commands = {
+  async cursor(args) {
+    const arg = (args || '').trim();
+    const p = state.page;
+    const cursor = cursorOf(p);
+    if (!arg) {
+      out.log(cursor
+        ? `The cursor is on in the selected tab, at ${cursor.x}, ${cursor.y}${cursor.owner ? ` (by ${cursor.owner})` : ''}; cursor off hides it`
+        : 'The cursor is off in the selected tab; cursor on shows it');
+      return;
+    }
+    if (arg === 'off') {
+      out.log(await cursorOff(p) ? 'The cursor is off' : 'The cursor was not on in the selected tab');
+      return;
+    }
+    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();
+    let at;
+    if (/^-?\d+(?:\.\d+)?\s+-?\d+(?:\.\d+)?$/.test(where)) {
+      const [x, y] = where.split(/\s+/).map(n => Math.round(Number(n)));
+      at = { x, y };
+    } else if (where) {
+      const target = p.locator(toSelector(unquote(where))).first();
+      try {
+        await target.scrollIntoViewIfNeeded({ timeout: 5000 });
+      } catch {
+        throw new Error(`No element matches ${where} that can be shown (waited 5s); the cursor is still off`);
+      }
+      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) };
+    } else {
+      at = tabState(p).mouseAt || await p.evaluate(() => ({ x: Math.round(innerWidth / 2), y: Math.round(innerHeight / 2) }));
+    }
+    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);
+    keepAcrossPages(p);
+    out.log(`The cursor is on, at ${at.x}, ${at.y}: commands on elements and the mouse glide it there first, and clicks show where they land; cursor off hides it`);
+  },
+};
+
+module.exports = { commands, cursorOf, cursorOff, aiming, aimAt, glideTo, showClick, showSelect };

package/lib/dialogs.js

@@ -5,11 +5,17 @@ const { OUTPUT_LIMIT } = out;
 const { unquote } = require('./syntax');
 const { hints } = require('./util');
 const { tabState } = require('./tabstate');
+const { keptSession } = require('./cdp');
 
 // page -> its open dialog. The page, and every command that reads it, waits
 // until the dialog is answered, in the browser or with the dialog command.
 const openDialogs = new Map();
 
+// cdp's session is new, and Chrome lets only one that saw a dialog open answer it: it would wait out its
+// timeout. Refused ahead of the queue too, which the dialog it means holds up.
+const CDP_ANSWER = /^cdp(?:\s+--all)?\s+Page\.handleJavaScriptDialog(?:\s|$)/;
+const CDP_REFUSED = 'cdp cannot answer a dialog, which Chrome lets only a session that saw it open do; dialog accept or dialog dismiss answers it';
+
 function ensureDialogHandler(p) {
   if ('dialogHandled' in tabState(p)) return;
   tabState(p).dialogHandled = true;
@@ -19,6 +25,12 @@ function ensureDialogHandler(p) {
     out.notice('It waits to be answered in the browser, or with dialog accept [text] | dialog dismiss; until then the page, and commands that read it, wait too.', p);
   });
   p.on('close', () => openDialogs.delete(p));
+  // One answered in the browser is gone too, which Playwright does not report. The tab's own session
+  // shares Playwright's connection, so a dialog's closing comes in before the next one opening.
+  keptSession(p).then(async session => {
+    session.on('Page.javascriptDialogClosed', () => openDialogs.delete(p));
+    await session.send('Page.enable');
+  }).catch(() => {});
 }
 
 // Runs ahead of the command queue (see runner.js), so it still works while
@@ -30,7 +42,9 @@ async function dialogCommand(args, selected = state.page) {
   const describe = (p, d) => `[${pages.indexOf(p)}] ${p.url()}: ${d.type()} ${JSON.stringify(String(d.message()).slice(0, 200))}`;
   if (!action) {
     if (!openDialogs.size) return 'No dialog is open.';
-    return [...[...openDialogs].map(([p, d]) => describe(p, d)), hints([['dialog accept [text]', 'accept it (text answers a prompt)'], ['dialog dismiss', 'dismiss it']])].join('\n');
+    // With several, the one accept and dismiss answer is marked, as tab marks the selected tab.
+    const mark = p => (openDialogs.size > 1 ? (p === selected ? '* ' : '  ') : '');
+    return [...[...openDialogs].map(([p, d]) => `${mark(p)}${describe(p, d)}`), hints([['dialog accept [text]', 'accept it (text answers a prompt)'], ['dialog dismiss', 'dismiss it']])].join('\n');
   }
   if (action !== 'accept' && action !== 'dismiss') throw new Error('Usage: dialog [accept [text] | dismiss]');
   // The selected tab's dialog, or the only one open.
@@ -40,7 +54,8 @@ async function dialogCommand(args, selected = state.page) {
   openDialogs.delete(page);
   const line = describe(page, dialog);
   try {
-    if (action === 'accept') await dialog.accept(rest.length ? unquote(rest.join(' ')) : undefined);
+    // Without text, as OK in the browser: a prompt's default stays its answer.
+    if (action === 'accept') await dialog.accept(rest.length ? unquote(rest.join(' ')) : dialog.defaultValue());
     else await dialog.dismiss();
   } catch (error) {
     // Answered in the browser meanwhile.
@@ -55,4 +70,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, ensureDialogHandler, dialogCommand };
+module.exports = { commands, ensureDialogHandler, dialogCommand, CDP_ANSWER, CDP_REFUSED };