pw-repl 0.8.1 → 0.9.0

package/lib/inspect.js

@@ -33,7 +33,7 @@ async function deviceShot(device, { ref, full, type }) {
     const box = await onElement(selector, async () => {
       const locator = state.page.locator(selector);
       await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
-      return locator.evaluate(el => { const r = el.getBoundingClientRect(); return { x: r.x + scrollX, y: r.y + scrollY, width: r.width, height: r.height }; });
+      return locator.evaluate(el => { const r = el.getBoundingClientRect(); return { x: r.x + scrollX, y: r.y + scrollY, width: r.width, height: r.height }; }, null, { timeout: 5000 });
     });
     clip = box;
   }

package/lib/record.js

@@ -8,9 +8,15 @@ const out = require('./output');
 const { tabState } = require('./tabstate');
 const { clock, NO_TAB, STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
 const { shellWords, splitSelector } = require('./syntax');
+const { keptSession } = require('./cdp');
+const { deviceMetrics, viewportMetrics, settled } = require('./emulation');
 
 const FPS = 25;
 const MAX_SECONDS = 3600;
+// While recording: a moment after each action for its result to be seen, and still page at both ends,
+// so a video neither starts nor stops on an action (record on --pause, --lead, --tail).
+const PACING = { pause: 750, lead: 1000, tail: 1000 };
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 // Frames waiting for ffmpeg past this are dropped rather than held in memory.
 const MAX_QUEUED = 32 * 1024 * 1024;
 // How long ffmpeg may go without progress on the frames still queued for it before it is stopped,
@@ -126,23 +132,39 @@ function recordingOf(p) {
   return tabState(p).recording || null;
 }
 
+async function restoreMetrics(p, rec) {
+  if (rec?.finishing) return;
+  const tab = tabState(p);
+  if (!tab.viewport && !tab.emulation?.device) return;
+  const kept = await keptSession(p);
+  if (rec?.finishing) return;
+  if (tab.viewport) await viewportMetrics(kept, tab.viewport);
+  else if (tab.emulation?.device) await deviceMetrics(kept, tab.emulation.device);
+  await settled(p);
+}
+
 // The tabs recording now, for the modes they count as.
 function recordingPages() {
   if (!state.browser) return [];
   return state.browser.contexts().flatMap(c => c.pages()).filter(p => recordingOf(p));
 }
 
-async function startRecording(p, file, seconds, format) {
+async function startRecording(p, file, seconds, format, keepSteps, pacing) {
   const exe = findFfmpeg(format);
   // As screenshot does: a tab that has not been in front since it was emulated as a phone can
   // be drawn at the window's size.
   await p.bringToFront();
+  // Bringing an emulated tab to the front can leave Chrome's capture surface at the window's size
+  // after its next navigation. Reapply the active screen metrics on the kept session before measuring
+  // or starting this recording, then wait for the page to draw at them.
+  await restoreMetrics(p);
   // Its own session: Chrome keeps one screencast per session, and the kept session's keeps the tab drawing.
   const session = await p.context().newCDPSession(p);
   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: '', starting: true, scale: 1, steps: [], step: null, stepsFile: null,
+    ffmpegError: '', starting: true, scale: 1, keepSteps, pacing, steps: [], step: null, stepsFile: null,
+    holdFrames: false, restarting: false, navigationVersion: 0, restoreError: null, mainFrameId: null, screencastParams: 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
@@ -150,11 +172,39 @@ async function startRecording(p, file, seconds, format) {
   // 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 {
+    await session.send('Page.enable');
+    const tree = await session.send('Page.getFrameTree');
+    rec.mainFrameId = tree.frameTree.frame.id;
+    // Full document navigations reset Chrome's capture surface; SPA route changes do not.
+    session.on('Page.frameNavigated', ({ frame }) => {
+      if (frame.id !== rec.mainFrameId || rec.finishing) return;
+      rec.navigationVersion += 1;
+      const tab = tabState(p);
+      rec.holdFrames = !!(tab.viewport || tab.emulation?.device);
+    });
+    session.on('Page.domContentEventFired', async () => {
+      if (!rec.holdFrames || rec.finishing) return;
+      const version = rec.navigationVersion;
+      try {
+        await restoreMetrics(p, rec);
+        if (rec.finishing || version !== rec.navigationVersion) return;
+        await session.send('Page.stopScreencast');
+        if (rec.finishing || version !== rec.navigationVersion) return;
+        rec.holdFrames = false;
+        rec.restarting = true;
+        await session.send('Page.startScreencast', rec.screencastParams);
+      } catch (error) {
+        if (rec.finishing || p.isClosed() || version !== rec.navigationVersion) return;
+        rec.restoreError = error.message;
+        out.notice(await finishRecording(rec, `Could not restore the recording size: ${error.message}`), p);
+      }
+    });
     const { cssVisualViewport: vv } = await session.send('Page.getLayoutMetrics');
     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) };
+    rec.screencastParams = { format: 'jpeg', quality: 85, maxWidth: rec.size.width, maxHeight: rec.size.height };
   } catch (error) {
     session.detach().catch(() => {});
     throw error;
@@ -180,6 +230,11 @@ async function startRecording(p, file, seconds, format) {
     if (!size) return;
     // A frame the size of the video, to a pixel (Chrome scales it to fit, keeping its shape).
     const fits = Math.abs(size.width - rec.size.width) <= 1 && Math.abs(size.height - rec.size.height) <= 1;
+    if (rec.restarting && rec.latest) {
+      if (!fits) { tick(); return; }
+      rec.restarting = false;
+    }
+    if (rec.holdFrames && rec.latest) { tick(); return; }
     if (!rec.ff) {
       rec.firstFrameAt = Date.now();
       rec.ff = spawnFfmpeg(rec);
@@ -195,7 +250,7 @@ async function startRecording(p, file, seconds, format) {
     rec.latest = image;
   });
   try {
-    await session.send('Page.startScreencast', { format: 'jpeg', quality: 85, maxWidth: rec.size.width, maxHeight: rec.size.height });
+    await session.send('Page.startScreencast', rec.screencastParams);
   } catch (error) {
     delete tabState(p).recording;
     session.detach().catch(() => {});
@@ -209,10 +264,10 @@ async function startRecording(p, file, seconds, format) {
   }, seconds * 1000);
   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.
+  // A new page, loaded or routed to by a single-page app, is a step of its own, for whoever edits the
+  // video to cut or caption there. Its URL is left out, as a step's values are.
   rec.onNavigated = frame => {
-    if (frame !== p.mainFrame() || rec.finishing) return;
+    if (frame !== p.mainFrame() || rec.finishing || !keepSteps) 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];
@@ -242,7 +297,7 @@ function spawnFfmpeg(rec) {
     // 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); });
+      finishRecording(rec, 'ffmpeg exited while recording, which ended it (help record --all)').then(text => { if (!rec.starting) out.notice(text, rec.page); });
     }
   }));
   return ff;
@@ -263,7 +318,7 @@ function finishRecording(rec, why = null, { shuttingDown = false } = {}) {
     const text = typeof result === 'string' ? result : result.text;
     // 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;
+    rec.failed = typeof result !== 'string' || !!rec.exitedEarly || !!rec.restoreError;
     const said = why ? `${why}. ${text}` : text;
     // 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.
@@ -318,7 +373,7 @@ async function finishFile(rec, shuttingDown) {
     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.resizedAt !== null) notes.push(`the page changed size at ${rec.resizedAt.toFixed(1)}s and was fitted into the first size (help record --all)`);
   if (rec.dropped) notes.push(`${rec.dropped} frames dropped, ${(rec.dropped / FPS).toFixed(1)}s, while ffmpeg fell behind`);
   // 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.
@@ -334,7 +389,7 @@ async function finishFile(rec, shuttingDown) {
 
 // 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.
+// whoever edits it (a caption or a cut at 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) {
@@ -347,7 +402,12 @@ function videoTime(rec) {
 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 (WHOLE.has(cmd)) {
+    const words = args.replace(/\s+--modifiers=\S+/, '').trim();
+    // An element's selector as written, without the quotes it needed on the command line (click's button after it).
+    const parsed = /^mouse/.test(cmd) ? null : splitSelector(words);
+    return `${cmd} ${parsed ? [parsed.word, parsed.rest].filter(Boolean).join(' ') : words}`.trim();
+  }
   if (!TARGET_FIRST.has(cmd)) return cmd;
   const rest = cmd === 'type' ? args.replace(/^\s*--delay(?:=|\s+)\S*\s*/, '') : args;
   const parsed = splitSelector(rest);
@@ -355,8 +415,14 @@ function stepLabel(cmd, args) {
   return parsed && parsed.rest !== undefined ? `${cmd} ${parsed.word}` : cmd;
 }
 
-function stepStarted(p, command) {
+// The recording that keeps its steps (record on --steps), if the tab has one.
+function stepsOf(p) {
   const rec = recordingOf(p);
+  return rec?.keepSteps ? rec : null;
+}
+
+function stepStarted(p, command) {
+  const rec = stepsOf(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 };
@@ -373,7 +439,7 @@ function stepEnded(step, failed) {
 
 // The element (box) or point the running step acts on, in CSS pixels.
 function stepTarget(p, box, point) {
-  const rec = recordingOf(p);
+  const rec = stepsOf(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);
@@ -382,13 +448,20 @@ function stepTarget(p, box, 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);
+  const rec = stepsOf(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 });
 }
 
+// The pause after an action on a recording tab, for its result to be seen (record on --pause).
+const ACTIONS = new Set([...WHOLE, ...TARGET_FIRST]);
+async function pauseAfter(p, cmd) {
+  const rec = p && !p.isClosed() ? recordingOf(p) : null;
+  if (rec && !rec.finishing && rec.pacing.pause && ACTIONS.has(cmd)) await sleep(rec.pacing.pause);
+}
+
 function stepsPath(file) {
   return file.replace(/\.[^./]+$/, '') + '.steps.txt';
 }
@@ -396,7 +469,7 @@ function stepsPath(file) {
 // 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;
+  if (!rec.keepSteps || !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`,
@@ -440,6 +513,12 @@ async function finishAll() {
 
 onShutdown(finishAll);
 
+// The pacing options record on was given, where they differ from the defaults.
+function pacingText(pacing) {
+  const changed = Object.keys(PACING).filter(k => pacing[k] !== PACING[k]).map(k => `--${k}=${pacing[k]}`);
+  return changed.length ? `, ${changed.join(' ')}` : '';
+}
+
 function statusText(p) {
   const rec = recordingOf(p);
   if (!rec) {
@@ -449,8 +528,8 @@ function statusText(p) {
   }
   const since = ((Date.now() - (rec.firstFrameAt || rec.startedAt)) / 1000).toFixed(1);
   const size = rec.size ? `, ${rec.size.width}x${rec.size.height}` : ', no frame yet';
-  const resized = rec.resizedAt !== null ? `; the page changed size at ${rec.resizedAt.toFixed(1)}s and is fitted into the first size` : '';
-  return `Recording the selected tab to ${rec.file} since ${clock(rec.startedAt)} (${since}s${size})${rec.owner ? `, by ${rec.owner}` : ''}${resized}; record off stops it and saves the file.`;
+  const resized = rec.resizedAt !== null ? `; the page changed size at ${rec.resizedAt.toFixed(1)}s and is fitted into the first size (help record --all)` : '';
+  return `Recording the selected tab to ${rec.file} since ${clock(rec.startedAt)} (${since}s${size})${rec.owner ? `, by ${rec.owner}` : ''}${rec.keepSteps ? ', with its steps' : ''}${pacingText(rec.pacing)}${resized}; record off stops it and saves the file.`;
 }
 
 // A file word, as given or as playwright-cli's --filename=<file> (or --filename <file>); any other
@@ -458,9 +537,17 @@ function statusText(p) {
 function fileWords(words, usage) {
   const files = [];
   const rest = [];
+  let steps = false;
+  const pacing = {};
   for (let i = 0; i < words.length; i++) {
     const word = words[i];
-    if (word.startsWith('--filename=') && word.length > 11) files.push(word.slice(11));
+    const timing = /^--(pause|lead|tail)(?:=(.*))?$/.exec(word);
+    if (word === '--steps') steps = true;
+    else if (timing) {
+      if (!/^\d+$/.test(timing[2] ?? '') || Number(timing[2]) > 10000) throw new Error(`record on --${timing[1]}=<ms> takes milliseconds, from 0 to 10000 (default ${PACING[timing[1]]})`);
+      pacing[timing[1]] = Number(timing[2]);
+    }
+    else 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.
@@ -470,7 +557,7 @@ function fileWords(words, usage) {
     else files.push(word);
   }
   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 };
+  return { file: files.length ? path.resolve(files[0]) : null, rest, steps, pacing };
 }
 
 function checkFile(file, format) {
@@ -499,7 +586,7 @@ const commands = {
   async record(args) {
     // 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})`;
+    const usage = `Usage: record [on [file.webm|file.mp4] [seconds] [--steps] [--pause=<ms>] [--lead=<ms>] [--tail=<ms>] | off [file]] (seconds from 1 to ${MAX_SECONDS})`;
     if (!words.length) {
       await Promise.allSettled([...(saving.get(state.client ?? null) || [])]);
       out.log(statusText(state.page));
@@ -511,8 +598,10 @@ const commands = {
     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);
+    const { file: named, rest: numbers, steps, pacing } = fileWords(rest, usage);
     if (what === 'off') {
+      if (Object.keys(pacing).length) throw new Error(`--${Object.keys(pacing)[0]} goes on record on`);
+      if (steps) throw new Error('--steps goes on record on, which notes each step from the start: record off, then record on <file> --steps for a take with its steps');
       if (numbers.length) throw new Error(usage);
       const rec = noTab ? null : recordingOf(state.page);
       if (!rec) {
@@ -534,6 +623,8 @@ const commands = {
       // 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';
+      // The tail: still page after the last action. Only record off has one; the seconds limit is a hard stop.
+      if (!rec.finishing) await sleep(rec.pacing.tail);
       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; }
@@ -574,7 +665,7 @@ const commands = {
     }
     let rec;
     try {
-      rec = await startRecording(state.page, file, seconds, format);
+      rec = await startRecording(state.page, file, seconds, format, steps, { ...PACING, ...pacing });
     } catch (error) {
       fs.rmSync(file, { force: true });
       throw error;
@@ -588,9 +679,13 @@ const commands = {
       return;
     }
     rec.starting = false;
+    // The lead: still page before the first action, counted from the first frame.
+    const until = Date.now() + 2000;
+    while (rec.firstFrameAt === null && !rec.finishing && Date.now() < until) await sleep(20);
+    if (rec.firstFrameAt !== null && !rec.finishing) await sleep(Math.max(0, rec.pacing.lead - (Date.now() - rec.firstFrameAt)));
     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.`);
+    out.log(`Recording the selected tab to ${file} ${limit}${steps ? ', with its steps' : ''}${pacingText(rec.pacing)}; record off stops it and saves the file.`);
   },
 };
 
-module.exports = { commands, recordingOf, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };
+module.exports = { commands, recordingOf, stepsOf, pauseAfter, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };

package/lib/runner.js

@@ -7,7 +7,7 @@ const { commands, cliCommands, needsTab } = require('./commands');
 const { dialogCommand, CDP_ANSWER, CDP_REFUSED } = require('./dialogs');
 const { activeModes } = require('./modes');
 const { NO_TAB } = require('./util');
-const { stepStarted, stepEnded, stepLabel } = require('./record');
+const { stepStarted, stepEnded, stepLabel, pauseAfter } = require('./record');
 const cliNames = require('./cli-names');
 
 // playwright-cli names already explained, per client: each client is told once.
@@ -111,6 +111,7 @@ async function executeCommand(text) {
   try {
     await run(args, all);
     stepEnded(step, false);
+    await pauseAfter(state.page, cmd);
   } catch (e) {
     stepEnded(step, true);
     // Playwright colours its call log; the codes are noise anywhere but a terminal.

package/lib/send.js

@@ -6,6 +6,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const client = require('./client');
+const { shellWords } = require('./syntax');
 
 // The prompt, after the modes on in the selected tab if any: (watch network:off) pw[serve]>
 const PROMPT = /^(?:\([^()]*\) )?pw(\[serve\])?>\s*$/;
@@ -87,7 +88,73 @@ async function viaTmux(session, command, timeoutMs) {
   return 2;
 }
 
+// A command's words as send was given them, made into the line the REPL reads: quoted again where the
+// shell had kept a word whole, and with the files it reads or writes made absolute from the sender's
+// folder, since the REPL's may be another.
+function commandLine(words) {
+  // For a command that reads a quoted selector (fill "text=Your name" Ada), a
+  // word the shell kept whole is quoted again so it stays one word. Any other
+  // command takes the rest of its line as it is (eval, route's JSON), so its
+  // words are joined as they are.
+  const { SELECTOR_FIRST } = require('./syntax');
+  // So does playwright-cli's storage key (localstorage-set "my key" v).
+  // And record's file, which may have spaces in it.
+  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0]));
+  // An empty word (fill #name "") is the empty value.
+  // upload's files are read by the REPL, whose folder may not be this one.
+  // So are the files upload reads and screenshot --filename writes.
+  const resolve = require('path').resolve;
+  let resolved = words[0] === 'upload' ? words.map((w, n) => (n > 1 ? resolve(w) : w)) : words;
+  // record on <file> writes it too.
+  if (words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0])) {
+    resolved = words.map((w, n) => {
+      if (n < (words[0] === 'record' ? 2 : 1)) return w;
+      if (w.startsWith('--filename=') && w.length > 11) return `--filename=${resolve(w.slice(11))}`;
+      return words[n - 1] === '--filename' || !/^(?:\d+|-.*)$/.test(w) ? resolve(w) : w;
+    });
+  }
+  if (words[0] === 'screenshot') {
+    resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : w));
+  }
+  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
+  // An option's value the shell kept whole stays whole too: --device='iPhone 15'.
+  // Single quotes escape nothing, so a backslash (a regexp's \d) reaches it as typed.
+  for (const [n, w] of quoted.entries()) {
+    const option = /^(--[A-Za-z][\w-]*=)([\s\S]*\s[\s\S]*)$/.exec(w);
+    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? JSON.stringify(option[2]) : `'${option[2]}'`}`;
+  }
+  return quoted.join(' ').trim();
+}
+
+// A file of commands, one per line, run in turn until one fails. A recording it started and did not
+// stop is still on: the next take would fail to start, so it says so.
+const PATHS = /^(?:upload|record|video-start|video-stop|screenshot)$/;
+async function sendFile(options) {
+  let text;
+  try { text = fs.readFileSync(options.file, 'utf8'); } catch (error) { return fail(`cannot read ${options.file} (${error.code || error.message})`); }
+  const lines = text.split(/\r?\n/);
+  let recording = false;
+  for (const [i, raw] of lines.entries()) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    console.log(`> ${line}`);
+    // Read as the prompt reads it; a file it reads or writes is the sender's, as on send's command line.
+    const words = shellWords(line);
+    const command = PATHS.test(words[0]) ? commandLine(words) : line;
+    const status = await send({ ...options, file: null, command });
+    if (status !== 0) {
+      console.error(`pw-repl: stopped at line ${i + 1} of ${options.file} (${line}), exit status ${status}`);
+      if (recording) console.error('pw-repl: record off was not reached, so the recording is still on; pw-repl send record off ends it');
+      return status;
+    }
+    if (/^(?:record\s+on|video-start)\b/.test(line)) recording = true;
+    if (/^(?:record\s+off|video-stop)\b/.test(line)) recording = false;
+  }
+  return 0;
+}
+
 async function send(options) {
+  if (options.file) return sendFile(options);
   const command = options.command;
   if (!command) return fail('no command given');
   // A newline would reach the REPL as a second, unmarked command.
@@ -157,4 +224,4 @@ async function where(options) {
   return 64;
 }
 
-module.exports = { send, where };
+module.exports = { send, where, commandLine };

package/package.json

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

package/skill/SKILL.md

@@ -63,10 +63,15 @@ opens in a new tab.
   tmux send-keys -t playwright-repl Enter
   ```
 
-`serve` and `serve --background` take a socket path of your own instead of the default
-(`pw-repl serve --background /tmp/mine.sock`); `send`, `attach`, `stop` and `where` then need
-`-e /tmp/mine.sock`, or `PW_SOCKET=/tmp/mine.sock`; a socket file left by a REPL that died is replaced
-when the next one starts there. The log of a background REPL is next to its socket
+A REPL of your own goes on a socket of its own, named with `-e` on every command, `serve` included:
+
+```bash
+pw-repl serve --background --launch -e /tmp/mine.sock
+pw-repl send -e /tmp/mine.sock tab new http://localhost:3000
+pw-repl stop -e /tmp/mine.sock
+```
+
+A socket file left by a REPL that died is replaced when the next one starts there. The log of a background REPL is next to its socket
 (`/tmp/mine.log`), appended to run after run, with a line where each starts and stops (past 5 MB, a
 start moves it to `/tmp/mine.log.1`); `tail -f` on it follows along without a terminal to attach from.
 `serve <port>` listens on TCP 127.0.0.1 instead of a socket, with no access control.
@@ -114,6 +119,10 @@ spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL
 `pw-repl where` says which one a command would reach (the server, or the tmux pane running the
 REPL), or why neither is reachable, without running anything.
 
+`send --file take.txt` runs a file of commands, one per line, as typed at the prompt (no shell quoting;
+files relative to your folder, as on `send`'s command line; `#` comments), and stops at the first that fails, saying which line.
+It is the way to record a video without gaps (`help record`), and to keep a repro to run again.
+
 `send` takes one command; chain several in your shell. Use `&&` when a step only makes sense if the one
 before it worked: it stops at any exit status but 0, a failure and an outcome not confirmed included.
 Use `;` when the steps do not depend on each other. `-t` is each command's own limit. Write each
@@ -157,7 +166,7 @@ blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --hel
 
 ## Learn the commands
 
-Run `pw-repl send help`. It lists six topics; `help <topic>` lists their commands, `help <command>`
+Run `pw-repl send help`. It lists seven topics; `help <topic>` lists their commands, `help <command>`
 gives usage and caveats, and `help --all` prints everything at once. pw-repl answers it itself: it needs
 no running REPL, and never reaches one. The
 help is the command reference; this file does not repeat it. If you know playwright-cli, its command
@@ -205,9 +214,9 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - 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.
+- For a video, `help video` says how: a take written as a file and sent with `send --file`, `record on`
+  around it, `cursor on` for a pointer, and the pacing recording adds for the viewer; a screen recorder on
+  the user's machine records what they see.
 
 ## Environment
 
@@ -223,8 +232,8 @@ pw-repl send -c <name> close                        # your modes off; tab close
   a REPL on a socket of its own saves them next to its socket, and any other in `/tmp`. `screenshot`
   prints each file's path; other REPLs may save theirs in the same place. Remove only your
   own, and keep those too if they are needed, e.g. as evidence or as something to hand over.
-- `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `send`
-  looks for when neither is given (default `/tmp/playwright-repl.sock`).
+- `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `serve`
+  serves on and `send` looks for when neither is given (default `/tmp/playwright-repl.sock`).
 
 ## Custom rules