pw-repl 0.8.2 → 0.10.0

package/lib/inspect.js

@@ -12,7 +12,7 @@ const { keptSession } = require('./cdp');
 const { CDP_REFUSED } = require('./dialogs');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
-const { deviceMetrics, viewportMetrics } = require('./emulation');
+const { deviceMetrics, viewportMetrics, reapplyMetrics } = require('./emulation');
 
 const SCREENSHOT_DELAY_MAX = 60;
 
@@ -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;
   }
@@ -51,6 +51,32 @@ async function deviceShot(device, { ref, full, type }) {
   return Buffer.from(data, 'base64');
 }
 
+// An element bigger than the viewport is taken with the page laid out again at its whole size, where
+// the page's scrollbar is gone and what was beside it moves over by its width, after the element was
+// measured: the shot came out shifted. Laid out without the scrollbar for the shot, by a stylesheet
+// adopted for it (under any CSP), the element is measured where it is taken. Someone looking at the
+// page sees its scrollbar go for a moment.
+const NO_SCROLLBAR = 'html:not([data-pw-repl])';
+async function elementShot(locator, type) {
+  const fits = await locator.evaluate(el => { const r = el.getBoundingClientRect(); return r.width <= innerWidth && r.height <= innerHeight; }, null, { timeout: 5000 });
+  if (fits) return locator.screenshot({ type, timeout: 5000 });
+  const sheet = hide => state.page.evaluate(([rule, on]) => {
+    const sheets = [...document.adoptedStyleSheets].filter(s => ![...s.cssRules].some(r => r.selectorText === rule));
+    if (on) {
+      const s = new CSSStyleSheet();
+      s.replaceSync(`${rule} { scrollbar-width: none !important; }`);
+      sheets.push(s);
+    }
+    document.adoptedStyleSheets = sheets;
+  }, [NO_SCROLLBAR, hide]);
+  await sheet(true);
+  try {
+    return await locator.screenshot({ type, timeout: 5000 });
+  } finally {
+    await sheet(false).catch(() => {});
+  }
+}
+
 // Unnamed generic nodes are layout wrappers (mostly divs): they add depth and
 // nothing to read. Drop them, lift their children, and drop cursor hints.
 function compactSnapshot(text) {
@@ -271,6 +297,8 @@ const commands = {
     // Chrome does not draw a tab that is not in front, and tabs open in the
     // background, so the tab is brought to the front for the shot.
     await state.page.bringToFront();
+    // A tab brought to the front before can be drawn at the window's size since its last navigation.
+    await reapplyMetrics(state.page);
     let image;
     const device = tabState(state.page).emulation?.device;
     try {
@@ -278,7 +306,7 @@ const commands = {
         image = await deviceShot(device, { ref, full, type });
       } else if (ref) {
         const selector = toSelector(ref);
-        image = await onElement(selector, () => state.page.locator(selector).screenshot({ type, timeout: 5000 }));
+        image = await onElement(selector, () => elementShot(state.page.locator(selector), type));
       } else {
         image = await state.page.screenshot({ fullPage: full, type });
       }

package/lib/modes.js

@@ -9,7 +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');
+const { hideHighlights, setLabels } = require('./elements');
 const { cursorOf, cursorOff } = require('./cursor');
 
 // The modes turned on in a tab, in the order the prompt shows them.
@@ -26,6 +26,7 @@ function activeModes(p) {
   if (routes) modes.push(`routes:${routes}`);
   const highlights = tabState(p).highlights?.size;
   if (highlights) modes.push(`highlight:${highlights}`);
+  if (tabState(p).labelsOn) modes.push('labels');
   if (cursorOf(p)) modes.push('cursor');
   if (currentCapture()?.page === p) modes.push('capture');
   if (recordingOf(p)) modes.push('record');
@@ -76,6 +77,8 @@ function modeOwners(p) {
   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 labels = tabState(p).labelsOn;
+  if (labels) owners.push([labels.owner ?? null, 'labels']);
   const cursor = cursorOf(p);
   if (cursor) owners.push([cursor.owner ?? null, 'cursor']);
   const capture = currentCapture();
@@ -114,6 +117,7 @@ async function allModesOff(mine = false) {
       if ('network' in tabState(p) && ours(tabState(p).network.owner)) { await setNetwork(p, null); done.push('network on'); }
       const hidden = await hideHighlights(p, mine);
       if (hidden) done.push(`${hidden} highlight${hidden === 1 ? '' : 's'} hidden`);
+      if (tabState(p).labelsOn && ours(tabState(p).labelsOn.owner)) { await setLabels(p, false); done.push('labels off'); }
       if (cursorOf(p) && ours(cursorOf(p).owner) && await cursorOff(p)) done.push('cursor off');
       // Before the page's size is reset, which the recording would otherwise end with.
       const recording = recordingOf(p);

package/lib/record.js

@@ -8,11 +8,14 @@ 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 { reapplyMetrics } = 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,
@@ -130,13 +133,7 @@ function recordingOf(p) {
 
 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);
+  await reapplyMetrics(p);
 }
 
 // The tabs recording now, for the modes they count as.
@@ -145,7 +142,7 @@ function recordingPages() {
   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.
@@ -159,7 +156,7 @@ 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: '', 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
@@ -260,10 +257,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];
@@ -293,7 +290,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;
@@ -369,7 +366,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.
@@ -385,7 +382,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) {
@@ -398,7 +395,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);
@@ -406,8 +408,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 };
@@ -424,7 +432,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);
@@ -433,13 +441,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';
 }
@@ -447,7 +462,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`,
@@ -491,6 +506,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) {
@@ -500,8 +521,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
@@ -509,9 +530,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.
@@ -521,7 +550,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) {
@@ -550,7 +579,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));
@@ -562,8 +591,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) {
@@ -585,6 +616,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; }
@@ -625,7 +658,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;
@@ -639,9 +672,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.2",
+  "version": "0.10.0",
   "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
   "keywords": [
     "playwright",

package/skill/SKILL.md

@@ -15,16 +15,18 @@ shared session: a person can have their own tabs open in it and be using it whil
 `npx pw-repl@latest` in its place, in that same form for every command, so each one runs the same
 version; from a clone, `<clone>/bin/pw-repl.js`.
 
-`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. When that
-is not the skill named at the top of this file, tell the user before going on:
+`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. When
+that is not the skill named at the top of this file, tell the user once, in these words and in passing,
+with whatever else you are telling them, and carry on with the task:
 
-- if this file's pw-repl version is newer than that one, pw-repl is behind: say "⚠️ pw-repl is older
-  than this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
+- if this file's pw-repl version is newer than that one, pw-repl is behind: "🔄 pw-repl is older than
+  this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
   `npm install -g pw-repl` updates it."
-- otherwise, the skill is: ask "⚠️ This pw-repl skill is out of date (from pw-repl <this file's
-  version>; <that version> has a newer one). Update it? Everything but its Custom rules section will be
-  replaced." On a yes, save what `pw-repl skill` prints over this file, with this file's Custom rules
-  section in place of the new one's.
+- otherwise, the skill is: "🔄 This pw-repl skill is out of date (from pw-repl <this file's version>;
+  <that version> has a newer one). If you'd like me to update it, just ask: everything but its Custom
+  rules section would be replaced." Update it only when the user asks for that; a yes to something else
+  is not one. To update it, save what `pw-repl skill` prints over this file, with this file's Custom
+  rules section in place of the new one's.
 
 ## Arguments
 
@@ -34,11 +36,12 @@ the sections below are how to carry it out. With no args, get a REPL running and
 
 ## Start it
 
-`pw-repl where` says whether a REPL is running and how `send` reaches it, or that one is still starting
-(retry shortly; it exits 64 until the REPL serves, as when none is running). Right after you start one,
-for a moment before its process is up, it can still say none is there: retry for a few seconds before
-taking that as a failed start. There are three ways to run one; each takes an optional start URL, which
-opens in a new tab.
+Run `pw-repl where` first, before anything else (with `-e <socket>` for a REPL you were told is on one),
+and check the skill it names against the top of this file. It says whether a REPL is running and how
+`send` reaches it, or that one is still starting (retry shortly; it exits 64 until the REPL serves, as
+when none is running). Right after you start one, for a moment before its process is up, it can still
+say none is there: retry for a few seconds before taking that as a failed start. There are three ways to
+run one; each takes an optional start URL, which opens in a new tab.
 
 - `pw-repl serve --background` runs it detached, with a command server on `/tmp/playwright-repl.sock`
   (owner-only) and its output in `/tmp/playwright-repl.log`. `pw-repl attach` shows everything it does
@@ -63,10 +66,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 +122,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 +169,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
@@ -203,11 +215,11 @@ pw-repl send -c <name> close                        # your modes off; tab close
   `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 (`cursor
-  on` draws a pointer where you act, for the viewer), and a screen recorder on the person's machine records
-  what they see.
+  without changing the page (`--style=<css>` restyles it; `highlight off` hides them), without
+  Playwright's locator label unless `highlight --labels on`.
+- 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 +235,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