pw-repl 0.4.1 → 0.5.0

package/AGENTS.md

@@ -1,8 +1,8 @@
 # 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
 
@@ -27,6 +27,10 @@ If you hit a limitation or write a workaround, consider adding the capability to
   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.
+- 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.
 - 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

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

@@ -41,9 +41,10 @@ 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), prints the command it ran, and stops it with the REPL. Flags after -- go to that
-Chromium; 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), 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.`;
 
@@ -138,9 +139,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

@@ -8,7 +8,13 @@ const client = require('./client');
 
 const BIN = path.join(__dirname, '..', 'bin', 'pw-repl.js');
 const START_TIMEOUT = 20000;
-const STOP_TIMEOUT = 10000;
+// Longer than --launch gives Chromium, twice when it retries without the sandbox, then the connect: its own
+// error, and its cleanup, come first.
+const LAUNCH_START_TIMEOUT = 2 * require('./launch').START_TIMEOUT + 20000;
+// Longer than a REPL can take to stop: its cleanups and letting go of the browser (up to
+// SHUTDOWN_TIMEOUT each), then stopping a Chromium it launched.
+const STOP_TIMEOUT = 2 * require('./state').SHUTDOWN_TIMEOUT + require('./launch').STOP_WORST + 4000;
+const LOG_LIMIT = 5 * 1024 * 1024;
 const FOLLOW_INTERVAL = 150;
 const ATTACH_BACKLOG = 20;
 const ATTACH_COMMAND_TIMEOUT = 3600000;
@@ -47,6 +53,13 @@ function tail(file, lines) {
   try { return fs.readFileSync(file, 'utf8').trimEnd().split('\n').slice(-lines).join('\n'); } catch { return ''; }
 }
 
+// Called in the background REPL as it starts: however it ends, served or not, its log says so.
+function markStopInLog() {
+  process.on('exit', code => {
+    try { fs.writeSync(process.stdout.fd, `--- ${new Date().toISOString()} stopped${code ? ` (exit code ${code})` : ''}\n`); } catch {}
+  });
+}
+
 // Called in the background REPL once it serves: its pid file says it runs, and goes when it exits.
 function claimPidFile(pidFile) {
   fs.writeFileSync(pidFile, String(process.pid), { mode: 0o600 });
@@ -62,8 +75,12 @@ async function start(options) {
   const running = runningPid(pidFile);
   if (running) return fail(`a background REPL is already serving on ${name} (pid ${running}); pw-repl attach uses it, pw-repl stop stops it`);
   if (await client.health(endpoint, 2000)) return fail(`a REPL is already serving on ${name}, in a terminal; pw-repl where says more`);
-  const log = fs.openSync(logFile, 'w', 0o600);
+  // Appended to, so an earlier run's log stays; each run is marked where it starts and stops. One grown
+  // past LOG_LIMIT is moved to <log>.1 first, replacing the one there.
+  try { if (fs.statSync(logFile).size > LOG_LIMIT) fs.renameSync(logFile, `${logFile}.1`); } catch {}
+  const log = fs.openSync(logFile, 'a', 0o600);
   fs.fchmodSync(log, 0o600);
+  fs.writeSync(log, `--- ${new Date().toISOString()} started\n`);
   const args = [BIN, 'serve', ...(options.launch ? ['--launch'] : []), ...(options.headed ? ['--headed'] : []),
     ...(options.endpoint ? [options.endpoint] : []), ...(options.startUrl ? [options.startUrl] : []),
     ...(options.chromeArgs.length ? ['--', ...options.chromeArgs] : [])];
@@ -74,11 +91,26 @@ async function start(options) {
   });
   fs.closeSync(log);
   let exited = false;
-  child.on('exit', () => { exited = true; });
-  const deadline = Date.now() + START_TIMEOUT;
-  while (!exited && Date.now() < deadline && !(await client.health(endpoint, 1000) && runningPid(pidFile))) {
+  const gone = new Promise(resolve => child.on('exit', () => { exited = true; resolve(); }));
+  // Ctrl-C while it waits gives up on the start: the REPL is stopped (and a Chromium it launched with it),
+  // rather than left starting where stop cannot reach it yet.
+  let interrupted = false;
+  const interrupt = () => { interrupted = true; };
+  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.ready(endpoint, 1000) && runningPid(pidFile))) {
     await new Promise(resolve => setTimeout(resolve, 200));
   }
+  for (const signal of signals) process.removeListener(signal, interrupt);
+  if (interrupted) {
+    if (!exited) child.kill();
+    await Promise.race([gone, new Promise(resolve => setTimeout(resolve, STOP_TIMEOUT))]);
+    try { fs.appendFileSync(logFile, `--- ${new Date().toISOString()} the start was interrupted\n`); } catch {}
+    console.error(`pw-repl: ${exited ? 'interrupted; the background REPL was stopped before it served' : `interrupted; the background REPL (pid ${child.pid}) has not stopped after ${STOP_TIMEOUT / 1000}s`}`);
+    // As a shell reports a command stopped by Ctrl-C.
+    return 130;
+  }
   if (exited || !runningPid(pidFile)) {
     if (!exited) child.kill();
     const last = tail(logFile, 12);
@@ -117,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);
@@ -186,4 +219,4 @@ function describeBackground(endpoint) {
   return `background: pid ${pid}${since}; log ${logFile} (pw-repl attach${e}, pw-repl stop${e})`;
 }
 
-module.exports = { filesFor, endpointFlag, claimPidFile, start, stop, attach, describeBackground };
+module.exports = { filesFor, endpointFlag, markStopInLog, claimPidFile, start, stop, attach, describeBackground };

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 };