pw-repl 0.7.0 → 0.8.0

package/lib/elements.js

@@ -1,11 +1,14 @@
 // Elements and the mouse: finding the match to act on, and the commands that click, type and choose.
 const path = require('path');
 const fs = require('fs');
-const { state } = require('./state');
+const { state, onShutdown } = require('./state');
 const out = require('./output');
 const { takeOptions } = require('./cli-names');
 const { unquote, toSelector, keyName, splitSelector, REF } = require('./syntax');
-const { numbers } = require('./util');
+const { numbers, hints } = require('./util');
+const { tabState } = require('./tabstate');
+const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
+const { recordingOf, stepTarget } = require('./record');
 
 // The type a page sees for a file it is given, from its extension.
 const MIME_TYPES = {
@@ -176,19 +179,25 @@ function mouseButton(args, name) {
 // click, dblclick and hover: on the match chooseMatch picks, or as Playwright does.
 // A page that renders the chosen element again (as React lists do) replaces it before it is
 // acted on; it is chosen again then, as Playwright finds a locator's element again.
-async function pointerAction(selector, act, options = {}) {
+async function pointerAction(selector, act, options = {}, clicks = 0) {
   const TIMEOUT = 5000;
   const deadline = Date.now() + TIMEOUT;
   const left = () => Math.max(1000, deadline - Date.now());
   for (;;) {
     const chosen = await onElement(selector, () => chooseMatch(selector, left()));
     if (!chosen) {
-      // Only counted so far, so the whole time is Playwright's, as it was before.
-      await onElement(selector, () => act(state.page, selector, { ...options, timeout: TIMEOUT }));
+      // Only counted so far, so the whole time is Playwright's, as it was before; the cursor's glide, if it
+      // is on, waits for the element as part of it.
+      const glided = Date.now();
+      const point = await onElement(selector, () => aimAt(state.page, state.page.locator(selector).first(), TIMEOUT));
+      await onElement(selector, () => act(state.page, selector, { ...options, timeout: Math.max(1000, TIMEOUT - (Date.now() - glided)) }));
+      await landed(point, clicks);
       return '';
     }
     try {
+      const point = await aimAt(state.page, chosen.handle, left());
       await onElement(selector, () => act(chosen.handle, null, { ...options, timeout: left() }));
+      await landed(point, clicks);
       return chosen.position === 1 ? '' : ` (match ${chosen.position} of ${chosen.count}; the ones before it are hidden or covered)`;
     } catch (error) {
       if (!/not attached/i.test(error.message) || Date.now() >= deadline) throw error;
@@ -198,16 +207,103 @@ async function pointerAction(selector, act, options = {}) {
   }
 }
 
+// After a pointer action: Playwright's mouse is where it acted, at the centre the cursor glided to,
+// or somewhere the REPL does not know without the cursor. A click shows where it landed.
+async function landed(point, clicks) {
+  tabState(state.page).mouseAt = point;
+  if (clicks) await showClick(state.page, clicks);
+}
+
+// Finds the element a command without a pointer acts on (fill, select...), for the cursor to glide
+// to, as someone would go to it first, and for a recording's steps; the mouse itself stays where it is. What is left of the command's
+// 5s is its timeout, so the glide does not make it wait longer for an element that never comes.
+async function aimFor(selector) {
+  if (!aiming(state.page)) return 5000;
+  const started = Date.now();
+  await onElement(selector, () => aimAt(state.page, state.page.locator(selector).first(), 5000));
+  return Math.max(1000, 5000 - (Date.now() - started));
+}
+
+// While the tab records, a wheel turn goes in small steps, eased, over 400ms to 1s by its length, so the
+// video scrolls rather than jumps; the same distance in all.
+async function smoothWheel(dx, dy) {
+  const ms = Math.min(1000, Math.max(400, Math.hypot(dx, dy) * 0.8));
+  const steps = Math.max(1, Math.round(ms / 25));
+  const ease = t => t * t * (3 - 2 * t);
+  let sentX = 0;
+  let sentY = 0;
+  for (let i = 1; i <= steps; i += 1) {
+    const x = Math.round(dx * ease(i / steps));
+    const y = Math.round(dy * ease(i / steps));
+    if (x !== sentX || y !== sentY) await state.page.mouse.wheel(x - sentX, y - sentY);
+    sentX = x;
+    sentY = y;
+    await new Promise(resolve => setTimeout(resolve, ms / steps));
+  }
+}
+
+// While the tab records, text is typed at a pace a viewer can follow, steady rather than human-like,
+// and faster for long text, so it takes 8s at most: a paragraph at 60ms a key would outrun send's 20s
+// default and hold every client's commands meanwhile. Otherwise at once, as before.
+function typingPace(text) {
+  if (!recordingOf(state.page) || !text.length) return 0;
+  return Math.round(Math.min(60, 8000 / text.length));
+}
+
+// check, uncheck and upload's button click it at its centre, where aimFor put the cursor.
+async function clickedHere() {
+  const cursor = cursorOf(state.page);
+  if (!cursor) return;
+  tabState(state.page).mouseAt = { x: cursor.x, y: cursor.y };
+  await showClick(state.page);
+}
+
+// The mouse commands act where the mouse is: the cursor goes back there first, if it went elsewhere.
+async function glideToMouse() {
+  const at = tabState(state.page).mouseAt;
+  if (!at) return;
+  stepTarget(state.page, null, at);
+  await glideTo(state.page, at.x, at.y);
+}
+
+// Highlights: Playwright's own overlay, as playwright-cli's highlight draws it. Each is a mode of its
+// tab, so modes shows it and modes off hides it, and none is left on the page when the REPL stops.
+function highlightsOf(p) {
+  if (!tabState(p).highlights) {
+    tabState(p).highlights = new Map();
+    // A new document drops the overlay; a page that routes on the client keeps it.
+    p.on('domcontentloaded', () => tabState(p).highlights?.clear());
+  }
+  return tabState(p).highlights;
+}
+
+// Hides a tab's highlights, or only the running client's (mine).
+async function hideHighlights(p, mine = false) {
+  const highlights = tabState(p).highlights;
+  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();
+  for (const [selector] of hidden) highlights.delete(selector);
+  return hidden.length;
+}
+
+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 => hideHighlights(p).catch(() => {})));
+});
+
 const commands = {
   async click(args) {
     const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
-    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.click(sel, o) : on.click(o)), options);
+    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.click(sel, o) : on.click(o)), options, 1);
     out.log(`Clicked: ${shown}${which}`);
   },
 
   async dblclick(args) {
     const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
-    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.dblclick(sel, o) : on.dblclick(o)), options);
+    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.dblclick(sel, o) : on.dblclick(o)), options, 2);
     out.log(`Double-clicked: ${shown}${which}`);
   },
 
@@ -217,22 +313,64 @@ const commands = {
     out.log(`Hovered: ${args.trim()}${which}`);
   },
 
+  async highlight(args) {
+    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | off]';
+    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag' });
+    const style = found.find(o => o.name === 'style');
+    const hide = found.some(o => o.name === 'hide');
+    const highlights = highlightsOf(state.page);
+    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']]));
+      return;
+    }
+    if (rest === 'off' && !found.length || hide && !rest) {
+      const count = await hideHighlights(state.page);
+      out.log(count ? `Hid ${count} highlight${count === 1 ? '' : 's'}` : 'Nothing was highlighted in the selected tab.');
+      return;
+    }
+    if (!rest || style && (hide || !style.value)) throw new Error(usage);
+    const selector = soleSelector(rest, usage);
+    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();
+      highlights.delete(selector);
+      out.log(`Hid the highlight on ${rest}`);
+      return;
+    }
+    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 });
+    out.log(`Highlighted ${rest}${count > 1 ? ` (all ${count} matches)` : ''}; highlight --hide ${rest} hides it`);
+  },
+
   // At a point, in CSS pixels from the top left of the tab's viewport, as playwright-cli's are.
   async mousemove(args) {
     const [x, y, extra] = numbers(args, 'mousemove <x> <y>');
     if (y === undefined || extra !== undefined) throw new Error('Usage: mousemove <x> <y>, in CSS pixels from the top left of the viewport');
+    stepTarget(state.page, null, { x, y });
+    await glideTo(state.page, x, y);
     await state.page.mouse.move(x, y);
+    tabState(state.page).mouseAt = { x, y };
     out.log(`Moved the mouse to ${x}, ${y}`);
   },
 
   async mousedown(args) {
     const button = mouseButton(args, 'mousedown');
+    await glideToMouse();
     await state.page.mouse.down({ button });
+    await showClick(state.page);
     out.log(`Pressed the ${button} button`);
   },
 
   async mouseup(args) {
     const button = mouseButton(args, 'mouseup');
+    await glideToMouse();
     await state.page.mouse.up({ button });
     out.log(`Released the ${button} button`);
   },
@@ -241,20 +379,27 @@ const commands = {
   async mousewheel(args) {
     const [dx, dy, extra] = numbers(args, 'mousewheel <dx> <dy>');
     if (dy === undefined || extra !== undefined) throw new Error('Usage: mousewheel <dx> <dy>, e.g. mousewheel 0 300 scrolls down (negative dy up)');
-    await state.page.mouse.wheel(dx, dy);
+    await glideToMouse();
+    if (recordingOf(state.page)) await smoothWheel(dx, dy);
+    else await state.page.mouse.wheel(dx, dy);
     out.log(`Turned the wheel by ${dx}, ${dy}`);
   },
 
   async fill(line) {
     const { args, submit } = submitFlag(line);
     const { selector, value, shown } = selectorAndValue(args, 'fill <selector> <value> [--submit]', 'fill #name Ada Lovelace');
-    await onElement(selector, () => state.page.fill(selector, value, { timeout: 5000 }));
+    const timeout = await aimFor(selector);
+    await onElement(selector, () => state.page.fill(selector, value, { timeout }));
     if (submit) await state.page.press(selector, 'Enter', { timeout: 5000 });
     out.log(`Filled${submit ? ' and submitted' : ''}: ${shown}`);
   },
 
   async type(line) {
-    const { args, submit } = submitFlag(line);
+    // --delay=<ms> goes first, so text with --delay in it is still text.
+    const paced = /^\s*--delay(?:=|\s+)(\S*)(?:\s+|$)/.exec(line || '');
+    if (paced && !/^\d+$/.test(paced[1])) throw new Error('Usage: type --delay=<ms> [<selector>] <text>, the pause between keys, e.g. type --delay=80 #search garden hose');
+    const { args, submit } = submitFlag(paced ? line.slice(paced[0].length) : line);
+    const delay = text => (paced ? Number(paced[1]) : typingPace(text));
     // One word, or one quoted, is typed into the focused element, as playwright-cli's type does.
     const sole = splitSelector(args);
     if (sole && sole.rest === undefined) {
@@ -269,12 +414,13 @@ const commands = {
       const usage = 'type <selector> <text> types into an element, e.g. type #search garden hose';
       if (!focused) throw new Error(`Nothing on the page has focus: ${usage}`);
       if (!focused.editable) throw new Error(`The focused element, ${focused.name}, takes no text: ${usage}`);
-      await state.page.keyboard.type(sole.word);
+      await state.page.keyboard.type(sole.word, { delay: delay(sole.word) });
       if (submit) await state.page.keyboard.press('Enter');
       out.log(`Typed into the focused ${focused.name}${submit ? ', and submitted' : ''}`);
       return;
     }
     const { selector, value, shown } = selectorAndValue(args, 'type [<selector>] <text> [--submit]', 'type #search garden hose');
+    const timeout = await aimFor(selector);
     // Typed after what the field already holds, as someone clicking into it
     // at the end would; focusing it alone leaves the caret at the start.
     await onElement(selector, () => state.page.locator(selector).first().evaluate(el => {
@@ -288,8 +434,8 @@ const commands = {
         getSelection().removeAllRanges();
         getSelection().addRange(range);
       }
-    }, null, { timeout: 5000 }));
-    await state.page.keyboard.type(value);
+    }, null, { timeout }));
+    await state.page.keyboard.type(value, { delay: delay(value) });
     if (submit) await state.page.keyboard.press('Enter');
     out.log(`Typed into${submit ? ' and submitted' : ''}: ${shown}`);
   },
@@ -303,25 +449,32 @@ const commands = {
       return;
     }
     const key = keyName(unquote(parsed.rest));
-    await onElement(parsed.selector, () => state.page.press(parsed.selector, key, { timeout: 5000 }));
+    const timeout = await aimFor(parsed.selector);
+    await onElement(parsed.selector, () => state.page.press(parsed.selector, key, { timeout }));
     out.log(`Pressed ${key} on ${parsed.word}`);
   },
 
   async select(args) {
     const { selector, value, shown } = selectorAndValue(args, 'select <selector> <value>', 'select #country Canada');
-    await onElement(selector, () => state.page.selectOption(selector, value, { timeout: 5000 }));
+    const timeout = await aimFor(selector);
+    const target = state.page.locator(selector).first();
+    await onElement(selector, () => showSelect(state.page, target, value, () => state.page.selectOption(selector, value, { timeout })));
     out.log(`Selected "${value}" in ${shown}`);
   },
 
   async check(args) {
     const selector = soleSelector(args, 'check <selector>');
-    await onElement(selector, () => state.page.check(selector, { timeout: 5000 }));
+    const timeout = await aimFor(selector);
+    await onElement(selector, () => state.page.check(selector, { timeout }));
+    await clickedHere();
     out.log(`Checked: ${args.trim()}`);
   },
 
   async uncheck(args) {
     const selector = soleSelector(args, 'uncheck <selector>');
-    await onElement(selector, () => state.page.uncheck(selector, { timeout: 5000 }));
+    const timeout = await aimFor(selector);
+    await onElement(selector, () => state.page.uncheck(selector, { timeout }));
+    await clickedHere();
     out.log(`Unchecked: ${args.trim()}`);
   },
 
@@ -343,6 +496,7 @@ const commands = {
       return { name: path.basename(file), mimeType: mimeType(file), buffer };
     });
     const { selector } = parsed;
+    await aimFor(selector);
     await onElement(selector, async () => {
       try {
         await state.page.setInputFiles(selector, payloads, { timeout: 5000 });
@@ -351,10 +505,11 @@ const commands = {
         // A button that opens the file picker itself: click it, and answer the picker.
         const [chooser] = await Promise.all([state.page.waitForEvent('filechooser', { timeout: 5000 }), state.page.click(selector, { timeout: 5000 })]);
         await chooser.setFiles(payloads);
+        await clickedHere();
       }
     });
     out.log(`Chose ${files.length === 1 ? 'a file' : `${files.length} files`} in ${parsed.word}: ${files.join(', ')}`);
   },
 };
 
-module.exports = { commands, soleSelector, onElement };
+module.exports = { commands, soleSelector, onElement, hideHighlights };

package/lib/help.js

@@ -74,7 +74,7 @@ fill for selectors with spaces. mousemove and the other mouse commands act at a
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
-    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'record', 'viewport', 'emulate', 'wait', 'sleep'],
+    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'highlight', 'cursor', 'record', 'viewport', 'emulate', 'wait', 'sleep'],
   },
   network: {
     intro: `requests and console record all the time; a capture records only while it runs.`,
@@ -105,7 +105,7 @@ selected tab, if any: (watch network:off routes:2 capture) pw>. modes lists them
 
 Times (requests, console, watch) are local, with their UTC offset: 18:16:15.721-06:00.
 
-Dialogs are reported and never answered on their own; dialog answers one.`,
+Dialogs are reported and never answered on their own; dialog accept or dismiss answers one, from any client, whoever opened it.`,
     commands: ['modes', 'dialog', 'help', 'quit'],
   },
 };
@@ -196,10 +196,22 @@ Examples: fill #name Ada Lovelace, fill "text=Your name" Ada, fill e7 Ada`,
     usage: 'type [<selector>] <text> [--submit]',
     summary: 'type key by key after what the field holds; text as for fill',
     detail: `With one word, or one quoted, it is typed into the element that has focus: type "garden hose".
---submit at the end presses Enter afterwards.`,
+--submit at the end presses Enter afterwards.
+
+Keys are sent all at once. While the tab is recording (help record), they are 60ms apart, so the video
+shows the text being typed; long text goes faster, so typing never takes more than 8s, well within
+pw-repl send's 20s default. type --delay=<ms> <selector> <text> sets the gap between keys yourself, with no limit on the
+total; for long text, raise send's -t. It is a gap between keys, not a wait before starting like
+screenshot's --delay. A page that reacts to each key, such as search as you type, may react to each one.`,
   },
   press: { usage: 'press <key> | press <selector> <key>', summary: 'press a key (Enter, Escape, Control+A; any case), maybe on an element' },
-  select: { usage: 'select <selector> <value>', summary: 'choose an option in a select (the value is the rest of the line)' },
+  select: {
+    usage: 'select <selector> <value>',
+    summary: 'choose an option in a select (the value is the rest of the line)',
+    detail: `The value is an option's value or its label. With the cursor on (help cursor), select also draws the
+select's list opening and the cursor choosing the option, since a native select's list opens outside
+the page, where no screenshot or recording sees it; the page gets the same input either way.`,
+  },
   check: { usage: 'check <selector>', summary: 'check a checkbox' },
   uncheck: { usage: 'uncheck <selector>', summary: 'uncheck a checkbox' },
   upload: {
@@ -287,6 +299,27 @@ says how many.`,
   visible: { usage: 'visible <selector>', summary: 'whether the first match is visible' },
   links: { usage: 'links [--all]', summary: 'links on the page (text and href)' },
   inputs: { usage: 'inputs [--all]', summary: 'form controls on the page; values are omitted' },
+  highlight: {
+    usage: 'highlight [<selector> [--style=<css>] | off]',
+    summary: 'draw a box over elements, for a person or a screenshot',
+    detail: `highlight <selector> draws Playwright's highlight over every match, as playwright-cli's does: a
+tinted box, labelled with its locator, that follows the element as the page scrolls or changes, and is
+in screenshots. --style=<css> adds CSS to the box, quoted if it has spaces; this circles e5 in blue:
+  highlight e5 --style="outline: 3px solid blue; border-radius: 50%"
+
+highlight on its own lists the selected tab's highlights. highlight --hide <selector> hides one, and
+highlight --hide or highlight off hides them all. A highlight is a mode of its tab: modes shows it,
+modes off hides it, and the REPL hides every one as it stops. Loading a new page drops them; a page that
+changes its route without loading keeps them.
+
+The box is drawn over the page, in an element of Playwright's own added to it (x-pw-glass); the page's
+own elements are not changed, and clicks and typing reach them as before. Playwright always labels the
+box, and the label can cover what is just below it. For a screenshot without one, eval can outline
+the element itself (with border-radius: 50% for a circle). That changes the page, so put it back
+afterwards, as it was if it had a style of its own:
+  eval document.querySelector("#rate-3").style.outline = "3px solid blue"
+  eval document.querySelector("#rate-3").style.outline = ""`,
+  },
   screenshot: {
     usage: 'screenshot [<ref>] [--full] [-d <secs>] [name]',
     summary: 'save a PNG of the viewport, --full page or an element',
@@ -301,6 +334,28 @@ is at CSS pixel size, one image pixel per CSS pixel. While emulate mobile is on,
 phone shows: a page laid out wider than the phone (no viewport meta tag) comes out shrunk to fit.
 
 --delay counts down out loud first (maximum 60s), so someone can hold a hover or open a menu.`,
+  },
+  cursor: {
+    usage: 'cursor [on [<selector> | <x> <y>] | off]',
+    summary: 'draw a pointer where the REPL acts, for videos',
+    detail: `The REPL's clicks and typing don't move a pointer on screen, so a recording shows things
+happening with nothing pointing at them. cursor on draws a pointer in the selected tab. After that, these
+commands move it smoothly to their element or point before they act: click, dblclick, hover, fill, type
+<selector>, press <selector>, select, check, uncheck, upload and mousemove. Each move takes 150 to 600ms,
+depending on the distance (300 to 1000ms while the tab is recording), and the command waits for it. Clicks (click, dblclick, check, uncheck,
+mousedown, and upload when it clicks a button) show a ring where they land.
+
+It shows only the REPL's input, from every client, never the user's own mouse. Only the drawing moves: no
+mouse events are sent along the way, so the page gets the same input as with the cursor off. fill, select
+and the like move the drawing to their element but leave the real mouse where it was; mousedown, mouseup
+and mousewheel act at the real mouse, so the pointer moves back there first.
+
+cursor on fades it in where the mouse last went (or the middle), cursor on <selector> or <x> <y> fades it in
+there instead (a video's first element, say), cursor off fades it out, and cursor alone says whether it
+is on and where. It is a
+mode of its tab: modes lists it and modes off turns it off. It stays on across page loads, at the same
+spot, and shows in screenshots and recordings. Selectors, snapshot and text don't see it, it takes no
+clicks, and it points at elements inside frames too.`,
   },
   record: {
     usage: 'record [on [file] [seconds] | off [file]]',
@@ -308,25 +363,33 @@ phone shows: a page laid out wider than the phone (no viewport meta tag) comes o
     detail: `record on starts recording the selected tab, and record off stops it and saves the file: its
 path, length, size and bytes. record on its own, or record off when nothing is recording, says whether the
 selected tab is recording, and how your last recording ended (record off, its seconds, its tab closing
-or the REPL stopping) with what record off would have said.
+or the REPL stopping) with what record off would have said. tab close says what became of a recording it ended. A REPL stopped with pw-repl stop cannot be asked: stop prints what became of each recording it ended, and of one that ended by itself that record has not shown since.
 
-record off <file> saves it under that name instead. --filename=<file> is file too, as playwright-cli
+record off <file> saves it under that name instead. The format is set by record on: a name that does not end as its file does, or cannot be used, is refused, and it goes on recording. --filename=<file> is file too, as playwright-cli
 writes it.
 
-The file is a .webm, or an .mp4 if its name ends so, absolute or relative to the folder pw-repl send runs in, and
+The file's ending picks the format: record on clip.mp4 records an MP4, and record on clip.webm, or record on with no file, a WebM (there is no --mp4 or --webm). The file is absolute or relative to the folder pw-repl send runs in, quoted if it has spaces, and
 owner-only, as a screenshot is; it never replaces a file. Without one, it is recording-<timestamp>.webm where screenshot saves. With seconds,
-it stops by itself after them (at most 3600, which is also the default); commands run meanwhile. One recording per tab.
+it stops by itself after them (at most 3600, which is also the default); commands run meanwhile. One recording per tab. Another client with the tab selected can stop it too, as it can any mode; both are then told whose it was.
 
 It brings the tab to the front of its window first, as screenshot does. It records the page only,
-from inside the browser, at the page's size in CSS pixels, made even (an
+from inside the browser, at the viewport's size in CSS pixels, scrollbars included, made even (an
 odd width or height loses a pixel), a phone's too under emulate mobile: a Pixel 7's is 412 wide, less
-sharp than the phone draws it. It has no pointer and no browser toolbars,
+sharp than the phone draws it. It has no pointer (cursor on draws one) and no browser toolbars,
 and a tab behind another, hidden or headless keeps recording. Set the size first with viewport
 (1280x720 fills a 16:9 player); a page that changes size while recording is fitted into the first size.
 Chrome sends a frame as the page draws, and a still page keeps its real length.
 
-It needs ffmpeg: $PW_FFMPEG, then Playwright's own (npx playwright-core install ffmpeg), then one on the
-PATH. Playwright's writes only WebM; an .mp4 needs a system ffmpeg, with H.264. WebM plays in browsers,
+While a tab records, type sends keys at a pace the video can show (help type), and mousewheel scrolls in
+small eased steps over up to 1s rather than at once; fill still sets the whole
+value at once, so use type for text the video should show being typed. record off also saves the steps
+next to the video, as clip.steps.txt for clip.webm: one line for each command run on the tab while it
+recorded, with when it began and ended in seconds into the video, the element or point it acted on in the
+video's pixels, and the command with what it acts on, never what it types or chooses, the code it runs or
+the URL it goes to. A (page) line marks each new page, loaded or routed to by a single-page app. They
+are for editing the video afterwards, such as zooming in on a step. After the page changes size, the steps leave out where they acted.
+
+It needs ffmpeg: $PW_FFMPEG, and only it when it is set (the REPL's, not send's); otherwise Playwright's own (npx playwright-core install ffmpeg, in $PLAYWRIGHT_BROWSERS_PATH or ~/.cache/ms-playwright), then one on the PATH. Playwright's writes only WebM; an .mp4 needs a system ffmpeg, with H.264. record on fails at once, recording nothing, without an ffmpeg that can write its format. If ffmpeg exits while recording, the recording ends then, the pane says what was saved, and the next record off fails with it. ffmpeg writes in blocks, so what it has not written yet is lost: the last seconds, or at first all of it. WebM plays in browsers,
 GitHub, GitLab and Slack; MP4 plays everywhere. It takes about 15 MB a minute.
 
 For a video with the pointer, or of the person's screen, help video compares the other ways.`,
@@ -493,16 +556,17 @@ already happened (requests lists those).`,
     summary: 'send one CDP command through a temporary session',
     detail: `The session is detached afterwards, so subscriptions and settings do not persist.
 
-Browser.close and Target.closeTarget are refused.`,
+Browser.close and Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog answers one.`,
   },
   cookies: { usage: 'cookies [--all]', summary: 'cookie names, domains and flags; values are omitted' },
   storage: { usage: 'storage [--all]', summary: 'localStorage keys; values are omitted' },
   modes: {
     usage: 'modes [off [--mine]]',
     summary: 'the modes on in every tab; modes off turns them all off',
-    detail: `The modes are watch, network off or slow, route, capture, record, emulate and viewport. Each is
-turned on and off with its own command: watch on|off, network off|slow|on, route <glob> ... | route off
-<glob>|--all, capture on|off, record on|off, emulate ... | emulate off, viewport <WxH> | viewport off.
+    detail: `The modes are watch, network off or slow, route, capture, record, emulate, viewport, highlight and cursor.
+Each is turned on and off with its own command: watch on|off, network off|slow|on, route <glob> ... |
+route off <glob>|--all, capture on|off, record on|off, emulate ... | emulate off, viewport <WxH> |
+viewport off, highlight <selector> | highlight off, cursor on|off.
 
 modes off turns off every one in every tab; a capture it stops is kept for capture to show, and a
 recording it stops is saved, as record off would. With
@@ -512,10 +576,11 @@ the sender's own.`,
   dialog: {
     usage: 'dialog [accept [text] | dismiss]',
     summary: 'show, accept or dismiss an open alert, confirm or prompt',
-    detail: `While a dialog is open, its page and the commands that read it wait. dialog runs at once, ahead
-of them; it answers the selected tab's dialog, or the only one open. accept text answers a prompt.
+    detail: `While a dialog is open, its page and the commands that read it wait, a click that opened it included, until it is answered. Commands run one at a time, so every client's commands behind that one wait too, in any tab: in a shared REPL, answer a dialog you open. dialog runs at once, ahead
+of them; it answers the selected tab's dialog (marked *), or the only one open. accept text answers a prompt, and accept alone keeps its default, as OK in the browser does.
 
-With nobody at the browser (e.g. headless), it is the only way to answer one.`,
+An agent can answer any dialog, one it opened included; one the person answers in the browser is gone
+from dialog then. cdp cannot answer one: Chrome lets only a session that saw it open do so. With nobody at the browser (e.g. headless), it is the only way to answer one.`,
   },
   help: { usage: 'help [topic | command | --all]', summary: 'this help; --all prints every topic and command in full' },
   quit: {
@@ -555,8 +620,9 @@ function renderAll() {
 const VIDEO = `There are three ways to record a video of a page, and each gives something up.
 
 record on (help record) records the selected tab's page from inside the browser: headless, hidden and
-background tabs too, with nothing to set up but ffmpeg. It has no pointer and no browser toolbars. For
-quick clips, and for an agent recording its own work.
+background tabs too, with nothing to set up but ffmpeg. It has no pointer and no browser toolbars:
+cursor on draws a pointer that shows where the REPL clicks. For quick clips, and for an agent recording
+its own work.
 
 A screen recorder on the person's machine (OBS, ffmpeg -f x11grab, macOS screencapture -v) records their
 screen as they see it, pointer included, smooth and in real time. It records the screen or a window, not

package/lib/inspect.js

@@ -9,6 +9,7 @@ const { toSelector, REF, unquote } = require('./syntax');
 const { regexOf, COMMAND_TIMEOUT } = require('./util');
 const { tabState } = require('./tabstate');
 const { keptSession } = require('./cdp');
+const { CDP_REFUSED } = require('./dialogs');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
 const { deviceMetrics, viewportMetrics } = require('./emulation');
@@ -429,6 +430,7 @@ const commands = {
     const match = /^(\S+)\s+([\s\S]+)$/.exec(args || '');
     if (!match) throw new Error('Usage: cdp <method> <JSON object>');
     if (['Browser.close', 'Target.closeTarget'].includes(match[1])) throw new Error('Browser lifecycle commands are reserved; use quit or tab close.');
+    if (match[1] === 'Page.handleJavaScriptDialog') throw new Error(CDP_REFUSED);
     const params = JSON.parse(match[2]);
     if (!params || Array.isArray(params) || typeof params !== 'object') throw new Error('Parameters must be a JSON object');
     const operation = async () => {

package/lib/modes.js

@@ -9,6 +9,8 @@ const { emulatedKinds, setEmulation, setViewport } = require('./emulation');
 const { recordingOf, finishRecording } = require('./record');
 const { currentCapture, endCapture } = require('./capture');
 const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
+const { hideHighlights } = require('./elements');
+const { cursorOf, cursorOff } = require('./cursor');
 
 // The modes turned on in a tab, in the order the prompt shows them.
 function activeModes(p) {
@@ -22,6 +24,9 @@ function activeModes(p) {
   if (viewport) modes.push(`viewport:${viewport.width}x${viewport.height}`);
   const routes = tabState(p).routes?.size;
   if (routes) modes.push(`routes:${routes}`);
+  const highlights = tabState(p).highlights?.size;
+  if (highlights) modes.push(`highlight:${highlights}`);
+  if (cursorOf(p)) modes.push('cursor');
   if (currentCapture()?.page === p) modes.push('capture');
   if (recordingOf(p)) modes.push('record');
   return modes;
@@ -70,6 +75,9 @@ function modeOwners(p) {
   const viewport = tabState(p).viewport;
   if (viewport) owners.push([viewport.owner ?? null, 'viewport']);
   for (const [glob, route] of tabState(p).routes || []) owners.push([route.owner ?? null, `route ${glob}`]);
+  for (const [selector, h] of tabState(p).highlights || []) owners.push([h.owner ?? null, `highlight ${selector}`]);
+  const cursor = cursorOf(p);
+  if (cursor) owners.push([cursor.owner ?? null, 'cursor']);
   const capture = currentCapture();
   if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
   const recording = recordingOf(p);
@@ -104,6 +112,9 @@ async function allModesOff(mine = false) {
       const globs = [...(tabState(p).routes || [])].filter(([, route]) => ours(route.owner)).map(([glob]) => glob);
       if (globs.length) { await unroute(p, globs); done.push(`${globs.length} route${globs.length === 1 ? '' : 's'} removed`); }
       if ('network' in tabState(p) && ours(tabState(p).network.owner)) { await setNetwork(p, null); done.push('network on'); }
+      const hidden = await hideHighlights(p, mine);
+      if (hidden) done.push(`${hidden} highlight${hidden === 1 ? '' : 's'} hidden`);
+      if (cursorOf(p) && ours(cursorOf(p).owner) && await cursorOff(p)) done.push('cursor off');
       // Before the page's size is reset, which the recording would otherwise end with.
       const recording = recordingOf(p);
       if (recording && ours(recording.owner)) done.push(`record off (${(await finishRecording(recording)).replace(/\n/g, '; ')})`);