pw-repl 0.12.0 → 0.12.2

package/AGENTS.md

@@ -102,7 +102,10 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 1.0, a change that breaks how the REPL is used is a minor bump (0.2.0 to 0.3.0), anything else a patch.
 
 1. `npm test` passes and the working tree is clean.
-2. `npm outdated` and `npm audit` show nothing that needs doing first.
+2. `npm outdated` and `npm audit` show nothing that needs doing first. The lockfile holds playwright-core
+   at 1.63: on 1.64, a click on a link to a 204 waits out its timeout instead of returning (the test
+   "waits for the page to load, counting a navigation that just began" fails). Update it once a version
+   passes `npm test`.
 3. `npm version <patch|minor|major> -m "chore: release %s"` sets the version in `package.json` and
    `package-lock.json`, commits it as `chore: release X.Y.Z`, and tags that commit `vX.Y.Z`.
 4. `git push --follow-tags` pushes the commits and the tag.

package/README.md

@@ -8,6 +8,11 @@ in one it starts itself. You type commands at a `pw>` prompt. Agents send the sa
 with `pw-repl send`. Every command shows in the REPL, whoever sent it, so you always see what an agent
 is doing in your browser, and the agent can see what you did.
 
+[![pw-repl demo, recorded by pw-repl](docs/pw-repl-demo.png)](docs/pw-repl-demo.webm)
+
+A 90-second demo (click to play), recorded by pw-repl itself from one script of commands. The command
+panel on the right is part of the demo page, showing what the agent sends.
+
 ```text
 pw> tab new http://localhost:3000/cart
 pw> snapshot                            # the page by role and name, with [ref=eN] labels
@@ -125,29 +130,30 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 
 ## Common tasks
 
-| I want to…                           | Commands                                                                             |
-| ------------------------------------ | ------------------------------------------------------------------------------------ |
-| see where I am                       | `tab` (it marks the tab you are looking at `(visible)`), `info`                      |
-| see what is on the page              | `snapshot`, `screenshot`                                                             |
-| do something on it                   | `click`, `fill`, `type`, `press`                                                     |
-| run some JavaScript in the page      | `eval document.title`                                                                |
-| wait for a page or element           | `wait load`, `wait <selector>`, `wait <selector> --gone`, `wait text <text>`         |
-| choose a file in a file input        | `upload <selector> <file>`                                                           |
-| see it as a phone, or in dark mode   | `emulate mobile`, `emulate dark` (also `emulate locale`, `emulate timezone`)         |
-| 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`                                                                    |
-| replay what I clicked through        | `watch on`, click around, `watch save flow.txt`, then `pw-repl send --file flow.txt` |
-| record requests and console together | `capture on`, then `capture off`                                                     |
-| fake a backend response              | `route <glob> <status> <json>`, `route <glob> abort`                                 |
-| change or slow an API response       | `route <glob> patch <json>`, `route <glob> delay <secs>`                             |
-| cut or slow the whole network        | `network off`, `network slow`, then `network on`                                     |
-| record a video of the page           | `record on`, then `record off` (`help video` for a take with a pointer)              |
-| show a pointer where the agent acts  | `cursor on`, then `cursor off` (in screenshots and videos)                           |
-| say what is happening on screen      | `toast <text>`, then `toast off` (`--duration=3s` hides it by itself)                |
-| point something out on the page      | `highlight <ref>` draws a box; `highlight off` hides it                              |
-| clean up                             | `modes off`                                                                          |
+| I want to…                            | Commands                                                                             |
+| ------------------------------------- | ------------------------------------------------------------------------------------ |
+| see where I am                        | `tab` (it marks the tab you are looking at `(visible)`), `info`                      |
+| see what is on the page               | `snapshot`, `screenshot`                                                             |
+| do something on it                    | `click`, `fill`, `type`, `press`                                                     |
+| click what has no selector (a canvas) | `mouseclick <x> <y>`                                                                 |
+| run some JavaScript in the page       | `eval document.title`                                                                |
+| wait for a page or element            | `wait load`, `wait <selector>`, `wait <selector> --gone`, `wait text <text>`         |
+| choose a file in a file input         | `upload <selector> <file>`                                                           |
+| see it as a phone, or in dark mode    | `emulate mobile`, `emulate dark` (also `emulate locale`, `emulate timezone`)         |
+| 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`                                                                    |
+| replay what I clicked through         | `watch on`, click around, `watch save flow.txt`, then `pw-repl send --file flow.txt` |
+| record requests and console together  | `capture on`, then `capture off`                                                     |
+| fake a backend response               | `route <glob> <status> <json>`, `route <glob> abort`                                 |
+| change or slow an API response        | `route <glob> patch <json>`, `route <glob> delay <secs>`                             |
+| cut or slow the whole network         | `network off`, `network slow`, then `network on`                                     |
+| record a video of the page            | `record on`, then `record off` (`help video` for a take with a pointer)              |
+| show a pointer where the agent acts   | `cursor on`, then `cursor off` (in screenshots and videos)                           |
+| say what is happening on screen       | `toast <text>`, then `toast off` (`--duration=3s` hides it by itself)                |
+| point something out on the page       | `highlight <ref>` draws a box; `highlight off` hides it                              |
+| clean up                              | `modes off`                                                                          |
 
 `help <topic>` lists the rest, and `help <command>` has usage and caveats.
 

package/bin/pw-repl.js

@@ -15,7 +15,8 @@ const USAGE = `Usage:
       see everything a background REPL does, and type commands to it; Ctrl-C leaves it running
 
   pw-repl stop [-e endpoint]
-      stop a background REPL, and say what became of each recording it ended
+      stop a background REPL, and say what became of each recording it ended; its socket is removed, its
+      log stays
 
   pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] [--no-vars] <command...> | --file <file>
       run one command in a running REPL and print its output; --file runs a file of them, one per line

package/lib/elements.js

@@ -465,6 +465,27 @@ const commands = {
     out.log(`Moved the mouse to ${x}, ${y}`);
   },
 
+  // A click at a point, as Playwright's mouse.click: for what has no selector, such as a marker drawn on a canvas.
+  async mouseclick(line) {
+    const usage = 'mouseclick <x> <y> [left|right|middle] [--delay=<ms>]';
+    const held = /(?:^|\s)--delay(?:=|\s+)(\S*)(?=\s|$)/.exec(line || '');
+    if (held && !/^\d+$/.test(held[1])) throw new Error(`Usage: ${usage}, the ms between press and release, e.g. mouseclick 400 300 --delay=500`);
+    const words = (held ? line.replace(held[0], ' ') : line || '').trim().split(/\s+/).filter(Boolean);
+    const button = /^[a-z]+$/.test(words[words.length - 1] || '') ? mouseButton(words.pop(), 'mouseclick <x> <y>') : 'left';
+    const [x, y, extra] = numbers(words.join(' '), usage);
+    if (y === undefined || extra !== undefined) throw new Error(`Usage: ${usage}, in CSS pixels from the top left of the viewport`);
+    stepTarget(state.page, null, { x, y });
+    await glideTo(state.page, x, y);
+    await state.page.mouse.move(x, y);
+    tabState(state.page).mouseAt = { x, y };
+    // The ring shows at the press, as mousedown's does, while a --delay holds the button.
+    await state.page.mouse.down({ button });
+    await showClick(state.page);
+    if (held) await new Promise(resolve => setTimeout(resolve, Number(held[1])));
+    await state.page.mouse.up({ button });
+    out.log(`Clicked the ${button} button at ${x}, ${y}`);
+  },
+
   async mousedown(args) {
     const button = mouseButton(args, 'mousedown');
     await glideToMouse();

package/lib/help.js

@@ -70,7 +70,7 @@ tab on its own lists them all.`,
     intro: `Selectors are Playwright selectors (CSS, text=..., role=...) or snapshot refs such as e5.
 Commands use the first match (click, dblclick and hover the first they can use: help click); see help
 fill for selectors with spaces. mousemove and the other mouse commands act at a point instead.`,
-    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mousemove', 'mousedown', 'mouseup', 'mousewheel'],
+    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mousemove', 'mouseclick', 'mousedown', 'mouseup', 'mousewheel'],
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
@@ -219,8 +219,21 @@ events) and that the outcome is unknown; Playwright's full call log goes to the
 eval (r => [r.x + r.width / 2, r.y + r.height / 2])(document.querySelector("#map")
   .getBoundingClientRect())
 
-A click at a point: mousemove <x> <y>, mousedown, mouseup. A drag: mousedown, then mousemove to another
-point, then mouseup.`,
+A click at a point: mouseclick <x> <y>. A drag: mousedown, then mousemove to another point, then mouseup.`,
+  },
+  mouseclick: {
+    usage: 'mouseclick <x> <y> [button]',
+    summary: 'click at a point in the viewport',
+    args: [
+      ['<x> <y>', 'CSS pixels from the top left of the tab\'s viewport, as for mousemove.'],
+      ['[button]', 'left, right or middle. Default: left.'],
+    ],
+    options: [
+      ['--delay=<ms>', 'holds the button down this long between press and release, as Playwright\'s mouse.click delay. Default: 0.'],
+    ],
+    detail: `For what has no selector, such as a marker drawn on a canvas; anything a selector finds is better
+clicked with click, which waits for it. help mousemove shows how to find a point. The mouse stays at the point, for a mousewheel or mousedown after
+it. The cursor (help cursor) moves there first and shows a ring at the press.`,
   },
   mousedown: { usage: 'mousedown [button]', summary: 'press a mouse button where the mouse is (left, right or middle)' },
   mouseup: { usage: 'mouseup [button]', summary: 'release a mouse button where the mouse is' },
@@ -460,7 +473,7 @@ circle). That changes the page, so put it back afterwards, as it was if it had a
       ['-d, --delay <secs>', 'counts down out loud first, up to 60, so someone can hold a hover or open a menu.'],
       ['--filename=<file>', 'saves it there instead (a JPEG if it ends in .jpg). Relative to the REPL\'s folder; through pw-repl send, the sender\'s. It never replaces a file.'],
     ],
-    detail: `Where: $PW_SCREENSHOT_DIR; without it, next to the REPL's socket when it serves on one of its own, or
+    detail: `Where: $PW_SCREENSHOT_DIR (a folder that exists); without it, next to the REPL's socket when it serves on one of its own, or
 else in /tmp.
 
 It brings the tab to the front of its window first: Chrome draws only the tab in front. The image is
@@ -511,8 +524,8 @@ shows in screenshots and recordings. Selectors, snapshot and text don't see it,
     detail: `The REPL's clicks and typing don't move a pointer on screen, so a recording shows things happening
 with nothing pointing at them. With the cursor on, these commands move it smoothly to their element or
 point before they act: click, dblclick, hover, fill, type <selector>, press <selector>, select, check,
-uncheck, upload and mousemove. Each move takes 150 to 600ms by distance (300 to 1000ms while the tab
-records), and the command waits for it. Clicks (click, dblclick, check, uncheck, mousedown, and upload
+uncheck, upload, mousemove and mouseclick. Each move takes 150 to 600ms by distance (300 to 1000ms while the tab
+records), and the command waits for it. Clicks (click, dblclick, check, uncheck, mouseclick, mousedown, and upload
 when it clicks a button) show a ring where they land.
 
 Only the drawing moves: no mouse events are sent along the way, so the page gets the same input as with
@@ -905,6 +918,11 @@ Different on purpose, since the browser may be someone else's too:
     return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${renderCommand(topicOrCommand)}` : text;
   }
   if (Object.hasOwn(COMMANDS, topicOrCommand)) return renderCommand(topicOrCommand);
+  // Not a topic: the mouse commands are in interact, with the others that act on the page.
+  if (topicOrCommand === 'mouse') {
+    const mice = TOPICS.interact.commands.filter(c => c.startsWith('mouse'));
+    return ['The mouse commands, which act at a point (part of help interact):', '', ...commandLines(mice)].join('\n');
+  }
   const full = /^(\S+)\s+--all$/.exec(topicOrCommand);
   if (full && Object.hasOwn(COMMANDS, full[1])) return renderCommand(full[1], true);
   // A playwright-cli name: what it runs here, with that command's help.

package/lib/record.js

@@ -392,7 +392,7 @@ function videoTime(rec) {
 // What a step is, for its line: the command and what it acts on, never what it types or chooses, the
 // code it runs or the URL it goes to, which can hold a password or a token. A steps file goes where the
 // video goes, and the video shows a password as dots.
-const WHOLE = new Set(['click', 'dblclick', 'hover', 'check', 'uncheck', 'mousemove', 'mousedown', 'mouseup', 'mousewheel']);
+const WHOLE = new Set(['click', 'dblclick', 'hover', 'check', 'uncheck', 'mousemove', 'mouseclick', 'mousedown', 'mouseup', 'mousewheel']);
 const TARGET_FIRST = new Set(['fill', 'type', 'select', 'press', 'upload']);
 function stepLabel(cmd, args) {
   if (WHOLE.has(cmd)) {

package/lib/start.js

@@ -27,6 +27,14 @@ curl ${CDP_URL}/json/version checks that it answers; PW_CDP_URL points at a brow
 Or let pw-repl start a private one for this REPL: pw-repl run --launch (or serve --launch).`;
 }
 
+// The command this REPL was started with, to start it again: a background one runs as serve, with
+// --background left out of its arguments.
+function startedAs() {
+  const args = process.argv.slice(2).map(a => (/[\s"'$]/.test(a) ? JSON.stringify(a) : a));
+  if (process.env.PW_REPL_PID_FILE && args[0] === 'serve') args.splice(1, 0, '--background');
+  return ['pw-repl', ...args].join(' ');
+}
+
 async function start(options) {
   const START_URL = options.startUrl || process.env.PW_START_URL || null;
   // First, so a terminal or a log says which pw-repl ran; where names the skill to compare a saved one with.
@@ -60,7 +68,7 @@ async function start(options) {
     state.connectionLost = true;
     state.stopping = true;
     process.exitCode = 1;
-    out.error('Chromium connection lost; queued commands will not run.');
+    out.error(`Chromium connection lost; queued commands will not run. Start the REPL again to carry on: ${startedAs()}`);
     void shutdown().then(beforeExit).then(() => process.exit(1));
   });
   out.log('Connected to Chromium via CDP');

package/package.json

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

package/skill/SKILL.md

@@ -187,10 +187,9 @@ blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --hel
 ## Learn the commands
 
 Run `pw-repl send help`. It lists seven topics; `help <topic>` lists their commands, `help <command>`
-gives usage and caveats, and `help --all` prints everything at once. pw-repl answers it itself: it needs
-no running REPL, and never reaches one. The
-help is the command reference; this file does not repeat it. If you know playwright-cli, its command
-names work too (`help playwright-cli` lists them).
+gives usage and caveats: read it before you use a command, since this file does not repeat them. `help
+--all` prints everything at once. pw-repl answers help itself: it needs no running REPL, and never
+reaches one. If you know playwright-cli, its command names work too (`help playwright-cli` lists them).
 
 ### Coming from playwright-cli
 
@@ -252,10 +251,10 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - Playwright's own Chromium and ffmpeg are found where Playwright installs them:
   `PLAYWRIGHT_BROWSERS_PATH`, or `~/.cache/ms-playwright`.
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
-- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots, read when it starts, not by `send`. Without
-  it, a REPL on a socket of its own saves them next to its socket, and any other in `/tmp`. `screenshot`
-  prints each file's path; other REPLs may save theirs in the same place. Remove only your own, and keep
-  those too if they are needed, e.g. as evidence or as something to hand over.
+- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots (a folder that exists), read when it starts,
+  not by `send`. Without it, a REPL on a socket of its own saves them next to its socket, and any other
+  in `/tmp`. `screenshot` prints each file's path; other REPLs may save theirs in the same place. 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 `serve`
   serves on and `send` looks for when neither is given (default `/tmp/pw-repl.sock`).