pw-repl 0.1.0 → 0.2.1

package/AGENTS.md

@@ -22,3 +22,18 @@ If you hit a limitation or write a workaround, consider adding the capability to
   and a new tab, not the user's.
 - `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.
+
+## Releasing
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`,
+`test:`, `chore:` and so on, with an optional scope (`fix(watch): ...`). Versions follow semver; before
+1.0, a change that breaks how the REPL is used is a minor bump (0.2.0 to 0.3.0), anything else a patch.
+
+1. `npm test` passes and the working tree is clean.
+2. `npm outdated` and `npm audit` show nothing that needs doing first.
+3. `npm version <patch|minor|major> -m "chore: release %s"` sets the version in `package.json` and
+   `package-lock.json`, commits it as `chore: release X.Y.Z`, and tags that commit `vX.Y.Z`.
+4. `git push --follow-tags` pushes the commits and the tag.
+5. `npm publish` publishes it; `prepublishOnly` runs the tests again first.
+
+Pushing and publishing need the maintainer's GitHub and npm credentials.

package/README.md

@@ -33,7 +33,8 @@ From a clone: `npm install`, then `bin/pw-repl.js run` (or `npm link` to get `pw
 
 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.
+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)).
 
 ### 3. Try it
 
@@ -41,7 +42,7 @@ start it with `pw-repl serve` instead, which needs no tmux.
 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 aria-ref=e3             # click by label (or any Playwright selector)
+pw> click e3                      # click by snapshot ref (or any Playwright selector)
 pw> requests                      # requests the tab made
 pw> tab close
 ```
@@ -78,11 +79,23 @@ run next.
 ## Options
 
 ```bash
-pw-repl run http://localhost:3000        # connect and navigate tab [0] to a URL
+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
 ```
 
+### In the background
+
+```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
+```
+
+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.
+
 **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}'`).

package/bin/pw-repl.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// The one command: pw-repl run | serve | send | where | help | skill.
+// The one command: pw-repl run | serve | attach | stop | send | where | help | skill.
 
 const { looksLikeEndpoint } = require('../lib/client');
 
@@ -7,8 +7,15 @@ const USAGE = `Usage:
   pw-repl run [start-url]
       connect to the browser and open the prompt
 
-  pw-repl serve [endpoint] [start-url]
-      the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/playwright-repl.sock)
+  pw-repl serve [--background] [endpoint] [start-url]
+      the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/playwright-repl.sock);
+      --background runs it detached, with its output in a log next to the socket
+
+  pw-repl attach [-e endpoint]
+      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
 
   pw-repl send [-e endpoint | -s session] [-t seconds] <command...>
       run one command in a running REPL and print its output
@@ -28,7 +35,9 @@ exists but nothing answers, send fails rather than fall back.
 
 send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable.
 
-The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).`;
+The browser must be running with --remote-debugging-port (default http://localhost:9222; set $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).
 
@@ -58,13 +67,21 @@ function parseSendArgs(args, allowCommand) {
   }
   const words = args.slice(i);
   if (!allowCommand && words.length) usage();
-  options.command = words.join(' ').trim();
+  // For a command that reads a quoted selector (fill "text=Your name" Ada), a
+  // word the shell kept whole is quoted again so it stays one word. Any other
+  // command takes the rest of its line as it is (eval, route's JSON), so its
+  // words are joined as they are.
+  const { SELECTOR_FIRST } = require('../lib/syntax');
+  const requote = words.length > 1 && SELECTOR_FIRST.has(words[0]);
+  const quoted = requote ? words.map(w => (/[\s"']/.test(w) ? JSON.stringify(w) : w)) : words;
+  options.command = quoted.join(' ').trim();
   return options;
 }
 
 function startOptions(args, serve) {
-  const options = { serve, endpoint: null, startUrl: null };
+  const options = { serve, endpoint: null, startUrl: null, background: false, pidFile: process.env.PW_REPL_PID_FILE || null };
   const rest = [...args];
+  if (serve && rest.includes('--background')) { options.background = true; rest.splice(rest.indexOf('--background'), 1); }
   if (serve && rest[0] && looksLikeEndpoint(rest[0])) options.endpoint = rest.shift();
   if (rest.length > 1 || (rest[0] && rest[0].startsWith('-'))) usage();
   options.startUrl = rest[0] || null;
@@ -93,8 +110,19 @@ async function main() {
   if (subcommand === undefined) return console.log(`${USAGE}\n\n${REPL_HELP}`);
   switch (subcommand) {
     case 'run':
-    case 'serve':
-      return require('../lib/start').start(startOptions(args, subcommand === 'serve'));
+    case 'serve': {
+      const options = startOptions(args, subcommand === 'serve');
+      if (options.background) process.exit(await require('../lib/background').start(options));
+      return require('../lib/start').start(options);
+    }
+    case 'attach':
+    case 'stop': {
+      const options = parseSendArgs(args, false);
+      if (options.session) usage();
+      const endpoint = options.endpoint || process.env.PW_ENDPOINT || null;
+      process.exit(await require('../lib/background')[subcommand]({ endpoint }));
+    }
+    // falls through never: process.exit above
     case 'send': {
       const options = parseSendArgs(args, true);
       // help is fixed text, so it needs no browser: answer it here.

package/lib/background.js

@@ -0,0 +1,187 @@
+// pw-repl serve --background, attach and stop: a REPL that runs detached,
+// found through the files it keeps next to its socket.
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { spawn } = require('child_process');
+const client = require('./client');
+
+const BIN = path.join(__dirname, '..', 'bin', 'pw-repl.js');
+const START_TIMEOUT = 20000;
+const STOP_TIMEOUT = 10000;
+const FOLLOW_INTERVAL = 150;
+const ATTACH_BACKLOG = 20;
+const ATTACH_COMMAND_TIMEOUT = 3600000;
+
+// /tmp/playwright-repl.sock keeps /tmp/playwright-repl.pid and .log; a port, /tmp/playwright-repl-<port>.*.
+function filesFor(endpoint) {
+  const base = endpoint.socket ? endpoint.socket.replace(/\.sock$/, '') : path.join('/tmp', `playwright-repl-${endpoint.port}`);
+  return { pidFile: `${base}.pid`, logFile: `${base}.log` };
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+
+// The pid of the background REPL, or null; a pid file left by one that died is removed.
+function runningPid(pidFile) {
+  let pid;
+  try { pid = Number(fs.readFileSync(pidFile, 'utf8').trim()); } catch { return null; }
+  if (pid > 0 && alive(pid)) return pid;
+  try { fs.unlinkSync(pidFile); } catch {}
+  return null;
+}
+
+// What attach and stop need to find a REPL that is not on the default socket.
+function endpointFlag(endpointArg) {
+  const endpoint = client.parseEndpoint(endpointArg);
+  return endpoint.socket === client.DEFAULT_SOCKET ? '' : ` -e ${client.describe(endpoint)}`;
+}
+
+function fail(message) {
+  console.error(`pw-repl: ${message}`);
+  return 64;
+}
+
+function tail(file, lines) {
+  try { return fs.readFileSync(file, 'utf8').trimEnd().split('\n').slice(-lines).join('\n'); } catch { return ''; }
+}
+
+// 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 });
+  process.on('exit', () => {
+    try { if (fs.readFileSync(pidFile, 'utf8').trim() === String(process.pid)) fs.unlinkSync(pidFile); } catch {}
+  });
+}
+
+async function start(options) {
+  const endpoint = client.parseEndpoint(options.endpoint);
+  const name = client.describe(endpoint);
+  const { pidFile, logFile } = filesFor(endpoint);
+  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);
+  fs.fchmodSync(log, 0o600);
+  const args = [BIN, 'serve', ...(options.endpoint ? [options.endpoint] : []), ...(options.startUrl ? [options.startUrl] : [])];
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: ['ignore', log, log],
+    env: { ...process.env, PW_REPL_PID_FILE: pidFile },
+  });
+  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))) {
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+  if (exited || !runningPid(pidFile)) {
+    if (!exited) child.kill();
+    const last = tail(logFile, 10);
+    return fail(`the background REPL did not start${last ? `; the end of ${logFile}:\n${last}` : ''}`);
+  }
+  child.unref();
+  const e = endpointFlag(options.endpoint);
+  console.log(`Serving in the background (pid ${child.pid}) on ${name}`);
+  console.log(`Log: ${logFile}`);
+  console.log('');
+  const attachCommand = `pw-repl attach${e}`;
+  console.log(`  ${attachCommand}  see everything it does, and type commands to it`);
+  console.log(`  ${`pw-repl stop${e}`.padEnd(attachCommand.length)}  stop it`);
+  return 0;
+}
+
+async function stop(options) {
+  const endpoint = client.parseEndpoint(options.endpoint);
+  const { pidFile } = filesFor(endpoint);
+  const pid = runningPid(pidFile);
+  if (!pid) return fail(`no background REPL is serving on ${client.describe(endpoint)}`);
+  // 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}); its log stays at ${filesFor(endpoint).logFile}`);
+  return 0;
+}
+
+// Follows the background REPL's log, which holds everything it prints, and
+// sends what is typed as commands; their output then shows in the log too.
+async function attach(options) {
+  const endpoint = client.parseEndpoint(options.endpoint);
+  const name = client.describe(endpoint);
+  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 fd = fs.openSync(logFile, 'r');
+  const backlog = tail(logFile, ATTACH_BACKLOG);
+  let position = fs.fstatSync(fd).size;
+  console.log(`Attached to the background REPL (pid ${pid}) on ${name}. Ctrl-C or Ctrl-D leaves it running.`);
+  if (backlog) console.log(`\n${backlog}`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: 'pw[attach]> ' });
+  let inputEnded = false;
+  // New log lines go above what is being typed, which is then redrawn.
+  const follow = () => {
+    const size = fs.fstatSync(fd).size;
+    if (size < position) position = 0;
+    if (size === position) return;
+    const buffer = Buffer.alloc(size - position);
+    fs.readSync(fd, buffer, 0, buffer.length, position);
+    position = size;
+    if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
+    process.stdout.write(buffer.toString('utf8'));
+    if (!inputEnded) rl.prompt(true);
+  };
+  let leaving = false;
+  const leave = message => {
+    if (leaving) return;
+    leaving = true;
+    clearInterval(timer);
+    follow();
+    process.stdout.write(`\n${message}\n`);
+    process.exit(0);
+  };
+  const timer = setInterval(() => {
+    follow();
+    if (!runningPid(pidFile)) leave('The background REPL stopped.');
+  }, FOLLOW_INTERVAL);
+  let queue = Promise.resolve();
+  rl.on('line', line => {
+    const command = line.trim();
+    if (!command) { if (!inputEnded) rl.prompt(); return; }
+    if (command === 'quit' || command === 'exit') { leave('Left; the background REPL keeps running (pw-repl stop stops it).'); return; }
+    queue = queue.then(async () => {
+      const answer = await client.request(endpoint, command, ATTACH_COMMAND_TIMEOUT);
+      if (answer.unreachable || answer.dropped) console.error(`pw-repl: the background REPL did not answer (${answer.unreachable || answer.dropped})`);
+      // Let the log catch up, so the prompt comes back after the output.
+      await new Promise(resolve => setTimeout(resolve, FOLLOW_INTERVAL));
+      follow();
+    });
+  });
+  // Input can end before the commands typed ahead of it have run (e.g. piped in).
+  rl.on('close', () => {
+    inputEnded = true;
+    queue.then(() => leave('Left; the background REPL keeps running (pw-repl stop stops it).'));
+  });
+  rl.on('SIGINT', () => leave('Left; the background REPL keeps running (pw-repl stop stops it).'));
+  rl.prompt();
+  return new Promise(() => {});
+}
+
+// For pw-repl where: the background REPL on an endpoint, if there is one.
+function describeBackground(endpoint) {
+  const { pidFile, logFile } = filesFor(endpoint);
+  const pid = runningPid(pidFile);
+  if (!pid) return null;
+  let since = '';
+  try { since = `, since ${fs.statSync(pidFile).mtime.toLocaleString()}`; } catch {}
+  const e = endpoint.socket === client.DEFAULT_SOCKET ? '' : ` -e ${client.describe(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 };

package/lib/commands.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const { state, withTimeout, onShutdown, shutdown } = require('./state');
 const out = require('./output');
 const HELP = require('./help');
+const { toSelector, unquote, splitSelector } = require('./syntax');
 
 const { printOutput, OUTPUT_LIMIT } = out;
 const SCREENSHOT_DIR = process.env.PW_SCREENSHOT_DIR || '/tmp';
@@ -42,9 +43,9 @@ async function startCapture(tokens) {
   };
   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', text: `${req.method()} ${req.url()}` }));
+  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: `console:${msg.type()}`, text: msg.text() }));
+    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.
@@ -201,6 +202,13 @@ function clipText(text) {
   return text.length > MAX_EVENT_TEXT ? `${text.slice(0, MAX_EVENT_TEXT)}…` : text;
 }
 
+// The browser's own "Failed to load resource" message does not say which one.
+function consoleText(msg) {
+  const text = msg.text();
+  const url = msg.location()?.url;
+  return /^Failed to load resource/.test(text) && url ? `${text}: ${url}` : text;
+}
+
 function keep(log, entry) {
   log.push(entry);
   if (log.length > RECENT_MAX) log.shift();
@@ -235,7 +243,7 @@ function ensureRecentLog(p) {
     finish(req, fakedRequests.has(req) ? `${status} faked` : status, res);
   });
   p.on('requestfailed', req => finish(req, `failed: ${req.failure()?.errorText || 'unknown'}`));
-  p.on('console', msg => keep(logs, { t: Date.now(), type: msg.type(), text: clipText(msg.text()) }));
+  p.on('console', msg => keep(logs, { t: Date.now(), type: msg.type(), text: clipText(consoleText(msg)) }));
   // Uncaught exceptions never reach the console event.
   p.on('pageerror', error => keep(logs, { t: Date.now(), type: 'pageerror', text: clipText(error.stack || error.message) }));
 }
@@ -531,6 +539,12 @@ async function startWatching(p, changes = false, live = false) {
     // Only now: a failed first attempt must leave nothing half set up to retry against.
     watches.set(p, created);
     watch = created;
+  } else if (!watch.on) {
+    // A watch on after watch off is a new recording: the old steps would read as part of it.
+    watch.events.length = 0;
+    watch.shownSeq = watch.nextSeq - 1;
+    watch.shownRequestId = Math.max(0, ...(recentLogs.get(p) || []).map(r => r.id));
+    watch.liveStep = null;
   }
   await p.evaluate(WATCH_SCRIPT);
   watch.changes = changes;
@@ -653,6 +667,38 @@ async function allModesOff() {
   if (!any) out.log('No modes were on.');
 }
 
+// Commands that take only a selector take the whole line, spaces and all.
+function soleSelector(args, usage) {
+  const text = unquote((args || '').trim());
+  if (!text) throw new Error(`Usage: ${usage}`);
+  return toSelector(text);
+}
+
+function selectorAndValue(args, usage, example) {
+  const parsed = splitSelector(args);
+  if (!parsed || parsed.rest === undefined) {
+    throw new Error(`Usage: ${usage}, e.g. ${example}; quote a selector with spaces: "text=Your name"`);
+  }
+  return { selector: parsed.selector, value: unquote(parsed.rest), shown: parsed.word };
+}
+
+// An element that never appeared is said plainly, not as Playwright's call
+// log. A ref that no longer matches usually means the page changed since the
+// snapshot it came from.
+async function onElement(selector, action) {
+  try {
+    return await action();
+  } catch (error) {
+    if (/resolved to/.test(error.message)) throw error;
+    const ref = selector.startsWith('aria-ref=') ? selector.slice(9) : null;
+    const staleRef = ref ? `\n${ref} is a snapshot ref; if the page changed since that snapshot, take a new one.` : '';
+    const waited = /Timeout (\d+)ms exceeded[\s\S]*waiting for locator/.exec(error.message);
+    if (waited) throw new Error(`No element matches ${ref || selector} (waited ${waited[1] / 1000}s)${staleRef}`);
+    error.message += staleRef;
+    throw error;
+  }
+}
+
 const WAIT_DEFAULT = 10;
 const WAIT_MAX = 120;
 
@@ -716,13 +762,17 @@ function clock(t) {
   return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}${zone}`;
 }
 
+// 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 events = capture.events.map(event => ({
-    elapsed: Number(((event.t - capture.startedAt) / 1000).toFixed(3)),
-    tag: event.tag,
-    text: event.text,
-  }));
-  if (events.length) printOutput(events, all);
+  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`);
@@ -736,6 +786,56 @@ function discardCapture() {
   cap = null;
 }
 
+// A tab of the REPL's own: closing it can go back to the tab before. It opens
+// in the background, so it does not take the front of the window from the
+// person using the browser; Playwright's newPage would bring it to the front.
+const OPEN_TIMEOUT = 10000;
+
+async function openTab() {
+  const ctx = state.browser.contexts()[0];
+  let opened = null;
+  const session = await state.browser.newBrowserCDPSession().catch(() => null);
+  if (session) {
+    try {
+      const { targetId } = await session.send('Target.createTarget', { url: 'about:blank', background: true });
+      opened = await pageForTarget(ctx, targetId);
+    } catch {} finally {
+      await session.detach().catch(() => {});
+    }
+  }
+  // A browser that cannot open one in the background (e.g. some headless ones) opens it as usual.
+  if (!opened) opened = await ctx.newPage();
+  openedTabs.add(opened);
+  return opened;
+}
+
+// page -> its CDP target id, asked for once per page.
+const targetIds = new WeakMap();
+
+async function targetIdOf(ctx, p) {
+  if (!targetIds.has(p)) {
+    const cdp = await ctx.newCDPSession(p).catch(() => null);
+    if (!cdp) return null;
+    const info = await cdp.send('Target.getTargetInfo').catch(() => null);
+    await cdp.detach().catch(() => {});
+    if (!info) return null;
+    targetIds.set(p, info.targetInfo.targetId);
+  }
+  return targetIds.get(p);
+}
+
+async function pageForTarget(ctx, targetId) {
+  const deadline = Date.now() + OPEN_TIMEOUT;
+  while (Date.now() < deadline) {
+    for (const p of ctx.pages()) {
+      if (openedTabs.has(p)) continue;
+      if (await targetIdOf(ctx, p) === targetId) return p;
+    }
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+  return null;
+}
+
 // Every tab, URL first, with * on the selected one. The numbers are what tab <index> uses.
 async function listTabs() {
   const all = state.browser.contexts().flatMap(c => c.pages());
@@ -788,18 +888,19 @@ const commands = {
     if (/^\d+$/.test(subcommand)) {
       if (parts.length) throw new Error(usage);
       const target = state.tabListing[Number(subcommand)];
-      if (!target || !all.includes(target)) throw new Error('That tab is unavailable. Run tab again.');
-      select(target);
-      return commands.info();
+      if (target && all.includes(target)) { select(target); return commands.info(); }
+      // A number that is not a tab in the listing may be part of a URL (a port).
+      if (!all.some(p => p.url().includes(subcommand))) throw new Error(`No tab [${subcommand}] in the latest listing, and no tab URL contains ${subcommand}. Run tab to list them.`);
     }
     if (subcommand === 'new') {
-      const ctx = state.browser.contexts()[0];
-      const opened = await ctx.newPage();
-      openedTabs.add(opened);
-      select(opened);
+      select(await openTab());
       const url = parts.join(' ');
-      if (url) await commands.goto(url);
-      else out.log('New tab created and selected');
+      if (url) {
+        try { await commands.goto(url); }
+        catch (error) { throw new Error(`${error.message}\nThe new tab stays open and selected; tab close closes it.`); }
+      } else {
+        out.log('New tab created and selected');
+      }
       return listTabs();
     }
     if (subcommand === 'close') {
@@ -852,104 +953,95 @@ const commands = {
   },
 
   async click(args) {
-    if (!args) throw new Error('Usage: click <selector>');
-    await state.page.click(args, { timeout: 5000 });
-    out.log(`Clicked: ${args}`);
+    const selector = soleSelector(args, 'click <selector>');
+    await onElement(selector, () => state.page.click(selector, { timeout: 5000 }));
+    out.log(`Clicked: ${args.trim()}`);
   },
 
   async dblclick(args) {
-    if (!args) throw new Error('Usage: dblclick <selector>');
-    await state.page.dblclick(args, { timeout: 5000 });
-    out.log(`Double-clicked: ${args}`);
+    const selector = soleSelector(args, 'dblclick <selector>');
+    await onElement(selector, () => state.page.dblclick(selector, { timeout: 5000 }));
+    out.log(`Double-clicked: ${args.trim()}`);
   },
 
   async hover(args) {
-    if (!args) throw new Error('Usage: hover <selector>');
-    await state.page.hover(args, { timeout: 5000 });
-    out.log(`Hovered: ${args}`);
+    const selector = soleSelector(args, 'hover <selector>');
+    await onElement(selector, () => state.page.hover(selector, { timeout: 5000 }));
+    out.log(`Hovered: ${args.trim()}`);
   },
 
   async fill(args) {
-    if (!args || !args.includes('=>')) {
-      throw new Error('Usage: fill <selector> => <value>');
-    }
-    const [selector, ...rest] = args.split('=>');
-    await state.page.fill(selector.trim(), rest.join('=>').trim(), { timeout: 5000 });
-    out.log(`Filled: ${selector.trim()}`);
+    const { selector, value, shown } = selectorAndValue(args, 'fill <selector> <value>', 'fill #name Ada Lovelace');
+    await onElement(selector, () => state.page.fill(selector, value, { timeout: 5000 }));
+    out.log(`Filled: ${shown}`);
   },
 
   async type(args) {
-    if (!args || !args.includes('=>')) {
-      throw new Error('Usage: type <selector> => <text>');
-    }
-    const [selector, ...rest] = args.split('=>');
-    await state.page.type(selector.trim(), rest.join('=>').trim(), { timeout: 5000 });
-    out.log(`Typed into: ${selector.trim()}`);
+    const { selector, value, shown } = selectorAndValue(args, 'type <selector> <text>', 'type #search garden hose');
+    await onElement(selector, () => state.page.type(selector, value, { timeout: 5000 }));
+    out.log(`Typed into: ${shown}`);
   },
 
   async press(args) {
-    if (!args) throw new Error('Usage: press <key> or press <selector> => <key>');
-    if (args.includes('=>')) {
-      const [selector, key] = args.split('=>').map(s => s.trim());
-      await state.page.press(selector, key, { timeout: 5000 });
-      out.log(`Pressed ${key} on ${selector}`);
-    } else {
-      await state.page.keyboard.press(args.trim());
-      out.log(`Pressed: ${args.trim()}`);
+    const parsed = splitSelector(args);
+    if (!parsed) throw new Error('Usage: press <key> | press <selector> <key>, e.g. press Enter or press #name Enter');
+    if (parsed.rest === undefined) {
+      await state.page.keyboard.press(parsed.word);
+      out.log(`Pressed: ${parsed.word}`);
+      return;
     }
+    const key = unquote(parsed.rest);
+    await onElement(parsed.selector, () => state.page.press(parsed.selector, key, { timeout: 5000 }));
+    out.log(`Pressed ${key} on ${parsed.word}`);
   },
 
-
   async select(args) {
-    if (!args || !args.includes('=>')) {
-      throw new Error('Usage: select <selector> => <value>');
-    }
-    const [selector, value] = args.split('=>').map(s => s.trim());
-    await state.page.selectOption(selector, value, { timeout: 5000 });
-    out.log(`Selected "${value}" in ${selector}`);
+    const { selector, value, shown } = selectorAndValue(args, 'select <selector> <value>', 'select #country Canada');
+    await onElement(selector, () => state.page.selectOption(selector, value, { timeout: 5000 }));
+    out.log(`Selected "${value}" in ${shown}`);
   },
 
   async check(args) {
-    if (!args) throw new Error('Usage: check <selector>');
-    await state.page.check(args, { timeout: 5000 });
-    out.log(`Checked: ${args}`);
+    const selector = soleSelector(args, 'check <selector>');
+    await onElement(selector, () => state.page.check(selector, { timeout: 5000 }));
+    out.log(`Checked: ${args.trim()}`);
   },
 
   async uncheck(args) {
-    if (!args) throw new Error('Usage: uncheck <selector>');
-    await state.page.uncheck(args, { timeout: 5000 });
-    out.log(`Unchecked: ${args}`);
+    const selector = soleSelector(args, 'uncheck <selector>');
+    await onElement(selector, () => state.page.uncheck(selector, { timeout: 5000 }));
+    out.log(`Unchecked: ${args.trim()}`);
   },
 
   async text(args, all) {
-    if (!args) throw new Error('Usage: text <selector>');
-    printOutput(await state.page.innerText(args, { timeout: 5000 }), all);
+    const selector = soleSelector(args, 'text <selector>');
+    printOutput(await onElement(selector, () => state.page.innerText(selector, { timeout: 5000 })), all);
   },
 
   async html(args, all) {
-    if (!args) throw new Error('Usage: html <selector>');
-    printOutput(await state.page.$eval(args, el => el.outerHTML), all);
+    const selector = soleSelector(args, 'html <selector>');
+    printOutput(await onElement(selector, () => state.page.$eval(selector, el => el.outerHTML)), all);
   },
 
   async attrs(args, all) {
-    if (!args) throw new Error('Usage: attrs <selector>');
-    const result = await state.page.$eval(args, el => {
+    const selector = soleSelector(args, 'attrs <selector>');
+    const result = await onElement(selector, () => state.page.$eval(selector, el => {
       const out = {};
       for (const attr of el.attributes) out[attr.name] = attr.value;
       return out;
-    });
+    }));
     printOutput(result, all);
   },
 
   async count(args) {
-    if (!args) throw new Error('Usage: count <selector>');
-    const els = await state.page.$$(args);
+    const selector = soleSelector(args, 'count <selector>');
+    const els = await state.page.$$(selector);
     out.log(`${els.length} element(s)`);
   },
 
   async visible(args) {
-    if (!args) throw new Error('Usage: visible <selector>');
-    const el = await state.page.$(args);
+    const selector = soleSelector(args, 'visible <selector>');
+    const el = await state.page.$(selector);
     if (!el) { out.log('Not found'); return; }
     out.log(await el.isVisible() ? 'visible' : 'hidden');
   },
@@ -1008,6 +1100,9 @@ const commands = {
     }
     // Named after the countdown so a default filename timestamps the capture.
     const filepath = nextScreenshotPath(name);
+    // Chrome does not draw a tab that is not in front, and tabs open in the
+    // background, so the tab is brought to the front for the shot.
+    await state.page.bringToFront();
     const image = await state.page.screenshot({ fullPage: full });
     try {
       fs.writeFileSync(filepath, image, { flag: 'wx', mode: 0o600 });
@@ -1029,7 +1124,7 @@ const commands = {
       rest = '';
     }
     // Playwright's labels are e5, or frame-prefixed like f1e5 in newer versions.
-    const selector = /^(?:f\d+)?e\d+$/.test(rest) ? `aria-ref=${rest}` : rest;
+    const selector = toSelector(rest);
     const target = selector ? state.page.locator(selector).first() : state.page;
     const raw = await target.ariaSnapshot({ mode: 'ai', timeout: 5000 });
     const text = full ? raw : compactSnapshot(raw);
@@ -1072,9 +1167,9 @@ const commands = {
       }
       return waitForRequest(what, timeout);
     }
-    const selector = tokens.join(' ');
+    const selector = toSelector(unquote(tokens.join(' ')));
     await state.page.waitForSelector(selector, { state: 'attached', timeout });
-    out.log(`Found: ${selector}`);
+    out.log(`Found: ${tokens.join(' ')}`);
   },
 
   async sleep(args) {
@@ -1158,6 +1253,12 @@ const commands = {
       const ms = e.ms === null ? '-' : `${e.ms}ms`;
       out.log(`#${e.id} ${clock(e.t)} ${e.method} ${e.status} ${ms} ${e.url}`);
     }
+    // The numbers skip what is hidden; say so, or they look like requests went missing.
+    const first = matches[0].id;
+    const last = matches[matches.length - 1].id;
+    // With a filter, the numbers skip what does not match too, so the count would mislead.
+    const hidden = everything || filter ? 0 : log.filter(e => e.id > first && e.id < last && !shown.includes(e)).length;
+    if (hidden) out.log(`(${hidden} hidden between these: images, fonts, stylesheets, media and extension requests; requests --all shows them)`);
   },
 
   async body(args, all) {
@@ -1177,7 +1278,8 @@ const commands = {
     const late = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`did not arrive within ${BODY_TIMEOUT / 1000}s`)), BODY_TIMEOUT); });
     let buffer;
     try { buffer = await Promise.race([entry.response.body(), late]); }
-    catch (error) { throw new Error(`The body of #${id} is not available: ${error.message}`); }
+    // Playwright's reason ends in advice for its own API ("Read response.body() before..."), so only its first line is kept.
+    catch (error) { throw new Error(`The body of #${id} is not available: ${String(error.message).split('\n')[0]} (the browser drops bodies, e.g. after the tab navigates)`); }
     finally { clearTimeout(timer); }
     const type = entry.response.headers()['content-type'] || '';
     out.log(`#${id} ${entry.method} ${entry.status} ${entry.url} (${type || 'no content type'}, ${buffer.length} bytes)`);
@@ -1367,4 +1469,4 @@ function complete(line) {
   return [[], current];
 }
 
-module.exports = { commands, listTabs, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };
+module.exports = { commands, listTabs, openTab, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };

package/lib/help.js

@@ -31,11 +31,11 @@ help <command> for usage and caveats (e.g. help route); help --all for everythin
 
 const TOPICS = {
   tabs: {
-    intro: 'The REPL selects tab [0] when it starts; tab on its own lists them all. After tab close, see help tab.',
+    intro: 'No tab is selected when the REPL starts: tab new opens one, tab <index|url-part> selects one.\ntab on its own lists them all.',
     commands: ['tab', 'goto', 'back', 'forward', 'reload', 'info'],
   },
   interact: {
-    intro: 'Selectors are Playwright selectors (CSS, text=..., role=...). Commands use the first match.',
+    intro: 'Selectors are Playwright selectors (CSS, text=..., role=...) or snapshot refs such as e5.\nCommands use the first match; see help fill for selectors with spaces.',
     commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck'],
   },
   inspect: {
@@ -53,7 +53,8 @@ const TOPICS = {
   session: {
     intro: `Completion: @<id> <command> makes the REPL print [[pw-done:<id>:ok|error]] when it finishes.
 
-Unknown outcome: a timed-out command may still be running, so the REPL disconnects instead of continuing.
+Unknown outcome: a command that timed out after it began acting on the page may or may not have done
+it. It says so (pw-repl send exits 2), and the REPL carries on.
 
 Server: pw-repl serve also takes commands on /tmp/playwright-repl.sock; they show here as [server] lines.
 
@@ -71,7 +72,7 @@ const COMMANDS = {
   tab: {
     usage: 'tab [<index>|<url-part>|new [url]|close [url-part]]',
     summary: 'list tabs (* is selected); select, open or close one',
-    detail: 'tab <index> uses the numbers from the latest tab listing; they change when tabs open or close.\n\ntab <url-part> selects the one tab whose URL contains it, and refuses if none or several do.\n\ntab new opens and selects a tab. tab close closes the selected tab, or the one matching url-part.\n\nClosing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is\nselected, and commands that need one refuse until one is.',
+    detail: 'tab <index> uses the numbers from the latest tab listing; they change when tabs open or close.\n\ntab <url-part> selects the one tab whose URL contains it, and refuses if none or several do.\n\ntab new opens a tab behind the one in front, so it does not take the window from whoever is using it,\nand selects it. tab close closes the selected tab, or the one matching url-part.\n\nClosing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is\nselected, and commands that need one refuse until one is.',
   },
   goto: { usage: 'goto <url>', summary: 'navigate the selected tab; https:// is assumed' },
   back: { usage: 'back', summary: 'go back one history entry' },
@@ -81,21 +82,25 @@ const COMMANDS = {
   click: { usage: 'click <selector>', summary: 'click the first match' },
   dblclick: { usage: 'dblclick <selector>', summary: 'double-click the first match' },
   hover: { usage: 'hover <selector>', summary: 'hover the first match' },
-  fill: { usage: 'fill <selector> => <value>', summary: 'clear an input and fill it' },
-  type: { usage: 'type <selector> => <text>', summary: 'type into an input key by key' },
-  press: { usage: 'press <key> | press <selector> => <key>', summary: 'press a key, optionally on an element' },
-  select: { usage: 'select <selector> => <value>', summary: 'choose an option in a select' },
+  fill: {
+    usage: 'fill <selector> <value>',
+    summary: 'clear an input and fill it',
+    detail: 'The selector is the first word; quote it if it has spaces. The rest of the line is the value, and\nquotes around all of it are removed, so fill #name "" clears the field.\n\nExamples: fill #name Ada Lovelace, fill "text=Your name" Ada, fill e7 Ada',
+  },
+  type: { usage: 'type <selector> <text>', summary: 'type into an input key by key; the text is as for fill' },
+  press: { usage: 'press <key> | press <selector> <key>', summary: 'press a key (Enter, Escape, Control+A), optionally on an element' },
+  select: { usage: 'select <selector> <value>', summary: 'choose an option in a select (the value is the rest of the line)' },
   check: { usage: 'check <selector>', summary: 'check a checkbox' },
   uncheck: { usage: 'uncheck <selector>', summary: 'uncheck a checkbox' },
   snapshot: {
     usage: 'snapshot [--full] [--grep <text> | <eN> | selector]',
     summary: 'outline by role and name, with [ref=eN] labels',
-    detail: 'Playwright\'s accessibility snapshot, with unnamed layout wrappers (generic) and cursor hints left\nout; --full shows it unchanged.\n\n--grep <text> prints only the lines containing text (role, name or flag such as [disabled], any\ncase), each with the named elements around it. A hit with no named element around it prints without\na path.\n\nsnapshot e3 outlines one element. A label (e3, or f1e3 in newer Playwright) works as a selector:\nclick aria-ref=e3. Labels can change when the page navigates (e102 may become f4e98), so take a new\nsnapshot after one.\n\nOutput over 60 lines ends with a line count.',
+    detail: 'Playwright\'s accessibility snapshot, with unnamed layout wrappers (generic) and cursor hints left\nout; --full shows it unchanged.\n\n--grep <text> prints only the lines containing text (role, name or flag such as [disabled], any\ncase), each with the named elements around it. A hit with no named element around it prints without\na path.\n\nsnapshot e3 outlines one element. A ref (e3, or f1e3 in newer Playwright) works as a selector in any\ncommand: click e3. Refs can change when the page changes (e102 may become f4e98), so take a new\nsnapshot after it does.\n\nOutput over 60 lines ends with a line count.',
   },
   watch: {
     usage: 'watch on [--changes] [--live] | off | [n|new]',
     summary: 'record what happens in the tab; show the last n steps',
-    detail: 'Off until watch on. Records clicks, typing (once it pauses), Enter and Escape, form changes, submits\nand navigations, each described by role and name like snapshot, with up to 5 of the requests it\ncaused underneath (their numbers in requests; body <#> for one), leaving out scripts and what\nrequests hides. The REPL\'s own fill is recorded as type.\n\nwatch on its own says whether it is on and shows the last 20 steps; watch <n> shows the last n.\nwatch new shows only the steps it has not shown yet, and requests that have since arrived for the\nlast one.\n\n--live also prints each step in the REPL window (never in the server\'s answer to a command) once it\nsettles, with its requests and changes, marked [watch], or [watch <url>] for a tab that is not the\nselected one. A step cut short by the next one, or by watch off, prints at once; changes it made\nthen show under the next step.\n\n--changes also shows what each step changed on the page once it settles, in up to 5 lines: + added,\n- removed, ~ changed, each element once with the first names inside it. Not for navigations.\n\nTyped values are not recorded, and password fields not at all; --changes leaves out field values,\nbut what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.',
+    detail: 'Off until watch on; a watch on after watch off starts a new recording. Records clicks, typing (once\nit pauses), Enter and Escape, form changes, submits and navigations, each described by role and name\nlike snapshot, with up to 5 of the requests it caused underneath (their numbers in requests; body\n<#> for one), leaving out scripts and what requests hides. The REPL\'s own fill is recorded as type.\n\nwatch on its own says whether it is on and shows the last 20 steps; watch <n> shows the last n.\nwatch new shows only the steps it has not shown yet, and requests that have since arrived for the\nlast one.\n\n--live also prints each step in the REPL window (never in the server\'s answer to a command) once it\nsettles, with its requests and changes, marked [watch], or [watch <url>] for a tab that is not the\nselected one. A step cut short by the next one, or by watch off, prints at once; changes it made\nthen show under the next step.\n\n--changes also shows what each step changed on the page once it settles, in up to 5 lines: + added,\n- removed, ~ changed, each element once with the first names inside it. Not for navigations.\n\nTyped values are not recorded, and password fields not at all; --changes leaves out field values,\nbut what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.',
   },
   text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
   html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match' },
@@ -107,7 +112,7 @@ const COMMANDS = {
   screenshot: {
     usage: 'screenshot [--full] [--delay|-d <seconds>] [name]',
     summary: 'save a PNG of the viewport (or --full page)',
-    detail: 'Saved as screenshot-<name or timestamp>.png in $PW_SCREENSHOT_DIR (default /tmp).\n\n--delay counts down out loud first (maximum 60s), so someone can hold a hover or open a menu.',
+    detail: 'Saved as screenshot-<name or timestamp>.png in $PW_SCREENSHOT_DIR (default /tmp). It brings the tab to\nthe front of its window first: Chrome draws only the tab in front.\n\n--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' },
   wait: {
@@ -134,17 +139,17 @@ const COMMANDS = {
   capture: {
     usage: 'capture on [requests|console] [secs] | off',
     summary: 'record requests and console together, in time order',
-    detail: 'capture on records both until capture off, which prints them; requests or console records only one.\nWith secs (1-3600 seconds) it records that long, then prints; the REPL waits meanwhile.\n\nOne capture runs at a time, on the tab selected when it started. Unlike requests and console it\nkeeps more than the last 200 and lists both together.\n\ncapture on its own says whether one is running, or shows the last one.',
+    detail: 'capture on records both until capture off, which prints them; requests or console records only one.\nWith secs (1-3600 seconds) it records that long, then prints. Other commands wait until a timed\ncapture ends, so it suits recording what someone does in the browser; around your own commands, use\ncapture on and capture off.\n\nOne capture runs at a time, on the tab selected when it started. Unlike requests and console it\nkeeps more than the last 200 and lists both together.\n\ncapture on its own says whether one is running, or shows the last one.',
   },
   route: {
     usage: 'route <glob> <status> <json> | off <glob>|--all',
     summary: 'answer the selected tab\'s matching requests with fake JSON',
-    detail: 'The fake is fulfilled inside the browser, so the page handles it as a real response and the request\nnever reaches the network. Each one prints "Faked: #<n> <METHOD> <url> -> <status>", with #<n> as in\nrequests. If fulfilling fails it prints "Fake failed" and aborts the request, so it never reaches\nthe network.\n\nStatus: 200-599. wait request <glob> after the page loads prints the request with its status, so a\nfake shows as <status> faked.\n\nRoutes belong to the tab and last until route off <glob> (or route off --all) or the REPL exits.\nRouting the same glob again replaces it. route on its own lists the selected tab\'s routes.\n\nExample: route **/api/health_check 503 {"detail":{"code":"service_unavailable"}}',
+    detail: 'The fake is fulfilled inside the browser, so the page handles it as a real response and the request\nnever reaches the network; it still answers while the network is off. Each one prints "Faked: #<n>\n<METHOD> <url> -> <status>" in the REPL window (and in the answer to a command running then), with\n#<n> as in requests. If fulfilling fails it prints "Fake failed" and aborts the request, so it never\nreaches the network.\n\nStatus: 200-599. wait request <glob> after the page loads prints the request with its status, so a\nfake shows as <status> faked.\n\nRoutes belong to the tab and last until route off <glob> (or route off --all) or the REPL exits.\nRouting the same glob again replaces it. route on its own lists the selected tab\'s routes.\n\nExample: route **/api/health_check 503 {"detail":{"code":"service_unavailable"}}',
   },
   network: {
     usage: 'network [on|off]',
     summary: 'cut or restore the tab\'s network, like dropped wifi',
-    detail: 'Stopping a service is not the same: a dev proxy in front of it usually holds the request open, so\nthe page spins instead of failing.\n\nPer tab; lasts until network on or the REPL exits.',
+    detail: 'Stopping a service is not the same: a dev proxy in front of it usually holds the request open, so\nthe page spins instead of failing.\n\nPer tab; lasts until network on or the REPL exits. Routes still answer while it is off.',
   },
   eval: {
     usage: 'eval [--all] <JavaScript>',
@@ -161,7 +166,7 @@ const COMMANDS = {
   modes: {
     usage: 'modes [off]',
     summary: 'the modes on in every tab; modes off turns them all off',
-    detail: 'The modes are watch, network off, route and capture. Each is turned on and off with its own command:\nwatch on|off, network off|on, route <glob> ... | route off, capture on|off.\n\nmodes off turns off every one in every tab; a capture it stops is kept for capture to show.',
+    detail: 'The modes are watch, network off, route and capture. Each is turned on and off with its own command:\nwatch on|off, network off|on, route <glob> ... | route off <glob>|--all, capture on|off.\n\nmodes off turns off every one in every tab; a capture it stops is kept for capture to show.',
   },
   help: { usage: 'help [topic | command | --all]', summary: 'this help; --all prints every topic and command in full' },
   quit: {

package/lib/runner.js

@@ -1,13 +1,13 @@
 // Runs commands one at a time, whether they come from the prompt or the server.
 // A prompt command tagged @<id> reports completion with a marker the caller can wait for.
 const readline = require('readline');
-const { state, shutdown, beforeExit } = require('./state');
+const { state, beforeExit } = require('./state');
 const out = require('./output');
 const { commands, activeModes } = require('./commands');
 
-// A timeout here cannot have changed anything, so it is reported as an error
-// and the REPL carries on. Any other command that times out may still be
-// acting on the page, so the REPL disconnects rather than continue.
+// A timeout here cannot have changed anything, so it is an ordinary error. Any
+// other command that times out may or may not have done what it was sent to
+// do; that is reported, and the REPL carries on.
 const READ_ONLY = new Set(['info', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs',
   'snapshot', 'screenshot', 'wait', 'sleep', 'requests', 'body', 'console', 'cookies', 'storage', 'capture', 'help']);
 
@@ -28,7 +28,10 @@ function parseInput(line) {
 }
 
 function isUncertain(error) {
-  return /timed out|timeout|connection (?:lost|closed)/i.test(error.message || '');
+  const message = error.message || '';
+  if (!/timed out|timeout|connection (?:lost|closed)/i.test(message)) return false;
+  // Playwright's call log shows whether the element was ever found; if not, nothing was done.
+  return !(/waiting for locator/.test(message) && !/resolved to/.test(message));
 }
 
 let running = 0;
@@ -69,20 +72,17 @@ async function executeCommand(text) {
   try {
     await commands[cmd](args, all);
   } catch (e) {
+    // Playwright colours its call log; the codes are noise anywhere but a terminal.
+    e.message = String(e.message || '').replace(/\x1b\[[0-9;]*m/g, '');
     out.error(`Error: ${e.message}`);
-    return { status: 'error', cmd, uncertain: !READ_ONLY.has(cmd) && isUncertain(e) };
+    const uncertain = !READ_ONLY.has(cmd) && isUncertain(e);
+    if (uncertain) out.error('Outcome unknown: it timed out after it began acting on the page. Check the page before trying again.');
+    return { status: 'error', cmd, uncertain };
   }
   if (cmd === 'quit' && state.shutdownFailed) return { status: 'error', cmd };
   return { status: 'ok', cmd };
 }
 
-// A timed-out browser command may still be running, so nothing after it can
-// be trusted to act on the page the caller thinks it is acting on.
-function giveUp() {
-  out.error('Browser command outcome is unknown; disconnecting instead of continuing.');
-  void shutdown().then(beforeExit).then(() => process.exit(process.exitCode || 1));
-}
-
 // A quit does not wait for the running server command, which may never finish
 // once the browser is gone, so its sender is answered now. A read-only command
 // changed nothing; any other may or may not have done what it was sent to do.
@@ -106,12 +106,12 @@ async function handleLine(line) {
   const result = await execute(input.text);
   done(result.status);
   if (result.cmd === 'quit') { await beforeExit(); process.exit(process.exitCode || 0); }
-  if (result.uncertain) return giveUp();
   if (!state.stopping) prompt();
 }
 
 // The prompt starts with the modes on in the selected tab: (watch network:off) pw>.
 function prompt(preserveCursor) {
+  if (!state.rl) return;
   const modes = state.page && !state.page.isClosed() ? activeModes(state.page) : [];
   state.rl.setPrompt(`${modes.length ? `(${modes.join(' ')}) ` : ''}${state.promptBase}`);
   state.rl.prompt(preserveCursor);
@@ -136,7 +136,7 @@ function submit(text) {
       if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
       out.log(`[server] ${text}`);
       // So the person at the prompt can bring an agent's command back with up-arrow.
-      if (state.rl.history && state.rl.history[0] !== text) {
+      if (state.rl?.history && state.rl.history[0] !== text) {
         state.rl.history.unshift(text);
         state.rl.history.length = Math.min(state.rl.history.length, 1000);
       }
@@ -160,4 +160,4 @@ function drained() {
   return queue;
 }
 
-module.exports = { enqueue, submit, giveUp, answerInterrupted, drained, busy };
+module.exports = { enqueue, submit, answerInterrupted, drained, busy };

package/lib/send.js

@@ -41,7 +41,7 @@ function fail(message) {
 // is unknown; ..."), so only a bare prompt counts. That also refuses while a
 // command runs or someone is typing.
 function paneProblem(session) {
-  if (!hasSession(session)) return `no tmux session '${session}'; ask the user before creating one (pw-repl skill: Start it)`;
+  if (!hasSession(session)) return `no tmux session '${session}' and no REPL server; pw-repl serve --background starts one (pw-repl skill: Start it)`;
   const running = tmux('display-message', '-p', '-t', session, '#{pane_current_command}').trim();
   if (running !== 'node') return `the REPL is not running in '${session}' (pane is running '${running}'); start it there with pw-repl run (pw-repl skill: Start it)`;
   const lines = tmux('capture-pane', '-t', session, '-p').split('\n').filter(line => line.trim());
@@ -101,7 +101,7 @@ async function send(options) {
   }
   if (answer.timeout) { console.error('completion not confirmed'); return 2; }
   if (answer.dropped) { console.error(`completion not confirmed: the REPL closed the connection (${answer.dropped})`); return 2; }
-  if (way.explicit) return fail(`cannot reach the REPL server at ${client.describe(way.endpoint)} (${answer.unreachable})`);
+  if (way.explicit) return fail(answer.unreachable === 'ENOENT' ? `no REPL is serving on ${client.describe(way.endpoint)} (there is no socket)` : `cannot reach the REPL server at ${client.describe(way.endpoint)} (${answer.unreachable})`);
   // The server was expected, so the REPL has most likely just exited or is
   // exiting. Falling back to tmux now could type into the shell it leaves behind.
   return fail(`the REPL server at ${way.socket} is not answering (${answer.unreachable}); not falling back to tmux. Check with pw-repl where; if the REPL now runs without the server, use -s or remove ${way.socket}`);
@@ -112,15 +112,25 @@ async function where(options) {
   const way = route(options);
   if (way.kind === 'server') {
     const name = client.describe(way.endpoint);
-    if (await client.health(way.endpoint, 5000)) { console.log(`server: ${name} (the REPL was started with pw-repl serve)`); return 0; }
-    console.error(`server: ${name} is not answering`);
+    if (await client.health(way.endpoint, 5000)) {
+      const background = require('./background').describeBackground(way.endpoint);
+      console.log(`server: ${name} (the REPL was started with pw-repl serve${background ? ' --background' : ''})`);
+      if (background) console.log(background);
+      return 0;
+    }
+    console.error(way.endpoint.socket && !fs.existsSync(way.endpoint.socket) ? `server: no REPL is serving on ${name} (there is no socket)` : `server: ${name} is not answering`);
     if (way.explicit) return 64;
   }
   const session = options.session || process.env.PW_TMUX_SESSION || 'playwright-repl';
-  if (!hasSession(session)) { console.error(`tmux: no session '${session}'`); return 64; }
+  if (!hasSession(session)) {
+    console.error(`tmux: no session '${session}'`);
+    console.error('A REPL on a socket of its own is found with -e <socket> or PW_SOCKET.');
+    return 64;
+  }
   const running = tmux('display-message', '-p', '-t', session, '#{pane_current_command}').trim();
   if (running === 'node') { console.log(`tmux: session '${session}' (the REPL was started with pw-repl run; no server)`); return 0; }
   console.error(`tmux: session '${session}' is running '${running}', not the REPL`);
+  console.error('A REPL on a socket of its own is found with -e <socket> or PW_SOCKET.');
   return 64;
 }
 

package/lib/server.js

@@ -47,9 +47,7 @@ function handle(req, res) {
     const result = await runner.submit(command.trim());
     if (!result.uncertain) return send(res, 200, { status: result.status, output: result.output });
     // unconfirmed: the command may or may not have done what it was sent to do.
-    if (result.interrupted) return send(res, 200, { status: result.status, output: result.output, unconfirmed: true });
-    send(res, 200, { status: result.status, output: `${result.output}\nBrowser command outcome is unknown; the REPL is disconnecting.`, unconfirmed: true });
-    runner.giveUp();
+    send(res, 200, { status: result.status, output: result.output, unconfirmed: true });
   });
 }
 

package/lib/start.js

@@ -3,7 +3,7 @@ const { chromium } = require('playwright-core');
 const readline = require('readline');
 const { state, withTimeout, shutdown, beforeExit } = require('./state');
 const out = require('./output');
-const { listTabs, watchPage, complete } = require('./commands');
+const { listTabs, openTab, watchPage, complete } = require('./commands');
 const runner = require('./runner');
 
 const CDP_URL = process.env.PW_CDP_URL || 'http://localhost:9222';
@@ -30,7 +30,8 @@ async function start(options) {
   const contexts = state.browser.contexts();
   const pages = contexts.flatMap(c => c.pages());
 
-  state.page = pages[0];
+  // Nothing is selected to begin with: the first tab may be someone else's.
+  state.page = null;
   state.tabListing = pages.slice();
 
   // Hooks first, so the start URL's own requests, logs and dialogs are recorded.
@@ -40,22 +41,27 @@ async function start(options) {
   }
 
   if (START_URL) {
-    if (!state.page) {
-      state.page = await contexts[0].newPage();
-    }
+    state.page = await openTab();
     await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
-    out.log(`Navigated to: ${state.page.url()}`);
-  }
-
-  if (!state.page) {
-    state.page = await (contexts[0] || await state.browser.newContext()).newPage();
-    out.log('Created new page');
+    out.log(`Opened ${state.page.url()} in a new tab`);
   }
 
   out.log('');
   await listTabs();
   out.log('');
+  if (!state.page) out.log('No tab is selected: tab new [url] opens one of your own, tab <index|url-part> selects one.');
   if (options.serve) await require('./server').serve(options.endpoint);
+  // In the background there is no prompt: commands come only through the server.
+  if (options.pidFile) {
+    require('./background').claimPidFile(options.pidFile);
+    out.onIdlePrint({ idle: () => !runner.busy() && !state.stopping, print: text => console.log(text) });
+    const e = require('./background').endpointFlag(options.endpoint);
+    out.log(`Running in the background: pw-repl attach${e} to use it, pw-repl stop${e} to stop it.`);
+    return;
+  }
+  if (!options.serve && !process.env.TMUX) {
+    out.log('Tip: run it in a tmux session named playwright-repl so pw-repl send can reach it, or use pw-repl serve.');
+  }
   out.log("Run 'help' to see the commands. They act on the selected tab (*).");
   out.log('');
 
@@ -89,19 +95,22 @@ async function start(options) {
     }
     runner.enqueue(line);
   });
+  // Input ends with Ctrl-D, or at once when nothing is attached to it (e.g.
+  // started in the background), so it says why it stops.
   rl.on('close', () => {
     if (state.stopping) return;
     endPromptLine();
+    out.error('Input ended; disconnecting.');
     runner.drained().then(() => shutdown(), () => shutdown())
       .then(() => process.exit(process.exitCode || 0));
   });
   rl.on('SIGINT', stop);
 }
 
-// Ctrl-C and Ctrl-D leave the cursor after the prompt; the shell's prompt
-// belongs on a line of its own.
+// Ctrl-C and Ctrl-D leave the cursor after the prompt; what follows belongs
+// on a line of its own.
 function endPromptLine() {
-  if (process.stdout.isTTY) process.stdout.write('\n');
+  process.stdout.write('\n');
 }
 
 // Like quit: a server command still running is answered before the REPL exits.

package/lib/syntax.js

@@ -0,0 +1,29 @@
+// How a command line's words are read, shared by the REPL and pw-repl send.
+
+// Commands whose first word is a selector, quoted if it has spaces, and whose
+// value is the rest of the line. Other commands take the rest of the line as it is.
+const SELECTOR_FIRST = new Set(['fill', 'type', 'select', 'press']);
+
+// A snapshot ref (e5, or f1e5 in newer Playwright) stands for aria-ref=e5.
+const REF = /^(?:f\d+)?e\d+$/;
+
+function toSelector(word) {
+  return REF.test(word) ? `aria-ref=${word}` : word;
+}
+
+// Quotes around the whole of a value are removed; \" inside double quotes is a quote.
+function unquote(text) {
+  const match = /^"((?:[^"\\]|\\.)*)"$|^'([^']*)'$/.exec(text);
+  if (!match) return text;
+  return match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2];
+}
+
+// The first word of args, or a quoted selector with spaces in it, and the rest of the line.
+function splitSelector(args) {
+  const match = /^(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+))(?:\s+([\s\S]*))?$/.exec((args || '').trim());
+  if (!match) return null;
+  const word = match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2] !== undefined ? match[2] : match[3];
+  return { word, selector: toSelector(word), rest: match[4] };
+}
+
+module.exports = { SELECTOR_FIRST, toSelector, unquote, splitSelector };

package/package.json

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

package/skill/SKILL.md

@@ -11,28 +11,42 @@ shared session: a person can have their own tabs open in it and be using it whil
 `pw-repl` below is the command the `pw-repl` npm package installs. Without a global install,
 `npx pw-repl` works the same; from a clone, `<clone>/bin/pw-repl.js`.
 
+## Arguments
+
+Freeform args describe what to do in the browser: a page to look at, a flow to try, a failure to
+reproduce (e.g. `pw-repl find out why the cart total shows 0 after adding an item`). They are the task;
+the sections below are how to carry it out. With no args, get a REPL running and ask what to do.
+
 ## Start it
 
-The REPL runs in the tmux session `playwright-repl`. Check it first:
+`pw-repl where` says whether a REPL is running and how `send` reaches it. There are three ways to run
+one; each takes an optional start URL, which opens in a new tab.
 
-```bash
-tmux capture-pane -t playwright-repl -p -S -5
-```
+- `pw-repl serve --background` runs it detached, with a command server on `/tmp/playwright-repl.sock`
+  (owner-only) and its output in `/tmp/playwright-repl.log`. `pw-repl attach` shows everything it does
+  and takes commands; `pw-repl stop` stops it.
+- `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
+  `pw[serve]>`.
+- `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
+  the tmux session `playwright-repl`:
 
-If the pane is at a shell prompt, start the REPL there. If there is no session, ask the user before
-creating one.
+  ```bash
+  tmux send-keys -t playwright-repl -l 'pw-repl run'
+  tmux send-keys -t playwright-repl Enter
+  ```
 
-```bash
-tmux send-keys -t playwright-repl -l 'pw-repl run'
-tmux send-keys -t playwright-repl Enter
-```
+`serve` and `serve --background` take a socket path of your own instead of the default
+(`pw-repl serve --background /tmp/mine.sock`); `send`, `attach`, `stop` and `where` then need
+`-e /tmp/mine.sock`, or `PW_SOCKET=/tmp/mine.sock`. The log of a background REPL is next to its socket
+(`/tmp/mine.log`); `tail -f` on it follows along without a terminal to attach from. `serve <port>`
+listens on TCP 127.0.0.1 instead of a socket, with no access control.
+
+Several REPLs can run at once, each on its own socket, e.g. one per agent. Each has its own selected tab,
+command queue and modes, so they do not wait on or select for each other. They share the browser,
+though: each sees every tab, `modes` lists only its own REPL's modes, and two REPLs acting on the same
+tab can undo each other's routes or network setting.
 
-`pw-repl serve` is the same plus a command server on `/tmp/playwright-repl.sock` (owner-only); its
-prompt is `pw[serve]>` instead of `pw>`. It is opt-in: use it when the user asks for it or agrees.
-Prefer the socket: `pw-repl serve <port>` (TCP on 127.0.0.1) has no authentication, so any local
-process could drive the browser; use it only for a client that cannot reach the socket. Both take an
-optional start URL, which navigates tab [0]. Stop either at the pane (`quit`, or Ctrl-C); `send quit` is
-refused so an agent cannot close a REPL the user is using.
+A REPL in a terminal stops at its prompt (`quit`, or Ctrl-C); `send quit` is refused.
 
 ## Send commands
 
@@ -41,29 +55,31 @@ pw-repl send tab
 pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
 ```
 
-Always send commands with `pw-repl send`; don't type into the pane yourself. Unquoted words are one
-command. It works however the REPL was started:
+Always send commands with `pw-repl send`; don't type into the pane yourself. The words after `send`
+are the command. For `fill`, `type`, `select` and `press`, a word quoted in your shell stays one word
+(`pw-repl send fill "text=Your name" Ada`); other commands get the words as they are
+(`pw-repl send eval "document.title + ' x'"`). It works however the REPL was started:
 
-- `run`: `send` types the command into the tmux pane and reads the result back off the screen. It
-  types only when the pane's last line is a bare prompt, so nothing lands in a shell or in the middle
-  of what the user is typing; while a command is running, the user is typing, or the REPL is exiting,
-  it refuses (exit 64). Wait and retry.
-- `serve`: `send` sends it over the socket and gets the output back as JSON. Same commands, more
-  reliable results: nothing is scraped, long output isn't cut off by scrollback, and a command can
-  never land in a shell. If you'll send many commands or read long output, ask the user whether to
-  restart the REPL with `pw-repl serve`.
+- `run` (in tmux): `send` types the command into the tmux pane and reads the result back off the screen.
+  It types only when the pane's last line is a bare prompt, so nothing lands in a shell or in the middle
+  of what the user is typing; while a command is running, the user is typing, or the REPL is exiting, it
+  refuses (exit 64). Wait and retry.
+- `serve`, in a terminal or in the background: `send` sends it over the socket and gets the output back
+  as JSON. Same commands, more reliable results: nothing is scraped, long output isn't cut off by
+  scrollback, and a command can never land in a shell.
 
 `pw-repl where` says which one a command would reach (the server, or the tmux pane running the
 REPL), or why neither is reachable, without running anything.
 
-Either way, every command you run and its output show in the pane (server commands as `[server]` lines),
-so the user sees what you do. The pane shows REPL commands only, not what the user clicked in the
-browser (unless `watch on --live` is on); for that, look at the browser itself: `tab` and `info` for
-where they are, `requests` for the requests their clicks made (`body <#>` for what one returned),
-`console` for console messages and page errors. When the user wants to show you what they do, `watch on`
-on their tab records each step with the requests it caused (`watch on --changes` adds what each step
-changed on the page); `watch` reads it back, and `watch new` only what it has not shown yet. Watching
-and reading are fine on the user's tabs; the rule below is about acting on them.
+Every command you run and its output show in the REPL's pane, or in `attach` and the log for a
+background REPL (server commands as `[server]` lines), so the user sees what you do. The pane shows REPL
+commands only, not what the user clicked in the browser (unless `watch on --live` is on); for that, look
+at the browser itself: `tab` and `info` for where they are, `requests` for the requests their clicks
+made (`body <#>` for what one returned), `console` for console messages and page errors. When the user
+wants to show you what they do, `watch on` on their tab records each step with the requests it caused
+(`watch on --changes` adds what each step changed on the page); `watch` reads it back, and `watch new`
+only what it has not shown yet. Watching and reading are fine on the user's tabs; the rule below is
+about acting on them.
 
 Exit status: `0` ok, `1` the command failed, `2` completion not confirmed (outcome unknown: do not
 blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --help` has the options.
@@ -71,14 +87,14 @@ 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 help is
-the command reference; this file does not repeat it.
+gives usage and caveats, and `help --all` prints everything at once. It needs no running REPL. The
+help is the command reference; this file does not repeat it.
 
 ## Shared-browser rules
 
 - Act only on tabs you opened (`tab new`), unless the user asks you to act on theirs (e.g. a `route` in
-  their tab while they test); then say what you are doing and undo it the moment you are done. The REPL
-  selects tab [0] at startup, and that tab may be the user's: run `tab` before acting. Closing your
+  their tab while they test); then say what you are doing and undo it the moment you are done. No tab
+  is selected when the REPL starts (unless it was given a start URL); `tab` lists them. Closing your
   tab goes back only to a tab you opened; otherwise no tab is selected. Tab numbers change when tabs
   open or close; `tab <url-part>` and `tab close <url-part>` pick a tab by its URL and refuse if it is
   ambiguous.