pw-repl 0.4.2 → 0.6.0

package/AGENTS.md

@@ -1,22 +1,32 @@
 # Agent Instructions — playwright-repl
 
-How to use the REPL is in `skill/SKILL.md` (the same text `pw-repl skill` prints). Read it first. In
-this clone, `pw-repl` there means `bin/pw-repl.js` (from the folder this file is in) when it is not
-installed globally.
+How to use the REPL is in the skill `bin/pw-repl.js skill` prints (from `skill/SKILL.md`, stamped with
+its version and hash). Read it first. In this clone, `pw-repl` there means `bin/pw-repl.js` (from the
+folder this file is in) when it is not installed globally.
 
 ## Contributing
 
 If you hit a limitation or write a workaround, consider adding the capability to the REPL instead.
 
-- A command is a function in the `commands` object in `lib/commands.js`, plus an entry in `lib/help.js`
-  under one topic.
+- A command is a function in the `commands` object of the module for what it works on, plus an entry
+  in `lib/help.js` under one topic; `lib/commands.js` gathers every module's commands. A command that
+  needs no tab, only reads, or takes `--all` is also listed in `lib/runner.js`'s `NO_TAB_NEEDED`,
+  `READ_ONLY` or `INSPECTION`, and one that takes fixed words in `complete` (`lib/commands.js`).
+- 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
+  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`
   runs commands one at a time (`quit` and `dialog` skip its queue); `lib/server.js` is the command
   server; `lib/send.js` and `lib/client.js` are `send` and `where`; `lib/background.js` is
   `serve --background`, `attach` and `stop`; `lib/launch.js` is `--launch`; `lib/syntax.js` is how a
   command line's words are read, shared with `send`; `lib/cli-names.js` maps playwright-cli's command
   names to these; `lib/state.js` holds the session state, with each client's selected tab;
-  `lib/output.js` routes all output so the server can return it.
+  `lib/output.js` routes all output so the server can return it; `lib/skill.js` stamps the skill
+  `pw-repl skill` prints, and gives `where` its hash.
 - Match playwright-cli (Microsoft's CLI for agents) where it is reasonable: agents are likelier to be
   trained on it. A new command, option or output that does what one of its does takes its name and form,
   or accepts them too (`lib/cli-names.js`, `help playwright-cli`). Differ where sharing a browser with a
@@ -26,11 +36,27 @@ If you hit a limitation or write a workaround, consider adding the capability to
   (`test/harness.js`), and the real REPL with its server. Nothing is mocked, and the shared browser is
   never touched. It finds Chromium through `PW_TEST_CHROME`, or where `--launch` looks (Playwright's
   browsers, then the `PATH`), and skips the browser tests if there is none. Add a test with each new
-  command or behaviour.
+  command or behaviour. In `test/repl.test.js` each test starts in a fresh tab of its own, and every mode
+  is turned off after it; a test whose REPL quits, times out or is killed goes in
+  `test/repl-alone.test.js`, with a Chromium of its own.
+- Help entries (`lib/help.js`) are plain paragraphs: `wrap()` lays each out at 104 columns, and keeps as
+  written a paragraph with a bullet, a table or an indented example. `test/fixtures` holds the rendered
+  help; after an intended change to it, save it again (the command is in `test/units.test.js`).
+- Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`).
+  Compare with the last commit that has one (`git log --grep='npm test:'`): a run that grew by more than
+  a few seconds means a slow test crept in, usually one waiting out a real timeout (5s for a click).
+  Find it (each test prints its time) and make it faster, or say why it can't be, before committing.
+- Don't race the clock in a test: a page that changes on a timer, or a command timed against a budget,
+  fails on a busy machine. Have the page change when the test asks (eval), or measure the thing itself
+  (frames drawn, not clicks timed). A click waits for its element to hold still for two frames.
+- A test that times out in a run much slower than usual (the machine is busy) may be load, not a bug:
+  run it again, alone. If it fails alone too, find out why before going on.
 - For anything the tests can't reach, exercise the change in a running REPL of your own: on a socket of
   your own, with `--launch` unless the change needs the user's browser, and then in a tab of your own.
 - `skill/SKILL.md` is how agents learn to use the REPL: keep it in step with a change to how it is
-  used, and leave its Custom rules section empty.
+  used, and leave its Custom rules section empty. Keep its `<!-- pw-repl skill stamp -->` line: `pw-repl
+  skill` replaces it with the version and a hash of the skill's text, which `where` reports, so agents
+  can tell a saved copy is out of date.
 
 ## Waves
 

package/README.md

@@ -1,10 +1,8 @@
 # playwright-repl
 
-A text REPL for driving an existing Chromium through Playwright over CDP: one session that people and agents
-share. People click in the browser and type commands at the prompt; agents send the same commands, and every
-one shows in the REPL, so each sees what the other does. The REPL inspects the page, records what happened
-(requests, console, and each step a person takes), fakes, patches or slows responses, and emulates phones,
-dark mode, locales and timezones.
+A command REPL for a Chromium you are already using, shared by you and your agents. It connects over CDP
+through Playwright; people click in the browser and type at the prompt, agents send the same commands,
+and every command shows in the REPL, so each sees what the other does.
 
 ## Why use it
 
@@ -19,83 +17,71 @@ For working on a web page together with an agent, in the browser you already use
 - **Breaking things on purpose.** Fake, patch, delay or fail responses, cut or slow the network, emulate a
   phone, a locale or a timezone, all per tab, so your other tabs are left alone.
 
-## How it differs from playwright-cli
-
-[playwright-cli](https://github.com/microsoft/playwright-cli) is Microsoft's command line for agents. It
-gives each agent a browser session of its own; pw-repl shares one browser between a person and agents.
-Its command names and most of their options work here too (`help playwright-cli` lists them), and where
-pw-repl differs, it is because someone else may be using the browser:
+Coming from Microsoft's playwright-cli? See [How it differs](#how-it-differs-from-playwright-cli).
 
-- `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
-- Routes, network and emulation apply to one tab, not the whole browser.
-- File pickers are not caught, since they may be the person's: `upload` names the input instead.
-- There is no snapshot after every command, since a person reads the REPL too; `snapshot` shows one.
-- Instead of `-s=<session>`, an agent is a client of its own (`send -c <name>`).
-- `watch` records what a person does as steps with their requests, not as generated code.
+## Quick start
 
-For a browser of its own per agent, isolated sessions, traces, video, PDFs or generated test code,
-playwright-cli is the better fit.
-
-## Getting started
-
-### Prerequisites
-
-- Node.js 20 or newer (`npm test` needs 21 or newer).
-- A Chromium-based browser (Chrome, Chromium, ungoogled-chromium, ...).
-- Optional: tmux, to use `pw-repl send` without the command server.
-
-### 1. Start the browser with remote debugging
+Needs Node.js 20 or newer and a Chromium-based browser (Chrome, Chromium, ...). With none installed,
+`npx playwright-core install chromium` downloads Playwright's.
 
 ```bash
-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
-# or: chromium --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chromium-debug"
+npx pw-repl@latest run --launch https://example.com
 ```
 
-Use a separate `--user-data-dir`: recent Chrome versions do not open the debugging port on the default
-profile. Check it is up with `curl http://localhost:9222/json/version`.
+`--launch` starts a private headless Chromium for the REPL, and stops it with the REPL; it prints the
+command it ran. `--headed` shows that browser, to click in it yourself. The page opens in a new tab,
+and a `pw>` prompt waits:
 
-**No browser to hand, or one you would rather not share?** Skip this step: `pw-repl run --launch` (or
-`serve --launch`) starts a private headless Chromium for the REPL and stops it with the REPL. It prints the
-command it ran, so you can start one your own way instead. If there is no Chromium at all,
-`npx playwright-core install chromium` downloads Playwright's.
+```text
+pw> help                          # common tasks and topics; help <topic>, help <command>, help --all
+pw> snapshot                      # the page by role and name, with [ref=eN] labels
+pw> click e3                      # click by snapshot ref (or any Playwright selector)
+pw> requests                      # requests the tab made
+pw> quit
+```
 
-**Headless** works the same way:
+Commands act on the selected tab (`tab` lists the tabs, with `*` on the selected one).
 
-```bash
-chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-headless
-```
+Without installing, use `npx pw-repl@latest <command>` in the same form every time, so each command runs
+the same version. Installed: `npm install -g pw-repl`, then `pw-repl <command>`. From a clone:
+`npm install`, then `bin/pw-repl.js <command>` (or `npm link` to get `pw-repl`).
 
-With nobody at the browser, `dialog accept` or `dialog dismiss` answers a dialog (`alert`, `confirm`);
-the REPL never answers one on its own. Pages start at about 800x600; `viewport 1280x800` sets another
-size.
+## Use your own browser
 
-### 2. Install and start the REPL
+Start it with remote debugging, then run the REPL without `--launch`:
 
 ```bash
-npm install -g pw-repl
+chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
 pw-repl run              # connects to localhost:9222; pw-repl on its own shows the usage
 ```
 
-Without installing: `npx pw-repl` (subcommands work the same way).
-From a clone: `npm install`, then `bin/pw-repl.js run` (or `npm link` to get `pw-repl`).
+Use a separate `--user-data-dir`: recent Chrome versions do not open the debugging port on the default
+profile. Check it is up with `curl http://localhost:9222/json/version`. `PW_CDP_URL=http://host:9222`
+reaches a browser elsewhere.
 
-It lists the open tabs and shows a `pw>` prompt. To send it commands from scripts or agents later
-(`pw-repl send`), run it in a tmux session named `playwright-repl` (`tmux new -s playwright-repl`), or
-start it with `pw-repl serve` instead, which needs no tmux (`pw-repl serve --background` runs it without
-a terminal; see [In the background](#in-the-background)).
+Headless works the same way (`chrome --headless=new --remote-debugging-port=9222
+--user-data-dir=/tmp/chrome-headless`). Nobody answers a headless browser's dialogs: `dialog
+accept|dismiss` does. Pages start at about 800x600; `viewport 1280x800` changes it.
+
+**Browser on the host, REPL in a container:** with host networking, `localhost:9222` reaches the host's
+browser directly. Otherwise set `PW_CDP_URL` to the host's address as seen from the container (for example
+the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 
-### 3. Try it
+## Ways to run it
 
-```text
-pw> help                          # common tasks and topics; help <topic>, help <command>, help --all
-pw> tab new https://example.com   # open your own tab to work in
-pw> snapshot                      # the page by role and name, with [ref=eN] labels
-pw> click e3                      # click by snapshot ref (or any Playwright selector)
-pw> requests                      # requests the tab made
-pw> tab close
-```
+| Command                      | What you get                                                                                  |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| `pw-repl run`                | a prompt in this terminal; `send` reaches it only through a tmux session named `playwright-repl` |
+| `pw-repl serve`              | a prompt (`pw[serve]>`), plus a command server on `/tmp/playwright-repl.sock`; `send` needs no tmux |
+| `pw-repl serve --background` | no terminal: `attach` to use it, `stop` to stop it, `where` to find it; output in `/tmp/playwright-repl.log` |
 
-Commands act on the selected tab (`tab` lists the tabs, with `*` on the selected one).
+- For `send` to reach `run`, start it in tmux: `tmux new -s playwright-repl`, then `pw-repl run` there.
+- A URL after the command opens in a new tab: `pw-repl run http://localhost:3000`.
+- `--launch` works with each of them; flags after `--` go to that Chromium.
+- `serve` takes a socket of its own (`pw-repl serve --background /tmp/mine.sock`; then `-e /tmp/mine.sock`
+  for `send`, `attach`, `stop` and `where`), or `serve <port>` for TCP on 127.0.0.1.
+- A background REPL cannot be brought back like a Ctrl-Z job; `attach` is how you get back to it, from
+  any terminal.
 
 ## Common tasks
 
@@ -129,31 +115,42 @@ lists them for every tab, and `modes off` turns them all off.
 `tab`, `watch`, `capture`, `route`, `network`, `emulate` and `modes` on their own show their state and what
 you can run next.
 
-## Options
+## How it differs from playwright-cli
 
-```bash
-pw-repl run http://localhost:3000        # connect and open a URL in a new tab
-pw-repl serve                            # also accept commands on /tmp/playwright-repl.sock (prompt: pw[serve]>)
-PW_CDP_URL=http://host:9222 pw-repl run  # a browser elsewhere
-```
+[playwright-cli](https://github.com/microsoft/playwright-cli) is Microsoft's command line for agents. It
+gives each agent a browser session of its own; pw-repl shares one browser between a person and agents.
+Its command names and most of their options work here too (`help playwright-cli` lists them), and where
+pw-repl differs, it is because someone else may be using the browser:
+
+- `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
+- Routes, network and emulation apply to one tab, not the whole browser.
+- File pickers are not caught, since they may be the person's: `upload` names the input instead.
+- There is no snapshot after every command, since a person reads the REPL too; `snapshot` shows one.
+- Instead of `-s=<session>`, an agent is a client of its own (`send -c <name>`).
+- `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).
 
-### In the background
+## From scripts and agents
+
+### A skill for agents
+
+`pw-repl skill` prints an agent skill (`SKILL.md`) that teaches an agent to use the REPL: how to start
+it, send commands, and share the browser with a person. Save it as `pw-repl/SKILL.md` in the folder
+your agent reads skills from:
 
 ```bash
-pw-repl serve --background   # detached, serving /tmp/playwright-repl.sock; output in /tmp/playwright-repl.log
-pw-repl attach               # see everything it does and type commands to it; Ctrl-C leaves it running
-pw-repl stop                 # stop it
-pw-repl where                # is one running, and where
+mkdir -p <skills folder>/pw-repl
+npx pw-repl@latest skill > <skills folder>/pw-repl/SKILL.md
 ```
 
-A background process cannot be brought back to the foreground like a Ctrl-Z job; `attach` is how you
-get back to it, from any terminal.
+It is stamped with the version it came from and a hash of its text, and `pw-repl where` names the skill
+of the pw-repl being run, so an agent can tell when its saved copy is out of date and offer to update it
+(keeping its Custom rules section). Working on the REPL itself: see `AGENTS.md`.
 
-**Browser on the host, REPL in a container:** with host networking, `localhost:9222` reaches the host's
-browser directly. Otherwise set `PW_CDP_URL` to the host's address as seen from the container (for example
-the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
-
-## From scripts and agents
+### send, clients and where
 
 ```bash
 pw-repl send info
@@ -162,34 +159,26 @@ pw-repl where           # which REPL send would reach
 ```
 
 `pw-repl send` sends one command and prints its result, through the server when it is running and through the
-`playwright-repl` tmux session otherwise. The server speaks HTTP with JSON:
-
-```bash
-curl --unix-socket /tmp/playwright-repl.sock -H 'Content-Type: application/json' \
-  -d '{"command": "info"}' http://localhost/run
-```
-
-It returns `{"status": "ok" | "error", "output": "..."}`, plus `"unconfirmed": true` when the command may or
-may not have done what it was sent to do (it timed out, or the REPL quit while it ran and it was not
-read-only). It is off unless started with `pw-repl serve`.
-`pw-repl serve <port>` serves TCP on 127.0.0.1 instead; other addresses are refused.
+`playwright-repl` tmux session otherwise.
 
 Several agents can share one REPL: `pw-repl send -c <name>` (or `PW_CLIENT=<name>`) sends as a client with a
 selected tab of its own, shown in the pane as `[server:<name>]`. `modes` says which client turned each mode on,
 and `modes off --mine` turns off only the sender's own.
 
-### A skill for agents
+### The HTTP protocol
 
-`pw-repl skill` prints an agent skill (`SKILL.md`) that teaches an agent to use the REPL: how to start
-it, send commands, and share the browser with a person. Save it as `pw-repl/SKILL.md` in the folder
-your agent reads skills from:
+With `pw-repl serve`, the server speaks HTTP with JSON, for clients of your own:
 
 ```bash
-mkdir -p <skills folder>/pw-repl
-pw-repl skill > <skills folder>/pw-repl/SKILL.md
+curl --unix-socket /tmp/playwright-repl.sock -H 'Content-Type: application/json' \
+  -d '{"command": "info"}' http://localhost/run
 ```
 
-The same text is in `skill/SKILL.md`. Working on the REPL itself: see `AGENTS.md`.
+It returns `{"status": "ok" | "error", "output": "..."}`, plus `"unconfirmed": true` when the command may or
+may not have done what it was sent to do (it timed out, or the REPL quit while it ran and it was not
+read-only). While the REPL starts, `/run` answers 503 with `"starting": true`: retry. `GET /health` says
+`"status": "starting"` until it serves, then `"ok"`. `pw-repl serve <port>` serves TCP on 127.0.0.1
+instead; other addresses are refused.
 
 ## Tests
 
@@ -197,6 +186,6 @@ The same text is in `skill/SKILL.md`. Working on the REPL itself: see `AGENTS.md
 npm test
 ```
 
-Runs against a private headless Chromium it starts itself (`PW_TEST_CHROME`, or the one `--launch` would
-use: Playwright's, e.g. from `npx playwright-core install chromium`, then one on the `PATH`) and a local
-test site; the browser tests are skipped when no Chromium is found.
+Needs Node.js 21 or newer. Runs against a private headless Chromium it starts itself (`PW_TEST_CHROME`, or
+the one `--launch` would use: Playwright's, e.g. from `npx playwright-core install chromium`, then one on
+the `PATH`) and a local test site; the browser tests are skipped when no Chromium is found.

package/bin/pw-repl.js

@@ -84,6 +84,16 @@ function parseSendArgs(args, allowCommand) {
       }
     } else if (arg === '--') { i++; break; } else break;
   }
+  // An address that is refused (not loopback) is a usage error, said once, not a stack trace.
+  const endpoint = options.endpoint || process.env.PW_ENDPOINT;
+  if (endpoint) {
+    try {
+      require('../lib/client').parseEndpoint(endpoint);
+    } catch (error) {
+      console.error(`pw-repl: ${error.message}`);
+      process.exit(64);
+    }
+  }
   const words = args.slice(i);
   if (!allowCommand && words.length) usage();
   // For a command that reads a quoted selector (fill "text=Your name" Ada), a
@@ -139,9 +149,9 @@ function help(topic) {
   console.log(text);
 }
 
-// Printed as is, to be saved as a skill; the hint goes to the terminal only.
+// Printed to be saved as a skill, stamped with where it came from; the hint goes to the terminal only.
 function skill() {
-  process.stdout.write(require('fs').readFileSync(require('path').join(__dirname, '..', 'skill', 'SKILL.md'), 'utf8'));
+  process.stdout.write(require('../lib/skill').stamped());
   if (process.stdout.isTTY) console.error('\nSave it as pw-repl/SKILL.md in the folder your agent reads skills from:\npw-repl skill > <skills folder>/pw-repl/SKILL.md');
 }
 

package/lib/background.js

@@ -99,7 +99,7 @@ async function start(options) {
   const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
   for (const signal of signals) process.on(signal, interrupt);
   const deadline = Date.now() + (options.launch ? LAUNCH_START_TIMEOUT : START_TIMEOUT);
-  while (!exited && !interrupted && Date.now() < deadline && !(await client.health(endpoint, 1000) && runningPid(pidFile))) {
+  while (!exited && !interrupted && Date.now() < deadline && !(await client.ready(endpoint, 1000) && runningPid(pidFile))) {
     await new Promise(resolve => setTimeout(resolve, 200));
   }
   for (const signal of signals) process.removeListener(signal, interrupt);
@@ -149,8 +149,9 @@ async function attach(options) {
   const { pidFile, logFile } = filesFor(endpoint);
   const pid = runningPid(pidFile);
   if (!pid) {
-    const served = await client.health(endpoint, 2000);
-    return fail(served ? `the REPL on ${name} runs in a terminal, not in the background; use it there` : `no background REPL is serving on ${name}; pw-repl serve --background starts one`);
+    const info = await client.healthInfo(endpoint, 2000);
+    if (info?.status === 'starting') return fail(`the REPL on ${name} is starting; retry shortly`);
+    return fail(info ? `the REPL on ${name} runs in a terminal, not in the background; use it there` : `no background REPL is serving on ${name}; pw-repl serve --background starts one`);
   }
   const fd = fs.openSync(logFile, 'r');
   const backlog = tail(logFile, ATTACH_BACKLOG);

package/lib/capture.js

@@ -0,0 +1,139 @@
+// Capturing a tab's requests and console messages together, from now until capture off.
+const { state, onShutdown } = require('./state');
+const out = require('./output');
+const { printOutput } = out;
+const { numbers, MAX_EVENT_TEXT, NO_TAB, clock, hints } = require('./util');
+const { consoleText, requestEntries } = require('./requestlog');
+
+const MAX_CAPTURE_EVENTS = 10000;
+const MAX_CAPTURE_TEXT = 400000;
+
+let cap = null;
+let lastCapture = null;
+
+// The capture running now, or null, for the modes it counts as.
+function currentCapture() {
+  return cap;
+}
+
+// Records the selected tab's requests and console messages together, in time
+// order, until capture off, or for a set number of seconds.
+async function startCapture(tokens) {
+  if (cap) { out.log('Already capturing; capture off stops it.'); return; }
+  if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
+  const usage = 'Usage: capture on [requests|console] [seconds] (seconds from 1 to 3600)';
+  const kinds = tokens.filter(t => t === 'requests' || t === 'console');
+  const numbers = tokens.filter(t => /^\d+$/.test(t));
+  if (kinds.length > 1 || numbers.length > 1 || kinds.length + numbers.length !== tokens.length) throw new Error(usage);
+  const seconds = numbers.length ? Number(numbers[0]) : null;
+  if (seconds !== null && (seconds < 1 || seconds > 3600)) throw new Error(usage);
+  const label = kinds[0] || 'requests and console';
+  const startedAt = Date.now();
+  const events = [];
+  const handlers = [];
+  let dropped = 0;
+  let shortened = 0;
+  let bytes = 0;
+  const record = event => {
+    let text = String(event.text);
+    if (text.length > MAX_EVENT_TEXT) { text = `${text.slice(0, MAX_EVENT_TEXT)}…`; shortened += 1; }
+    const size = text.length;
+    if (events.length >= MAX_CAPTURE_EVENTS || bytes + size > MAX_CAPTURE_TEXT) { dropped += 1; return; }
+    bytes += size;
+    events.push({ ...event, text });
+  };
+  const page = state.page;
+  const listen = (event, handler) => { page.on(event, handler); handlers.push([event, handler]); };
+  if (label !== 'console') listen('request', req => record({ t: Date.now(), tag: 'request', req, text: `${req.method()} ${req.url()}` }));
+  if (label !== 'requests') {
+    listen('console', msg => record({ t: Date.now(), tag: msg.type(), text: consoleText(msg) }));
+    listen('pageerror', error => record({ t: Date.now(), tag: 'pageerror', text: error.stack || error.message }));
+  }
+  // A capture must not outlive its tab: nothing could see or stop it.
+  listen('close', () => {
+    if (cap?.page !== page) return;
+    endCapture();
+    out.notice('The captured tab closed, which ended the capture; capture shows what it recorded.', page);
+  });
+  const capture = {
+    page, label, startedAt, events, handlers, wake: null, owner: state.client,
+    get dropped() { return dropped; },
+    get shortened() { return shortened; },
+  };
+  cap = capture;
+  if (seconds) {
+    out.log(`Capturing ${label} for ${seconds}s...`);
+    // Also ends early if the capture does, e.g. because its tab closed.
+    await new Promise(resolve => {
+      const timer = setTimeout(resolve, seconds * 1000);
+      capture.wake = () => { clearTimeout(timer); resolve(); };
+    });
+    if (cap === capture) stopCapture();
+    else printCapture(lastCapture);
+  } else {
+    out.log(`Capturing ${label}; capture off stops it and prints what it recorded.`);
+  }
+}
+
+function endCapture() {
+  cap.handlers.forEach(([event, h]) => cap.page.off(event, h));
+  const { label, startedAt, events, dropped, shortened, wake } = cap;
+  cap = null;
+  lastCapture = { label, startedAt, events, dropped, shortened };
+  if (wake) wake();
+}
+
+function stopCapture(all = false) {
+  if (!cap) { out.log('Not capturing.'); return; }
+  endCapture();
+  printCapture(lastCapture, all);
+}
+
+// One line per event, from the start of the capture: a request as requests
+// shows it (its status is looked up now, so it is known if it has finished),
+// a console message or page error as console shows it.
+function printCapture(capture, all = false) {
+  const lines = capture.events.map(event => {
+    const at = `+${((event.t - capture.startedAt) / 1000).toFixed(3)}s`;
+    if (event.tag !== 'request') return `${at} [${event.tag}] ${event.text}`;
+    const entry = requestEntries.get(event.req);
+    return entry ? `${at} #${entry.id} ${entry.method} ${entry.status} ${entry.url}` : `${at} ${event.text}`;
+  });
+  if (lines.length) printOutput(lines.join('\n'), all);
+  else out.log('Nothing captured');
+  const notes = [];
+  if (capture.dropped) notes.push(`${capture.dropped} event(s) omitted`);
+  if (capture.shortened) notes.push(`${capture.shortened} message(s) shortened`);
+  if (notes.length) out.log(`[capture limits: ${notes.join('; ')}]`);
+}
+
+function discardCapture() {
+  if (!cap) return;
+  cap.handlers.forEach(([event, handler]) => cap.page.off(event, handler));
+  cap = null;
+}
+
+onShutdown(discardCapture);
+
+const commands = {
+  async capture(args, all) {
+    const [sub, ...rest] = (args || '').trim().split(/\s+/).filter(Boolean);
+    if (sub === 'on') return startCapture(rest);
+    if (sub === 'off' && !rest.length) return stopCapture(all);
+    if (sub) throw new Error('Usage: capture on [requests|console] [seconds] | capture off');
+    if (cap) {
+      out.log(`Capturing ${cap.label} on ${cap.page.url()} since ${clock(cap.startedAt)} (${cap.events.length} so far)`);
+      out.log(hints([['capture off', 'stop and print what it recorded']]));
+      return;
+    }
+    if (lastCapture) {
+      out.log(`Not capturing. The last capture, of ${lastCapture.label} from ${clock(lastCapture.startedAt)}:`);
+      printCapture(lastCapture, all);
+    } else {
+      out.log('Not capturing.');
+    }
+    out.log(hints([['capture on [requests|console] [seconds]', 'record the selected tab\'s requests and console messages in time order']]));
+  },
+};
+
+module.exports = { commands, currentCapture, endCapture };

package/lib/cdp.js

@@ -0,0 +1,31 @@
+// The CDP session kept for each tab, and keeping a background tab drawing.
+const { tabState } = require('./tabstate');
+
+// Per page: a CDP session's emulation applies to the page it is attached to
+// and resets, in part, when it detaches, so one is kept for each tab.
+function keptSession(p) {
+  if (!('session' in tabState(p))) tabState(p).session = p.context().newCDPSession(p).catch(error => { delete tabState(p).session; throw error; });
+  return tabState(p).session;
+}
+
+// Chrome all but stops drawing a tab that is not in front once it has had
+// input (about a frame a second), and Playwright waits for frames to see an
+// element hold still before acting on it, so each click in a tab opened in the
+// background took 1-2s. A screencast keeps the tab drawing without bringing it
+// to the front, for as long as the REPL runs (the throttle is back within
+// seconds of stopping it). Its frames are tiny and rare; the cost is that the
+// tab renders at full rate, as if in front, an animation or a video included.
+async function keepDrawing(p) {
+  if ('drawing' in tabState(p)) return;
+  tabState(p).drawing = true;
+  try {
+    const session = await keptSession(p);
+    session.on('Page.screencastFrame', frame => session.send('Page.screencastFrameAck', { sessionId: frame.sessionId }).catch(() => {}));
+    await session.send('Page.startScreencast', { format: 'jpeg', quality: 1, maxWidth: 8, maxHeight: 8, everyNthFrame: 60 });
+  } catch {
+    // Only slower without it.
+    delete tabState(p).drawing;
+  }
+}
+
+module.exports = { keptSession, keepDrawing };

package/lib/cli-names.js

@@ -68,7 +68,6 @@ const NEAREST = {
   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',
   keydown: 'not here yet; press <key> presses and releases one', keyup: 'not here yet; press <key> presses and releases one',
-  mousewheel: 'not here yet; eval scrollBy(<dx>, <dy>) scrolls the page, without wheel events',
   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',
   'cookie-get': 'not here yet; cookies lists them without values, and cdp Network.getCookies {} shows the values',
@@ -84,14 +83,13 @@ const NEAREST = {
   install: 'not needed here: pw-repl needs no workspace set up; pw-repl skill says how to use it',
   'install-browser': 'not needed here: --launch uses Playwright\'s Chromium or one on the PATH (PW_CHROME)',
 };
-for (const name of ['mousemove', 'mousedown', 'mouseup']) NEAREST[name] = 'not here yet; click, dblclick and hover act on an element';
 for (const what of ['reduced-motion', 'forced-colors', 'contrast', 'media']) {
   NEAREST[`set-${what}`] = 'not here yet; emulate dark|light sets the color scheme';
   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; screenshot saves an image, and watch on records each step';
+  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 ['pause-at', 'resume', 'step-over']) NEAREST[name] = 'not here: they step through a Playwright test';
 

package/lib/client.js

@@ -53,6 +53,11 @@ async function health(endpoint, timeoutMs) {
   return (await healthInfo(endpoint, timeoutMs)) !== null;
 }
 
+// Serving, not only starting.
+async function ready(endpoint, timeoutMs) {
+  return (await healthInfo(endpoint, timeoutMs))?.status === 'ok';
+}
+
 // One command. Resolves to { result }, { timeout: true }, { dropped: reason }
 // (the connection closed after the command was sent, so it may have run) or
 // { unreachable: reason } (it was never sent).
@@ -85,4 +90,4 @@ function request(endpoint, command, timeoutMs, client = null) {
   });
 }
 
-module.exports = { DEFAULT_SOCKET, parseEndpoint, looksLikeEndpoint, describe, health, healthInfo, request };
+module.exports = { DEFAULT_SOCKET, parseEndpoint, looksLikeEndpoint, describe, health, ready, healthInfo, request };