pw-repl 0.6.1 → 0.7.0

package/AGENTS.md

@@ -15,8 +15,8 @@ If you hit a limitation or write a workaround, consider adding the capability to
 - The modules, one per facility, each with its commands: `lib/tabs.js` (tabs, navigating),
   `lib/elements.js` (choosing a match; the interact and mouse commands), `lib/inspect.js` (reading the
   page, screenshots, eval, CDP, waits), `lib/watch.js`, `lib/requestlog.js` (requests, bodies, console),
-  `lib/routes.js`, `lib/network.js`, `lib/emulation.js`, `lib/capture.js`, `lib/dialogs.js` and
-  `lib/modes.js`. Beneath them, `lib/tabstate.js` is the one record kept per tab, `lib/cdp.js` the CDP
+  `lib/routes.js`, `lib/network.js`, `lib/emulation.js` (and viewport), `lib/capture.js`, `lib/record.js`
+  (video, through ffmpeg), `lib/dialogs.js` and `lib/modes.js`. Beneath them, `lib/tabstate.js` is the one record kept per tab, `lib/cdp.js` the CDP
   session kept per tab, and `lib/util.js` small shared helpers. No facility requires `lib/modes.js` or
   `lib/commands.js`, and a unit test fails on a require cycle, which CommonJS would not report.
 - `bin/pw-repl.js` is the command line; `lib/start.js` connects and runs the prompt; `lib/runner.js`

package/README.md

@@ -98,6 +98,7 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | show an agent what I do              | `watch on`, click around in the browser, then `watch`                                 |
 | see each step as I click             | `watch on --live`                                                                     |
 | record requests and console together | `capture on`, then `capture off`                                                      |
+| record a video of the page           | `record on`, then `record off` (`help video` for the other ways)                      |
 | break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `route <glob> abort`, `network off` |
 | change or slow an API response       | `route <glob> patch <json>`, `route <glob> delay <secs>`                              |
 | slow the whole network               | `network slow`                                                                        |
@@ -130,8 +131,8 @@ pw-repl differs, it is because someone else may be using the browser:
 - `watch` records what a person does as steps with their requests, not as generated code.
 
 For a browser of its own per agent, isolated sessions, traces, video, PDFs or generated test code,
-playwright-cli is the better fit. pw-repl does not record video; for one of the shared browser as you
-see it, use a screen recorder (`ffmpeg -f x11grab`, macOS `screencapture -v`, OBS).
+playwright-cli is the better fit. `record on` records a tab's page, without the pointer; for the shared
+browser as you see it, use a screen recorder (`ffmpeg -f x11grab`, macOS `screencapture -v`, OBS).
 
 ## From scripts and agents
 

package/bin/pw-repl.js

@@ -50,7 +50,8 @@ In a tmux session named playwright-repl, pw-repl send reaches pw-repl run withou
 
 const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl send help here (no REPL needed).
 
-pw-repl help <topic | command | --all> shows one part of it.`;
+pw-repl help <topic | command | --all> shows one part of it; pw-repl help video and pw-repl help
+playwright-cli are guides.`;
 
 function usage() {
   console.error(USAGE);
@@ -108,6 +109,14 @@ function parseSendArgs(args, allowCommand) {
   // 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));
   }

package/lib/cli-names.js

@@ -31,6 +31,9 @@ const NAMES = {
   unroute: [a => (a ? `route off ${a}` : 'route off --all'), 'route off <glob>|--all'],
   request: [a => `body ${a}`, 'body <#>, the response body only'],
   'response-body': [a => `body ${a}`, 'body <#>'],
+  // The file is named when recording starts here.
+  'video-start': [a => `record on ${a}`.trim(), 'record on [file.webm|file.mp4]; --filename=<file> is the file'],
+  'video-stop': [a => `record off ${a}`.trim(), 'record off [file]'],
 };
 
 // Storage by eval: a key is the first word, quoted if it has spaces, and a value the rest.
@@ -88,8 +91,8 @@ for (const what of ['reduced-motion', 'forced-colors', 'contrast', 'media']) {
   NEAREST[`clear-${what}`] = 'not here yet; emulate dark|light sets the color scheme';
 }
 for (const name of ['request-headers', 'response-headers', 'request-body']) NEAREST[name] = 'not here yet; body <#> shows the response body';
-for (const name of ['video-start', 'video-stop', 'video-chapter', 'video-show-actions', 'video-hide-actions']) {
-  NEAREST[name] = 'not here: pw-repl does not record video (playwright-cli itself does, in a browser of its own); screenshot saves an image, and watch on records each step';
+for (const name of ['video-chapter', 'video-show-actions', 'video-hide-actions']) {
+  NEAREST[name] = 'not here: record on|off records a video, without chapters or action labels';
 }
 for (const name of ['pause-at', 'resume', 'step-over']) NEAREST[name] = 'not here: they step through a Playwright test';
 
@@ -277,4 +280,11 @@ function table() {
   return [...lines, '', 'Not here as such:', ...nearest].join('\n');
 }
 
-module.exports = { translate, table, takeOptions, NAME_LIST };
+// What help says for a playwright-cli name: what it is here, or why it is not.
+function describe(name) {
+  if (Object.hasOwn(NAMES, name)) return { as: NAMES[name][1] };
+  if (Object.hasOwn(NEAREST, name)) return { nearest: NEAREST[name] };
+  return null;
+}
+
+module.exports = { translate, table, takeOptions, describe, NAME_LIST };

package/lib/commands.js

@@ -11,6 +11,7 @@ const { commands: routesCommands, routesFor } = require('./routes');
 const { commands: networkCommands } = require('./network');
 const { commands: emulationCommands, EMULATE_KINDS } = require('./emulation');
 const { commands: captureCommands } = require('./capture');
+const { commands: recordCommands } = require('./record');
 const { commands: inspectCommands } = require('./inspect');
 const { commands: watchCommands, nextTabWanted, waitingForMe, watchNewTab } = require('./watch');
 const { commands: tabsCommands, isOpening } = require('./tabs');
@@ -27,6 +28,7 @@ const commands = {
   ...networkCommands,
   ...emulationCommands,
   ...captureCommands,
+  ...recordCommands,
   ...dialogsCommands,
   ...modesCommands,
 
@@ -110,6 +112,8 @@ function complete(line) {
     if (command === 'dialog') return match(['accept', 'dismiss']);
     if (command === 'watch') return match(['on', 'off', 'new', '--all']);
     if (command === 'capture') return match(['on', 'off']);
+    if (command === 'record') return match(['on', 'off']);
+    if (command === 'viewport') return match(['off']);
     if (command === 'route') return match(['off']);
   }
   if (words.length >= 3 && command === 'watch' && words[1] === 'on') return match(['--changes', '--live', '--next-tab'].filter(f => !words.slice(2, -1).includes(f)));

package/lib/emulation.js

@@ -17,7 +17,7 @@ async function viewportText() {
     const wider = laidOut && laidOut > width ? `; the page lays out ${laidOut} wide, shown shrunk: it has no viewport meta tag` : '';
     return `${width}x${height} (emulate mobile: ${device}${wider})`;
   }
-  const set = state.page.viewportSize();
+  const set = tabState(state.page).viewport;
   if (set) return `${set.width}x${set.height} (set with viewport)`;
   const size = await state.page.evaluate(() => `${innerWidth}x${innerHeight}`).catch(() => null);
   return size ? `${size} (the window's size)` : 'unknown';
@@ -49,6 +49,35 @@ function deviceText(name) {
   return `${name}, ${d.viewport.width}x${d.viewport.height} at ${d.deviceScaleFactor}x${d.hasTouch ? ', touch' : ''}`;
 }
 
+// A viewport set with viewport, on the kept session, as a phone's size is, so that viewport off can
+// undo it: Playwright's setViewportSize has no undo. As Playwright sets it, at one device pixel per
+// CSS pixel, and the window is left as it is.
+function viewportMetrics(session, { width, height }) {
+  return session.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false, screenWidth: width, screenHeight: height });
+}
+
+// Chrome answers a change of screen size before the page has it (a clear, often), so the size read
+// next, a screenshot or a recording would be the old one: two frames later it has it. Bounded, as a
+// dialog holds the page.
+function settled(p) {
+  return Promise.race([
+    p.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))).catch(() => {}),
+    new Promise(resolve => setTimeout(resolve, 1000)),
+  ]);
+}
+
+async function setViewport(p, size) {
+  const session = await keptSession(p);
+  if (size) {
+    await viewportMetrics(session, size);
+    tabState(p).viewport = { ...size, owner: state.client };
+  } else {
+    await session.send('Emulation.clearDeviceMetricsOverride');
+    delete tabState(p).viewport;
+  }
+  await settled(p);
+}
+
 // Sends only what changed. Chrome takes the user agent and the languages
 // together, so a change to either sends both.
 function deviceMetrics(session, name) {
@@ -71,6 +100,7 @@ async function setEmulation(p, next) {
       await send('Emulation.clearDeviceMetricsOverride');
     }
     await send('Emulation.setTouchEmulationEnabled', d?.hasTouch ? { enabled: true, maxTouchPoints: 5 } : { enabled: false });
+    await settled(p);
   }
   if (next.device !== previous.device || next.locale !== previous.locale) {
     if (next.device || next.locale) {
@@ -111,23 +141,34 @@ function showEmulation() {
   out.log(hints([...forms, ['emulate <what> off | emulate off', 'stop one, or all']]));
 }
 
-// Resets every tab's emulation, which detaching would only partly undo.
+// Resets every tab's emulation and viewport, which detaching would only partly undo.
 async function resetEmulations() {
   if (!state.browser || state.connectionLost) return;
-  const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => 'emulation' in tabState(p) && !p.isClosed());
-  await Promise.all(pages.map(p => setEmulation(p, {}).catch(() => {})));
+  const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => !p.isClosed());
+  await Promise.all(pages.map(async p => {
+    if ('emulation' in tabState(p)) await setEmulation(p, {}).catch(() => {});
+    if ('viewport' in tabState(p)) await setViewport(p, null).catch(() => {});
+  }));
 }
 
 onShutdown(resetEmulations);
 
 const commands = {
   async viewport(args) {
-    if (!args) { out.log(await viewportText()); return; }
-    const [w, h] = args.split('x').map(Number);
-    if (!w || !h) throw new Error('Usage: viewport <width>x<height>');
+    const arg = (args || '').trim();
+    if (!arg) { out.log(await viewportText()); return; }
+    if (arg === 'off') {
+      if (!tabState(state.page).viewport) { out.log(`No viewport is set in the selected tab: ${await viewportText()}`); return; }
+      await setViewport(state.page, null);
+      out.log(`Viewport off: ${await viewportText()}`);
+      return;
+    }
+    const match = /^(\d+)x(\d+)$/.exec(arg);
+    const [w, h] = match ? [Number(match[1]), Number(match[2])] : [];
+    if (!w || !h) throw new Error('Usage: viewport [<width>x<height> | off]');
     // Both set the screen size; whichever came last would win without saying so.
     if (tabState(state.page).emulation?.device) throw new Error('emulate mobile sets the size of the selected tab; emulate mobile off first');
-    await state.page.setViewportSize({ width: w, height: h });
+    await setViewport(state.page, { width: w, height: h });
     out.log(`Viewport set to ${w}x${h}`);
   },
 
@@ -156,6 +197,8 @@ const commands = {
     }
     let next;
     if (what === 'mobile') {
+      // One screen size at a time, as viewport refuses while a phone's is set.
+      if (tabState(state.page).viewport) throw new Error('viewport sets the size of the selected tab; viewport off first');
       next = deviceNamed(value || DEFAULT_DEVICE);
     } else if (what === 'dark' || what === 'light') {
       if (value) throw new Error(usage);
@@ -177,4 +220,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, setEmulation };
+module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, viewportMetrics, setEmulation, setViewport };

package/lib/help.js

@@ -38,14 +38,15 @@ Common tasks:
   see each step as I click          watch on --live
   watch a tab someone will open     watch on --next-tab [url-part]
   requests and console together     capture on, then capture off
+  a video of the page               record on, then record off
   break the backend on purpose      route <glob> <status> <json>, route <glob> abort, network off
   change or slow an API response    route <glob> patch <json>, route <glob> delay <secs>
   slow the whole network            network slow
   clean up                          modes off
 
-Modes (watch, capture, route, network off or slow, emulate) stay on until turned off; the prompt shows
-the selected tab's: (watch routes:1) pw>. tab, watch, capture, route, network, emulate and modes on
-their own show their state and what you can run next.
+Modes (watch, capture, record, route, network off or slow, emulate, viewport) stay on until turned off;
+the prompt shows the selected tab's: (watch routes:1) pw>. tab, watch, capture, record, route, network,
+emulate and modes on their own show their state and what you can run next.
 
 Topics (help <topic>):
   tabs      open, select, close, navigate        network   requests, bodies, console, fakes, network off
@@ -55,7 +56,9 @@ Topics (help <topic>):
 help <command> for usage and caveats (e.g. help route); help --all for everything.
 
 Know playwright-cli? Its command names work here too (tab-list, go-back, set-color-scheme, route
---status=...); help playwright-cli lists them.`);
+--status=...); help playwright-cli lists them.
+
+Recording video? help video says which way suits what you want.`);
 
 const TOPICS = {
   tabs: {
@@ -71,15 +74,15 @@ fill for selectors with spaces. mousemove and the other mouse commands act at a
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
-    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'emulate', 'wait', 'sleep'],
+    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'record', 'viewport', 'emulate', 'wait', 'sleep'],
   },
   network: {
     intro: `requests and console record all the time; a capture records only while it runs.`,
     commands: ['requests', 'body', 'console', 'capture', 'route', 'network'],
   },
   devtools: {
-    intro: `Cookie and storage listings omit values. eval, cdp, html, screenshots and URLs can still show
-sensitive data (cdp Network.getCookies shows cookie values).`,
+    intro: `Cookie and storage listings omit values. eval, cdp, html, screenshots, recordings and URLs can
+still show sensitive data (cdp Network.getCookies shows cookie values).`,
     commands: ['eval', 'cdp', 'cookies', 'storage'],
   },
   session: {
@@ -219,7 +222,7 @@ out; --full shows it unchanged.
 case), each with the named elements around it. A hit with no named element around it prints without
 a path. A hit on text (a label) keeps the ref of the element holding it, so snapshot <that ref>
 shows what sits beside it, such as the value next to the label. --regex <pattern> is --grep by a
-regular expression: snapshot --regex "Total: \\d+".
+regular expression: snapshot --regex "Total: \\d+". Refs belong to the tab whose snapshot gave them.
 
 An element with no role or name of its own (a card that is only a div) is left out, with its ref;
 snapshot --full keeps it.
@@ -299,7 +302,42 @@ phone shows: a page laid out wider than the phone (no viewport meta tag) comes o
 
 --delay counts down out loud first (maximum 60s), so someone can hold a hover or open a menu.`,
   },
-  viewport: { usage: 'viewport [WxH]', summary: 'show or set the viewport size' },
+  record: {
+    usage: 'record [on [file] [seconds] | off [file]]',
+    summary: 'record the selected tab\'s page to a video',
+    detail: `record on starts recording the selected tab, and record off stops it and saves the file: its
+path, length, size and bytes. record on its own, or record off when nothing is recording, says whether the
+selected tab is recording, and how your last recording ended (record off, its seconds, its tab closing
+or the REPL stopping) with what record off would have said.
+
+record off <file> saves it under that name instead. --filename=<file> is file too, as playwright-cli
+writes it.
+
+The file is a .webm, or an .mp4 if its name ends so, absolute or relative to the folder pw-repl send runs in, and
+owner-only, as a screenshot is; it never replaces a file. Without one, it is recording-<timestamp>.webm where screenshot saves. With seconds,
+it stops by itself after them (at most 3600, which is also the default); commands run meanwhile. One recording per tab.
+
+It brings the tab to the front of its window first, as screenshot does. It records the page only,
+from inside the browser, at the page's size in CSS pixels, made even (an
+odd width or height loses a pixel), a phone's too under emulate mobile: a Pixel 7's is 412 wide, less
+sharp than the phone draws it. It has no pointer and no browser toolbars,
+and a tab behind another, hidden or headless keeps recording. Set the size first with viewport
+(1280x720 fills a 16:9 player); a page that changes size while recording is fitted into the first size.
+Chrome sends a frame as the page draws, and a still page keeps its real length.
+
+It needs ffmpeg: $PW_FFMPEG, then Playwright's own (npx playwright-core install ffmpeg), then one on the
+PATH. Playwright's writes only WebM; an .mp4 needs a system ffmpeg, with H.264. WebM plays in browsers,
+GitHub, GitLab and Slack; MP4 plays everywhere. It takes about 15 MB a minute.
+
+For a video with the pointer, or of the person's screen, help video compares the other ways.`,
+  },
+  viewport: {
+    usage: 'viewport [WxH | off]',
+    summary: 'show, set or unset the viewport size',
+    detail: `viewport 1280x720 sets the selected tab's page to that size, until viewport off, modes off or the
+REPL exits. The window is not resized. viewport on its own shows the size, and whether it was set or is
+the window's. emulate mobile sets a phone's size instead, and each refuses while the other is on.`,
+  },
   emulate: {
     usage: 'emulate [<what> [off] | off]',
     summary: 'emulate a phone, dark mode, a locale or a timezone',
@@ -312,10 +350,12 @@ emulate locale <tag>     the language (Accept-Language, navigator.language) and
 emulate timezone <zone>  an IANA timezone, e.g. Asia/Tokyo
 emulate <what> off       stop one (dark or light off stops the color scheme); emulate off stops all
 
-Per tab, until turned off or the REPL exits. emulate on its own shows what is on.
+Per tab, until turned off or the REPL exits; emulate mobile <device> while another is on switches to it.
+emulate on its own shows what is on.
 
 The page sees the user agent, touch and navigator.languages from its next load: reload after
-turning mobile or locale on or off. Dark, light and timezone apply at once, but what the page
+turning mobile or locale on or off. Touch means the page sees a touch screen; click still clicks
+with the mouse, and sends no touch events. Dark, light and timezone apply at once, but what the page
 already drew with them (times, colors set by its script) changes only when it reloads.
 
 While mobile is on, viewport refuses: the device sets the size.`,
@@ -460,11 +500,12 @@ Browser.close and Target.closeTarget are refused.`,
   modes: {
     usage: 'modes [off [--mine]]',
     summary: 'the modes on in every tab; modes off turns them all off',
-    detail: `The modes are watch, network off or slow, route, capture and emulate. Each is turned on and off with
-its own command: watch on|off, network off|slow|on, route <glob> ... | route off <glob>|--all,
-capture on|off, emulate ... | emulate off.
+    detail: `The modes are watch, network off or slow, route, capture, record, emulate and viewport. Each is
+turned on and off with its own command: watch on|off, network off|slow|on, route <glob> ... | route off
+<glob>|--all, capture on|off, record on|off, emulate ... | emulate off, viewport <WxH> | viewport off.
 
-modes off turns off every one in every tab; a capture it stops is kept for capture to show. With
+modes off turns off every one in every tab; a capture it stops is kept for capture to show, and a
+recording it stops is saved, as record off would. With
 clients (help session), modes says which client turned each on, and modes off --mine turns off only
 the sender's own.`,
   },
@@ -510,6 +551,22 @@ function renderAll() {
   return [OVERVIEW, ...sections].join('\n\n');
 }
 
+// Not a command: the ways to record a video, since none is right for every use.
+const VIDEO = `There are three ways to record a video of a page, and each gives something up.
+
+record on (help record) records the selected tab's page from inside the browser: headless, hidden and
+background tabs too, with nothing to set up but ffmpeg. It has no pointer and no browser toolbars. For
+quick clips, and for an agent recording its own work.
+
+A screen recorder on the person's machine (OBS, ffmpeg -f x11grab, macOS screencapture -v) records their
+screen as they see it, pointer included, smooth and in real time. It records the screen or a window, not
+a tab: size the window, and crop off the toolbars, for just the page. Ask before starting one, or have
+them start it. It cannot see a headless browser: for a browser of the REPL's own, --launch --headed on
+a screen. For a polished video of a person's browser.
+
+Microsoft's playwright-cli (the npm package @playwright/cli; video-start and video-stop) records a
+browser of its own, not this one, which starts logged out. For a scripted flow in a clean browser.`;
+
 function render(topicOrCommand) {
   if (!topicOrCommand) return OVERVIEW;
   if (topicOrCommand === 'playwright-cli') {
@@ -530,6 +587,7 @@ Different on purpose, since the browser may be someone else's too:
   no snapshot after each command    a person reads the pane too; snapshot when you need one
   -s=<session>                      -c <name> is the nearest: a client with a selected tab of its own`);
   }
+  if (topicOrCommand === 'video') return wrap(VIDEO);
   if (topicOrCommand === '--all') return renderAll();
   if (Object.hasOwn(TOPICS, topicOrCommand)) {
     const topic = TOPICS[topicOrCommand];
@@ -538,6 +596,14 @@ Different on purpose, since the browser may be someone else's too:
     return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${renderCommand(topicOrCommand)}` : text;
   }
   if (Object.hasOwn(COMMANDS, topicOrCommand)) return renderCommand(topicOrCommand);
+  // A playwright-cli name: what it runs here, with that command's help.
+  const cli = require('./cli-names').describe(topicOrCommand);
+  if (cli?.nearest) return wrap(`${topicOrCommand} is playwright-cli's; ${cli.nearest}`);
+  if (cli) {
+    const here = cli.as.split(/\s/)[0];
+    const intro = wrap(`${topicOrCommand} is playwright-cli's name for ${cli.as} here.`);
+    return Object.hasOwn(COMMANDS, here) ? `${intro}\n\n${renderCommand(here)}` : intro;
+  }
   return null;
 }
 

package/lib/inspect.js

@@ -11,7 +11,7 @@ const { tabState } = require('./tabstate');
 const { keptSession } = require('./cdp');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
-const { deviceMetrics } = require('./emulation');
+const { deviceMetrics, viewportMetrics } = require('./emulation');
 
 const SCREENSHOT_DELAY_MAX = 60;
 
@@ -283,11 +283,12 @@ const commands = {
       }
     } finally {
       // Playwright's screenshot resets the screen size and pixel ratio it
-      // finds; an emulated phone's are set again.
-      if (device) {
+      // finds; an emulated phone's, or a viewport's, are set again.
+      const viewport = tabState(state.page).viewport;
+      if (device || viewport) {
         const session = await keptSession(state.page);
         await session.send('Emulation.clearDeviceMetricsOverride');
-        await deviceMetrics(session, device);
+        await (device ? deviceMetrics(session, device) : viewportMetrics(session, viewport));
       }
     }
     try {

package/lib/modes.js

@@ -5,7 +5,8 @@ const { hints } = require('./util');
 const { tabState } = require('./tabstate');
 const { unroute } = require('./routes');
 const { setNetwork } = require('./network');
-const { emulatedKinds, setEmulation } = require('./emulation');
+const { emulatedKinds, setEmulation, setViewport } = require('./emulation');
+const { recordingOf, finishRecording } = require('./record');
 const { currentCapture, endCapture } = require('./capture');
 const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
 
@@ -17,9 +18,12 @@ function activeModes(p) {
   if (network) modes.push(network.offline ? 'network:off' : 'network:slow');
   const emulated = emulatedKinds(tabState(p).emulation);
   if (emulated.length) modes.push(`emulate:${emulated.join(',')}`);
+  const viewport = tabState(p).viewport;
+  if (viewport) modes.push(`viewport:${viewport.width}x${viewport.height}`);
   const routes = tabState(p).routes?.size;
   if (routes) modes.push(`routes:${routes}`);
   if (currentCapture()?.page === p) modes.push('capture');
+  if (recordingOf(p)) modes.push('record');
   return modes;
 }
 
@@ -47,7 +51,11 @@ function listModes() {
     const owners = modeOwners(p);
     if (owners.some(([owner]) => owner)) out.log(`      on by ${ownersText(owners)}`);
   }
-  out.log(hints([['modes off', 'turn them all off']]));
+  // With clients' modes among them, the sender's own first: modes off turns off everyone's.
+  const clients = on.some(([p]) => modeOwners(p).some(([owner]) => owner));
+  out.log(hints(clients && state.client
+    ? [['modes off --mine', 'turn off the ones you turned on'], ['modes off', 'turn them all off, everyone\'s']]
+    : [['modes off', 'turn them all off']]));
 }
 
 // Who turned on each mode in a tab: [client, what], client null for the prompt or an unnamed sender.
@@ -59,9 +67,13 @@ function modeOwners(p) {
   if (network) owners.push([network.owner ?? null, network.offline ? 'network:off' : 'network:slow']);
   const emulated = tabState(p).emulation;
   if (emulated) owners.push([emulated.owner ?? null, 'emulate']);
+  const viewport = tabState(p).viewport;
+  if (viewport) owners.push([viewport.owner ?? null, 'viewport']);
   for (const [glob, route] of tabState(p).routes || []) owners.push([route.owner ?? null, `route ${glob}`]);
   const capture = currentCapture();
   if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
+  const recording = recordingOf(p);
+  if (recording) owners.push([recording.owner ?? null, 'record']);
   return owners;
 }
 
@@ -92,7 +104,11 @@ async function allModesOff(mine = false) {
       const globs = [...(tabState(p).routes || [])].filter(([, route]) => ours(route.owner)).map(([glob]) => glob);
       if (globs.length) { await unroute(p, globs); done.push(`${globs.length} route${globs.length === 1 ? '' : 's'} removed`); }
       if ('network' in tabState(p) && ours(tabState(p).network.owner)) { await setNetwork(p, null); done.push('network on'); }
+      // Before the page's size is reset, which the recording would otherwise end with.
+      const recording = recordingOf(p);
+      if (recording && ours(recording.owner)) done.push(`record off (${(await finishRecording(recording)).replace(/\n/g, '; ')})`);
       if ('emulation' in tabState(p) && ours(tabState(p).emulation.owner)) { await setEmulation(p, {}); done.push('emulate off'); }
+      if ('viewport' in tabState(p) && ours(tabState(p).viewport.owner)) { await setViewport(p, null); done.push('viewport off'); }
     } catch (error) {
       problem = error.message;
     }

package/lib/record.js

@@ -0,0 +1,392 @@
+// Recording a tab's page to a video, from Chrome's screencast of it through ffmpeg.
+const { spawn, execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { state, onShutdown } = require('./state');
+const out = require('./output');
+const { tabState } = require('./tabstate');
+const { clock, NO_TAB } = require('./util');
+
+const FPS = 25;
+const MAX_SECONDS = 3600;
+// 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,
+// and the file may be cut short; at shutdown, how long it may take at all, within the REPL's cleanup.
+const FINISH_TIMEOUT = 5000;
+const SHUTDOWN_FINISH_TIMEOUT = 3000;
+const FIRST_FRAME_TIMEOUT = 2000;
+const INSTALL = 'npx playwright-core install ffmpeg (WebM only), or ffmpeg from your system\'s packages';
+// One thread each: ffmpeg's default of one per core thrashes on a busy machine (a 720p WebM took
+// 26s of work for 10s of video with 20 cores, and 1s with one thread), and it shares the machine
+// with the browser it records.
+const FORMATS = {
+  webm: { encoder: 'libvpx', args: ['-c:v', 'vp8', '-b:v', '2M', '-g', String(FPS * 2), '-deadline', 'realtime', '-cpu-used', '8', '-threads', '1'] },
+  // Fragmented, so a recording cut short still plays up to its last fragment.
+  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.
+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 {}
+  for (const name of names) {
+    for (const exe of ['ffmpeg-linux', 'ffmpeg-mac', 'ffmpeg-win64.exe']) {
+      const candidate = path.join(dir, name, exe);
+      if (fs.existsSync(candidate)) found.push(candidate);
+    }
+  }
+  for (const folder of (process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(folder, process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg');
+    try { fs.accessSync(candidate, fs.constants.X_OK); found.push(candidate); } catch {}
+  }
+  return [...new Set(found)];
+}
+
+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 {}
+    encoderLists.set(exe, list);
+  }
+  return new RegExp(`^\\s*V\\S*\\s+${encoder}\\s`, 'm').test(encoderLists.get(exe));
+}
+
+// The first ffmpeg that can write the format.
+function findFfmpeg(format) {
+  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 (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`);
+}
+
+// A JPEG's width and height, from its frame header.
+function jpegSize(buffer) {
+  let i = 2;
+  while (i + 9 < buffer.length) {
+    if (buffer[i] !== 0xff) return null;
+    const marker = buffer[i + 1];
+    if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+      return { width: buffer.readUInt16BE(i + 7), height: buffer.readUInt16BE(i + 5) };
+    }
+    i += 2 + buffer.readUInt16BE(i + 2);
+  }
+  return null;
+}
+
+function nextRecordingPath() {
+  // Where screenshots go, so both are found in one place.
+  return path.join(process.env.PW_SCREENSHOT_DIR || state.ownDir || '/tmp', `recording-${Date.now()}.webm`);
+}
+
+function sizeText(bytes) {
+  return bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB`;
+}
+
+// Each client's last recording that ended, and how, for record to report: one that ends on
+// its own (its seconds, its tab closing) says so only in the pane.
+const lastEnded = new Map();
+// Each client's recordings still being saved, which record waits for before it reports.
+const saving = new Map();
+
+function recordingOf(p) {
+  return tabState(p).recording || null;
+}
+
+// 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) {
+  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();
+  // 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: '',
+  };
+  // 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.
+  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)) };
+  } catch (error) {
+    session.detach().catch(() => {});
+    throw error;
+  }
+  tabState(p).recording = rec;
+  let firstFrame;
+  const gotFirstFrame = new Promise(resolve => { firstFrame = resolve; });
+  const tick = () => {
+    if (!rec.latest || !rec.ff || 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);
+    for (; rec.written < due; rec.written++) {
+      if (rec.ff.stdin.writableLength > MAX_QUEUED) { rec.dropped += 1; continue; }
+      rec.ff.stdin.write(rec.latest);
+    }
+  };
+  session.on('Page.screencastFrame', frame => {
+    session.send('Page.screencastFrameAck', { sessionId: frame.sessionId }).catch(() => {});
+    if (rec.finishing) return;
+    const image = Buffer.from(frame.data, 'base64');
+    const size = jpegSize(image);
+    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.ff) {
+      rec.firstFrameAt = Date.now();
+      rec.ff = spawnFfmpeg(rec);
+      rec.timer = setInterval(tick, 1000 / FPS);
+      firstFrame();
+    } else {
+      tick();
+      // Once the page has been drawn at its size, one of another size means it changed; it is
+      // fitted into the video's.
+      if (rec.resizedAt === null && rec.fitted && !fits) rec.resizedAt = (Date.now() - rec.firstFrameAt) / 1000;
+    }
+    if (fits) rec.fitted = true;
+    rec.latest = image;
+  });
+  try {
+    await session.send('Page.startScreencast', { format: 'jpeg', quality: 85, maxWidth: rec.size.width, maxHeight: rec.size.height });
+  } catch (error) {
+    delete tabState(p).recording;
+    session.detach().catch(() => {});
+    throw error;
+  }
+  // Chrome sends the page as it is at once; the recording starts with it. A page that has not
+  // drawn yet (a tab still opening) starts it when it does.
+  await Promise.race([gotFirstFrame, new Promise(resolve => setTimeout(resolve, FIRST_FRAME_TIMEOUT))]);
+  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));
+  p.once('close', rec.onClose);
+  return rec;
+}
+
+function spawnFfmpeg(rec) {
+  const { width, height } = rec.size;
+  // A frame of another size (the viewport or window changed) is scaled to fit, and centred.
+  const fit = `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,format=yuv420p`;
+  // Warnings too (an empty output is one), kept for a failure's message only.
+  const ff = spawn(rec.exe, ['-hide_banner', '-loglevel', 'warning', '-threads', '1', '-filter_threads', '1', '-f', 'image2pipe', '-c:v', 'mjpeg', '-r', String(FPS), '-i', 'pipe:0',
+    '-vf', fit, ...FORMATS[rec.format].args, '-an', '-y', rec.file], { stdio: ['pipe', 'ignore', 'pipe'] });
+  ff.stderr.setEncoding('utf8');
+  ff.stderr.on('data', chunk => { rec.ffmpegError = (rec.ffmpegError + chunk).slice(-2000); });
+  // 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)));
+  return ff;
+}
+
+// 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;
+  const owner = rec.owner ?? null;
+  const stoppedAt = Date.now();
+  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';
+    const said = why ? `${why}. ${text}` : text;
+    lastEnded.set(owner, { text: said, at: stoppedAt });
+    return said;
+  })();
+  const pending = saving.get(owner) || new Set();
+  saving.set(owner, pending.add(rec.finishing));
+  rec.finishing.finally(() => pending.delete(rec.finishing)).catch(() => {});
+  return rec.finishing;
+}
+
+async function finishFile(rec, shuttingDown) {
+  clearTimeout(rec.limit);
+  if (rec.onClose) rec.page.off('close', rec.onClose);
+  if (tabState(rec.page).recording === rec) delete tabState(rec.page).recording;
+  // The last frame runs to now, and a recording has one frame at least.
+  if (rec.ff && rec.latest) {
+    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);
+  }
+  clearInterval(rec.timer);
+  await rec.session.send('Page.stopScreencast').catch(() => {});
+  rec.session.detach().catch(() => {});
+  if (!rec.ff) {
+    fs.rmSync(rec.file, { force: true });
+    return { failed: true, text: `Nothing was recorded: the tab drew no frame, so no file was saved (${rec.file}).` };
+  }
+  rec.ff.stdin.end();
+  let cut = false;
+  // Frames still queued are encoded before the file is done, however long that takes, while
+  // ffmpeg keeps getting through them.
+  const progress = () => `${rec.ff.stdin.writableLength}:${fs.existsSync(rec.file) ? fs.statSync(rec.file).size : 0}`;
+  const stalled = new Promise(resolve => {
+    if (shuttingDown) { setTimeout(() => resolve('timeout'), SHUTDOWN_FINISH_TIMEOUT); return; }
+    let last = progress();
+    let since = Date.now();
+    const check = setInterval(() => {
+      const now = progress();
+      if (now !== last) { last = now; since = Date.now(); } else if (Date.now() - since > FINISH_TIMEOUT) { clearInterval(check); resolve('timeout'); }
+    }, 250);
+    rec.exited.then(() => clearInterval(check));
+  });
+  const code = await Promise.race([rec.exited, stalled]);
+  if (code === 'timeout') { cut = true; rec.ff.kill('SIGKILL'); await rec.exited; }
+  const seconds = (rec.written - rec.dropped) / FPS;
+  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'}`;
+    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('; ')}` : ''}`;
+}
+
+// Ends every recording, as the REPL stops, and says in the pane and the log what each saved.
+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), () => {})));
+}
+
+onShutdown(finishAll);
+
+function statusText(p) {
+  const rec = recordingOf(p);
+  if (!rec) {
+    const last = lastEnded.get(state.client ?? null);
+    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);
+  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.`;
+}
+
+// A file word, as given or as playwright-cli's --filename=<file> (or --filename <file>); any other
+// option is refused, never taken for a file name.
+function fileWords(words, usage) {
+  const files = [];
+  const rest = [];
+  for (let i = 0; i < words.length; i++) {
+    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 (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);
+  return { file: files.length ? path.resolve(files[0]) : null, rest };
+}
+
+function checkFile(file, format) {
+  const ext = path.extname(file).toLowerCase().slice(1);
+  if (!FORMATS[ext]) throw new Error(`A recording is a .webm or .mp4 file, not ${path.basename(file)}`);
+  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`);
+  return ext;
+}
+
+// Moves a saved recording to the name record off was given, across file systems too.
+function moveRecording(from, to) {
+  try {
+    fs.renameSync(from, to);
+  } catch (error) {
+    if (error.code !== 'EXDEV') throw error;
+    fs.copyFileSync(from, to, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(to, 0o600);
+    fs.unlinkSync(from);
+  }
+}
+
+const commands = {
+  async record(args) {
+    const words = (args || '').trim().split(/\s+/).filter(Boolean);
+    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) || [])]);
+      out.log(statusText(state.page));
+      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);
+    // 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);
+      if (!rec) {
+        await Promise.allSettled([...(saving.get(state.client ?? null) || [])]);
+        out.log(statusText(state.page));
+        return;
+      }
+      // Its own name again (named at both ends, as playwright-cli habits have it) is no rename.
+      const rename = named && named !== rec.file ? named : null;
+      // Checked first, so a name that cannot be used leaves it recording, and says so.
+      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);
+      if (!rename || !fs.existsSync(rec.file)) { out.log(text); return; }
+      moveRecording(rec.file, rename);
+      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));
+      return;
+    }
+    if (numbers.length > 1) throw new Error(usage);
+    const seconds = numbers.length ? Number(numbers[0]) : MAX_SECONDS;
+    if (seconds < 1 || seconds > MAX_SECONDS) throw new Error(usage);
+    const file = named || nextRecordingPath();
+    const current = recordingOf(state.page);
+    if (current) throw new Error(`The selected tab is already being recorded to ${current.file}; record off stops it`);
+    const format = checkFile(file);
+    findFfmpeg(format);
+    // Created here, owner-only as a screenshot is, since a recording shows whatever the page does;
+    // ffmpeg writes over it and keeps the mode. It never replaces a file.
+    try {
+      fs.closeSync(fs.openSync(file, 'wx', 0o600));
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error(`Recording already exists: ${file}`);
+      throw error;
+    }
+    try {
+      await startRecording(state.page, file, seconds, format);
+    } catch (error) {
+      fs.rmSync(file, { force: true });
+      throw error;
+    }
+    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 };

package/lib/runner.js

@@ -31,7 +31,7 @@ const READ_ONLY = new Set(['info', 'listeners', 'text', 'html', 'attrs', 'count'
   'snapshot', 'screenshot', 'wait', 'sleep', 'requests', 'body', 'console', 'cookies', 'storage', 'capture', 'help']);
 
 // Commands that work with no tab selected.
-const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'dialog', 'help', 'quit', 'tab-select', 'close']);
+const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'record', 'dialog', 'help', 'quit', 'tab-select', 'close']);
 
 // Commands that accept --all, right after the command or at the end, to lift the output limit.
 const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];

package/lib/tabstate.js

@@ -9,6 +9,8 @@
 //                  (ms, kbps), with the owner
 //   emulation      what emulate changed: { device, scheme, locale, timezone }, each unset when off,
 //                  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
 //   routes         Map(glob -> { status, body, handler, owner })
 //   log            its recent requests (requests)
 //   consoleLog     its recent console messages and page errors (console)

package/package.json

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

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, and recording what the person does. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
+description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, recording what the person does, and recording a video of a tab. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
 allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 ---
 
@@ -158,7 +158,8 @@ 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>`
-gives usage and caveats, and `help --all` prints everything at once. It needs no running REPL. The
+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
 names work too (`help playwright-cli` lists them).
 
@@ -200,17 +201,15 @@ pw-repl send -c <name> close                        # your modes off; tab close
   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.
-- pw-repl does not record video. For one of a flow in a browser of its own, Microsoft's playwright-cli (a
-  separate tool, the npm package `@playwright/cli`: `video-start`, `video-stop`); for this browser as the
-  person sees it, a screen recorder (`ffmpeg -f x11grab`, macOS `screencapture -v`, OBS). A screen
-  recorder records their whole screen, not the tab: ask before starting one, or have them start it. A
-  headless browser is not on the screen, so it does not show.
+- 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.
 
 ## 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_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`