pw-repl 0.7.0 → 0.7.2

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/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 };

package/lib/elements.js

@@ -1,11 +1,12 @@
 // 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');
 
 // The type a page sees for a file it is given, from its extension.
 const MIME_TYPES = {
@@ -198,6 +199,34 @@ async function pointerAction(selector, act, options = {}) {
   }
 }
 
+// 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>]]');
@@ -217,6 +246,42 @@ 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>');
@@ -357,4 +422,4 @@ const commands = {
   },
 };
 
-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', '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'],
   },
 };
@@ -287,6 +287,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',
@@ -308,25 +329,24 @@ 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,
 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,
+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 +513,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 and highlight.
+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.
 
 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 +533,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: {

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,7 @@ 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');
 
 // The modes turned on in a tab, in the order the prompt shows them.
 function activeModes(p) {
@@ -22,6 +23,8 @@ 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 (currentCapture()?.page === p) modes.push('capture');
   if (recordingOf(p)) modes.push('record');
   return modes;
@@ -70,6 +73,7 @@ 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 capture = currentCapture();
   if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
   const recording = recordingOf(p);
@@ -104,6 +108,8 @@ 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`);
       // 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, '; ')})`);

package/lib/record.js

@@ -6,7 +6,8 @@ const path = require('path');
 const { state, onShutdown } = require('./state');
 const out = require('./output');
 const { tabState } = require('./tabstate');
-const { clock, NO_TAB } = require('./util');
+const { clock, NO_TAB, STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
+const { shellWords } = require('./syntax');
 
 const FPS = 25;
 const MAX_SECONDS = 3600;
@@ -27,10 +28,11 @@ const FORMATS = {
   mp4: { encoder: 'libx264', args: ['-c:v', 'libx264', '-preset', 'veryfast', '-crf', '23', '-threads', '1', '-g', String(FPS * 2), '-movflags', '+frag_keyframe+empty_moov+default_base_moof'] },
 };
 
-// PW_FFMPEG, then Playwright's own (wherever PLAYWRIGHT_BROWSERS_PATH puts it), then one on the PATH.
+const FORMAT_NAMES = { webm: 'WebM (VP8)', mp4: 'MP4 (H.264)' };
+
+// Playwright's own (wherever PLAYWRIGHT_BROWSERS_PATH puts it), then one on the PATH.
 function ffmpegCandidates() {
   const found = [];
-  if (process.env.PW_FFMPEG) found.push(process.env.PW_FFMPEG);
   const dir = process.env.PLAYWRIGHT_BROWSERS_PATH || path.join(os.homedir(), '.cache', 'ms-playwright');
   let names = [];
   try { names = fs.readdirSync(dir).filter(n => /^ffmpeg-\d+$/.test(n)).sort().reverse(); } catch {}
@@ -49,20 +51,43 @@ function ffmpegCandidates() {
 
 const encoderLists = new Map();
 
-function hasEncoder(exe, encoder) {
-  if (!encoderLists.has(exe)) {
-    let list = '';
-    try { list = execFileSync(exe, ['-hide_banner', '-encoders'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }); } catch {}
+// What an ffmpeg's -encoders lists, or why it could not say. Only a list is kept: a probe that
+// failed, as one slowed past its timeout on a busy machine can, is tried again the next time.
+function encoderList(exe) {
+  if (encoderLists.has(exe)) return { list: encoderLists.get(exe) };
+  try {
+    const list = execFileSync(exe, ['-hide_banner', '-encoders'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
     encoderLists.set(exe, list);
+    return { list };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { error: 'not found' };
+    if (error.code === 'EACCES') return { error: 'not executable' };
+    if (error.code === 'ETIMEDOUT') return { error: '-encoders did not answer within 5s' };
+    return { error: `-encoders failed (${error.status !== null && error.status !== undefined ? `exit ${error.status}` : error.signal || error.message})` };
   }
-  return new RegExp(`^\\s*V\\S*\\s+${encoder}\\s`, 'm').test(encoderLists.get(exe));
 }
 
-// The first ffmpeg that can write the format.
+function hasEncoder(list, encoder) {
+  return new RegExp(`^\\s*V\\S*\\s+${encoder}\\s`, 'm').test(list || '');
+}
+
+// PW_FFMPEG when it is set, and never another in its place; otherwise the first ffmpeg that can
+// write the format.
 function findFfmpeg(format) {
+  const { encoder } = FORMATS[format];
+  const named = process.env.PW_FFMPEG;
+  if (named) {
+    const { list, error } = encoderList(named);
+    if (error) throw new Error(`PW_FFMPEG=${named} cannot be used: ${error}`);
+    if (!hasEncoder(list, encoder)) throw new Error(`PW_FFMPEG=${named} cannot write ${FORMAT_NAMES[format]}: its -encoders lists no ${encoder}`);
+    return named;
+  }
   const candidates = ffmpegCandidates();
-  if (!candidates.length) throw new Error(`record needs ffmpeg, and none was found: ${INSTALL}; PW_FFMPEG names one`);
-  const exe = candidates.find(c => hasEncoder(c, FORMATS[format].encoder));
+  if (!candidates.length) {
+    const how = format === 'mp4' ? 'an .mp4 needs ffmpeg from your system\'s packages, with H.264 (Playwright\'s writes only WebM)' : INSTALL;
+    throw new Error(`record needs ffmpeg, and none was found: ${how}; PW_FFMPEG names one`);
+  }
+  const exe = candidates.find(c => hasEncoder(encoderList(c).list, encoder));
   if (exe) return exe;
   if (format === 'mp4') throw new Error(`No ffmpeg found can write MP4 (H.264): Playwright's writes only WebM. Install ffmpeg from your system's packages, or name one with PW_FFMPEG; or record to a .webm file`);
   throw new Error(`No ffmpeg found can write WebM (VP8): ${INSTALL}; PW_FFMPEG names one`);
@@ -117,15 +142,18 @@ async function startRecording(p, file, seconds, format) {
   const rec = {
     page: p, file, format, exe, session, owner: state.client, startedAt: Date.now(), firstFrameAt: null,
     size: null, resizedAt: null, written: 0, dropped: 0, latest: null, ff: null, timer: null, limit: null, finishing: null,
-    ffmpegError: '',
+    ffmpegError: '', starting: true,
   };
   // The size is the page's as the screen shows it, in CSS pixels (a phone's too, whose frames come in
   // its device pixels), and Chrome scales each frame to fit it. Not the first frame's: just after a
-  // reload or a change of emulation, that can still be the window's.
+  // reload or a change of emulation, that can still be the window's. Its scrollbars too, as the
+  // frames have them (innerWidth has them; the viewport's clientWidth does not).
   const even = n => Math.max(2, Math.round(n) - (Math.round(n) % 2));
   try {
     const { cssVisualViewport: vv } = await session.send('Page.getLayoutMetrics');
-    rec.size = { width: even(vv.clientWidth * (vv.scale || 1)), height: even(vv.clientHeight * (vv.scale || 1)) };
+    const { result } = await session.send('Runtime.evaluate', { expression: '[innerWidth, innerHeight]', returnByValue: true });
+    const [width, height] = result.value;
+    rec.size = { width: even(width * (vv.scale || 1)), height: even(height * (vv.scale || 1)) };
   } catch (error) {
     session.detach().catch(() => {});
     throw error;
@@ -134,7 +162,7 @@ async function startRecording(p, file, seconds, format) {
   let firstFrame;
   const gotFirstFrame = new Promise(resolve => { firstFrame = resolve; });
   const tick = () => {
-    if (!rec.latest || !rec.ff || rec.finishing) return;
+    if (!rec.latest || !rec.ff || rec.ffExited || rec.finishing) return;
     // The video keeps the wall clock: Chrome sends a frame only when the page redraws,
     // so the latest one is repeated while the page is still.
     const due = Math.floor(((Date.now() - rec.firstFrameAt) / 1000) * FPS);
@@ -178,7 +206,7 @@ async function startRecording(p, file, seconds, format) {
   rec.limit = setTimeout(() => {
     finishRecording(rec, `It reached its ${seconds}s and stopped`).then(text => out.notice(text, p));
   }, seconds * 1000);
-  rec.onClose = () => finishRecording(rec, 'Its tab closed, which ended it').then(text => out.notice(text, p));
+  rec.onClose = () => finishRecording(rec, TAB_CLOSED).then(text => out.notice(text, p));
   p.once('close', rec.onClose);
   return rec;
 }
@@ -195,10 +223,24 @@ function spawnFfmpeg(rec) {
   // A write after ffmpeg has gone is reported when the recording finishes, not thrown.
   ff.stdin.on('error', () => {});
   ff.on('error', error => { rec.ffmpegError += error.message; });
-  rec.exited = new Promise(resolve => ff.once('close', code => resolve(code)));
+  rec.exited = new Promise(resolve => ff.once('close', (code, signal) => {
+    rec.ffExited = true;
+    resolve(code ?? signal);
+    // ffmpeg gone before record off ends the recording now, so no one goes on thinking it records;
+    // record on, still starting it, says so itself.
+    if (!rec.finishing) {
+      rec.exitedEarly = true;
+      finishRecording(rec, 'ffmpeg exited while recording, which ended it').then(text => { if (!rec.starting) out.notice(text, rec.page); });
+    }
+  }));
   return ff;
 }
 
+// An exit code, or the signal that ended ffmpeg.
+function exitText(code) {
+  return typeof code === 'string' ? `was killed by ${code}` : `exited with ${code}`;
+}
+
 // Stops the screencast, lets ffmpeg finish the file, and says what was saved. Once per recording.
 function finishRecording(rec, why = null, { shuttingDown = false } = {}) {
   if (rec.finishing) return rec.finishing;
@@ -207,10 +249,13 @@ function finishRecording(rec, why = null, { shuttingDown = false } = {}) {
   rec.finishing = (async () => {
     const result = await finishFile(rec, shuttingDown);
     const text = typeof result === 'string' ? result : result.text;
-    // A recording that saved nothing makes record off fail, rather than report it as done.
-    rec.failed = typeof result !== 'string';
+    // A recording that saved nothing, or that ffmpeg cut short, makes record off fail rather than
+    // report it as done.
+    rec.failed = typeof result !== 'string' || !!rec.exitedEarly;
     const said = why ? `${why}. ${text}` : text;
-    lastEnded.set(owner, { text: said, at: stoppedAt });
+    // A failure is kept unreported until record off (or record on) has failed with it. One that
+    // ended by itself is unseen until record shows it, and the REPL stopping logs it for stop.
+    lastEnded.set(owner, { text: said, at: stoppedAt, failed: rec.failed, reported: false, seen: !why || shuttingDown });
     return said;
   })();
   const pending = saving.get(owner) || new Set();
@@ -224,7 +269,7 @@ async function finishFile(rec, shuttingDown) {
   if (rec.onClose) rec.page.off('close', rec.onClose);
   if (tabState(rec.page).recording === rec) delete tabState(rec.page).recording;
   // The last frame runs to now, and a recording has one frame at least.
-  if (rec.ff && rec.latest) {
+  if (rec.ff && rec.latest && !rec.ffExited) {
     const due = Math.max(1, Math.floor(((Date.now() - rec.firstFrameAt) / 1000) * FPS));
     for (; rec.written < due; rec.written++) rec.ff.stdin.write(rec.latest);
   }
@@ -256,20 +301,38 @@ async function finishFile(rec, shuttingDown) {
   const saved = fs.existsSync(rec.file) ? fs.statSync(rec.file).size : 0;
   if (!saved) {
     fs.rmSync(rec.file, { force: true });
-    const why = cut ? 'it stopped making progress and was stopped' : `it exited with ${code}${rec.ffmpegError ? `: ${rec.ffmpegError.trim()}` : ', saying nothing'}`;
+    const why = cut ? 'it stopped making progress and was stopped' : `it ${exitText(code)}${rec.ffmpegError ? `: ${rec.ffmpegError.trim()}` : ', saying nothing'}`;
     return { failed: true, text: `Nothing was saved: ffmpeg wrote no video (${rec.written} frames sent; ${why}).` };
   }
   const notes = [];
   if (rec.resizedAt !== null) notes.push(`the page changed size at ${rec.resizedAt.toFixed(1)}s and was fitted into the first size`);
   if (rec.dropped) notes.push(`${rec.dropped} frames dropped, ${(rec.dropped / FPS).toFixed(1)}s, while ffmpeg fell behind`);
-  if (cut) notes.push(`ffmpeg ${shuttingDown ? `did not finish within ${SHUTDOWN_FINISH_TIMEOUT / 1000}s as the REPL stopped` : 'stopped making progress'} and was stopped, so the file is likely cut short of the ${seconds.toFixed(1)}s recorded`);
-  else if (code !== 0) notes.push(`ffmpeg exited with ${code}${rec.ffmpegError ? `: ${rec.ffmpegError.trim()}` : ''}`);
-  return `Saved: ${rec.file} (${seconds.toFixed(1)}s, ${rec.size.width}x${rec.size.height}, ${sizeText(saved)})${notes.length ? `\n${notes.join('; ')}` : ''}`;
+  // An ffmpeg stopped before it finished leaves only what it had written, which it writes in
+  // blocks: seconds of video short of the frames it was sent, and no length in the file's header.
+  const short = `so the file holds only what it had written, short of the ${seconds.toFixed(1)}s recorded, and may not show its length or seek`;
+  if (cut) notes.push(`ffmpeg ${shuttingDown ? `did not finish within ${SHUTDOWN_FINISH_TIMEOUT / 1000}s as the REPL stopped` : 'stopped making progress'} and was stopped, ${short}`);
+  else if (rec.exitedEarly) notes.push(`ffmpeg ${exitText(code)}${rec.ffmpegError ? ` (${rec.ffmpegError.trim()})` : ''}, ${short}`);
+  else if (code !== 0) notes.push(`ffmpeg ${exitText(code)}${rec.ffmpegError ? `: ${rec.ffmpegError.trim()}` : ''}`);
+  const length = cut || rec.exitedEarly ? '' : `${seconds.toFixed(1)}s, `;
+  return `Saved: ${rec.file} (${length}${rec.size.width}x${rec.size.height}, ${sizeText(saved)})${notes.length ? `\n${notes.join('; ')}` : ''}`;
+}
+
+const TAB_CLOSED = 'Its tab closed, which ended it';
+
+// What became of a recording that tab close ended by closing its tab, for it to say.
+async function endedByTabClose(rec) {
+  const text = await finishRecording(rec, TAB_CLOSED);
+  const last = lastEnded.get(rec.owner ?? null);
+  if (last?.text === text) last.seen = true;
+  return text;
 }
 
-// Ends every recording, as the REPL stops, and says in the pane and the log what each saved.
+// Ends every recording, as the REPL stops, and says in the pane and the log what each saved, and
+// what became of any that ended by itself that record has not shown since.
 async function finishAll() {
-  await Promise.all(recordingPages().map(p => finishRecording(recordingOf(p), 'The REPL stopped, which ended a recording', { shuttingDown: true }).then(text => out.log(text), () => {})));
+  for (const last of lastEnded.values()) if (!last.seen) out.log(`${ENDED_UNSEEN}: ${last.text.replace(/\n/g, '; ')}`);
+  // One line each, for stop to find in the log.
+  await Promise.all(recordingPages().map(p => finishRecording(recordingOf(p), STOPPED_RECORDING, { shuttingDown: true }).then(text => out.log(text.replace(/\n/g, '; ')), () => {})));
 }
 
 onShutdown(finishAll);
@@ -278,6 +341,7 @@ function statusText(p) {
   const rec = recordingOf(p);
   if (!rec) {
     const last = lastEnded.get(state.client ?? null);
+    if (last) last.seen = true;
     return `The selected tab is not being recorded; record on starts it.${last ? `\nYour last recording, ended at ${clock(last.at)}: ${last.text}` : ''}`;
   }
   const since = ((Date.now() - (rec.firstFrameAt || rec.startedAt)) / 1000).toFixed(1);
@@ -295,11 +359,14 @@ function fileWords(words, usage) {
     const word = words[i];
     if (word.startsWith('--filename=') && word.length > 11) files.push(word.slice(11));
     else if (word === '--filename' && words[i + 1]) files.push(words[++i]);
+    else if (/^--(?:mp4|webm)$/.test(word)) throw new Error(`record takes no ${word}: the file's ending picks the format, as in record on clip.${word.slice(2)}`);
+    // playwright-cli's video-start --size: here the video is the page's size.
+    else if (/^--size(?:=|$)/.test(word)) throw new Error(`record takes no --size: the video is the page's size; set it first with viewport <width>x<height>`);
     else if (word.startsWith('-')) throw new Error(`record takes no ${word}. ${usage}`);
     else if (/^\d+$/.test(word)) rest.push(word);
     else files.push(word);
   }
-  if (files.length > 1) throw new Error(usage);
+  if (files.length > 1) throw new Error(`record takes one file, and ${files.map(f => `"${f}"`).join(' and ')} are two: quote a file name with spaces in it. ${usage}`);
   return { file: files.length ? path.resolve(files[0]) : null, rest };
 }
 
@@ -309,6 +376,7 @@ function checkFile(file, format) {
   if (format && ext !== format) throw new Error(`This recording is ${format === 'webm' ? 'WebM' : 'MP4'}: name it .${format}, not ${path.basename(file)}`);
   if (fs.existsSync(file)) throw new Error(`Recording already exists: ${file}`);
   if (!fs.existsSync(path.dirname(file))) throw new Error(`No folder ${path.dirname(file)} to save ${path.basename(file)} in`);
+  try { fs.accessSync(path.dirname(file), fs.constants.W_OK); } catch { throw new Error(`Cannot write in ${path.dirname(file)} to save ${path.basename(file)} there`); }
   return ext;
 }
 
@@ -326,7 +394,8 @@ function moveRecording(from, to) {
 
 const commands = {
   async record(args) {
-    const words = (args || '').trim().split(/\s+/).filter(Boolean);
+    // A file may be quoted, with spaces in it.
+    const words = shellWords(args);
     const usage = `Usage: record [on [file.webm|file.mp4] [seconds] | off [file]] (seconds from 1 to ${MAX_SECONDS})`;
     if (!words.length) {
       await Promise.allSettled([...(saving.get(state.client ?? null) || [])]);
@@ -334,17 +403,23 @@ const commands = {
       return;
     }
     const [what, ...rest] = words;
-    // record on its own works with no tab selected, as after the recorded tab closed.
-    if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
     if (what !== 'on' && what !== 'off') throw new Error(usage);
+    // record on its own, and record off, work with no tab selected, as after the recorded tab closed.
+    const noTab = !state.page || state.page.isClosed();
+    if (noTab && what === 'on') throw new Error(NO_TAB);
     // A file given is relative to the REPL's folder; pw-repl send makes it the sender's.
     const { file: named, rest: numbers } = fileWords(rest, usage);
     if (what === 'off') {
       if (numbers.length) throw new Error(usage);
-      const rec = recordingOf(state.page);
+      const rec = noTab ? null : recordingOf(state.page);
       if (!rec) {
         await Promise.allSettled([...(saving.get(state.client ?? null) || [])]);
-        out.log(statusText(state.page));
+        // A recording that ended by itself and saved nothing fails record off, once, as it would
+        // have had record off ended it: its exit status is what an agent checks.
+        const last = lastEnded.get(state.client ?? null);
+        const text = statusText(state.page);
+        if (last?.failed && !last.reported) { last.reported = true; throw new Error(text); }
+        out.log(text);
         return;
       }
       // Its own name again (named at both ends, as playwright-cli habits have it) is no rename.
@@ -353,10 +428,17 @@ const commands = {
       if (rename) {
         try { checkFile(rename, rec.format); } catch (error) { throw new Error(`${error.message}; still recording to ${rec.file}`); }
       }
-      const text = await finishRecording(rec);
-      if (rec.failed) throw new Error(text);
+      // Any client with the tab selected stops it, as it turns off any mode; both are told whose it was.
+      const other = (rec.owner ?? null) !== (state.client ?? null);
+      const clientName = c => c ?? 'the unnamed client';
+      const text = await finishRecording(rec, other ? `${clientName(state.client)}'s record off ended ${clientName(rec.owner)}'s recording` : null);
+      if (rec.failed) { lastEnded.get(rec.owner ?? null).reported = true; throw new Error(text); }
       if (!rename || !fs.existsSync(rec.file)) { out.log(text); return; }
-      moveRecording(rec.file, rename);
+      try {
+        moveRecording(rec.file, rename);
+      } catch (error) {
+        throw new Error(`${text}\nIt could not be renamed to ${rename} (${error.message}), so it stays where it was saved`);
+      }
       const last = lastEnded.get(rec.owner ?? null);
       if (last) last.text = last.text.split(rec.file).join(rename);
       out.log(text.split(rec.file).join(rename));
@@ -378,15 +460,25 @@ const commands = {
       if (error.code === 'EEXIST') throw new Error(`Recording already exists: ${file}`);
       throw error;
     }
+    let rec;
     try {
-      await startRecording(state.page, file, seconds, format);
+      rec = await startRecording(state.page, file, seconds, format);
     } catch (error) {
       fs.rmSync(file, { force: true });
       throw error;
     }
+    // An ffmpeg that stopped as it started (bad arguments, an encoder that failed) has ended it
+    // already, and record on says so instead of a notice.
+    if (rec.finishing) {
+      const text = await rec.finishing;
+      if (rec.failed) { lastEnded.get(rec.owner ?? null).reported = true; throw new Error(text); }
+      out.log(text);
+      return;
+    }
+    rec.starting = false;
     const limit = numbers.length ? `for ${seconds}s` : `until record off (at most ${MAX_SECONDS / 60} minutes)`;
     out.log(`Recording the selected tab to ${file} ${limit}; record off stops it and saves the file.`);
   },
 };
 
-module.exports = { commands, recordingOf, finishRecording, findFfmpeg, jpegSize };
+module.exports = { commands, recordingOf, finishRecording, endedByTabClose, findFfmpeg, jpegSize };

package/lib/runner.js

@@ -4,7 +4,7 @@ const readline = require('readline');
 const { state, clientRecord, asClient, beforeExit } = require('./state');
 const out = require('./output');
 const { commands, cliCommands, needsTab } = require('./commands');
-const { dialogCommand } = require('./dialogs');
+const { dialogCommand, CDP_ANSWER, CDP_REFUSED } = require('./dialogs');
 const { activeModes } = require('./modes');
 const { NO_TAB } = require('./util');
 const cliNames = require('./cli-names');
@@ -172,7 +172,8 @@ function prompt(preserveCursor) {
 function enqueue(line) {
   const text = parseInput(line).text;
   const direct = /^quit(?:\s|$)/.test(text) || DIALOG.test(text);
-  if (direct) handleLine(line, true).catch(e => out.error(`Error: ${e.message}`));
+  if (CDP_ANSWER.test(text)) out.error(`Error: ${CDP_REFUSED}`);
+  else if (direct) handleLine(line, true).catch(e => out.error(`Error: ${e.message}`));
   else queue = queue.then(() => handleLine(line)).catch(e => out.error(`Error: ${e.message}`));
 }
 
@@ -181,6 +182,10 @@ function enqueue(line) {
 // client names the sender: its commands show as [server:<client>] and use its own selected tab.
 function submit(text, client = null) {
   if (DIALOG.test(text)) return answerDialog(text, client);
+  if (CDP_ANSWER.test(text)) {
+    console.log(`[server${client ? `:${client}` : ''}] ${text}\nError: ${CDP_REFUSED}`);
+    return Promise.resolve({ status: 'error', output: `Error: ${CDP_REFUSED}` });
+  }
   return new Promise(resolve => {
     queue = queue.then(async () => {
       if (state.stopping) return resolve({ status: 'error', output: 'The REPL is shutting down.' });

package/lib/syntax.js

@@ -18,6 +18,13 @@ function unquote(text) {
   return match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2];
 }
 
+// The words of a line as a shell reads them: quoted parts may hold spaces, and lose their quotes
+// (--filename="my dir/a.webm" is one word, --filename=my dir/a.webm).
+function shellWords(text) {
+  return [...(text || '').matchAll(/(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']+|["'])+/g)]
+    .map(m => m[0].replace(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g, (_, double, single) => (double !== undefined ? double.replace(/\\(.)/g, '$1') : single)));
+}
+
 // The first word of args, or a quoted selector with spaces in it, and the rest of the line.
 function splitSelector(args) {
   const match = /^(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+))(?:\s+([\s\S]*))?$/.exec((args || '').trim());
@@ -47,4 +54,4 @@ function keyName(key) {
   return key.split(/\+(?!$)/).map(part => (part.length > 1 ? KEYS.get(part.toLowerCase()) || part : part)).join('+');
 }
 
-module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, splitSelector, keyName };
+module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, shellWords, splitSelector, keyName };

package/lib/tabs.js

@@ -7,6 +7,7 @@ const { keepDrawing } = require('./cdp');
 const { ensureDialogHandler } = require('./dialogs');
 const { notLoaded, stayedPut } = require('./requestlog');
 const { viewportText } = require('./emulation');
+const { recordingOf, endedByTabClose } = require('./record');
 
 // A navigation that does not load is said as wait load says it, from its request, rather than as
 // Playwright's net:: error and call log.
@@ -184,6 +185,7 @@ const commands = {
       if (all.length <= 1) throw new Error('Refusing to close the last tab');
       const url = target.url();
       const wasSelected = target === state.page;
+      const recording = recordingOf(target);
       await target.close();
       if (wasSelected) {
         const back = state.previousPage;
@@ -191,6 +193,7 @@ const commands = {
         state.previousPage = null;
       }
       out.log(`Closed ${url}${wasSelected && !state.page ? '; no tab is selected now' : ''}`);
+      if (recording) out.log(await endedByTabClose(recording));
       return listTabs();
     }
     select(byUrl(trimmed));

package/lib/util.js

@@ -46,4 +46,9 @@ function clock(t) {
   return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}${zone}`;
 }
 
-module.exports = { COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock };
+// How the REPL, as it stops, begins what it says of each recording it ended, and of one that ended
+// by itself unseen: stop prints those lines.
+const STOPPED_RECORDING = 'The REPL stopped, which ended a recording';
+const ENDED_UNSEEN = 'A recording ended before the REPL stopped, unseen since';
+
+module.exports = { STOPPED_RECORDING, ENDED_UNSEEN, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock };

package/package.json

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

package/skill/SKILL.md

@@ -195,12 +195,16 @@ pw-repl send -c <name> close                        # your modes off; tab close
   one too; otherwise no tab is selected.
   Tab numbers change when tabs open or close; `tab <url-part>` and `tab close <url-part>` pick a tab by
   its URL and refuse if it is ambiguous.
-- Dialogs are never answered on their own. While one is open, its page and the commands that read it
-  wait; `dialog` shows it, and `dialog accept` or `dialog dismiss` answers it.
+- You can answer any dialog yourself, one you opened included: `dialog` shows it, and `dialog accept`
+  or `dialog dismiss` answers it. Nothing answers one on its own, and while one is open its page and
+  the commands that read it wait. One answered in the browser is gone from `dialog` too.
 - Modes and tabs stay on or open until they are turned off or closed, whoever started them. `modes`
   lists what is on in every tab (the prompt shows the selected tab's, e.g. `(watch routes:1) pw>`);
   `modes off` turns off every mode in every tab.
 - Someone may be attached to the REPL's tmux session; killing the session ends it for them too.
+- To point something out, to the person or in a screenshot, `highlight <ref|selector>` draws a box over it
+  without changing the page (`--style=<css>` restyles it; `highlight off` hides them). Its label can
+  cover what is below it; `help highlight` says how to mark a screenshot without one.
 - For a video, `help video` says which way suits what you want: `record on` records a tab's page, and a
   screen recorder on the person's machine records what they see.
 
@@ -209,7 +213,10 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - Chromium must be running with `--remote-debugging-port=9222`, unless `--launch` starts one. A headless
   one works too (`--headless=new`); nobody answers its dialogs but `dialog`.
 - `PW_CHROME` — the Chromium `--launch` starts (default: Playwright's own, then one on the `PATH`).
-- `PW_FFMPEG` — the ffmpeg `record` uses (default: Playwright's own, then one on the `PATH`).
+- `PW_FFMPEG` — the ffmpeg `record` uses, and no other, read by the REPL, not by `send` (default:
+  Playwright's own, then one on the `PATH`).
+- Playwright's own Chromium and ffmpeg are found where Playwright installs them: `PLAYWRIGHT_BROWSERS_PATH`,
+  or `~/.cache/ms-playwright`.
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
 - `PW_SCREENSHOT_DIR` — where the REPL saves screenshots, read when it starts, not by `send`. Without it,
   a REPL on a socket of its own saves them next to its socket, and any other in `/tmp`. `screenshot`