pw-repl 0.3.1 → 0.3.2

package/AGENTS.md

@@ -27,6 +27,29 @@ If you hit a limitation or write a workaround, consider adding the capability to
 - `skill/SKILL.md` is how agents learn to use the REPL: keep it in step with a change to how it is
   used, and leave its Custom rules section empty.
 
+## Waves
+
+Work goes in waves, and each one ends with a release that is ready to push.
+
+1. Build what was asked, with tests, and try it in a running REPL.
+2. Try it on a fresh agent that has not seen the code or the change (a guinea pig), on something real: a
+   small local page whose planted bugs need the change to find.
+   - Brief it with goals only: what to find out or do in the browser, never the commands.
+   - First it reads back its plan, learned from `pw-repl skill` and help alone: the commands, where it
+     found them, and what is unclear. It runs nothing yet.
+   - A wrong or unsure plan means the docs or the brief were unclear: find out which, fix that, then
+     ask again.
+   - Then it carries the plan out, in a browser and on a socket of its own, and reports as it goes:
+     above all, where the tool did something other than what the docs led it to expect.
+3. Triage what it reports. Fix what matters, and what is small and useful; don't put off something
+   useful for later. Leave trivia alone, and say why.
+4. Repeat 2 and 3, with a fresh agent each time, until a pass comes back clean: no real bugs, and
+   nothing unclear in the docs or the brief that changed the plan. A pass after fixes tries the fixes,
+   and something not tried yet.
+5. Only then cut the release (Releasing, steps 1-3), and say it is ready. The maintainer pushes and
+   publishes it, and the next wave starts from what they find. A release cut too early and not pushed
+   yet is undone (its commit and tag) and cut again after the fixes.
+
 ## Releasing
 
 Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`,

package/lib/commands.js

@@ -154,12 +154,12 @@ async function viewportText() {
 
 // 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.
+// the document to be parsed, which a restored one already is.
 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(() => {});
+  await state.page.waitForFunction(() => document.readyState !== 'loading', null, { timeout: 3000 }).catch(() => {});
 }
 
 const SCREENSHOT_DELAY_MAX = 60;
@@ -212,10 +212,18 @@ function emulatedKinds(e) {
   return [e?.device && 'mobile', e?.scheme, e?.locale && 'locale', e?.timezone && 'timezone'].filter(Boolean);
 }
 
+const DEVICES_SHOWN = 20;
+
 function deviceNamed(name) {
-  const found = Object.keys(devices).find(d => d.toLowerCase() === name.toLowerCase());
-  if (!found) throw new Error(`No device ${JSON.stringify(name)}; names are Playwright's, e.g. Pixel 7, iPhone 13, iPad Mini, Galaxy S9+`);
-  return found;
+  const names = Object.keys(devices);
+  const found = names.find(d => d.toLowerCase() === name.toLowerCase());
+  if (found) return found;
+  // The names that have every word typed, so a near miss finds the exact name.
+  const words = name.toLowerCase().split(/\s+/);
+  const close = names.filter(d => !/ landscape$/.test(d) && words.every(w => d.toLowerCase().includes(w)));
+  if (!close.length) throw new Error(`No device ${JSON.stringify(name)}; names are Playwright's, e.g. Pixel 7, iPhone 13, iPad Mini, Galaxy S9+`);
+  const more = close.length > DEVICES_SHOWN ? `, and ${close.length - DEVICES_SHOWN} more` : '';
+  throw new Error(`No device ${JSON.stringify(name)}; matching: ${close.slice(0, DEVICES_SHOWN).join(', ')}${more} (each also as "<name> landscape")`);
 }
 
 function deviceText(name) {
@@ -225,6 +233,14 @@ function deviceText(name) {
 
 // Sends only what changed. Chrome takes the user agent and the languages
 // together, so a change to either sends both.
+function deviceMetrics(session, name) {
+  const d = devices[name];
+  return session.send('Emulation.setDeviceMetricsOverride', {
+    width: d.viewport.width, height: d.viewport.height, deviceScaleFactor: d.deviceScaleFactor, mobile: d.isMobile,
+    screenWidth: d.screen?.width || d.viewport.width, screenHeight: d.screen?.height || d.viewport.height,
+  });
+}
+
 async function setEmulation(p, next) {
   const session = await keptSession(p);
   const previous = emulations.get(p) || {};
@@ -232,10 +248,7 @@ async function setEmulation(p, next) {
   if (next.device !== previous.device) {
     const d = devices[next.device];
     if (d) {
-      await send('Emulation.setDeviceMetricsOverride', {
-        width: d.viewport.width, height: d.viewport.height, deviceScaleFactor: d.deviceScaleFactor, mobile: d.isMobile,
-        screenWidth: d.screen?.width || d.viewport.width, screenHeight: d.screen?.height || d.viewport.height,
-      });
+      await deviceMetrics(session, next.device);
     } else {
       await send('Emulation.clearDeviceMetricsOverride');
     }
@@ -1042,7 +1055,11 @@ function grepSnapshot(text, needle) {
     const indent = line.length - line.trimStart().length;
     while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
     if (line.toLowerCase().includes(lower)) {
-      const path = stack.filter(a => !/^generic(?: \[|$)/.test(a.label)).map(a => a.label.replace(/ \[ref=[^\]]+\]/g, ''));
+      const around = stack.filter(a => !/^generic(?: \[|$)/.test(a.label));
+      // A hit with no ref of its own (text) keeps the ref of what holds it, so
+      // snapshot <ref> can show what sits beside it: the value next to a label.
+      const own = /\[ref=/.test(line);
+      const path = around.map((a, i) => (!own && i === around.length - 1 ? a.label : a.label.replace(/ \[ref=[^\]]+\]/g, '')));
       hits.push([...path, label(line)].join(' › '));
     }
     stack.push({ indent, label: label(line) });
@@ -1473,7 +1490,19 @@ const commands = {
     // 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 });
+    let image;
+    try {
+      image = await state.page.screenshot({ fullPage: full });
+    } finally {
+      // Playwright's screenshot resets the screen size and pixel ratio it
+      // finds; an emulated phone's are set again.
+      const device = emulations.get(state.page)?.device;
+      if (device) {
+        const session = await keptSession(state.page);
+        await session.send('Emulation.clearDeviceMetricsOverride');
+        await deviceMetrics(session, device);
+      }
+    }
     try {
       fs.writeFileSync(filepath, image, { flag: 'wx', mode: 0o600 });
     } catch (error) {
@@ -1570,6 +1599,8 @@ const commands = {
     if (tokens.length > 1 && /^\d+$/.test(tokens[tokens.length - 1])) seconds = Number(tokens.pop());
     if (!tokens.length || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
     const timeout = seconds * 1000;
+    // Said plainly, not as Playwright's call log.
+    const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };
     const kind = tokens[0];
     if (kind === 'load' && tokens.length === 1) {
       if (gone) throw new Error(usage);
@@ -1582,13 +1613,13 @@ const commands = {
         return waitForRequest(what, timeout);
       }
       if (gone) return waitGone(state.page.getByText(what), what, timeout);
-      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout });
+      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${seconds}s`));
       out.log(`Visible: ${what}`);
       return;
     }
     const selector = toSelector(unquote(tokens.join(' ')));
     if (gone) return waitGone(state.page.locator(selector), tokens.join(' '), timeout);
-    await state.page.waitForSelector(selector, { state: 'attached', timeout });
+    await state.page.waitForSelector(selector, { state: 'attached', timeout }).catch(plainly(`No element matches ${tokens.join(' ')} within ${seconds}s`));
     out.log(`Found: ${tokens.join(' ')}`);
   },
 

package/lib/help.js

@@ -52,7 +52,7 @@ const TOPICS = {
     commands: ['requests', 'body', 'console', 'capture', 'route', 'network'],
   },
   devtools: {
-    intro: 'Cookie and storage listings omit values. eval, html, screenshots and URLs can still show sensitive data.',
+    intro: 'Cookie and storage listings omit values. eval, cdp, html, screenshots and URLs can still show\nsensitive data (cdp Network.getCookies shows cookie values).',
     commands: ['eval', 'cdp', 'cookies', 'storage'],
   },
   session: {
@@ -84,8 +84,12 @@ const COMMANDS = {
     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' },
+  back: {
+    usage: 'back',
+    summary: 'go back one history entry',
+    detail: 'The browser may bring the page back from its back/forward cache, as it was: nothing loads or runs\nagain, so a loading message or a request the page makes on load does not come back. reload loads it\nafresh.',
+  },
+  forward: { usage: 'forward', summary: 'go forward one history entry', detail: 'Like back, it may bring the page back from the back/forward cache without loading it again.' },
   reload: { usage: 'reload', summary: 'reload the selected tab' },
   info: { usage: 'info', summary: 'selected tab URL, title and viewport' },
   click: { usage: 'click <selector>', summary: 'click the first match' },
@@ -109,7 +113,7 @@ const COMMANDS = {
   snapshot: {
     usage: 'snapshot [--full] [--grep <text> | <eN> | selector]',
     summary: 'outline by role and name, with [ref=eN] labels',
-    detail: 'Playwright\'s accessibility snapshot, with unnamed layout wrappers (generic) and cursor hints left\nout; --full shows it unchanged.\n\n--grep <text> prints only the lines containing text (role, name or flag such as [disabled], any\ncase), each with the named elements around it. A hit with no named element around it prints without\na path.\n\nsnapshot e3 outlines one element. A ref (e3, or f1e3 in newer Playwright) works as a selector in any\ncommand: click e3. Refs can change when the page changes (e102 may become f4e98), so take a new\nsnapshot after it does.\n\nOutput over 60 lines ends with a line count.',
+    detail: 'Playwright\'s accessibility snapshot, with unnamed layout wrappers (generic) and cursor hints left\nout; --full shows it unchanged.\n\n--grep <text> prints only the lines containing text (role, name or flag such as [disabled], any\ncase), each with the named elements around it. A hit with no named element around it prints without\na path. A hit on text (a label) keeps the ref of the element holding it, so snapshot <that ref>\nshows what sits beside it, such as the value next to the label.\n\nsnapshot e3 outlines one element. A ref (e3, or f1e3 in newer Playwright) works as a selector in any\ncommand: click e3. Refs can change when the page changes (e102 may become f4e98), so take a new\nsnapshot after it does.\n\nOutput over 60 lines ends with a line count.',
   },
   watch: {
     usage: 'watch on [--changes] [--live] | off | [n|new]',
@@ -131,18 +135,18 @@ 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). 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.',
+    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. The image is at CSS pixel size,\none image pixel per CSS pixel, also while emulate mobile is on.\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' },
   emulate: {
     usage: 'emulate [<what> [off] | off]',
     summary: 'emulate a phone, dark mode, a locale or a timezone',
-    detail: 'emulate mobile [device]  a phone\'s screen, touch and user agent: a Pixel 7, or a device named as in\n                         Playwright\'s list, e.g. emulate mobile iPhone 13\nemulate dark | light     the color scheme the page\'s CSS and matchMedia see\nemulate locale <tag>     the language (Accept-Language, navigator.language) and date and number\n                         formats, e.g. fr-FR\nemulate timezone <zone>  an IANA timezone, e.g. Asia/Tokyo\nemulate <what> off       stop one (dark or light off stops the color scheme); emulate off stops all\n\nPer tab, until turned off or the REPL exits. emulate on its own shows what is on.\n\nThe page sees the user agent, touch and navigator.languages from its next load: reload after\nemulate mobile or emulate locale. While mobile is on, viewport refuses: the device sets the size.',
+    detail: 'emulate mobile [device]  a phone\'s screen, touch and user agent: a Pixel 7, or a device named as in\n                         Playwright\'s list, e.g. emulate mobile iPhone 13; a name that is not\n                         exact lists the devices it matches (emulate mobile galaxy)\nemulate dark | light     the color scheme the page\'s CSS and matchMedia see\nemulate locale <tag>     the language (Accept-Language, navigator.language) and date and number\n                         formats, e.g. fr-FR\nemulate timezone <zone>  an IANA timezone, e.g. Asia/Tokyo\nemulate <what> off       stop one (dark or light off stops the color scheme); emulate off stops all\n\nPer tab, until turned off or the REPL exits. emulate on its own shows what is on.\n\nThe page sees the user agent, touch and navigator.languages from its next load: reload after\nturning mobile or locale on or off. While mobile is on, viewport refuses: the device sets the size.',
   },
   wait: {
     usage: 'wait [text|request] <what> [--gone] [secs]',
     summary: 'wait for an element, text, a response or a load (10s)',
-    detail: 'wait <selector> waits for a matching element; wait text <text> for text to be visible; wait request\n<url-part|glob> for a matching response, counting one that finished since the previous command began\n(so click, then wait request, does not miss it).\n\nwait load waits for the page to finish loading (its load event). A navigation that began since the\nprevious command began counts, so click a link, then wait load, waits for the new page.\n\n--gone waits instead until nothing matching is visible (removed or hidden): wait .spinner --gone.\n\nUp to 120s. A wait that times out is an error; the REPL carries on.',
+    detail: 'wait <selector> waits for a matching element; wait text <text> for text to be visible; wait request\n<url-part|glob> for a matching response, counting one that finished since the previous command began\n(so click, then wait request, does not miss it).\n\nwait load waits for the page to finish loading (its load event). A navigation that began since the\nprevious command began counts, so click a link, then wait load, waits for the new page. A page\nthat changes its own URL without loading (an app\'s own routing) is not a load: wait for something on\nthe new view instead.\n\nwait text matches any part of an element\'s text, in any case.\n\n--gone waits instead until nothing matching is visible (removed or hidden): wait .spinner --gone.\nIt is done at once if nothing matches yet, so wait for it to appear first if it may not have.\n\nUp to 120s. A wait that times out is an error; the REPL carries on.',
   },
   sleep: { usage: 'sleep <ms>', summary: 'wait a fixed time (maximum 3600000)' },
   requests: {
@@ -158,7 +162,7 @@ const COMMANDS = {
   console: {
     usage: 'console [--all] [n] [filter]',
     summary: 'the last n console messages and page errors',
-    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: time, [type],\ntext. Types are console levels (log, warning, error, ...) and pageerror for uncaught exceptions.\n\nfilter matches the type or the text, e.g. console error.',
+    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: time, [type],\ntext. Types are console levels (log, warning, error, ...) and pageerror for uncaught exceptions.\n\nfilter matches the type or the text, e.g. console error.\n\nA page brought back from the back/forward cache (back, forward) reports its earlier messages again,\nat the time it comes back, though nothing loaded again.',
   },
   capture: {
     usage: 'capture on [requests|console] [secs] | off',
@@ -173,7 +177,7 @@ const COMMANDS = {
   network: {
     usage: 'network [on|off|slow [<ms> [<kbps>]]]',
     summary: 'cut, slow or restore the tab\'s network',
-    detail: 'network off cuts it, like dropped wifi. Stopping a service is not the same: a dev proxy in front of\nit usually holds the request open, so the page spins instead of failing.\n\nnetwork slow adds latency to each request and limits its speed: by default as DevTools\' Slow 4G\n(563ms, 1440 kbps down, 675 up); network slow <ms> [<kbps>] sets them. To slow one API, use route\n<glob> delay <secs>.\n\nPer tab; lasts until network on or the REPL exits. Routes still answer while it is off or slow.',
+    detail: 'network off cuts it, like dropped wifi. Stopping a service is not the same: a dev proxy in front of\nit usually holds the request open, so the page spins instead of failing.\n\nnetwork slow makes each request take at least <ms> (Chrome\'s latency is a minimum, not added to a\nslow server\'s own time) and limits its speed: by default as DevTools\' Slow 4G (563ms, 1440 kbps\ndown, 675 up); network slow <ms> [<kbps>] sets them, kbps both ways (left out, it stays Slow\n4G\'s). To slow one API, use route <glob> delay <secs>.\n\nPer tab; lasts until network on or the REPL exits. Routes still answer while it is off or slow.',
   },
   eval: {
     usage: 'eval [--all] <JavaScript>',

package/lib/send.js

@@ -117,7 +117,8 @@ async function where(options) {
   // 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' : '';
+  // With no REPL running, it is only where one would connect, not a browser of a REPL that stopped.
+  const whose = info?.launched ? ', launched by this REPL' : info ? '' : '; run and serve connect here without --launch';
   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);

package/package.json

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

package/skill/SKILL.md

@@ -59,9 +59,10 @@ 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. 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:
+are the command. For `fill`, `type`, `select`, `press` and `upload`, 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, joined by
+spaces (`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the whole
+line, spaces and all: `pw-repl send click "text=Your name"`. 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
@@ -114,8 +115,9 @@ help is the command reference; this file does not repeat it.
   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.
+- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots (default `/tmp`), read when it starts, not by
+  `send`. `screenshot` prints each file's path; other REPLs may save theirs there too. Remove only your
+  own, and keep those too if they are needed, e.g. as evidence or as something to hand over.
 - `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `send`
   looks for when neither is given (default `/tmp/playwright-repl.sock`).