pw-repl 0.2.1 → 0.3.0

package/README.md

@@ -21,6 +21,21 @@ chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
 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`.
 
+**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.
+
+**Headless** works the same way:
+
+```bash
+chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-headless
+```
+
+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.
+
 ### 2. Install and start the REPL
 
 ```bash
@@ -51,18 +66,19 @@ Commands act on the selected tab (`tab` lists the tabs, with `*` on the selected
 
 ## Common tasks
 
-| I want to…                           | Commands                                                        |
-| ------------------------------------ | --------------------------------------------------------------- |
-| see where I am                       | `tab`, `info`                                                   |
-| see what is on the page              | `snapshot`, `screenshot`                                        |
-| do something on it                   | `click`, `fill`, `press`                                        |
-| see what the page requested          | `requests`, then `body <#>` for what one got back               |
-| see console messages and errors      | `console`                                                       |
-| show an agent what I do              | `watch on`, click around in the browser, then `watch`           |
-| see each step as I click             | `watch on --live`                                               |
-| record requests and console together | `capture on`, then `capture off`                                |
-| break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `network off` |
-| clean up                             | `modes off`                                                     |
+| I want to…                           | Commands                                                                              |
+| ------------------------------------ | ------------------------------------------------------------------------------------- |
+| see where I am                       | `tab`, `info`                                                                         |
+| see what is on the page              | `snapshot`, `screenshot`                                                              |
+| do something on it                   | `click`, `fill`, `press`                                                              |
+| see what the page requested          | `requests`, then `body <#>` for what one got back                                     |
+| see console messages and errors      | `console`                                                                             |
+| show an agent what I do              | `watch on`, click around in the browser, then `watch`                                 |
+| see each step as I click             | `watch on --live`                                                                     |
+| record requests and console together | `capture on`, then `capture off`                                                      |
+| break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `route <glob> abort`, `network off` |
+| change or slow an API response       | `route <glob> patch <json>`, `route <glob> delay <secs>`                              |
+| clean up                             | `modes off`                                                                           |
 
 Everything else is in `help <topic>`; `help <command>` has usage and caveats.
 

package/bin/pw-repl.js

@@ -4,10 +4,10 @@
 const { looksLikeEndpoint } = require('../lib/client');
 
 const USAGE = `Usage:
-  pw-repl run [start-url]
+  pw-repl run [--launch [--headed]] [start-url] [-- <chromium flags>]
       connect to the browser and open the prompt
 
-  pw-repl serve [--background] [endpoint] [start-url]
+  pw-repl serve [--background] [--launch [--headed]] [endpoint] [start-url] [-- <chromium flags>]
       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
 
@@ -37,6 +37,11 @@ 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.
+
 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).
@@ -73,15 +78,23 @@ function parseSendArgs(args, allowCommand) {
   // 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;
+  // An empty word (fill #name "") is the empty value.
+  const quoted = requote ? words.map(w => (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, 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); }
+  const options = { serve, endpoint: null, startUrl: null, background: false, launch: false, headed: false, chromeArgs: [], pidFile: process.env.PW_REPL_PID_FILE || null };
+  // Whatever follows -- is for the Chromium that --launch starts.
+  const split = args.indexOf('--');
+  const rest = split === -1 ? [...args] : args.slice(0, split);
+  if (split !== -1) options.chromeArgs = args.slice(split + 1);
+  const flag = name => { const i = rest.indexOf(name); if (i === -1) return false; rest.splice(i, 1); return true; };
+  if (serve) options.background = flag('--background');
+  options.launch = flag('--launch');
+  options.headed = flag('--headed');
+  if ((options.headed || options.chromeArgs.length) && !options.launch) usage();
   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;
@@ -119,7 +132,8 @@ async function main() {
     case 'stop': {
       const options = parseSendArgs(args, false);
       if (options.session) usage();
-      const endpoint = options.endpoint || process.env.PW_ENDPOINT || null;
+      // The same socket send would use when there is no -e: PW_ENDPOINT, then PW_SOCKET.
+      const endpoint = options.endpoint || process.env.PW_ENDPOINT || process.env.PW_SOCKET || null;
       process.exit(await require('../lib/background')[subcommand]({ endpoint }));
     }
     // falls through never: process.exit above

package/lib/background.js

@@ -64,7 +64,9 @@ async function start(options) {
   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 args = [BIN, 'serve', ...(options.launch ? ['--launch'] : []), ...(options.headed ? ['--headed'] : []),
+    ...(options.endpoint ? [options.endpoint] : []), ...(options.startUrl ? [options.startUrl] : []),
+    ...(options.chromeArgs.length ? ['--', ...options.chromeArgs] : [])];
   const child = spawn(process.execPath, args, {
     detached: true,
     stdio: ['ignore', log, log],
@@ -79,7 +81,7 @@ async function start(options) {
   }
   if (exited || !runningPid(pidFile)) {
     if (!exited) child.kill();
-    const last = tail(logFile, 10);
+    const last = tail(logFile, 12);
     return fail(`the background REPL did not start${last ? `; the end of ${logFile}:\n${last}` : ''}`);
   }
   child.unref();
@@ -103,7 +105,7 @@ async function stop(options) {
   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}`);
+  console.log(`Stopped the background REPL (pid ${pid}) on ${client.describe(endpoint)}; its log stays at ${filesFor(endpoint).logFile}`);
   return 0;
 }
 

package/lib/client.js

@@ -32,17 +32,27 @@ function target(endpoint) {
 }
 
 // GET /health: does not go through the command queue or show in the pane.
-function health(endpoint, timeoutMs) {
+// Resolves to what the REPL says about itself (e.g. its browser), or null.
+function healthInfo(endpoint, timeoutMs) {
   return new Promise(resolve => {
     const req = http.get({ ...target(endpoint), path: '/health', timeout: timeoutMs }, res => {
-      res.resume();
-      resolve(res.statusCode === 200);
+      let text = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { text += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) return resolve(null);
+        try { resolve(JSON.parse(text)); } catch { resolve({}); }
+      });
     });
-    req.on('timeout', () => { req.destroy(); resolve(false); });
-    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.on('error', () => resolve(null));
   });
 }
 
+async function health(endpoint, timeoutMs) {
+  return (await healthInfo(endpoint, timeoutMs)) !== null;
+}
+
 // 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).
@@ -75,4 +85,4 @@ function request(endpoint, command, timeoutMs) {
   });
 }
 
-module.exports = { DEFAULT_SOCKET, parseEndpoint, looksLikeEndpoint, describe, health, request };
+module.exports = { DEFAULT_SOCKET, parseEndpoint, looksLikeEndpoint, describe, health, healthInfo, request };

package/lib/commands.js

@@ -97,13 +97,66 @@ function hints(pairs) {
 
 const dialogPages = new WeakSet();
 
+// page -> its open dialog. The page, and every command that reads it, waits
+// until the dialog is answered, in the browser or with the dialog command.
+const openDialogs = new Map();
+
 function ensureDialogHandler(p) {
   if (dialogPages.has(p)) return;
   dialogPages.add(p);
   p.on('dialog', dialog => {
+    openDialogs.set(p, dialog);
     out.notice(`Dialog [${dialog.type()}]: ${String(dialog.message()).slice(0, OUTPUT_LIMIT)}`);
-    out.notice('Handle this dialog in the browser window; the triggering command is waiting.');
+    out.notice('It waits to be answered in the browser, or with dialog accept [text] | dialog dismiss; until then the page, and commands that read it, wait too.');
   });
+  p.on('close', () => openDialogs.delete(p));
+}
+
+// Runs ahead of the command queue (see runner.js), so it still works while
+// commands wait on the dialog; it returns its output rather than printing it.
+async function dialogCommand(args) {
+  const [action, ...rest] = (args || '').trim().split(/\s+/).filter(Boolean);
+  const pages = state.browser.contexts().flatMap(c => c.pages());
+  for (const p of openDialogs.keys()) if (p.isClosed() || !pages.includes(p)) openDialogs.delete(p);
+  const describe = (p, d) => `[${pages.indexOf(p)}] ${p.url()}: ${d.type()} ${JSON.stringify(String(d.message()).slice(0, 200))}`;
+  if (!action) {
+    if (!openDialogs.size) return 'No dialog is open.';
+    return [...[...openDialogs].map(([p, d]) => describe(p, d)), hints([['dialog accept [text]', 'accept it (text answers a prompt)'], ['dialog dismiss', 'dismiss it']])].join('\n');
+  }
+  if (action !== 'accept' && action !== 'dismiss') throw new Error('Usage: dialog [accept [text] | dismiss]');
+  // The selected tab's dialog, or the only one open.
+  const page = openDialogs.has(state.page) ? state.page : openDialogs.size === 1 ? [...openDialogs.keys()][0] : null;
+  if (!page) throw new Error(openDialogs.size ? 'Several tabs have a dialog open; select one with tab <index|url-part> first' : 'No dialog is open.');
+  const dialog = openDialogs.get(page);
+  openDialogs.delete(page);
+  const line = describe(page, dialog);
+  try {
+    if (action === 'accept') await dialog.accept(rest.length ? unquote(rest.join(' ')) : undefined);
+    else await dialog.dismiss();
+  } catch (error) {
+    // Answered in the browser meanwhile.
+    return `No dialog is open (${error.message.split('\n')[0]})`;
+  }
+  return `${action === 'accept' ? 'Accepted' : 'Dismissed'}: ${line}`;
+}
+
+// A tab in a browser the REPL connected to has no viewport set, so its size is
+// the window's; it is read from the page.
+async function viewportText() {
+  const set = state.page.viewportSize();
+  if (set) return `${set.width}x${set.height} (set with viewport)`;
+  const size = await state.page.evaluate(() => `${innerWidth}x${innerHeight}`).catch(() => null);
+  return size ? `${size} (the window's size)` : 'unknown';
+}
+
+// A page restored from the back/forward cache never fires its load events
+// again, so back and forward wait only for the navigation, then briefly for
+// the page, rather than time out on a page that is already there.
+async function historyStep(go, direction) {
+  const before = state.page.url();
+  const response = await go();
+  if (response === null && state.page.url() === before) throw new Error(`No page to go ${direction} to`);
+  await state.page.waitForLoadState('domcontentloaded', { timeout: 3000 }).catch(() => {});
 }
 
 const SCREENSHOT_DELAY_MAX = 60;
@@ -144,23 +197,108 @@ function routesFor(p) {
   return pageRoutes.get(p);
 }
 
+const ROUTE_DELAY_MAX = 120;
+
+// Marks a request a route answered, now: the browser reports it finished only later.
+function markChanged(req, status, how) {
+  changedRequests.set(req, how);
+  const entry = requestEntries.get(req);
+  if (entry) { entry.status = `${status} ${how}`; entry.ms = Date.now() - entry.t; }
+}
+
+// A JSON Merge Patch (RFC 7386): objects merge, null removes a key, anything else replaces.
+function mergePatch(target, patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return patch;
+  const result = target && typeof target === 'object' && !Array.isArray(target) ? { ...target } : {};
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) delete result[key];
+    else result[key] = mergePatch(result[key], value);
+  }
+  return result;
+}
+
+function parseJson(text, what) {
+  try { return JSON.parse(text); } catch (error) { throw new Error(`${what} is not valid JSON: ${error.message}`); }
+}
+
+// How a route treats the requests it matches: its text for listing, and what it does to each one.
+function routeKind(how, rest, usage) {
+  if (/^\d{3}$/.test(how)) {
+    const status = Number(how);
+    if (status < 200 || status > 599) throw new Error('Status must be from 200 to 599');
+    if (!rest) throw new Error(usage);
+    parseJson(rest, 'Body');
+    const preview = rest.length > ROUTE_PREVIEW ? `${rest.slice(0, ROUTE_PREVIEW)}…` : rest;
+    return {
+      text: `${status} ${preview}`,
+      async handle(r, req, tag) {
+        markChanged(req, status, 'faked');
+        await r.fulfill({ status, contentType: 'application/json', body: rest });
+        out.notice(`Faked: ${tag()} -> ${status}`);
+      },
+    };
+  }
+  if (how === 'patch') {
+    if (!rest) throw new Error(usage);
+    const patch = parseJson(rest, 'Patch');
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('Patch must be a JSON object, e.g. {"total": 0}');
+    return {
+      text: `patch ${rest.length > ROUTE_PREVIEW ? `${rest.slice(0, ROUTE_PREVIEW)}…` : rest}`,
+      async handle(r, req, tag) {
+        const response = await r.fetch();
+        let body;
+        try { body = await response.json(); } catch {
+          await r.fulfill({ response });
+          out.notice(`Not patched: ${tag()} — its response is not JSON, so it went through unchanged`);
+          return;
+        }
+        markChanged(req, response.status(), 'patched');
+        await r.fulfill({ response, json: mergePatch(body, patch) });
+        out.notice(`Patched: ${tag()} -> ${response.status()}`);
+      },
+    };
+  }
+  if (how === 'delay') {
+    const seconds = Number(rest);
+    if (!/^\d+(?:\.\d+)?$/.test(rest || '') || seconds <= 0 || seconds > ROUTE_DELAY_MAX) throw new Error(`Usage: route <url-glob> delay <seconds> (up to ${ROUTE_DELAY_MAX})`);
+    return {
+      text: `delay ${seconds}s`,
+      async handle(r, req, tag) {
+        await new Promise(resolve => setTimeout(resolve, seconds * 1000));
+        await r.continue();
+        out.notice(`Delayed ${seconds}s: ${tag()}`);
+      },
+    };
+  }
+  if (how === 'abort' && !rest) {
+    return {
+      text: 'abort',
+      async handle(r, req, tag) {
+        await r.abort('failed');
+        out.notice(`Aborted: ${tag()}`);
+      },
+    };
+  }
+  throw new Error(usage);
+}
+
 function listRoutes() {
   const routes = routesFor(state.page);
+  const forms = [
+    ['route <url-glob> <status> <json-body>', 'answer it with this status and JSON'],
+    ['route <url-glob> patch <json>', 'let it through, then change its JSON'],
+    ['route <url-glob> delay <seconds>', 'hold it, then let it through'],
+    ['route <url-glob> abort', 'fail it as if the connection broke'],
+  ];
   if (!routes.size) {
-    out.log('No fake responses on the selected tab.');
-    out.log(hints([['route <url-glob> <status> <json-body>', 'add one']]));
+    out.log('No routes on the selected tab.');
+    out.log(hints(forms));
     return;
   }
-  out.log(`Fake responses on the selected tab (${routes.size}):`);
+  out.log(`Routes on the selected tab (${routes.size}):`);
   const width = Math.max(...[...routes.keys()].map(glob => glob.length));
-  for (const [glob, { status, body }] of routes) {
-    const preview = body.length > ROUTE_PREVIEW ? `${body.slice(0, ROUTE_PREVIEW)}…` : body;
-    out.log(`  ${glob.padEnd(width)}  ${status}  ${preview}`);
-  }
-  out.log(hints([
-    ['route <url-glob> <status> <json-body>', 'add one, or replace the one for that glob'],
-    ['route off <url-glob> | route off --all', 'remove'],
-  ]));
+  for (const [glob, { text }] of routes) out.log(`  ${glob.padEnd(width)}  ${text}`);
+  out.log(hints([...forms, ['route off <url-glob> | route off --all', 'remove']]));
 }
 
 async function removeRoutes(glob) {
@@ -169,7 +307,7 @@ async function removeRoutes(glob) {
   if (glob !== '--all' && !routes.has(glob)) throw new Error(`No route for ${glob} on the selected tab`);
   const removed = await unroute(state.page, glob === '--all' ? [...routes.keys()] : [glob]);
   for (const g of removed) out.log(`Removed: ${g}`);
-  if (!removed.length) out.log('No fake responses on the selected tab');
+  if (!removed.length) out.log('No routes on the selected tab');
 }
 
 async function unroute(p, globs) {
@@ -193,7 +331,8 @@ const BODY_TIMEOUT = 15000;
 const RECENT_HIDDEN_TYPES = new Set(['image', 'font', 'stylesheet', 'media']);
 const recentLogs = new WeakMap();
 const consoleLogs = new WeakMap();
-const fakedRequests = new WeakSet();
+// request -> how a route changed it (faked or patched), shown after its status.
+const changedRequests = new WeakMap();
 const requestEntries = new WeakMap();
 // Tabs this REPL opened with tab new.
 const openedTabs = new WeakSet();
@@ -240,7 +379,7 @@ function ensureRecentLog(p) {
       res = await req.response();
       if (res) status = String(res.status());
     } catch {}
-    finish(req, fakedRequests.has(req) ? `${status} faked` : status, res);
+    finish(req, changedRequests.has(req) ? `${status} ${changedRequests.get(req)}` : 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(consoleText(msg)) }));
@@ -300,16 +439,24 @@ const WATCH_SCRIPT = `(() => {
   // An element holding an editable area would be named partly by what was typed there.
   const hasEditable = el => !!el.querySelector('[contenteditable]:not([contenteditable=false])');
   const clip = text => (text || '').replace(/\\s+/g, ' ').trim().slice(0, 60);
+  // A label's own words, without the options or values of the controls inside it.
+  const labelText = label => {
+    const copy = label.cloneNode(true);
+    copy.querySelectorAll('select,textarea,input,button').forEach(n => n.remove());
+    return copy.textContent;
+  };
   const nameOf = el => {
     const labelledBy = el.getAttribute('aria-labelledby');
     const byId = labelledBy && labelledBy.split(/\\s+/).map(id => document.getElementById(id)?.innerText).join(' ');
     const label = (el.id && document.querySelector('label[for="' + CSS.escape(el.id) + '"]')) || el.closest('label');
-    return clip(el.getAttribute('aria-label') || byId || (label && label !== el && label.innerText) || el.getAttribute('alt')
+    return clip(el.getAttribute('aria-label') || byId || (label && label !== el && labelText(label)) || el.getAttribute('alt')
       || el.getAttribute('placeholder') || el.getAttribute('title') || (typedInto(el) || hasEditable(el) ? '' : el.innerText));
   };
   const describe = el => { const name = nameOf(el); return roleOf(el) + (name ? ' ' + JSON.stringify(name) : ''); };
   // el null: the page itself, e.g. Escape with nothing focused.
   const send = (action, el, extra, since) => {
+    // Typing still waiting for its pause is recorded first, so the steps stay in order.
+    if (action !== 'type') for (const field of [...pending.keys()]) flushTyping(field);
     if (typeof window.__pwReplWatch === 'function') window.__pwReplWatch({ action, target: el ? describe(el) : 'page', extra: extra || '', since: since || 0 });
   };
   document.addEventListener('click', e => {
@@ -925,18 +1072,20 @@ const commands = {
   async goto(args) {
     if (!args) throw new Error('Usage: goto <url>');
     let url = args;
-    if (!/^[a-z][a-z\d+.-]*:\/\//i.test(url) && !/^(about|data|file|javascript):/i.test(url)) url = 'https://' + url;
+    // As a browser's address bar does: a local dev server is almost always plain http.
+    const local = /^(?:localhost|127(?:\.\d+){3}|\[::1\]|0\.0\.0\.0)(?:[:/?#]|$)/i.test(url);
+    if (!/^[a-z][a-z\d+.-]*:\/\//i.test(url) && !/^(about|data|file|javascript):/i.test(url)) url = `${local ? 'http' : 'https'}://${url}`;
     await state.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 });
     out.log(`${state.page.url()} — ${await state.page.title()}`);
   },
 
   async back() {
-    await state.page.goBack({ waitUntil: 'domcontentloaded', timeout: 10000 });
+    await historyStep(() => state.page.goBack({ waitUntil: 'commit', timeout: 10000 }), 'back');
     out.log(`Back to: ${state.page.url()}`);
   },
 
   async forward() {
-    await state.page.goForward({ waitUntil: 'domcontentloaded', timeout: 10000 });
+    await historyStep(() => state.page.goForward({ waitUntil: 'commit', timeout: 10000 }), 'forward');
     out.log(`Forward to: ${state.page.url()}`);
   },
 
@@ -948,8 +1097,7 @@ const commands = {
   async info() {
     out.log(`  URL:   ${state.page.url()}`);
     out.log(`  Title: ${await state.page.title()}`);
-    const vp = state.page.viewportSize();
-    if (vp) out.log(`  Viewport: ${vp.width}x${vp.height}`);
+    out.log(`  Viewport: ${await viewportText()}`);
   },
 
   async click(args) {
@@ -978,7 +1126,21 @@ const commands = {
 
   async type(args) {
     const { selector, value, shown } = selectorAndValue(args, 'type <selector> <text>', 'type #search garden hose');
-    await onElement(selector, () => state.page.type(selector, value, { timeout: 5000 }));
+    // Typed after what the field already holds, as someone clicking into it
+    // at the end would; focusing it alone leaves the caret at the start.
+    await onElement(selector, () => state.page.locator(selector).first().evaluate(el => {
+      el.focus();
+      if (typeof el.value === 'string' && typeof el.setSelectionRange === 'function') {
+        try { el.setSelectionRange(el.value.length, el.value.length); } catch {}
+      } else if (el.isContentEditable) {
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        range.collapse(false);
+        getSelection().removeAllRanges();
+        getSelection().addRange(range);
+      }
+    }, null, { timeout: 5000 }));
+    await state.page.keyboard.type(value);
     out.log(`Typed into: ${shown}`);
   },
 
@@ -1033,6 +1195,36 @@ const commands = {
     printOutput(result, all);
   },
 
+  // The page's own event listeners on an element, which only DevTools can
+  // list: the element is handed to a CDP session through the page, so any
+  // Playwright selector works, and the session asks for its listeners.
+  async listeners(args, all) {
+    const text = (args || '').trim();
+    const usage = 'listeners <selector> | listeners document | listeners window';
+    if (!text) throw new Error(`Usage: ${usage}`);
+    const which = text === 'document' || text === 'window' ? text : null;
+    const selector = which ? null : soleSelector(args, usage);
+    if (selector) await onElement(selector, () => state.page.locator(selector).first().evaluate(el => { window.__pwReplListenersOf = el; }, null, { timeout: 5000 }));
+    const cdp = await state.page.context().newCDPSession(state.page);
+    try {
+      // Chrome includes each handler's source only for an object in a named group.
+      const { result } = await cdp.send('Runtime.evaluate', { expression: which || 'window.__pwReplListenersOf', objectGroup: 'pw-repl-listeners' });
+      if (!result.objectId) throw new Error(`No element matches ${text}`);
+      const { listeners } = await cdp.send('DOMDebugger.getEventListeners', { objectId: result.objectId });
+      if (!listeners.length) { out.log(`No event listeners on ${text}`); return; }
+      const lines = listeners.map(l => {
+        const how = [l.useCapture && 'capture', l.once && 'once', l.passive && 'passive'].filter(Boolean).join(', ');
+        const handler = (l.handler?.description || '').replace(/\s+/g, ' ').slice(0, 100);
+        return `${l.type}${how ? ` (${how})` : ''}: ${handler} (line ${l.lineNumber + 1})`;
+      });
+      printOutput(lines.join('\n'), all);
+    } finally {
+      await cdp.send('Runtime.evaluate', { expression: 'delete window.__pwReplListenersOf' }).catch(() => {});
+      await cdp.send('Runtime.releaseObjectGroup', { objectGroup: 'pw-repl-listeners' }).catch(() => {});
+      await cdp.detach().catch(() => {});
+    }
+  },
+
   async count(args) {
     const selector = soleSelector(args, 'count <selector>');
     const els = await state.page.$$(selector);
@@ -1126,7 +1318,7 @@ const commands = {
     // Playwright's labels are e5, or frame-prefixed like f1e5 in newer versions.
     const selector = toSelector(rest);
     const target = selector ? state.page.locator(selector).first() : state.page;
-    const raw = await target.ariaSnapshot({ mode: 'ai', timeout: 5000 });
+    const raw = selector ? await onElement(selector, () => target.ariaSnapshot({ mode: 'ai', timeout: 5000 })) : await target.ariaSnapshot({ mode: 'ai', timeout: 5000 });
     const text = full ? raw : compactSnapshot(raw);
     if (needle !== null) {
       const hits = grepSnapshot(text, needle);
@@ -1139,11 +1331,7 @@ const commands = {
   },
 
   async viewport(args) {
-    if (!args) {
-      const vp = state.page.viewportSize();
-      out.log(vp ? `${vp.width}x${vp.height}` : 'No viewport set');
-      return;
-    }
+    if (!args) { out.log(await viewportText()); return; }
     const [w, h] = args.split('x').map(Number);
     if (!w || !h) throw new Error('Usage: viewport <width>x<height>');
     await state.page.setViewportSize({ width: w, height: h });
@@ -1206,35 +1394,28 @@ const commands = {
     if (!trimmed) return listRoutes();
     const off = /^off(?:\s+(\S+))?$/.exec(trimmed);
     if (off) return removeRoutes(off[1]);
-    const match = /^(\S+)\s+(\d{3})\s+([\s\S]+)$/.exec(trimmed);
-    if (!match) throw new Error('Usage: route <url-glob> <status> <json-body> | route off <url-glob>|--all');
-    const [, glob, statusText, body] = match;
-    const status = Number(statusText);
-    if (status < 200 || status > 599) throw new Error('Status must be from 200 to 599');
-    try { JSON.parse(body); } catch (error) { throw new Error(`Body is not valid JSON: ${error.message}`); }
+    const usage = 'Usage: route <url-glob> <status> <json-body> | route <url-glob> patch <json> | route <url-glob> delay <seconds> | route <url-glob> abort | route off <url-glob>|--all';
+    const match = /^(\S+)\s+(\S+)(?:\s+([\s\S]+))?$/.exec(trimmed);
+    if (!match) throw new Error(usage);
+    const [, glob, how, rest] = match;
+    const route = routeKind(how, rest, usage);
     const routes = routesFor(state.page);
     const previous = routes.get(glob);
     if (previous) await state.page.unroute(glob, previous.handler);
     const handler = async r => {
       const req = r.request();
-      fakedRequests.add(req);
+      const tag = () => { const id = requestEntries.get(req)?.id; return `${id ? `#${id} ` : ''}${req.method()} ${req.url()}`; };
       try {
-        await r.fulfill({ status, contentType: 'application/json', body });
-        // Recorded now: the browser reports the request finished only later.
-        const entry = requestEntries.get(req);
-        if (entry) { entry.status = `${status} faked`; entry.ms = Date.now() - entry.t; }
-        const id = entry?.id;
-        out.notice(`Faked: ${id ? `#${id} ` : ''}${req.method()} ${req.url()} -> ${status}`);
+        await route.handle(r, req, tag);
       } catch (error) {
-        // Aborted, never continued: a request meant to be faked must not reach the network.
+        // Aborted, never continued: a request meant to be changed must not reach the page as it was.
         await r.abort().catch(() => {});
-        const id = requestEntries.get(req)?.id;
-        out.notice(`Fake failed: ${id ? `#${id} ` : ''}${req.method()} ${req.url()} — ${error.message}; the request was aborted`);
+        out.notice(`Route failed: ${tag()} — ${error.message}; the request was aborted`);
       }
     };
     await state.page.route(glob, handler);
-    routes.set(glob, { status, body, handler });
-    out.log(`${previous ? 'Replaced' : 'Routed'}: ${glob} -> ${status}`);
+    routes.set(glob, { text: route.text, handler });
+    out.log(`${previous ? 'Replaced' : 'Routed'}: ${glob} -> ${route.text}`);
   },
 
   async requests(args) {
@@ -1268,7 +1449,7 @@ const commands = {
     const entry = (recentLogs.get(state.page) || []).find(e => e.id === id);
     if (!entry) throw new Error(`No request #${id} on the selected tab; requests lists them`);
     // A fake is marked answered before the browser hands over its response.
-    for (let waited = 0; !entry.response && /faked$/.test(entry.status) && waited < 2000; waited += 50) {
+    for (let waited = 0; !entry.response && /(?:faked|patched)$/.test(entry.status) && waited < 2000; waited += 50) {
       await new Promise(resolve => setTimeout(resolve, 50));
     }
     if (!entry.response) throw new Error(`#${id} has no response${entry.status === 'pending' ? ' yet' : ` (${entry.status})`}`);
@@ -1414,6 +1595,10 @@ const commands = {
     out.log(hints([['capture on [requests|console] [seconds]', 'record the selected tab\'s requests and console messages in time order']]));
   },
 
+  async dialog(args) {
+    out.log(await dialogCommand(args));
+  },
+
   async modes(args) {
     const arg = (args || '').trim();
     if (!arg) return listModes();
@@ -1459,6 +1644,7 @@ function complete(line) {
     if (command === 'tab') return match(['new', 'close']);
     if (command === 'network') return match(['on', 'off']);
     if (command === 'modes') return match(['off']);
+    if (command === 'dialog') return match(['accept', 'dismiss']);
     if (command === 'watch') return match(['on', 'off', 'new', '--all']);
     if (command === 'capture') return match(['on', 'off']);
     if (command === 'route') return match(['off']);
@@ -1469,4 +1655,4 @@ function complete(line) {
   return [[], current];
 }
 
-module.exports = { commands, listTabs, openTab, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };
+module.exports = { commands, dialogCommand, listTabs, openTab, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };

package/lib/help.js

@@ -15,7 +15,8 @@ Common tasks:
   show an agent what I do           watch on, click around, then watch
   see each step as I click          watch on --live
   requests and console together     capture on, then capture off
-  break the backend on purpose      route <glob> <status> <json>, network off
+  break the backend on purpose      route <glob> <status> <json>, route <glob> abort, network off
+  change or slow an API response    route <glob> patch <json>, route <glob> delay <secs>
   clean up                          modes off
 
 Modes (watch, capture, route, network off) stay on until turned off; the prompt shows the selected tab's:
@@ -40,7 +41,7 @@ const TOPICS = {
   },
   inspect: {
     intro: 'Output is capped; put --all right after the command for everything (e.g. text --all body).',
-    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'wait', 'sleep'],
+    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'wait', 'sleep'],
   },
   network: {
     intro: 'requests and console record all the time; a capture records only while it runs.',
@@ -63,8 +64,8 @@ selected tab, if any: (watch network:off routes:2 capture) pw>. modes lists them
 
 Times (requests, console, watch) are local, with their UTC offset: 18:16:15.721-06:00.
 
-Dialogs are reported and never answered automatically.`,
-    commands: ['modes', 'help', 'quit'],
+Dialogs are reported and never answered on their own; dialog answers one.`,
+    commands: ['modes', 'dialog', 'help', 'quit'],
   },
 };
 
@@ -74,7 +75,11 @@ const COMMANDS = {
     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 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' },
+  goto: {
+    usage: 'goto <url>',
+    summary: 'navigate the selected tab',
+    detail: 'Without a scheme, http:// is assumed for localhost, 127.x and [::1], and https:// otherwise, as in\nthe address bar. tab new <url> reads its URL the same way.',
+  },
   back: { usage: 'back', summary: 'go back one history entry' },
   forward: { usage: 'forward', summary: 'go forward one history entry' },
   reload: { usage: 'reload', summary: 'reload the selected tab' },
@@ -87,7 +92,7 @@ const COMMANDS = {
     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' },
+  type: { usage: 'type <selector> <text>', summary: 'type key by key after what the field holds; text 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' },
@@ -105,6 +110,11 @@ const COMMANDS = {
   text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
   html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match' },
   attrs: { usage: 'attrs [--all] <selector>', summary: 'attributes of the first match' },
+  listeners: {
+    usage: 'listeners <selector>|document|window',
+    summary: 'the page\'s event listeners on an element',
+    detail: 'One line each: the event, how it was added (capture, once, passive), the start of the handler and\nits line in its script. Listeners added on a parent (e.g. document, for delegation) are not the\nelement\'s own: check listeners document too.',
+  },
   count: { usage: 'count <selector>', summary: 'number of matches' },
   visible: { usage: 'visible <selector>', summary: 'whether the first match is visible' },
   links: { usage: 'links [--all]', summary: 'links on the page (text and href)' },
@@ -142,9 +152,9 @@ const COMMANDS = {
     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; 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"}}',
+    usage: 'route <glob> <how> | off <glob>|--all',
+    summary: 'fake, patch, delay or fail the selected tab\'s matching requests',
+    detail: 'route <glob> <status> <json>  answer with this status (200-599) and JSON; it never reaches the network,\n                              so it still answers while the network is off\nroute <glob> patch <json>     let it through, then change its JSON response: a JSON Merge Patch, where\n                              objects merge, null removes a key and anything else replaces\nroute <glob> delay <secs>     hold it for up to 120 seconds, then let it through\nroute <glob> abort            fail it as if the connection broke\n\nEach matching request prints a line (Faked:, Patched:, Delayed:, Aborted:) in the REPL window, and in\nthe answer to a command running then, with its number as in requests; requests shows a fake as\n<status> faked and a patch as <status> patched. If a route fails it prints "Route failed" and aborts\nthe request.\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/cart patch {"total": 0}',
   },
   network: {
     usage: 'network [on|off]',
@@ -168,6 +178,11 @@ const COMMANDS = {
     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 <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.',
   },
+  dialog: {
+    usage: 'dialog [accept [text] | dismiss]',
+    summary: 'show, accept or dismiss an open alert, confirm or prompt',
+    detail: 'While a dialog is open, its page and the commands that read it wait. dialog runs at once, ahead\nof them; it answers the selected tab\'s dialog, or the only one open. accept text answers a prompt.\n\nWith nobody at the browser (e.g. headless), it is the only way to answer one.',
+  },
   help: { usage: 'help [topic | command | --all]', summary: 'this help; --all prints every topic and command in full' },
   quit: {
     usage: 'quit',

package/lib/launch.js

@@ -0,0 +1,115 @@
+// pw-repl run|serve --launch: a Chromium of the REPL's own, started for it and
+// stopped with it, in a profile that is removed afterwards. It is the quick
+// start; a browser set up any other way is reached with PW_CDP_URL instead.
+const { spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const START_TIMEOUT = 20000;
+const STOP_TIMEOUT = 5000;
+const INSTALL = 'npx playwright-core install chromium';
+const ON_PATH = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome', 'microsoft-edge'];
+const MAC_APPS = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+];
+
+// PW_CHROME, then Playwright's own Chromium (wherever PLAYWRIGHT_BROWSERS_PATH
+// puts it), then any other revision of it, then a Chromium on the PATH.
+function findChrome() {
+  if (process.env.PW_CHROME) return process.env.PW_CHROME;
+  try {
+    const bundled = require('playwright-core').chromium.executablePath();
+    if (fs.existsSync(bundled)) return bundled;
+  } catch {}
+  // Any Chromium works over CDP, so a revision other than this Playwright's is fine.
+  const dir = process.env.PLAYWRIGHT_BROWSERS_PATH || path.join(os.homedir(), '.cache', 'ms-playwright');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter(n => /^chromium-\d+$/.test(n)).sort().reverse(); } catch {}
+  for (const name of names) {
+    for (const sub of ['chrome-linux64/chrome', 'chrome-linux/chrome', 'chrome-mac/Chromium.app/Contents/MacOS/Chromium']) {
+      const candidate = path.join(dir, name, sub);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  for (const folder of (process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    for (const name of ON_PATH) {
+      const candidate = path.join(folder, name);
+      try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch {}
+    }
+  }
+  return MAC_APPS.find(app => fs.existsSync(app)) || null;
+}
+
+// Containers often give /dev/shm too little room, and Chromium's tabs then crash.
+function smallShm() {
+  try { const shm = fs.statfsSync('/dev/shm'); return shm.blocks * shm.bsize < 1024 ** 3; } catch { return false; }
+}
+
+// Starts it and waits for the port it picked, which it writes into its profile.
+function start(exe, args, profile) {
+  return new Promise(resolve => {
+    // Its own process group, so stopping it also stops the helper processes it starts.
+    const proc = spawn(exe, args, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+    let stderr = '';
+    let settled = false;
+    const done = result => { if (!settled) { settled = true; clearInterval(poll); clearTimeout(timer); resolve(result); } };
+    proc.stderr.on('data', d => { if (stderr.length < 20000) stderr += d; });
+    proc.on('error', error => done({ error: error.message, stderr }));
+    proc.on('exit', code => done({ error: `it exited with code ${code}`, stderr }));
+    const portFile = path.join(profile, 'DevToolsActivePort');
+    const poll = setInterval(() => {
+      try { const port = fs.readFileSync(portFile, 'utf8').split('\n')[0].trim(); if (port) done({ proc, port }); } catch {}
+    }, 100);
+    const timer = setTimeout(() => { proc.kill('SIGKILL'); done({ error: `no debugging port within ${START_TIMEOUT / 1000}s`, stderr }); }, START_TIMEOUT);
+  });
+}
+
+function quoted(args) {
+  return args.map(a => (/[\s"'$]/.test(a) ? JSON.stringify(a) : a)).join(' ');
+}
+
+async function launch({ headed = false, extraArgs = [] }) {
+  const exe = findChrome();
+  if (!exe) {
+    throw new Error(`No Chromium found to launch. Install Playwright's with:\n  ${INSTALL}\nor set PW_CHROME to one, or start one yourself with --remote-debugging-port and set PW_CDP_URL.`);
+  }
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-repl-chrome-'));
+  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', `--user-data-dir=${profile}`,
+    '--no-first-run', '--no-default-browser-check', ...(smallShm() ? ['--disable-dev-shm-usage'] : [])];
+  // Flags given after -- come after these, so they can override them.
+  let args = [...ours, ...extraArgs, 'about:blank'];
+  let result = await start(exe, args, profile);
+  let note = null;
+  // Tried with the sandbox first; a container often cannot give Chromium one.
+  if (result.error && /sandbox/i.test(result.stderr)) {
+    args = [...ours, '--no-sandbox', ...extraArgs, 'about:blank'];
+    result = await start(exe, args, profile);
+    note = 'Chromium could not use its sandbox here, so it runs with --no-sandbox.';
+  }
+  const command = quoted([exe, ...args]);
+  if (result.error) {
+    fs.rmSync(profile, { recursive: true, force: true });
+    const last = result.stderr.trim().split('\n').slice(-5).join('\n');
+    throw new Error(`Chromium did not start (${result.error}):\n  ${command}${last ? `\n${last}` : ''}`);
+  }
+  const { proc, port } = result;
+  const signal = name => { try { process.kill(-proc.pid, name); } catch {} };
+  const stop = async () => {
+    if (proc.exitCode === null && proc.signalCode === null) {
+      signal('SIGTERM');
+      await new Promise(resolve => { const t = setTimeout(() => { signal('SIGKILL'); resolve(); }, STOP_TIMEOUT); proc.once('exit', () => { clearTimeout(t); resolve(); }); });
+    }
+    // Its helper processes can still be writing to the profile for a moment.
+    for (let tries = 0; tries < 30; tries++) {
+      try { fs.rmSync(profile, { recursive: true, force: true }); return; } catch { await new Promise(resolve => setTimeout(resolve, 100)); }
+    }
+  };
+  // If the REPL goes without shutting down, the browser still goes with it.
+  process.on('exit', () => signal('SIGKILL'));
+  return { url: `http://127.0.0.1:${port}`, command, note, headed, stop };
+}
+
+module.exports = { findChrome, launch, INSTALL };

package/lib/runner.js

@@ -3,19 +3,19 @@
 const readline = require('readline');
 const { state, beforeExit } = require('./state');
 const out = require('./output');
-const { commands, activeModes } = require('./commands');
+const { commands, dialogCommand, activeModes } = require('./commands');
 
 // 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',
+const READ_ONLY = new Set(['info', 'listeners', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs',
   'snapshot', 'screenshot', 'wait', 'sleep', 'requests', 'body', 'console', 'cookies', 'storage', 'capture', 'help']);
 
 // Commands that work with no tab selected.
-const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'help', 'quit']);
+const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'dialog', 'help', 'quit']);
 
 // Commands that accept a leading --all to lift the output limit.
-const INSPECTION = ['info', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
+const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
 
 let queue = Promise.resolve();
 // The server command running now, so a quit at the prompt can answer it.
@@ -117,9 +117,10 @@ function prompt(preserveCursor) {
   state.rl.prompt(preserveCursor);
 }
 
-// quit skips the queue so it still works while a long command is running.
+// quit and dialog skip the queue: quit so it works while a long command runs,
+// dialog because the commands queued behind a dialog wait for its answer.
 function enqueue(line) {
-  const direct = /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\s+)?quit(?:\s|$)/.test(line.trim());
+  const direct = /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\s+)?(?:quit|dialog)(?:\s|$)/.test(line.trim());
   const run = () => handleLine(line);
   if (direct) run().catch(e => out.error(`Error: ${e.message}`));
   else queue = queue.then(run).catch(e => out.error(`Error: ${e.message}`));
@@ -128,6 +129,7 @@ function enqueue(line) {
 // Server commands share the prompt's queue and are echoed to the pane, so
 // someone watching sees everything an agent does.
 function submit(text) {
+  if (/^dialog(?:\s|$)/.test(text)) return answerDialog(text);
   return new Promise(resolve => {
     queue = queue.then(async () => {
       if (state.stopping) return resolve({ status: 'error', output: 'The REPL is shutting down.' });
@@ -156,6 +158,18 @@ function submit(text) {
   });
 }
 
+// Outside the queue, and so outside out.collect, whose single sink belongs to
+// the command that is waiting on the dialog.
+async function answerDialog(text) {
+  console.log(`[server] ${text}`);
+  let result;
+  try { result = { status: 'ok', output: await dialogCommand(text.slice(6)) }; }
+  catch (error) { result = { status: 'error', output: `Error: ${error.message}` }; }
+  console.log(result.output);
+  if (!state.stopping) prompt(true);
+  return result;
+}
+
 function drained() {
   return queue;
 }

package/lib/send.js

@@ -18,14 +18,16 @@ function hasSession(session) {
   try { tmux('has-session', '-t', session); return true; } catch { return false; }
 }
 
-// Which way a command goes: an explicit -e or -s wins; otherwise the server
-// when its socket exists, else tmux.
+// Which way a command goes: an explicit -e or -s wins, and so does a socket
+// named in PW_SOCKET, even one that is gone (a tmux pane is then someone
+// else's); otherwise the server when the default socket exists, else tmux.
 function route(options) {
   const socket = process.env.PW_SOCKET || client.DEFAULT_SOCKET;
   const endpoint = options.endpoint || process.env.PW_ENDPOINT || '';
   const session = options.session || process.env.PW_TMUX_SESSION || 'playwright-repl';
   if (options.session) return { kind: 'tmux', session };
   if (endpoint) return { kind: 'server', endpoint: client.parseEndpoint(endpoint), explicit: true };
+  if (process.env.PW_SOCKET) return { kind: 'server', endpoint: client.parseEndpoint(socket), explicit: true };
   if (fs.existsSync(socket) && fs.statSync(socket).isSocket()) return { kind: 'server', endpoint: client.parseEndpoint(socket), explicit: false, socket };
   return { kind: 'tmux', session };
 }
@@ -110,9 +112,16 @@ async function send(options) {
 // Reports the route a command would take, checking it the way a command would.
 async function where(options) {
   const way = route(options);
+  const info = way.kind === 'server' ? await client.healthInfo(way.endpoint, 5000) : null;
+  // The browser a running REPL uses (one it launched has its own address); otherwise the one it would
+  // use, so a REPL that will not start can be told apart from one that is not running.
+  const cdp = info?.browser || process.env.PW_CDP_URL || 'http://localhost:9222';
+  const version = await fetch(`${cdp}/json/version`, { signal: AbortSignal.timeout(2000) }).then(r => r.json()).catch(() => null);
+  const whose = info?.launched ? ', launched by this REPL' : '';
+  console.log(version ? `browser: ${cdp} answers (${version.Browser}${whose})` : `browser: nothing answers at ${cdp}; pw-repl run says how to start one`);
   if (way.kind === 'server') {
     const name = client.describe(way.endpoint);
-    if (await client.health(way.endpoint, 5000)) {
+    if (info) {
       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);

package/lib/server.js

@@ -5,7 +5,7 @@ const net = require('net');
 const fs = require('fs');
 const out = require('./output');
 const runner = require('./runner');
-const { onShutdown, onBeforeExit } = require('./state');
+const { state, onShutdown, onBeforeExit } = require('./state');
 const { parseEndpoint, describe } = require('./client');
 
 const MAX_BODY = 1024 * 1024;
@@ -29,7 +29,7 @@ function handle(req, res) {
   // cross-origin POST, and cannot send a JSON content type without a
   // preflight this server never answers.
   if (req.headers.origin) return send(res, 403, { status: 'error', output: 'Requests from web pages are refused' });
-  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: 'ok' });
+  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: 'ok', browser: state.cdpUrl, launched: state.launched });
   if (req.method !== 'POST' || req.url !== '/run') return send(res, 404, { status: 'error', output: 'Use POST /run or GET /health' });
   if (!/^application\/json\b/.test(req.headers['content-type'] || '')) return send(res, 415, { status: 'error', output: 'Content-Type must be application/json' });
   let body = '';

package/lib/start.js

@@ -1,17 +1,47 @@
 // Connects to the browser and runs the prompt (and the server with serve).
 const { chromium } = require('playwright-core');
 const readline = require('readline');
-const { state, withTimeout, shutdown, beforeExit } = require('./state');
+const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./state');
 const out = require('./output');
 const { listTabs, openTab, watchPage, complete } = require('./commands');
 const runner = require('./runner');
 
-const CDP_URL = process.env.PW_CDP_URL || 'http://localhost:9222';
+// A browser --launch starts has its own address instead.
+let CDP_URL = process.env.PW_CDP_URL || 'http://localhost:9222';
+const CONNECT_TIMEOUT = 15000;
+
+// What to do about a browser that cannot be reached, rather than the bare socket error.
+function connectHelp(error) {
+  const reason = String(error.message).split('\n')[0].replace(/^browserType\.connectOverCDP: /, '');
+  if (/timeout/i.test(reason)) {
+    return `Chromium at ${CDP_URL} answered but did not finish attaching within ${CONNECT_TIMEOUT / 1000}s. A tab with a\ndialog open (alert, confirm) holds this up: answer it or close that tab, then try again.`;
+  }
+  return `No browser answered at ${CDP_URL} (${reason}).
+
+pw-repl needs a Chromium-based browser (Chrome, Chromium, Edge, ...) started with remote debugging:
+  chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
+  chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-headless
+It needs a --user-data-dir of its own: Chrome does not open the port on its default profile.
+curl ${CDP_URL}/json/version checks that it answers; PW_CDP_URL points at a browser elsewhere.
+Or let pw-repl start a private one for this REPL: pw-repl run --launch (or serve --launch).`;
+}
 
 async function start(options) {
   const START_URL = options.startUrl || process.env.PW_START_URL || null;
+  if (options.launch) {
+    const launched = await require('./launch').launch({ headed: options.headed, extraArgs: options.chromeArgs });
+    onBeforeExit(launched.stop);
+    CDP_URL = launched.url;
+    out.log(`Launched a ${launched.headed ? 'visible' : 'headless'} Chromium of this REPL's own; it stops with the REPL:`);
+    out.log(`  ${launched.command}`);
+    if (launched.note) out.log(launched.note);
+    out.log(`Another REPL reaches it with PW_CDP_URL=${CDP_URL}`);
+  }
+  state.cdpUrl = CDP_URL;
+  state.launched = !!options.launch;
   out.log(`Connecting to ${CDP_URL}...`);
-  state.browser = await chromium.connectOverCDP(CDP_URL);
+  try { state.browser = await chromium.connectOverCDP(CDP_URL, { timeout: CONNECT_TIMEOUT }); }
+  catch (error) { throw new Error(connectHelp(error)); }
   if (state.stopping) {
     try { await withTimeout(state.browser.close(), 'Chromium shutdown'); }
     catch (error) { process.exitCode = 1; out.error(`Could not confirm Chromium shutdown: ${error.message}`); }
@@ -23,7 +53,7 @@ async function start(options) {
     state.stopping = true;
     process.exitCode = 1;
     out.error('Chromium connection lost; queued commands will not run.');
-    void shutdown().then(() => process.exit(1));
+    void shutdown().then(beforeExit).then(() => process.exit(1));
   });
   out.log('Connected to Chromium via CDP');
 
@@ -102,7 +132,7 @@ async function start(options) {
     endPromptLine();
     out.error('Input ended; disconnecting.');
     runner.drained().then(() => shutdown(), () => shutdown())
-      .then(() => process.exit(process.exitCode || 0));
+      .then(beforeExit).then(() => process.exit(process.exitCode || 0));
   });
   rl.on('SIGINT', stop);
 }
@@ -123,4 +153,4 @@ function stop() {
 // SIGHUP too: closing the terminal must still remove the server's socket.
 for (const signal of ['SIGTERM', 'SIGHUP']) process.on(signal, stop);
 
-module.exports = { start: options => start(options).catch(e => { out.error(e.message); shutdown().finally(() => process.exit(1)); }) };
+module.exports = { start: options => start(options).catch(e => { out.error(e.message); shutdown().then(beforeExit).finally(() => process.exit(1)); }) };

package/lib/state.js

@@ -11,6 +11,9 @@ const state = {
   tabListing: [],
   rl: null,
   promptBase: 'pw> ',
+  // The browser the REPL is connected to, and whether --launch started it.
+  cdpUrl: null,
+  launched: false,
   stopping: false,
   connectionLost: false,
   shutdownFailed: false,

package/package.json

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

package/skill/SKILL.md

@@ -27,6 +27,9 @@ one; each takes an optional start URL, which opens in a new tab.
   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]>`.
+- Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
+  own instead of connecting to one: headless unless `--headed`, in a temporary profile, stopped with the
+  REPL. It prints the command it ran; flags after `--` are passed to that Chromium.
 - `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`:
 
@@ -62,7 +65,7 @@ are the command. For `fill`, `type`, `select` and `press`, a word quoted in your
 
 - `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
+  of what someone is typing; while a command is running, someone 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
@@ -72,14 +75,13 @@ are the command. For `fill`, `type`, `select` and `press`, a word quoted in your
 REPL), or why neither is reachable, without running anything.
 
 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.
+background REPL (server commands as `[server]` lines), so whoever looks there sees what you do. The pane
+shows REPL commands only, not what was clicked in the browser (unless `watch on --live` is on); for
+that, look at the browser itself: `tab` and `info` for where things are, `requests` for the requests the
+clicks made (`body <#>` for what one returned), `console` for console messages and page errors. `watch
+on` records each step someone takes in a tab, 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.
 
 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.
@@ -90,23 +92,27 @@ Run `pw-repl send help`. It lists six topics; `help <topic>` lists their 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.
 
-## 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. 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.
-- Dialogs are never answered automatically. The person at the browser handles them.
-- Before leaving: turn off the modes you turned on (`modes` lists what is on in every tab; the prompt
-  shows the selected tab's, e.g. `(watch routes:1) pw>`), and close the tabs you opened. `modes off`
-  turns off everything, including modes the user turned on, so use it only when they are all yours.
-- The tmux session may be attached by the user. Never kill it.
+## Sharing the browser
+
+- The browser may have tabs that are not yours, and someone may be using it. Whether to read or act in
+  one of those tabs, or to open your own (`tab new <url>`), depends on the task; when that is not
+  clear, ask.
+- No tab is selected when the REPL starts (unless it was given a start URL). Closing a tab the REPL
+  opened goes back to the tab before it, if the REPL opened that one too; 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.
+- Dialogs are never answered on their own. While one is open, its page and the commands that read it
+  wait; `dialog` shows it, and `dialog accept` or `dialog dismiss` answers it.
+- Modes and tabs stay on or open until they are turned off or closed, whoever started them. `modes`
+  lists what is on in every tab (the prompt shows the selected tab's, e.g. `(watch routes:1) pw>`);
+  `modes off` turns off every mode in every tab.
+- Someone may be attached to the REPL's tmux session; killing the session ends it for them too.
 
 ## Environment
 
-- Chromium must be running with `--remote-debugging-port=9222`.
+- Chromium must be running with `--remote-debugging-port=9222`, unless `--launch` starts one. A headless
+  one works too (`--headless=new`); nobody answers its dialogs but `dialog`.
+- `PW_CHROME` — the Chromium `--launch` starts (default: Playwright's own, then one on the `PATH`).
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
 - `PW_SCREENSHOT_DIR` — where screenshots go (default `/tmp`). They are all named `screenshot-*.png`,
   so `rm /tmp/screenshot-*.png` cleans up.