pw-repl 0.2.0 → 0.2.2

package/README.md

@@ -21,6 +21,16 @@ 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`.
 
+**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

package/bin/pw-repl.js

@@ -67,9 +67,14 @@ function parseSendArgs(args, allowCommand) {
   }
   const words = args.slice(i);
   if (!allowCommand && words.length) usage();
-  // A word the shell kept whole (fill "text=Your name" Ada) is quoted again, so
-  // it stays one word; a command given as a single word is sent as it is.
-  const quoted = words.length > 1 ? words.map(w => (/[\s"']/.test(w) ? JSON.stringify(w) : w)) : words;
+  // 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]);
+  // 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;
 }
@@ -115,7 +120,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

@@ -79,7 +79,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 +103,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/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';
@@ -96,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;
@@ -299,16 +353,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 => {
@@ -666,28 +728,6 @@ async function allModesOff() {
   if (!any) out.log('No modes were on.');
 }
 
-// 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] };
-}
-
 // Commands that take only a selector take the whole line, spaces and all.
 function soleSelector(args, usage) {
   const text = unquote((args || '').trim());
@@ -703,14 +743,19 @@ function selectorAndValue(args, usage, example) {
   return { selector: parsed.selector, value: unquote(parsed.rest), shown: parsed.word };
 }
 
-// A ref that no longer matches usually means the page changed since the snapshot.
+// 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 (selector.startsWith('aria-ref=') && !/resolved to/.test(error.message)) {
-      error.message += `\n${selector.slice(9)} is a snapshot ref; if the page changed since that snapshot, take a new one.`;
-    }
+    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;
   }
 }
@@ -802,13 +847,56 @@ function discardCapture() {
   cap = null;
 }
 
-// A tab of the REPL's own: closing it can go back to the tab before.
+// 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 opened = await state.browser.contexts()[0].newPage();
+  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());
@@ -898,18 +986,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()}`);
   },
 
@@ -921,8 +1011,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) {
@@ -951,7 +1040,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}`);
   },
 
@@ -1073,6 +1176,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 });
@@ -1109,11 +1215,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 });
@@ -1226,7 +1328,8 @@ const commands = {
     // 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;
-    const hidden = everything ? 0 : log.filter(e => e.id > first && e.id < last && !shown.includes(e)).length;
+    // 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)`);
   },
 
@@ -1247,7 +1350,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)`);
@@ -1382,6 +1486,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();
@@ -1427,6 +1535,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']);
@@ -1437,4 +1546,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

@@ -63,8 +63,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'],
   },
 };
 
@@ -72,9 +72,13 @@ 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',
+    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.',
   },
-  goto: { usage: 'goto <url>', summary: 'navigate the selected tab; https:// is assumed' },
   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 +91,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' },
@@ -112,7 +116,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: {
@@ -139,7 +143,7 @@ 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',
@@ -166,7 +170,12 @@ 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.',
+  },
+  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: {

package/lib/runner.js

@@ -3,7 +3,7 @@
 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
@@ -12,7 +12,7 @@ const READ_ONLY = new Set(['info', 'text', 'html', 'attrs', 'count', 'visible',
   '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'];
@@ -72,6 +72,8 @@ 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}`);
     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.');
@@ -115,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}`));
@@ -126,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.' });
@@ -154,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,6 +112,10 @@ 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);
+  // Whether the browser answers, so a REPL that will not start can be told apart from one that is not running.
+  const cdp = 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);
+  console.log(version ? `browser: ${cdp} answers (${version.Browser})` : `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)) {
@@ -122,10 +128,15 @@ async function where(options) {
     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/start.js

@@ -7,11 +7,28 @@ const { listTabs, openTab, watchPage, complete } = require('./commands');
 const runner = require('./runner');
 
 const 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.`;
+}
 
 async function start(options) {
   const START_URL = options.startUrl || process.env.PW_START_URL || null;
   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}`); }

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.2.0",
+  "version": "0.2.2",
   "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
   "keywords": [
     "playwright",

package/skill/SKILL.md

@@ -11,6 +11,12 @@ 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
 
 `pw-repl where` says whether a REPL is running and how `send` reaches it. There are three ways to run
@@ -29,8 +35,18 @@ one; each takes an optional start URL, which opens in a new tab.
   tmux send-keys -t playwright-repl Enter
   ```
 
-`serve <port>` listens on TCP 127.0.0.1 instead of the socket, with no access control. A REPL in a
-terminal stops at its prompt (`quit`, or Ctrl-C); `send quit` is refused.
+`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.
+
+A REPL in a terminal stops at its prompt (`quit`, or Ctrl-C); `send quit` is refused.
 
 ## Send commands
 
@@ -40,12 +56,13 @@ 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. The words after `send`
-are the command, and a word quoted in your shell stays one word:
-`pw-repl send fill "text=Your name" Ada`. It works however the REPL was started:
+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` (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
@@ -55,14 +72,13 @@ are the command, and a word quoted in your shell stays one word:
 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.
@@ -73,23 +89,26 @@ 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`. A headless one works too
+  (`--headless=new`); nobody answers its dialogs but `dialog`.
 - `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.