pw-repl 0.4.2 → 0.5.0

package/lib/help.js

@@ -44,8 +44,8 @@ const TOPICS = {
     commands: ['tab', 'goto', 'back', 'forward', 'reload', 'info'],
   },
   interact: {
-    intro: 'Selectors are Playwright selectors (CSS, text=..., role=...) or snapshot refs such as e5.\nCommands use the first match; see help fill for selectors with spaces.',
-    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload'],
+    intro: 'Selectors are Playwright selectors (CSS, text=..., role=...) or snapshot refs such as e5.\nCommands use the first match (click, dblclick and hover the first they can use: help click); see help\nfill 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'],
   },
   inspect: {
     intro: 'Output is capped; --all right after the command, or at the end, shows everything (text --all body).',
@@ -91,7 +91,7 @@ const COMMANDS = {
   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.',
+    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.\n\nA page that does not load says why, as wait load does: a failed request, after which the tab shows\nChrome\'s error page (info names the URL that failed), or an answer with no page (a 204), which\nleaves the tab where it was. reload, back and forward say it the same way.',
   },
   back: {
     usage: 'back',
@@ -103,11 +103,23 @@ const COMMANDS = {
   info: { usage: 'info', summary: 'selected tab URL, title and viewport' },
   click: {
     usage: 'click <selector> [button]',
-    summary: 'click the first match',
-    detail: 'After a ref or a quoted selector, a button (left, right, middle) may follow: click e5 right.\n--modifiers=<key>[,<key>] holds keys down meanwhile (Alt, Control, ControlOrMeta, Meta, Shift).',
+    summary: 'click the first match that can be clicked',
+    detail: 'After a ref or a quoted selector, a button (left, right, middle) may follow: click e5 right.\n--modifiers=<key>[,<key>] holds keys down meanwhile (Alt, Control, ControlOrMeta, Meta, Shift).\n\nWhen a selector matches several elements, hidden ones and ones covered by something else (a dialog\'s\noverlay) are passed over, and it says which match it used: Clicked: text=Buy (match 3 of 4; ...). If\nnone can be clicked within 5s, it says why for each and does nothing. A ref, or a single match, is\nclicked as it is, waiting up to 5s for it to be ready.\n\nTimed out after it began acting, it says what stopped it (e.g. <div class="overlay"> intercepts\npointer events) and that the outcome is unknown; Playwright\'s full call log goes to the REPL\'s pane\nor log.',
+  },
+  dblclick: { usage: 'dblclick <selector> [button]', summary: 'double-click, choosing the match as click does' },
+  hover: { usage: 'hover <selector>', summary: 'hover, choosing the match as click does' },
+  mousemove: {
+    usage: 'mousemove <x> <y>',
+    summary: 'move the mouse to a point in the viewport',
+    detail: 'x and y are CSS pixels from the top left of the tab\'s viewport (not the page), as mouse events\nhave them. A snapshot has no coordinates; eval of getBoundingClientRect gives an element\'s centre:\neval (r => [r.x + r.width / 2, r.y + r.height / 2])(document.querySelector("#map")\n  .getBoundingClientRect())\n\nA click at a point: mousemove <x> <y>, mousedown, mouseup. A drag: mousedown, then mousemove to\nanother point, then mouseup.',
+  },
+  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' },
+  mousewheel: {
+    usage: 'mousewheel <dx> <dy>',
+    summary: 'turn the wheel where the mouse is',
+    detail: 'Wheel events at the mouse\'s point (mousemove puts it there), in CSS pixels: positive dy scrolls\ndown. A map zooms around that point: mousemove 400 300, then mousewheel 0 -300 zooms in. It returns\nonce the events are sent, not once the page has scrolled or redrawn.',
   },
-  dblclick: { usage: 'dblclick <selector> [button]', summary: 'double-click the first match; button and --modifiers as for click' },
-  hover: { usage: 'hover <selector>', summary: 'hover the first match' },
   fill: {
     usage: 'fill <selector> <value> [--submit]',
     summary: 'clear an input and fill it',
@@ -130,12 +142,12 @@ 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. 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. --regex <pattern> is --grep by a\nregular expression: snapshot --regex "Total: \\d+".\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. --regex <pattern> is --grep by a\nregular expression: snapshot --regex "Total: \\d+".\n\nAn element with no role or name of its own (a card that is only a div) is left out, with its ref;\nsnapshot --full keeps it.\n\nsnapshot e3 outlines one element, and the refs of the last snapshot keep working. A ref (e3, or f1e3\nin newer Playwright) works as a selector in any command: click e3. Refs can change when the page\nchanges (e102 may become f4e98), so take a new snapshot after it does. snapshot <selector> (not a\nref) gives new refs, and those from before stop working.\n\nOutput over 60 lines ends with a line count.',
   },
   watch: {
     usage: 'watch on [--changes] [--live] | off | [n|new]',
     summary: 'record what happens in the tab; show the last n steps',
-    detail: 'Off until watch on; a watch on after watch off starts a new recording. Records clicks, typing (once\nit pauses), Enter and Escape, form changes, submits and navigations, each described by role and name\nlike snapshot, with up to 5 of the requests it caused underneath, each with its status as in requests\n(body <#> for one), leaving out scripts and what requests hides. The REPL\'s own fill is recorded\nas type.\n\nFrom its first watch on, a tab keeps response bodies of up to 100 KB, so body <#> still shows one\nafter the tab navigates, even when the page navigates as soon as the request answers.\n\nwatch on --next-tab [url-part] returns at once, then waits for the next tab someone opens (tab new,\na client\'s own, does not count), or the next whose URL contains url-part, and watches it from its\nfirst page and selects it for the client that asked: for a tab someone is about to open. It takes\n--changes and --live too; watch off stops waiting, and modes lists it.\n\nwatch on its own says whether it is on and shows the last 20 steps; watch <n> shows the last n.\nwatch new shows only the steps it has not shown yet, and requests that have since arrived for the\nlast one.\n\n--live also prints each step in the REPL window (never in the server\'s answer to a command) once it\nsettles, with its requests and changes, marked [watch], or [watch <url>] for a tab that is not the\nselected one. A step cut short by the next one, or by watch off, prints at once; changes it made\nthen show under the next step.\n\n--changes also shows what each step changed on the page once it settles, in up to 5 lines: + added,\n- removed, ~ changed, each element once with the first names inside it. Not for navigations: what a\npage changes on its own after a step settles (data arriving later) shows under the next step.\n\nA watch belongs to the tab, not to a client: every client sees the same steps, watch new\'s place is\nshared, and anyone\'s watch off stops it.\n\nTyped values are not recorded, and password fields not at all; --changes leaves out field values,\nbut what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.',
+    detail: 'Off until watch on; a watch on after watch off starts a new recording. Records clicks, typing (once\nit pauses), Enter and Escape, form changes, submits and navigations, each described by role and name\nlike snapshot, with up to 5 of the requests it caused underneath, each with its status as in requests\n(body <#> for one), leaving out scripts and what requests hides. The REPL\'s own fill is recorded\nas type. A double-click shows as two clicks; hovering and moving the mouse are not recorded.\n\nFrom its first watch on, a tab keeps response bodies of up to 100 KB, so body <#> still shows one\nafter the tab navigates, even when the page navigates as soon as the request answers.\n\nwatch on --next-tab [url-part] returns at once, then waits for the next tab someone opens (tab new,\na client\'s own, does not count), or the next whose URL contains url-part, and watches it from its\nfirst page and selects it for the client that asked: for a tab someone is about to open. It takes\n--changes and --live too; watch off stops waiting, and modes lists it.\n\nwatch on its own says whether it is on and shows the last 20 steps; watch <n> shows the last n.\nwatch new shows only the steps it has not shown yet, and requests that have since arrived for the\nlast one.\n\n--live also prints each step in the REPL window (never in the server\'s answer to a command) once it\nsettles, with its requests and changes, marked [watch], or [watch <url>] for a tab that is not the\nselected one. A step cut short by the next one, or by watch off, prints at once; changes it made\nthen show under the next step.\n\n--changes also shows what each step changed on the page once it settles, in up to 5 lines: + added,\n- removed, ~ changed, each element once with the first names inside it. Not for navigations: what a\npage changes on its own after a step settles (data arriving later) shows under the next step.\n\nA watch belongs to the tab, not to a client: every client sees the same steps, watch new\'s place is\nshared, and anyone\'s watch off stops it.\n\nTyped values are not recorded, and password fields not at all; --changes leaves out field values,\nbut what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.',
   },
   text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
   html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match' },
@@ -143,7 +155,7 @@ const COMMANDS = {
   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.',
+    detail: 'For the first match, one line each: the event, how it was added (capture, once, passive), the\nstart of the handler, where ↵ marks a line break, and its line in its script. --all shows each handler\nwhole, as written. Listeners added on a parent (e.g. document, for delegation) are not the element\'s\nown: check listeners document too. Those Playwright adds to window as it acts are left out, and it\nsays how many.',
   },
   count: { usage: 'count <selector>', summary: 'number of matches' },
   visible: { usage: 'visible <selector>', summary: 'whether the first match is visible' },
@@ -152,7 +164,7 @@ const COMMANDS = {
   screenshot: {
     usage: 'screenshot [<ref>] [--full] [-d <secs>] [name]',
     summary: 'save a PNG of the viewport, --full page or an element',
-    detail: 'Saved as screenshot-<name or timestamp>.png in $PW_SCREENSHOT_DIR; without it, next to the REPL\'s\nsocket when it serves on one of its own, or else in /tmp. --filename=<file> saves it there instead (a\nJPEG if it ends in .jpg), relative to the folder pw-repl send runs in; it never replaces a file.\n\nscreenshot e5 saves only that element, from a snapshot ref. --full-page is --full.\n\nIt brings the tab to the front of its window first: Chrome draws only the tab in front. The image\nis at CSS pixel size, one 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.',
+    detail: 'Saved as screenshot-<name or timestamp>.png in $PW_SCREENSHOT_DIR; without it, next to the REPL\'s\nsocket when it serves on one of its own, or else in /tmp. --filename=<file> saves it there instead (a\nJPEG if it ends in .jpg), relative to the folder pw-repl send runs in; it never replaces a file.\n\nscreenshot e5 saves only that element, from a snapshot ref. --full-page is --full.\n\nIt brings the tab to the front of its window first: Chrome draws only the tab in front. The image\nis at CSS pixel size, one image pixel per CSS pixel. While emulate mobile is on, it is what the\nphone shows: a page laid out wider than the phone (no viewport meta tag) comes out shrunk to fit.\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: {
@@ -163,13 +175,13 @@ const COMMANDS = {
   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 to be visible, and wait text <text> for text to be;\nwait request <url-part|glob> waits for a matching response, counting one that finished since the\nprevious command began (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.',
+    detail: 'wait <selector> waits for a matching element to be visible, and wait text <text> for text to be;\nwait request <url-part|glob> waits for a matching response, counting one that finished since the\nprevious command began, or is still under way (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, in milliseconds (maximum 3600000)' },
   requests: {
     usage: 'requests [--all] [n] [url-filter]',
     summary: 'the selected tab\'s last n requests (default 20)',
-    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: #number, time,\nmethod, status (HTTP code, pending, no response, failed: <reason>, or <code> faked), duration, URL.\nA request that finished a moment ago can still show pending.\n\nbody <#> shows what a request got back.\n\nImages, fonts, stylesheets, media and extension requests are hidden unless --all is given.\n\nurl-filter is a substring: requests 20 /api/ shows API calls only, e.g. when dev-server scripts\ncrowd the list. --regex <pattern>, at the end, matches URLs by a regular expression instead.',
+    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept, of every kind the page\nrequests (not the browser\'s own, such as the favicon). Each line: #number, time, method, status (HTTP\ncode, pending, no response, failed: <reason>, <code>, then failed: <reason> when its body was cut\noff, or <code> faked), duration, kind (document, fetch, xhr, script, image, ...), URL. A request that\nfinished a moment ago can still show pending.\n\nn is how many of the latest to show (default 20). When more match, a first line says so: (last 20\nof 112 kept; requests 112 shows them all). A page often makes more than 20 in one load. A line\n"--- the page loads <url>" marks where each page load starts, even when a filter hides that request.\n\nbody <#> shows what a request got back.\n\nImages, fonts, stylesheets, media and extension requests are hidden unless --all is given.\n\nurl-filter is a substring: requests 20 /api/ shows API calls only, e.g. when dev-server scripts\ncrowd the list. --regex <pattern>, at the end, matches URLs by a regular expression instead.',
   },
   body: {
     usage: 'body [--all] <#>|<url-part>',
@@ -179,7 +191,7 @@ const COMMANDS = {
   console: {
     usage: 'console [--all] [n] [level|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. A\n"--- the page loaded <url>" line marks each load after the first message shown.\n\nA level (error, warning, info, debug) shows that level and those above it: console warning shows\nwarnings and errors, page errors among them. info, which leaves out debug, is what playwright-cli\nshows by default. Anything else is a filter, matching part of the type or the text.\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.',
+    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. A\n"--- the page loaded <url>" line marks each load after the first message shown.\n\nA level (error, warning, info, debug) shows that level and those above it: console warning shows\nwarnings and errors, page errors among them. info, which leaves out debug, is what playwright-cli\nshows by default. Anything else is a filter, matching part of the type or the text.\n\nn is how many of the latest to show (default 20); when more match, a first line says so.\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',
@@ -189,7 +201,7 @@ const COMMANDS = {
   route: {
     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, or no body; it never\n                              reaches the network, so it still answers while the network is off.\n                              The body is the rest of the line. Another kind needs its type:\n                              route <glob> 200 --content-type=text/plain hello\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. A glob may\nbe quoted.\n\nExample: route **/api/cart patch {"total": 0}',
+    detail: 'route <glob> <status> <json>  answer with this status (200-599) and JSON, or no body; it never\n                              reaches the network, so it still answers while the network is off.\n                              The body is the rest of the line. Another kind needs its type:\n                              route <glob> 200 --content-type=text/plain hello\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; a\n                              patch that is not an object (an array) replaces the whole body\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 (one the page makes after reload or\na click has answered shows only in the window: wait request <glob> waits for it); requests shows a fake\nas <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. A glob may\nbe quoted.\n\nExample: route **/api/cart patch {"total": 0}',
   },
   network: {
     usage: 'network [on|off|slow [<ms> [<kbps>]]]',
@@ -221,7 +233,7 @@ const COMMANDS = {
   help: { usage: 'help [topic | command | --all]', summary: 'this help; --all prints every topic and command in full' },
   quit: {
     usage: 'quit',
-    summary: 'disconnect, leaving Chromium running',
+    summary: 'disconnect, leaving Chromium running (one --launch started stops too)',
     detail: 'Runs immediately, even while another command is waiting. Only available at the prompt.',
   },
 };

package/lib/runner.js

@@ -44,6 +44,7 @@ function parseInput(line) {
 }
 
 function isUncertain(error) {
+  if (typeof error.uncertain === 'boolean') return error.uncertain;
   const message = error.message || '';
   if (!/timed out|timeout|connection (?:lost|closed)/i.test(message)) return false;
   // Playwright's call log shows whether the element was ever found; if not, nothing was done.

package/lib/send.js

@@ -100,6 +100,7 @@ async function send(options) {
   if (way.kind === 'tmux' && options.client) return fail('-c needs the command server (pw-repl serve); a REPL in tmux has no clients');
   if (way.kind === 'tmux') return viaTmux(way.session, command, timeoutMs);
   const answer = await client.request(way.endpoint, command, timeoutMs, name);
+  if (answer.result?.starting) return fail(`${answer.result.output} (pw-repl where says when it serves)`);
   if (answer.result) {
     if (answer.result.output) console.log(answer.result.output);
     if (answer.result.unconfirmed) { console.error('completion not confirmed'); return 2; }
@@ -115,6 +116,9 @@ async function send(options) {
 
 // Reports the route a command would take, checking it the way a command would.
 async function where(options) {
+  // First, whatever else is reachable: a saved skill is compared with it (pw-repl skill: Start it).
+  const skill = require('./skill').current();
+  console.log(`skill: ${skill.hash} (pw-repl ${skill.version})`);
   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
@@ -126,6 +130,11 @@ async function where(options) {
   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 (info?.status === 'starting') {
+      // Not an error, but not serving yet: exit 64 as for no REPL, so a loop on where waits for it.
+      console.log(`server: ${name} (the REPL was started with pw-repl serve and is starting: ${info.step || 'starting'}; retry shortly)`);
+      return 64;
+    }
     if (info) {
       const background = require('./background').describeBackground(way.endpoint);
       console.log(`server: ${name} (the REPL was started with pw-repl serve${background ? ' --background' : ''})`);

package/lib/server.js

@@ -31,7 +31,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', browser: state.cdpUrl, launched: state.launched });
+  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: state.serving ? 'ok' : 'starting', step: state.serving ? undefined : state.startingStep, 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 = '';
@@ -50,6 +50,8 @@ function handle(req, res) {
     if (client !== undefined && client !== null && !CLIENT_NAME.test(client)) {
       return send(res, 400, { status: 'error', output: 'A client name is 1-40 letters, digits, dots, dashes and underscores' });
     }
+    // Bound before the browser is reached, so where and send find it while it starts.
+    if (!state.serving) return send(res, 503, { status: 'error', starting: true, output: `The REPL is starting (${state.startingStep}); retry shortly` });
     const result = await runner.submit(command.trim(), client || null);
     if (!result.uncertain) return send(res, 200, { status: result.status, output: result.output });
     // unconfirmed: the command may or may not have done what it was sent to do.
@@ -71,6 +73,8 @@ async function clearStaleSocket(socketPath) {
   fs.unlinkSync(socketPath);
 }
 
+// Listens before the REPL connects, answering "starting" until the function it returns is called,
+// so a REPL that is still connecting is not taken for one without a server.
 async function serve(endpointArg) {
   const endpoint = parseEndpoint(endpointArg);
   if (endpoint.socket) await clearStaleSocket(endpoint.socket);
@@ -90,7 +94,10 @@ async function serve(endpointArg) {
   const removeSocket = () => { if (endpoint.socket) try { fs.unlinkSync(endpoint.socket); } catch {} };
   onShutdown(() => { server.close(); removeSocket(); });
   process.on('exit', removeSocket);
-  out.log(`Serving commands on ${describe(endpoint)}`);
+  return () => {
+    state.serving = true;
+    out.log(`Serving commands on ${describe(endpoint)}`);
+  };
 }
 
 module.exports = { serve };

package/lib/skill.js

@@ -0,0 +1,29 @@
+// The agent skill, stamped as it is printed with the version it came from and a hash of its text,
+// so a saved copy can be told apart from the skill of the pw-repl being run.
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const FILE = path.join(__dirname, '..', 'skill', 'SKILL.md');
+const STAMP = '<!-- pw-repl skill stamp -->';
+
+// Only the skill's own text counts: not the stamp line, nor the Custom rules a person adds to a
+// saved copy. Line endings are made the same first, so a Windows checkout gets the same hash.
+function hashOf(text) {
+  const own = text.replace(/\r\n?/g, '\n').split('\n## Custom rules\n')[0]
+    .split('\n').filter(line => line !== STAMP && !/^This skill is from pw-repl /.test(line)).join('\n').trimEnd();
+  return crypto.createHash('sha256').update(own).digest('hex').slice(0, 8);
+}
+
+function current() {
+  const text = fs.readFileSync(FILE, 'utf8');
+  return { text, hash: hashOf(text), version: require('../package.json').version };
+}
+
+// What `pw-repl skill` prints.
+function stamped() {
+  const { text, hash, version } = current();
+  return text.replace(STAMP, `This skill is from pw-repl ${version} (skill ${hash}).`);
+}
+
+module.exports = { STAMP, hashOf, current, stamped };

package/lib/start.js

@@ -29,7 +29,9 @@ Or let pw-repl start a private one for this REPL: pw-repl run --launch (or serve
 async function start(options) {
   const START_URL = options.startUrl || process.env.PW_START_URL || null;
   if (options.pidFile) require('./background').markStopInLog();
+  const serving = options.serve ? await require('./server').serve(options.endpoint) : null;
   if (options.launch) {
+    state.startingStep = 'launching a Chromium of its own';
     const launched = await require('./launch').launch({ headed: options.headed, extraArgs: options.chromeArgs });
     onBeforeExit(launched.stop);
     CDP_URL = launched.url;
@@ -41,6 +43,7 @@ async function start(options) {
   state.cdpUrl = CDP_URL;
   state.launched = !!options.launch;
   out.log(`Connecting to ${CDP_URL}...`);
+  state.startingStep = 'connecting to the browser';
   try { state.browser = await chromium.connectOverCDP(CDP_URL, { timeout: CONNECT_TIMEOUT }); }
   catch (error) { throw new Error(connectHelp(error)); }
   if (state.stopping) {
@@ -72,6 +75,7 @@ async function start(options) {
   }
 
   if (START_URL) {
+    state.startingStep = 'opening the start URL';
     state.page = await openTab();
     startTabs.add(state.page);
     await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
@@ -82,7 +86,7 @@ async function start(options) {
   await listTabs();
   out.log('');
   if (!state.page) out.log('No tab is selected: tab new [url] opens one of your own, tab <index|url-part> selects one.');
-  if (options.serve) await require('./server').serve(options.endpoint);
+  if (serving) serving();
   // In the background there is no prompt: commands come only through the server.
   if (options.pidFile) {
     require('./background').claimPidFile(options.pidFile);

package/lib/state.js

@@ -14,6 +14,9 @@ const state = {
   // The browser the REPL is connected to, and whether --launch started it.
   cdpUrl: null,
   launched: false,
+  // The command server takes commands; before, it answers that the REPL is starting, and what it is doing.
+  serving: false,
+  startingStep: 'starting',
   stopping: false,
   connectionLost: false,
   shutdownFailed: false,

package/package.json

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

package/skill/SKILL.md

@@ -1,16 +1,30 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, requests and their bodies, console messages, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, and recording what the person does. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
-allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl:*)
+description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, and recording what the person does. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
+allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 ---
 
 # pw-repl
 
+<!-- pw-repl skill stamp -->
+
 pw-repl (playwright-repl) is a REPL that drives a running Chromium over CDP. The browser may be a
 shared session: a person can have their own tabs open in it and be using it while you work.
 
-`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`.
+`pw-repl` below is the command the `pw-repl` npm package installs. Without a global install, use
+`npx pw-repl@latest` in its place, in that same form for every command, so each one runs the same
+version; from a clone, `<clone>/bin/pw-repl.js`.
+
+`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. When that
+is not the skill named at the top of this file, tell the user before going on:
+
+- if this file's pw-repl version is newer than that one, pw-repl is behind: say "⚠️ pw-repl is older
+  than this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
+  `npm install -g pw-repl` updates it."
+- otherwise, the skill is: ask "⚠️ This pw-repl skill is out of date (from pw-repl <this file's
+  version>; <that version> has a newer one). Update it? Everything but its Custom rules section will be
+  replaced." On a yes, save what `pw-repl skill` prints over this file, with this file's Custom rules
+  section in place of the new one's.
 
 ## Arguments
 
@@ -20,15 +34,18 @@ the sections below are how to carry it out. With no args, get a REPL running and
 
 ## Start it
 
-`pw-repl where` says whether a REPL is running and how `send` reaches it. There are three ways to run
-one; each takes an optional start URL, which opens in a new tab.
+`pw-repl where` says whether a REPL is running and how `send` reaches it, or that one is still starting
+(retry shortly; it exits 64 until the REPL serves, as when none is running). Right after you start one,
+for a moment before its process is up, it can still say none is there: retry for a few seconds before
+taking that as a failed start. There are three ways to run one; each takes an optional start URL, which
+opens in a new tab.
 
 - `pw-repl serve --background` runs it detached, with a command server on `/tmp/playwright-repl.sock`
   (owner-only) and its output in `/tmp/playwright-repl.log`. `pw-repl attach` shows everything it does
   and takes commands; `pw-repl stop` stops it. It returns once the REPL serves; Ctrl-C before then gives
   up on the start, stops the REPL, exits 130, and says so in the log.
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
-  `pw[serve]>`.
+  `pw[serve]>`. It stops at that prompt (`quit`, or Ctrl-C); `pw-repl stop` is for a background one.
 - 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, on a free port of
   its own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns once
@@ -79,11 +96,12 @@ pw-repl send tab
 pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
 ```
 
-Always send commands with `pw-repl send`; don't type into the pane yourself. The words after `send`
-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:
+Always send commands with `pw-repl send`; don't type into the pane yourself, except `quit` at the prompt
+of a REPL of your own, which `send` refuses. The words after `send` 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
@@ -166,6 +184,11 @@ pw-repl send -c <name> close                        # your modes off; tab close
   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.
+- pw-repl does not record video. For one of a flow in a browser of its own, Microsoft's playwright-cli (a
+  separate tool, the npm package `@playwright/cli`: `video-start`, `video-stop`); for this browser as the
+  person sees it, a screen recorder (`ffmpeg -f x11grab`, macOS `screencapture -v`, OBS). A screen
+  recorder records their whole screen, not the tab: ask before starting one, or have them start it. A
+  headless browser is not on the screen, so it does not show.
 
 ## Environment