pw-repl 0.7.0 → 0.8.0

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, splitSelector } = 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,19 @@ 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, scale: 1, steps: [], step: null, stepsFile: null,
   };
   // 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.scale = vv.scale || 1;
+    rec.size = { width: even(width * rec.scale), height: even(height * rec.scale) };
   } catch (error) {
     session.detach().catch(() => {});
     throw error;
@@ -134,7 +163,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,8 +207,19 @@ 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);
+  // A new page, loaded or routed to by a single-page app, is a step of its own: a zoom that follows the
+  // cursor ends there. Its URL is left out, as a step's values are.
+  rec.onNavigated = frame => {
+    if (frame !== p.mainFrame() || rec.finishing) return;
+    const t = videoTime(rec);
+    // An app that sets its URL twice in a row (push, then replace) is one new page.
+    const last = rec.steps[rec.steps.length - 1];
+    if (last?.command === '(page)' && t - last.t0 < 0.5) return;
+    rec.steps.push({ rec, t0: t, t1: t, command: '(page)', box: null, point: null, offSize: false, failed: false });
+  };
+  p.on('framenavigated', rec.onNavigated);
   return rec;
 }
 
@@ -195,10 +235,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 +261,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();
@@ -222,9 +279,10 @@ function finishRecording(rec, why = null, { shuttingDown = false } = {}) {
 async function finishFile(rec, shuttingDown) {
   clearTimeout(rec.limit);
   if (rec.onClose) rec.page.off('close', rec.onClose);
+  if (rec.onNavigated) rec.page.off('framenavigated', rec.onNavigated);
   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 +314,128 @@ 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, `;
+  const steps = writeSteps(rec, seconds);
+  const stepsLine = !steps ? '' : steps.error ? `\nIts steps were not saved: ${steps.error}` : `\nSteps: ${steps.file} (${steps.count}; when each command ran, and where)`;
+  return `Saved: ${rec.file} (${length}${rec.size.width}x${rec.size.height}, ${sizeText(saved)})${notes.length ? `\n${notes.join('; ')}` : ''}${stepsLine}`;
+}
+
+// The steps: when each command the REPL ran on a recording tab began and ended, in the video's own
+// seconds, and the element or point it acted on in the video's pixels, saved next to the video for
+// whoever edits it (a zoom on a step, say). Only that: watch is the log of what happened.
+
+// The video's clock: frames are written against the wall clock since the first, less those dropped.
+function videoTime(rec) {
+  return rec.firstFrameAt === null ? 0 : Math.max(0, (Date.now() - rec.firstFrameAt) / 1000 - rec.dropped / FPS);
+}
+
+// What a step is, for its line: the command and what it acts on, never what it types or chooses, the
+// code it runs or the URL it goes to, which can hold a password or a token. A steps file goes where the
+// video goes, and the video shows a password as dots.
+const WHOLE = new Set(['click', 'dblclick', 'hover', 'check', 'uncheck', 'mousemove', 'mousedown', 'mouseup', 'mousewheel']);
+const TARGET_FIRST = new Set(['fill', 'type', 'select', 'press', 'upload']);
+function stepLabel(cmd, args) {
+  if (WHOLE.has(cmd)) return `${cmd} ${args.replace(/\s+--modifiers=\S+/, '')}`.trim();
+  if (!TARGET_FIRST.has(cmd)) return cmd;
+  const rest = cmd === 'type' ? args.replace(/^\s*--delay(?:=|\s+)\S*\s*/, '') : args;
+  const parsed = splitSelector(rest);
+  // type and press with one word act on the focused element: the word is the text or the key.
+  return parsed && parsed.rest !== undefined ? `${cmd} ${parsed.word}` : cmd;
+}
+
+function stepStarted(p, command) {
+  const rec = recordingOf(p);
+  if (!rec || rec.finishing) return null;
+  // After the page changed size, its frames are fitted into the first size, so its pixels are not the video's.
+  rec.step = { rec, t0: videoTime(rec), t1: null, command, box: null, point: null, offSize: rec.resizedAt !== null, failed: false };
+  rec.steps.push(rec.step);
+  return rec.step;
+}
+
+function stepEnded(step, failed) {
+  if (!step) return;
+  step.t1 = videoTime(step.rec);
+  step.failed = failed;
+  if (step.rec.step === step) step.rec.step = null;
 }
 
-// Ends every recording, as the REPL stops, and says in the pane and the log what each saved.
+// The element (box) or point the running step acts on, in CSS pixels.
+function stepTarget(p, box, point) {
+  const rec = recordingOf(p);
+  if (!rec?.step) return;
+  const scaled = o => o && Object.fromEntries(Object.entries(o).map(([k, v]) => [k, Math.round(v * rec.scale)]));
+  rec.step.box = scaled(box);
+  rec.step.point = scaled(point);
+}
+
+// Where the cursor went (cursor on), and when: a line of its own, not a command's step.
+function cursorStep(p, what, point, ms) {
+  const rec = recordingOf(p);
+  if (!rec || rec.finishing) return;
+  const t0 = videoTime(rec);
+  const scaled = Math.round(point.x * rec.scale);
+  rec.steps.push({ rec, t0, t1: t0 + ms / 1000, command: what.replace(/-?\d+(?:\.\d+)?/g, n => String(Math.round(Number(n) * rec.scale))), box: null, point: { x: scaled, y: Math.round(point.y * rec.scale) }, offSize: rec.resizedAt !== null, failed: false });
+}
+
+function stepsPath(file) {
+  return file.replace(/\.[^./]+$/, '') + '.steps.txt';
+}
+
+// One line a step: t0 t1, then x y w h of its element (a point is x y 0 0; none, or not in the video's
+// pixels, is - - - -), then the command. Plain words, for a shell script to read.
+function writeSteps(rec, seconds) {
+  if (!rec.steps.length) return null;
+  const file = stepsPath(rec.file);
+  const lines = [
+    `# pw-repl record steps, for a video of ${rec.size.width}x${rec.size.height}, ${seconds.toFixed(2)}s long`,
+    '# t0 t1: when the command began and ended, in seconds into the video',
+    '# x y w h: its element in the video\'s pixels (a point: w and h are 0; none: -)',
+    '# (cursor from X Y): the cursor (cursor on) glided from X Y to x y between t0 and t1',
+    '# (page): the tab went to a new page, loaded or routed to by a single-page app',
+    ...(rec.resizedAt !== null ? [`# the page changed size at ${rec.resizedAt.toFixed(2)}s: boxes after it are left out`] : []),
+  ];
+  for (const s of rec.steps) {
+    const where = s.offSize ? null : s.box || (s.point && { x: s.point.x, y: s.point.y, width: 0, height: 0 });
+    const xywh = where ? `${where.x} ${where.y} ${where.width} ${where.height}` : '- - - -';
+    lines.push(`${s.t0.toFixed(2)} ${(s.t1 ?? videoTime(rec)).toFixed(2)} ${xywh} ${s.command}${s.failed ? '  # failed' : ''}`);
+  }
+  try {
+    fs.writeFileSync(file, `${lines.join('\n')}\n`, { flag: 'wx', mode: 0o600 });
+  } catch (error) {
+    return { file, error: error.code === 'EEXIST' ? `${file} already exists` : error.message };
+  }
+  rec.stepsFile = file;
+  return { file, count: rec.steps.length };
+}
+
+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, 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 +444,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 +462,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 +479,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 +497,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 +506,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,13 +531,29 @@ 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`);
+      }
+      // Its steps go with it, unless a file has the new name already.
+      let renamed = t => t.split(rec.file).join(rename);
+      if (rec.stepsFile && !fs.existsSync(stepsPath(rename))) {
+        try {
+          moveRecording(rec.stepsFile, stepsPath(rename));
+          const before = renamed;
+          renamed = t => before(t.split(rec.stepsFile).join(stepsPath(rename)));
+        } catch {}
+      }
       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));
+      if (last) last.text = renamed(last.text);
+      out.log(renamed(text));
       return;
     }
     if (numbers.length > 1) throw new Error(usage);
@@ -378,15 +572,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, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };

package/lib/runner.js

@@ -4,9 +4,10 @@ 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 { stepStarted, stepEnded, stepLabel } = require('./record');
 const cliNames = require('./cli-names');
 
 // playwright-cli names already explained, per client: each client is told once.
@@ -105,9 +106,13 @@ async function executeCommand(text) {
     out.error(`Error: ${NO_TAB}`);
     return { status: 'error', cmd };
   }
+  // A recording tab notes when each command that may change it ran, for its steps file (help record).
+  const step = READ_ONLY.has(cmd) || NO_TAB_NEEDED.has(cmd) || !state.page || state.page.isClosed() ? null : stepStarted(state.page, stepLabel(cmd, args));
   try {
     await run(args, all);
+    stepEnded(step, false);
   } catch (e) {
+    stepEnded(step, true);
     // Playwright colours its call log; the codes are noise anywhere but a terminal.
     e.message = String(e.message || '').replace(/\x1b\[[0-9;]*m/g, '');
     out.error(`Error: ${e.message}`);
@@ -172,7 +177,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 +187,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/tabstate.js

@@ -11,6 +11,9 @@
 //                  with the owner
 //   viewport       the size viewport set: { width, height }, with the owner
 //   recording      its recording (record on): the ffmpeg writing it, its file, its owner
+//   cursor         its cursor (cursor on): where it is drawn { x, y }, with the owner
+//   cursorKept     its cursor is drawn again on each new page
+//   mouseAt        where the REPL last put the mouse { x, y }, when it knows
 //   routes         Map(glob -> { status, body, handler, owner })
 //   log            its recent requests (requests)
 //   consoleLog     its recent console messages and page errors (console)

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.8.0",
   "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
   "keywords": [
     "playwright",

package/skill/SKILL.md

@@ -195,21 +195,29 @@ 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.
-- 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.
+- 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 (`cursor
+  on` draws a pointer where you act, for the viewer), and a screen recorder on the person's machine records
+  what they see.
 
 ## Environment
 
 - 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`