pw-repl 0.6.1 → 0.7.2

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

@@ -15,7 +15,7 @@ const USAGE = `Usage:
       see everything a background REPL does, and type commands to it; Ctrl-C leaves it running
 
   pw-repl stop [-e endpoint]
-      stop a background REPL
+      stop a background REPL, and say what became of each recording it ended
 
   pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] <command...>
       run one command in a running REPL and print its output
@@ -41,16 +41,17 @@ send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or
 The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
 
 --launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
-a temporary profile, on a free port of its own), prints the command it ran, and stops it with the REPL
-(Ctrl-C while it starts too); stop returns once that Chromium has exited. Flags after -- go to it; a
---user-data-dir=<dir> among them is used instead of the temporary profile, and kept. PW_CHROME picks
-which one. To set a browser up your own way, start it yourself and use PW_CDP_URL.
+a temporary profile, on a free port of its own, which pw-repl where names), prints the command it ran,
+and stops it with the REPL (Ctrl-C while it starts too); stop returns once that Chromium has exited.
+Flags after -- go to it; a --user-data-dir=<dir> among them is used instead of the temporary profile, and
+kept. PW_CHROME picks which one. To set a browser up your own way, start it yourself and use PW_CDP_URL.
 
 In a tmux session named playwright-repl, pw-repl send reaches pw-repl run without the server.`;
 
 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);
@@ -102,12 +103,21 @@ function parseSendArgs(args, allowCommand) {
   // words are joined as they are.
   const { SELECTOR_FIRST } = require('../lib/syntax');
   // So does playwright-cli's storage key (localstorage-set "my key" v).
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]));
+  // And record's file, which may have spaces in it.
+  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0]));
   // An empty word (fill #name "") is the empty value.
   // upload's files are read by the REPL, whose folder may not be this one.
   // So are the files upload reads and screenshot --filename writes.
   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/background.js

@@ -5,6 +5,7 @@ const path = require('path');
 const readline = require('readline');
 const { spawn } = require('child_process');
 const client = require('./client');
+const { STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
 
 const BIN = path.join(__dirname, '..', 'bin', 'pw-repl.js');
 const START_TIMEOUT = 20000;
@@ -132,12 +133,26 @@ async function stop(options) {
   const { pidFile } = filesFor(endpoint);
   const pid = runningPid(pidFile);
   if (!pid) return fail(`no background REPL is serving on ${client.describe(endpoint)}`);
+  // What it logs as it stops, from here on, holds what became of each recording it ended.
+  const { logFile } = filesFor(endpoint);
+  let logFrom = 0;
+  try { logFrom = fs.statSync(logFile).size; } catch {}
   // Like Ctrl-C: a command still running is answered, and the socket is removed.
   process.kill(pid, 'SIGTERM');
   const deadline = Date.now() + STOP_TIMEOUT;
   while (alive(pid) && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 100));
   if (alive(pid)) return fail(`the background REPL (pid ${pid}) has not stopped after ${STOP_TIMEOUT / 1000}s`);
-  console.log(`Stopped the background REPL (pid ${pid}) on ${client.describe(endpoint)}; its log stays at ${filesFor(endpoint).logFile}`);
+  console.log(`Stopped the background REPL (pid ${pid}) on ${client.describe(endpoint)}; its log stays at ${logFile}`);
+  // The REPL is gone, so record can no longer say where a recording it ended went, or that it was lost.
+  let logged = '';
+  try {
+    const fd = fs.openSync(logFile, 'r');
+    const buffer = Buffer.alloc(Math.max(0, fs.fstatSync(fd).size - logFrom));
+    fs.readSync(fd, buffer, 0, buffer.length, logFrom);
+    fs.closeSync(fd);
+    logged = buffer.toString('utf8');
+  } catch {}
+  for (const line of logged.split('\n')) if (line.startsWith(STOPPED_RECORDING) || line.startsWith(ENDED_UNSEEN)) console.log(line);
   return 0;
 }
 

package/lib/cli-names.js

@@ -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.
@@ -66,7 +69,7 @@ const NEAREST = {
   list: 'pw-repl where says which REPL is running; one REPL serves everyone using its browser',
   attach: 'pw-repl serve connects to the browser on PW_CDP_URL; pw-repl skill has the rest',
   detach: 'pw-repl stop, or quit at the prompt, disconnects and leaves the browser running',
-  drag: 'not here yet', drop: 'not here yet', highlight: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
+  drag: 'not here yet', drop: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
   keydown: 'not here yet; press <key> presses and releases one', keyup: 'not here yet; press <key> presses and releases one',
   pdf: 'not here yet; screenshot --full saves the whole page as a PNG',
   'generate-locator': 'not here yet; a snapshot ref (e5) works as a selector in any command',
@@ -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/dialogs.js

@@ -5,11 +5,17 @@ const { OUTPUT_LIMIT } = out;
 const { unquote } = require('./syntax');
 const { hints } = require('./util');
 const { tabState } = require('./tabstate');
+const { keptSession } = require('./cdp');
 
 // page -> its open dialog. The page, and every command that reads it, waits
 // until the dialog is answered, in the browser or with the dialog command.
 const openDialogs = new Map();
 
+// cdp's session is new, and Chrome lets only one that saw a dialog open answer it: it would wait out its
+// timeout. Refused ahead of the queue too, which the dialog it means holds up.
+const CDP_ANSWER = /^cdp(?:\s+--all)?\s+Page\.handleJavaScriptDialog(?:\s|$)/;
+const CDP_REFUSED = 'cdp cannot answer a dialog, which Chrome lets only a session that saw it open do; dialog accept or dialog dismiss answers it';
+
 function ensureDialogHandler(p) {
   if ('dialogHandled' in tabState(p)) return;
   tabState(p).dialogHandled = true;
@@ -19,6 +25,12 @@ function ensureDialogHandler(p) {
     out.notice('It waits to be answered in the browser, or with dialog accept [text] | dialog dismiss; until then the page, and commands that read it, wait too.', p);
   });
   p.on('close', () => openDialogs.delete(p));
+  // One answered in the browser is gone too, which Playwright does not report. The tab's own session
+  // shares Playwright's connection, so a dialog's closing comes in before the next one opening.
+  keptSession(p).then(async session => {
+    session.on('Page.javascriptDialogClosed', () => openDialogs.delete(p));
+    await session.send('Page.enable');
+  }).catch(() => {});
 }
 
 // Runs ahead of the command queue (see runner.js), so it still works while
@@ -30,7 +42,9 @@ async function dialogCommand(args, selected = state.page) {
   const describe = (p, d) => `[${pages.indexOf(p)}] ${p.url()}: ${d.type()} ${JSON.stringify(String(d.message()).slice(0, 200))}`;
   if (!action) {
     if (!openDialogs.size) return 'No dialog is open.';
-    return [...[...openDialogs].map(([p, d]) => describe(p, d)), hints([['dialog accept [text]', 'accept it (text answers a prompt)'], ['dialog dismiss', 'dismiss it']])].join('\n');
+    // With several, the one accept and dismiss answer is marked, as tab marks the selected tab.
+    const mark = p => (openDialogs.size > 1 ? (p === selected ? '* ' : '  ') : '');
+    return [...[...openDialogs].map(([p, d]) => `${mark(p)}${describe(p, d)}`), hints([['dialog accept [text]', 'accept it (text answers a prompt)'], ['dialog dismiss', 'dismiss it']])].join('\n');
   }
   if (action !== 'accept' && action !== 'dismiss') throw new Error('Usage: dialog [accept [text] | dismiss]');
   // The selected tab's dialog, or the only one open.
@@ -40,7 +54,8 @@ async function dialogCommand(args, selected = state.page) {
   openDialogs.delete(page);
   const line = describe(page, dialog);
   try {
-    if (action === 'accept') await dialog.accept(rest.length ? unquote(rest.join(' ')) : undefined);
+    // Without text, as OK in the browser: a prompt's default stays its answer.
+    if (action === 'accept') await dialog.accept(rest.length ? unquote(rest.join(' ')) : dialog.defaultValue());
     else await dialog.dismiss();
   } catch (error) {
     // Answered in the browser meanwhile.
@@ -55,4 +70,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, ensureDialogHandler, dialogCommand };
+module.exports = { commands, ensureDialogHandler, dialogCommand, CDP_ANSWER, CDP_REFUSED };

package/lib/elements.js

@@ -1,11 +1,12 @@
 // Elements and the mouse: finding the match to act on, and the commands that click, type and choose.
 const path = require('path');
 const fs = require('fs');
-const { state } = require('./state');
+const { state, onShutdown } = require('./state');
 const out = require('./output');
 const { takeOptions } = require('./cli-names');
 const { unquote, toSelector, keyName, splitSelector, REF } = require('./syntax');
-const { numbers } = require('./util');
+const { numbers, hints } = require('./util');
+const { tabState } = require('./tabstate');
 
 // The type a page sees for a file it is given, from its extension.
 const MIME_TYPES = {
@@ -198,6 +199,34 @@ async function pointerAction(selector, act, options = {}) {
   }
 }
 
+// Highlights: Playwright's own overlay, as playwright-cli's highlight draws it. Each is a mode of its
+// tab, so modes shows it and modes off hides it, and none is left on the page when the REPL stops.
+function highlightsOf(p) {
+  if (!tabState(p).highlights) {
+    tabState(p).highlights = new Map();
+    // A new document drops the overlay; a page that routes on the client keeps it.
+    p.on('domcontentloaded', () => tabState(p).highlights?.clear());
+  }
+  return tabState(p).highlights;
+}
+
+// Hides a tab's highlights, or only the running client's (mine).
+async function hideHighlights(p, mine = false) {
+  const highlights = tabState(p).highlights;
+  if (!highlights?.size) return 0;
+  const hidden = [...highlights].filter(([, h]) => !mine || (h.owner ?? null) === (state.client ?? null));
+  if (hidden.length === highlights.size) await p.hideHighlight();
+  else for (const [selector] of hidden) await p.locator(selector).hideHighlight();
+  for (const [selector] of hidden) highlights.delete(selector);
+  return hidden.length;
+}
+
+onShutdown(async () => {
+  if (!state.browser || state.connectionLost) return;
+  const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => !p.isClosed());
+  await Promise.all(pages.map(p => hideHighlights(p).catch(() => {})));
+});
+
 const commands = {
   async click(args) {
     const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
@@ -217,6 +246,42 @@ const commands = {
     out.log(`Hovered: ${args.trim()}${which}`);
   },
 
+  async highlight(args) {
+    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | off]';
+    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag' });
+    const style = found.find(o => o.name === 'style');
+    const hide = found.some(o => o.name === 'hide');
+    const highlights = highlightsOf(state.page);
+    if (!rest && !found.length) {
+      if (!highlights.size) { out.log(`Nothing is highlighted in the selected tab.\n${hints([['highlight <selector>', 'draw a box around it']])}`); return; }
+      for (const [selector, h] of highlights) out.log(`${selector}${h.style ? `  --style=${JSON.stringify(h.style)}` : ''}${h.owner ? `  (by ${h.owner})` : ''}`);
+      out.log(hints([['highlight --hide [<selector>]', 'hide one, or all']]));
+      return;
+    }
+    if (rest === 'off' && !found.length || hide && !rest) {
+      const count = await hideHighlights(state.page);
+      out.log(count ? `Hid ${count} highlight${count === 1 ? '' : 's'}` : 'Nothing was highlighted in the selected tab.');
+      return;
+    }
+    if (!rest || style && (hide || !style.value)) throw new Error(usage);
+    const selector = soleSelector(rest, usage);
+    const locator = state.page.locator(selector);
+    if (hide) {
+      if (!highlights.has(selector)) throw new Error(`${rest} is not highlighted; highlight lists what is`);
+      await locator.hideHighlight();
+      highlights.delete(selector);
+      out.log(`Hid the highlight on ${rest}`);
+      return;
+    }
+    const count = await locator.count();
+    if (!count) throw new Error(`No element matches ${rest}; nothing was highlighted`);
+    // Drawn again, with its new style, rather than twice.
+    if (highlights.has(selector)) await locator.hideHighlight();
+    await locator.highlight(style ? { style: style.value } : {});
+    highlights.set(selector, { owner: state.client, style: style?.value || null });
+    out.log(`Highlighted ${rest}${count > 1 ? ` (all ${count} matches)` : ''}; highlight --hide ${rest} hides it`);
+  },
+
   // At a point, in CSS pixels from the top left of the tab's viewport, as playwright-cli's are.
   async mousemove(args) {
     const [x, y, extra] = numbers(args, 'mousemove <x> <y>');
@@ -357,4 +422,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, soleSelector, onElement };
+module.exports = { commands, soleSelector, onElement, hideHighlights };

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