pw-repl 0.4.1 → 0.5.0

package/lib/help.js

@@ -44,11 +44,11 @@ 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; put --all right after the command for everything (e.g. text --all body).',
+    intro: 'Output is capped; --all right after the command, or at the end, shows everything (text --all body).',
     commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'emulate', 'wait', 'sleep'],
   },
   network: {
@@ -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 (maximum 3600000)' },
+  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/launch.js

@@ -1,13 +1,19 @@
 // pw-repl run|serve --launch: a Chromium of the REPL's own, started for it and
 // stopped with it, in a profile that is removed afterwards. It is the quick
 // start; a browser set up any other way is reached with PW_CDP_URL instead.
+// A --user-data-dir among the flags after -- is used instead, and kept.
 const { spawn } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
 const START_TIMEOUT = 20000;
-const STOP_TIMEOUT = 5000;
+// Stopping: a moment to connect and ask it to close, a few seconds to close, as long again after SIGTERM,
+// and up to 3s to remove a profile its helpers are still writing to. STOP_WORST is what it can take.
+const CLOSE_CONNECT_TIMEOUT = 2000;
+const CLOSE_TIMEOUT = 3000;
+const TERM_TIMEOUT = 3000;
+const STOP_WORST = CLOSE_CONNECT_TIMEOUT + CLOSE_TIMEOUT + TERM_TIMEOUT + 3000;
 const INSTALL = 'npx playwright-core install chromium';
 const ON_PATH = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome', 'microsoft-edge'];
 const MAC_APPS = [
@@ -48,25 +54,69 @@ function smallShm() {
   try { const shm = fs.statfsSync('/dev/shm'); return shm.blocks * shm.bsize < 1024 ** 3; } catch { return false; }
 }
 
-// Starts it and waits for the port it picked, which it writes into its profile.
-function start(exe, args, profile) {
+const GROUP_GONE_TIMEOUT = 2000;
+
+// A launched Chromium runs in its own process group, so this stops the helper processes it starts too.
+function killGroup(pid) {
+  try { process.kill(-pid, 'SIGKILL'); } catch {}
+}
+
+async function groupGone(pid) {
+  const deadline = Date.now() + GROUP_GONE_TIMEOUT;
+  while (Date.now() < deadline) {
+    try { process.kill(-pid, 0); } catch { return; }
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+}
+
+// Starts it and waits for the port it picked, which it prints (as Playwright reads it too): a
+// DevToolsActivePort file in a profile of the caller's can be one an earlier run left behind.
+// One that does not start is stopped, helpers and all, before this returns.
+function start(exe, args, onSpawn) {
   return new Promise(resolve => {
-    // Its own process group, so stopping it also stops the helper processes it starts.
     const proc = spawn(exe, args, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+    onSpawn(proc);
     let stderr = '';
+    let partial = '';
     let settled = false;
-    const done = result => { if (!settled) { settled = true; clearInterval(poll); clearTimeout(timer); resolve(result); } };
-    proc.stderr.on('data', d => { if (stderr.length < 20000) stderr += d; });
+    const done = result => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      if (!result.error) return resolve(result);
+      killGroup(proc.pid);
+      // A helper still holding the profile's lock would make a retry in the same profile fail.
+      groupGone(proc.pid).then(() => resolve(result));
+    };
+    proc.stderr.on('data', d => {
+      if (stderr.length < 20000) stderr += d;
+      const text = partial + d;
+      const listening = /^DevTools listening on ws:\/\/[^/\s]+:(\d+)\//m.exec(text);
+      if (listening) done({ proc, port: listening[1] });
+      partial = text.slice(text.lastIndexOf('\n') + 1);
+    });
     proc.on('error', error => done({ error: error.message, stderr }));
     proc.on('exit', code => done({ error: `it exited with code ${code}`, stderr }));
-    const portFile = path.join(profile, 'DevToolsActivePort');
-    const poll = setInterval(() => {
-      try { const port = fs.readFileSync(portFile, 'utf8').split('\n')[0].trim(); if (port) done({ proc, port }); } catch {}
-    }, 100);
-    const timer = setTimeout(() => { proc.kill('SIGKILL'); done({ error: `no debugging port within ${START_TIMEOUT / 1000}s`, stderr }); }, START_TIMEOUT);
+    const timer = setTimeout(() => done({ error: `no debugging port within ${START_TIMEOUT / 1000}s`, stderr }), START_TIMEOUT);
   });
 }
 
+// Chromium takes only --user-data-dir=<dir>, and the last one given.
+function userDataDir(args) {
+  const given = args.filter(a => a.startsWith('--user-data-dir=')).pop();
+  return given ? path.resolve(given.slice('--user-data-dir='.length)) : null;
+}
+
+async function closeBrowser(url) {
+  let browser;
+  try {
+    browser = await require('playwright-core').chromium.connectOverCDP(url, { timeout: CLOSE_CONNECT_TIMEOUT });
+    const session = await browser.newBrowserCDPSession();
+    // It closes before it answers, or as it does.
+    await session.send('Browser.close').catch(() => {});
+  } catch {}
+  try { await browser?.close(); } catch {}
+}
+
 function quoted(args) {
   return args.map(a => (/[\s"'$]/.test(a) ? JSON.stringify(a) : a)).join(' ');
 }
@@ -76,40 +126,60 @@ async function launch({ headed = false, extraArgs = [] }) {
   if (!exe) {
     throw new Error(`No Chromium found to launch. Install Playwright's with:\n  ${INSTALL}\nor set PW_CHROME to one, or start one yourself with --remote-debugging-port and set PW_CDP_URL.`);
   }
-  const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-repl-chrome-'));
-  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', `--user-data-dir=${profile}`,
+  const given = userDataDir(extraArgs);
+  const profile = given || fs.mkdtempSync(path.join(os.tmpdir(), 'pw-repl-chrome-'));
+  const removeProfile = () => { if (!given) fs.rmSync(profile, { recursive: true, force: true }); };
+  // Registered before Chromium starts, and kept for the REPL's life: a REPL that goes without shutting
+  // down, even while it waits for Chromium, still takes it (and a profile of its own) along.
+  let group = null;
+  const onExit = () => { if (group) killGroup(group); try { removeProfile(); } catch {} };
+  process.on('exit', onExit);
+  const onSpawn = proc => { group = proc.pid; };
+  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', ...(given ? [] : [`--user-data-dir=${profile}`]),
     '--no-first-run', '--no-default-browser-check', ...(smallShm() ? ['--disable-dev-shm-usage'] : [])];
+  // A profile already used has tabs to restore; a blank tab of its own each time would pile up there.
+  // Local State is written at its root on the first run, whichever --profile-directory is used.
+  const blank = given && fs.existsSync(path.join(given, 'Local State')) ? [] : ['about:blank'];
   // Flags given after -- come after these, so they can override them.
-  let args = [...ours, ...extraArgs, 'about:blank'];
-  let result = await start(exe, args, profile);
+  let args = [...ours, ...extraArgs, ...blank];
+  let result = await start(exe, args, onSpawn);
   let note = null;
   // Tried with the sandbox first; a container often cannot give Chromium one.
   if (result.error && /sandbox/i.test(result.stderr)) {
-    args = [...ours, '--no-sandbox', ...extraArgs, 'about:blank'];
-    result = await start(exe, args, profile);
+    args = [...ours, '--no-sandbox', ...extraArgs, ...blank];
+    result = await start(exe, args, onSpawn);
     note = 'Chromium could not use its sandbox here, so it runs with --no-sandbox.';
   }
   const command = quoted([exe, ...args]);
   if (result.error) {
-    fs.rmSync(profile, { recursive: true, force: true });
+    process.removeListener('exit', onExit);
+    removeProfile();
     const last = result.stderr.trim().split('\n').slice(-5).join('\n');
     throw new Error(`Chromium did not start (${result.error}):\n  ${command}${last ? `\n${last}` : ''}`);
   }
   const { proc, port } = result;
-  const signal = name => { try { process.kill(-proc.pid, name); } catch {} };
+  const url = `http://127.0.0.1:${port}`;
+  const exited = new Promise(resolve => { if (proc.exitCode !== null || proc.signalCode !== null) resolve(); else proc.once('exit', resolve); });
+  const exitsWithin = ms => Promise.race([exited.then(() => true), new Promise(resolve => setTimeout(resolve, ms, false))]);
   const stop = async () => {
-    if (proc.exitCode === null && proc.signalCode === null) {
-      signal('SIGTERM');
-      await new Promise(resolve => { const t = setTimeout(() => { signal('SIGKILL'); resolve(); }, STOP_TIMEOUT); proc.once('exit', () => { clearTimeout(t); resolve(); }); });
+    if (!(await exitsWithin(0))) {
+      // Browser.close shuts it down in order: its helpers save the profile (what pages last wrote to
+      // localStorage) and it removes the profile's lock. SIGTERM to the browser process saves the
+      // profile too but leaves the lock; to the whole group, it loses the last writes.
+      // Not awaited: a browser that hangs may never answer; its exit is what counts.
+      void closeBrowser(url);
+      if (!(await exitsWithin(CLOSE_CONNECT_TIMEOUT + CLOSE_TIMEOUT))) {
+        try { process.kill(proc.pid, 'SIGTERM'); } catch {}
+        await exitsWithin(TERM_TIMEOUT);
+      }
     }
+    killGroup(proc.pid);
     // Its helper processes can still be writing to the profile for a moment.
     for (let tries = 0; tries < 30; tries++) {
-      try { fs.rmSync(profile, { recursive: true, force: true }); return; } catch { await new Promise(resolve => setTimeout(resolve, 100)); }
+      try { removeProfile(); return; } catch { await new Promise(resolve => setTimeout(resolve, 100)); }
     }
   };
-  // If the REPL goes without shutting down, the browser still goes with it.
-  process.on('exit', () => signal('SIGKILL'));
-  return { url: `http://127.0.0.1:${port}`, command, note, headed, stop };
+  return { url, command, note, headed, stop };
 }
 
-module.exports = { findChrome, launch, INSTALL };
+module.exports = { findChrome, launch, INSTALL, START_TIMEOUT, STOP_WORST };

package/lib/output.js

@@ -61,7 +61,7 @@ function printOutput(value, all = false) {
   else text = JSON.stringify(value, null, 2);
   if (text === undefined) text = 'undefined';
   if (!all && text.length > OUTPUT_LIMIT) {
-    log(`${text.slice(0, OUTPUT_LIMIT)}\n[truncated; use --all after the command to show all]`);
+    log(`${text.slice(0, OUTPUT_LIMIT)}\n[truncated; add --all to the command to show all]`);
   } else {
     log(text);
   }

package/lib/runner.js

@@ -30,7 +30,7 @@ const READ_ONLY = new Set(['info', 'listeners', 'text', 'html', 'attrs', 'count'
 // Commands that work with no tab selected.
 const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'dialog', 'help', 'quit', 'tab-select', 'close']);
 
-// Commands that accept a leading --all to lift the output limit.
+// Commands that accept --all, right after the command or at the end, to lift the output limit.
 const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
 
 let queue = Promise.resolve();
@@ -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.
@@ -85,8 +86,10 @@ async function executeCommand(text) {
   const spaceIdx = text.indexOf(' ');
   const cmd = spaceIdx === -1 ? text : text.slice(0, spaceIdx);
   let args = spaceIdx === -1 ? '' : text.slice(spaceIdx + 1);
-  const all = INSPECTION.includes(cmd) && /^--all(?:\s|$)/.test(args);
-  if (all) args = args.slice(5).trimStart();
+  let all = false;
+  if (INSPECTION.includes(cmd) && /^--all(?:\s|$)/.test(args)) { all = true; args = args.slice(5).trimStart(); }
+  // At the end too, where the truncation note's reader tends to put it (console 200 --all).
+  else if (INSPECTION.includes(cmd) && /(?:^|\s)--all$/.test(args)) { all = true; args = args.slice(0, -5).trimEnd(); }
   // wait request counts responses since the previous command began.
   state.previousCommandAt = state.currentCommandAt;
   state.currentCommandAt = Date.now();

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

@@ -3,7 +3,7 @@ const { chromium } = require('playwright-core');
 const readline = require('readline');
 const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./state');
 const out = require('./output');
-const { listTabs, openTab, watchPage, complete } = require('./commands');
+const { listTabs, openTab, startTabs, watchPage, complete } = require('./commands');
 const runner = require('./runner');
 
 // A browser --launch starts has its own address instead.
@@ -28,7 +28,10 @@ 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;
@@ -40,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) {
@@ -71,7 +75,9 @@ 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 });
     out.log(`Opened ${state.page.url()} in a new tab`);
   }
@@ -80,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);
@@ -150,7 +156,11 @@ function stop() {
   shutdown().then(beforeExit).then(() => process.exit(process.exitCode || 0));
 }
 
-// SIGHUP too: closing the terminal must still remove the server's socket.
-for (const signal of ['SIGTERM', 'SIGHUP']) process.on(signal, stop);
+// SIGHUP too: closing the terminal must still remove the server's socket. SIGINT is Ctrl-C before the
+// prompt reads it (while --launch starts Chromium, or while connecting): without this, node exits at
+// once and leaves a launched Chromium running.
+for (const signal of ['SIGTERM', 'SIGHUP', 'SIGINT']) process.on(signal, stop);
 
-module.exports = { start: options => start(options).catch(e => { out.error(e.message); shutdown().then(beforeExit).finally(() => process.exit(1)); }) };
+// Stopped while it starts (Ctrl-C), what was under way fails as the browser goes: stop() says nothing
+// of that, and exits.
+module.exports = { start: options => start(options).catch(e => { if (state.stopping) return; out.error(e.message); shutdown().then(beforeExit).finally(() => process.exit(1)); }) };

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,
@@ -83,4 +86,4 @@ async function shutdown() {
   return shutdownPromise;
 }
 
-module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown };
+module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown, SHUTDOWN_TIMEOUT };

package/package.json

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