pw-repl 0.3.1 → 0.4.0

package/lib/help.js

@@ -17,6 +17,7 @@ Common tasks:
   console messages and errors       console
   show an agent what I do           watch on, click around, then watch
   see each step as I click          watch on --live
+  watch a tab someone will open     watch on --next-tab [url-part]
   requests and console together     capture on, then capture off
   break the backend on purpose      route <glob> <status> <json>, route <glob> abort, network off
   change or slow an API response    route <glob> patch <json>, route <glob> delay <secs>
@@ -32,7 +33,10 @@ Topics (help <topic>):
   interact  click, fill, type, press, select     devtools  eval, CDP commands, cookie and storage names
   inspect   snapshot, watch, text, screenshots   session   modes, markers, server, quitting
 
-help <command> for usage and caveats (e.g. help route); help --all for everything.`;
+help <command> for usage and caveats (e.g. help route); help --all for everything.
+
+Know playwright-cli? Its command names work here too (tab-list, go-back, set-color-scheme, route
+--status=...); help playwright-cli lists them.`;
 
 const TOPICS = {
   tabs: {
@@ -52,7 +56,7 @@ const TOPICS = {
     commands: ['requests', 'body', 'console', 'capture', 'route', 'network'],
   },
   devtools: {
-    intro: 'Cookie and storage listings omit values. eval, html, screenshots and URLs can still show sensitive data.',
+    intro: 'Cookie and storage listings omit values. eval, cdp, html, screenshots and URLs can still show\nsensitive data (cdp Network.getCookies shows cookie values).',
     commands: ['eval', 'cdp', 'cookies', 'storage'],
   },
   session: {
@@ -63,6 +67,11 @@ it. It says so (pw-repl send exits 2), and the REPL carries on.
 
 Server: pw-repl serve also takes commands on /tmp/playwright-repl.sock; they show here as [server] lines.
 
+Clients: pw-repl send -c <name> (or $PW_CLIENT) sends as a client of its own. It has a selected tab of
+its own, so clients do not move each other's; its commands show as [server:<name>] lines. modes and tab
+say which client turned each mode on and opened each tab, and modes off --mine turns off only the
+sender's own. Senders without a name share the prompt's selected tab.
+
 The prompt is pw[serve]> while the server is on and pw> without it. Before it are the modes on in the
 selected tab, if any: (watch network:off routes:2 capture) pw>. modes lists them for every tab.
 
@@ -77,27 +86,39 @@ const COMMANDS = {
   tab: {
     usage: 'tab [<index>|<url-part>|new [url]|close [url-part]]',
     summary: 'list tabs (* is selected); select, open or close one',
-    detail: 'tab <index> uses the numbers from the latest tab listing; they change when tabs open or close.\n\ntab <url-part> selects the one tab whose URL contains it, and refuses if none or several do.\n\ntab new opens a tab behind the one in front, so it does not take the window from whoever is using it,\nand selects it. tab close closes the selected tab, or the one matching url-part.\n\nClosing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is\nselected, and commands that need one refuse until one is.',
+    detail: 'tab <index> uses the numbers from your latest tab listing (each client has its own); they change\nwhen tabs open or close.\n\ntab <url-part> selects the one tab whose URL contains it, and refuses if none or several do.\n\ntab new opens a tab behind the one in front, so it does not take the window from whoever is using it,\nand selects it; tab shows who opened each tab opened this way. tab close closes the selected tab, or\nthe one matching url-part.\n\nClosing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is\nselected, and commands that need one refuse until one is.',
   },
   goto: {
     usage: 'goto <url>',
     summary: 'navigate the selected tab',
     detail: 'Without a scheme, http:// is assumed for localhost, 127.x and [::1], and https:// otherwise, as in\nthe address bar. tab new <url> reads its URL the same way.',
   },
-  back: { usage: 'back', summary: 'go back one history entry' },
-  forward: { usage: 'forward', summary: 'go forward one history entry' },
+  back: {
+    usage: 'back',
+    summary: 'go back one history entry',
+    detail: 'The browser may bring the page back from its back/forward cache, as it was: nothing loads or runs\nagain, so a loading message or a request the page makes on load does not come back. reload loads it\nafresh.',
+  },
+  forward: { usage: 'forward', summary: 'go forward one history entry', detail: 'Like back, it may bring the page back from the back/forward cache without loading it again.' },
   reload: { usage: 'reload', summary: 'reload the selected tab' },
   info: { usage: 'info', summary: 'selected tab URL, title and viewport' },
-  click: { usage: 'click <selector>', summary: 'click the first match' },
-  dblclick: { usage: 'dblclick <selector>', summary: 'double-click the first match' },
+  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).',
+  },
+  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>',
+    usage: 'fill <selector> <value> [--submit]',
     summary: 'clear an input and fill it',
-    detail: 'The selector is the first word; quote it if it has spaces. The rest of the line is the value, and\nquotes around all of it are removed, so fill #name "" clears the field.\n\nExamples: fill #name Ada Lovelace, fill "text=Your name" Ada, fill e7 Ada',
+    detail: 'The selector is the first word; quote it if it has spaces. The rest of the line is the value, and\nquotes around all of it are removed, so fill #name "" clears the field. --submit at the end presses\nEnter in it afterwards.\n\nExamples: fill #name Ada Lovelace, fill "text=Your name" Ada, fill e7 Ada',
+  },
+  type: {
+    usage: 'type [<selector>] <text> [--submit]',
+    summary: 'type key by key after what the field holds; text as for fill',
+    detail: 'With one word, or one quoted, it is typed into the element that has focus: type "garden hose".\n--submit at the end presses Enter afterwards.',
   },
-  type: { usage: 'type <selector> <text>', summary: 'type key by key after what the field holds; text as for fill' },
-  press: { usage: 'press <key> | press <selector> <key>', summary: 'press a key (Enter, Escape, Control+A), optionally on an element' },
+  press: { usage: 'press <key> | press <selector> <key>', summary: 'press a key (Enter, Escape, Control+A; any case), maybe on an element' },
   select: { usage: 'select <selector> <value>', summary: 'choose an option in a select (the value is the rest of the line)' },
   check: { usage: 'check <selector>', summary: 'check a checkbox' },
   uncheck: { usage: 'uncheck <selector>', summary: 'uncheck a checkbox' },
@@ -109,12 +130,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.\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\nsnapshot e3 outlines one element. A ref (e3, or f1e3 in newer Playwright) works as a selector in any\ncommand: click e3. Refs can change when the page changes (e102 may become f4e98), so take a new\nsnapshot after it does.\n\nOutput over 60 lines ends with a line count.',
   },
   watch: {
     usage: 'watch on [--changes] [--live] | off | [n|new]',
     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 (their numbers in requests; body\n<#> for one), leaving out scripts and what requests hides. The REPL\'s own fill is recorded as type.\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.\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.\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' },
@@ -129,36 +150,36 @@ const COMMANDS = {
   links: { usage: 'links [--all]', summary: 'links on the page (text and href)' },
   inputs: { usage: 'inputs [--all]', summary: 'form controls on the page; values are omitted' },
   screenshot: {
-    usage: 'screenshot [--full] [--delay|-d <seconds>] [name]',
-    summary: 'save a PNG of the viewport (or --full page)',
-    detail: 'Saved as screenshot-<name or timestamp>.png in $PW_SCREENSHOT_DIR (default /tmp). It brings the tab to\nthe front of its window first: Chrome draws only the tab in front.\n\n--delay counts down out loud first (maximum 60s), so someone can hold a hover or open a menu.',
+    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.',
   },
   viewport: { usage: 'viewport [WxH]', summary: 'show or set the viewport size' },
   emulate: {
     usage: 'emulate [<what> [off] | off]',
     summary: 'emulate a phone, dark mode, a locale or a timezone',
-    detail: 'emulate mobile [device]  a phone\'s screen, touch and user agent: a Pixel 7, or a device named as in\n                         Playwright\'s list, e.g. emulate mobile iPhone 13\nemulate dark | light     the color scheme the page\'s CSS and matchMedia see\nemulate locale <tag>     the language (Accept-Language, navigator.language) and date and number\n                         formats, e.g. fr-FR\nemulate timezone <zone>  an IANA timezone, e.g. Asia/Tokyo\nemulate <what> off       stop one (dark or light off stops the color scheme); emulate off stops all\n\nPer tab, until turned off or the REPL exits. emulate on its own shows what is on.\n\nThe page sees the user agent, touch and navigator.languages from its next load: reload after\nemulate mobile or emulate locale. While mobile is on, viewport refuses: the device sets the size.',
+    detail: 'emulate mobile [device]  a phone\'s screen, touch and user agent: a Pixel 7, or a device named as in\n                         Playwright\'s list, e.g. emulate mobile iPhone 13; a name that is not\n                         exact lists the devices it matches (emulate mobile galaxy)\nemulate dark | light     the color scheme the page\'s CSS and matchMedia see\nemulate locale <tag>     the language (Accept-Language, navigator.language) and date and number\n                         formats, e.g. fr-FR\nemulate timezone <zone>  an IANA timezone, e.g. Asia/Tokyo\nemulate <what> off       stop one (dark or light off stops the color scheme); emulate off stops all\n\nPer tab, until turned off or the REPL exits. emulate on its own shows what is on.\n\nThe page sees the user agent, touch and navigator.languages from its next load: reload after\nturning mobile or locale on or off. Dark, light and timezone apply at once, but what the page\nalready drew with them (times, colors set by its script) changes only when it reloads.\n\nWhile mobile is on, viewport refuses: the device sets the size.',
   },
   wait: {
     usage: 'wait [text|request] <what> [--gone] [secs]',
     summary: 'wait for an element, text, a response or a load (10s)',
-    detail: 'wait <selector> waits for a matching element; wait text <text> for text to be visible; wait request\n<url-part|glob> for a matching response, counting one that finished since the previous command began\n(so click, then wait request, does not miss it).\n\nwait load waits for the page to finish loading (its load event). A navigation that began since the\nprevious command began counts, so click a link, then wait load, waits for the new page.\n\n--gone waits instead until nothing matching is visible (removed or hidden): wait .spinner --gone.\n\nUp to 120s. A wait that times out is an error; the REPL carries on.',
+    detail: 'wait <selector> waits for a matching element 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.',
   },
   sleep: { usage: 'sleep <ms>', summary: 'wait a fixed time (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.',
+    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.',
   },
   body: {
-    usage: 'body [--all] <#>',
-    summary: 'the response body of request <#> from requests',
-    detail: 'Read from the browser on demand: JSON is pretty-printed, binary is not shown, output is capped. The\nbrowser may drop a body (e.g. after the tab navigates); then body reports not available.\n\nBodies can contain sensitive data.',
+    usage: 'body [--all] <#>|<url-part>',
+    summary: 'the response body of request <#>, or of the latest one matching',
+    detail: 'body <url-part> shows the latest finished request whose URL contains url-part (body slots.json).\n\nRead from the browser on demand: JSON is pretty-printed, binary is not shown, output is capped. The\nbrowser may drop a body (e.g. after the tab navigates); then body reports not available.\n\nBodies can contain sensitive data.',
   },
   console: {
-    usage: 'console [--all] [n] [filter]',
+    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.\n\nfilter matches the type or the text, e.g. console error.',
+    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: time, [type],\ntext. Types are console levels (log, warning, error, ...) and pageerror for uncaught exceptions. 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.',
   },
   capture: {
     usage: 'capture on [requests|console] [secs] | off',
@@ -168,17 +189,17 @@ 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; it never reaches the network,\n                              so it still answers while the network is off\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.\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\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}',
   },
   network: {
     usage: 'network [on|off|slow [<ms> [<kbps>]]]',
     summary: 'cut, slow or restore the tab\'s network',
-    detail: 'network off cuts it, like dropped wifi. Stopping a service is not the same: a dev proxy in front of\nit usually holds the request open, so the page spins instead of failing.\n\nnetwork slow adds latency to each request and limits its speed: by default as DevTools\' Slow 4G\n(563ms, 1440 kbps down, 675 up); network slow <ms> [<kbps>] sets them. To slow one API, use route\n<glob> delay <secs>.\n\nPer tab; lasts until network on or the REPL exits. Routes still answer while it is off or slow.',
+    detail: 'network off cuts it, like dropped wifi. Stopping a service is not the same: a dev proxy in front of\nit usually holds the request open, so the page spins instead of failing.\n\nnetwork slow makes each request take at least <ms> (Chrome\'s latency is a minimum, not added to a\nslow server\'s own time) and limits its speed: by default as DevTools\' Slow 4G (563ms, 1440 kbps\ndown, 675 up); network slow <ms> [<kbps>] sets them, kbps both ways (left out, it stays Slow\n4G\'s). To slow one API, use route <glob> delay <secs>.\n\nPer tab; lasts until network on or the REPL exits. Routes still answer while it is off or slow.',
   },
   eval: {
     usage: 'eval [--all] <JavaScript>',
     summary: 'evaluate JavaScript in the selected tab and print the result',
-    detail: 'Promises are awaited. eval fetch(...) sends a new request, which can change state on the server; it\ncannot read one that already happened (requests lists those).',
+    detail: 'Promises are awaited, await works at the top level, and a function (() => document.title) is\ncalled. eval <function> <ref> calls it with that element: eval "el => el.textContent" e5.\n\neval fetch(...) sends a new request, which can change state on the server; it cannot read one that\nalready happened (requests lists those).',
   },
   cdp: {
     usage: 'cdp [--all] <method> <JSON object>',
@@ -188,9 +209,9 @@ const COMMANDS = {
   cookies: { usage: 'cookies [--all]', summary: 'cookie names, domains and flags; values are omitted' },
   storage: { usage: 'storage [--all]', summary: 'localStorage keys; values are omitted' },
   modes: {
-    usage: 'modes [off]',
+    usage: 'modes [off [--mine]]',
     summary: 'the modes on in every tab; modes off turns them all off',
-    detail: 'The modes are watch, network off or slow, route, capture and emulate. Each is turned on and off with\nits own command: watch on|off, network off|slow|on, route <glob> ... | route off <glob>|--all,\ncapture on|off, emulate ... | emulate off.\n\nmodes off turns off every one in every tab; a capture it stops is kept for capture to show.',
+    detail: 'The modes are watch, network off or slow, route, capture and emulate. Each is turned on and off with\nits own command: watch on|off, network off|slow|on, route <glob> ... | route off <glob>|--all,\ncapture on|off, emulate ... | emulate off.\n\nmodes off turns off every one in every tab; a capture it stops is kept for capture to show. With\nclients (help session), modes says which client turned each on, and modes off --mine turns off only\nthe sender\'s own.',
   },
   dialog: {
     usage: 'dialog [accept [text] | dismiss]',
@@ -230,6 +251,24 @@ function renderAll() {
 
 function render(topicOrCommand) {
   if (!topicOrCommand) return OVERVIEW;
+  if (topicOrCommand === 'playwright-cli') {
+    return `playwright-cli's command names, and what they run here (each says so the first time):
+
+${require('./cli-names').table()}
+
+Names both have (goto, click, fill, snapshot, eval, ...) take playwright-cli's forms too: click <ref>
+[button] [--modifiers=<keys>], fill and type --submit, type <text> into what has focus, eval <function>
+<ref>, press in any case, screenshot <ref> --full-page --filename=<file>, console <level>, requests
+--static --filter=<regexp>, find --regex <regexp>, route <pattern> --status= --body= --content-type=.
+Its other options are refused, never read as part of a selector or a value.
+
+Different on purpose, since the browser may be someone else's too:
+  routes, network and emulation     per tab, not the whole browser, so other people's tabs are untouched
+  close                             turns off your modes; tabs stay open (tab close <url-part> closes one)
+  upload <selector> <file>          names the input: file pickers are not caught, as a person's would be
+  no snapshot after each command    a person reads the pane too; snapshot when you need one
+  -s=<session>                      -c <name> is the nearest: a client with a selected tab of its own`;
+  }
   if (topicOrCommand === '--all') return renderAll();
   if (Object.hasOwn(TOPICS, topicOrCommand)) {
     const topic = TOPICS[topicOrCommand];

package/lib/runner.js

@@ -1,9 +1,25 @@
 // Runs commands one at a time, whether they come from the prompt or the server.
 // A prompt command tagged @<id> reports completion with a marker the caller can wait for.
 const readline = require('readline');
-const { state, beforeExit } = require('./state');
+const { state, clientRecord, asClient, beforeExit } = require('./state');
 const out = require('./output');
-const { commands, dialogCommand, activeModes } = require('./commands');
+const { commands, cliCommands, needsTab, dialogCommand, activeModes } = require('./commands');
+const cliNames = require('./cli-names');
+
+// playwright-cli names already explained, per client: each client is told once.
+const explained = new Set();
+
+// The line saying what a playwright-cli name is here, the first time its client uses it.
+function explain(text, translated, client = state.client) {
+  const name = translated.key || text.split(/\s/)[0];
+  const key = `${client ?? ''}\0${name}`;
+  if (explained.has(key)) return null;
+  explained.add(key);
+  return `(playwright-cli's ${name} is ${translated.as} here)`;
+}
+
+// quit and dialog skip the queue; so do playwright-cli's dialog-accept and dialog-dismiss.
+const DIALOG = /^dialog(?:-accept|-dismiss)?(?:\s|$)/;
 
 // A timeout here cannot have changed anything, so it is an ordinary error. Any
 // other command that times out may or may not have done what it was sent to
@@ -12,7 +28,7 @@ const READ_ONLY = new Set(['info', 'listeners', 'text', 'html', 'attrs', 'count'
   'snapshot', 'screenshot', 'wait', 'sleep', 'requests', 'body', 'console', 'cookies', 'storage', 'capture', 'help']);
 
 // Commands that work with no tab selected.
-const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'dialog', 'help', 'quit']);
+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.
 const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
@@ -41,10 +57,12 @@ function busy() {
   return running > 0;
 }
 
-async function execute(text) {
+// A queued command runs as its client; quit and dialog, which skip the queue,
+// run as whoever is running, so they never switch the client under a command.
+async function execute(text, client, direct = false) {
   running += 1;
   try {
-    return await executeCommand(text);
+    return direct ? await executeCommand(text) : await asClient(client, () => executeCommand(text));
   } finally {
     running -= 1;
   }
@@ -53,6 +71,17 @@ async function execute(text) {
 async function executeCommand(text) {
   if (state.connectionLost) return { status: 'error', cmd: '' };
   if (!text) return { status: 'ok', cmd: '' };
+  const translated = cliNames.translate(text);
+  if (translated?.refuse) {
+    out.error(`Error: ${translated.refuse}`);
+    return { status: 'error', cmd: text.split(/\s/)[0] };
+  }
+  if (translated) {
+    const note = explain(text, translated);
+    if (note) out.log(note);
+    if (translated.steps) return runSteps(translated);
+    text = translated.text;
+  }
   const spaceIdx = text.indexOf(' ');
   const cmd = spaceIdx === -1 ? text : text.slice(0, spaceIdx);
   let args = spaceIdx === -1 ? '' : text.slice(spaceIdx + 1);
@@ -61,16 +90,17 @@ async function executeCommand(text) {
   // wait request counts responses since the previous command began.
   state.previousCommandAt = state.currentCommandAt;
   state.currentCommandAt = Date.now();
-  if (!Object.hasOwn(commands, cmd)) {
+  const run = Object.hasOwn(commands, cmd) ? commands[cmd] : translated && Object.hasOwn(cliCommands, cmd) ? cliCommands[cmd] : null;
+  if (!run) {
     out.log(`Unknown command: ${cmd}. Type 'help' for commands.`);
     return { status: 'error', cmd };
   }
-  if (!NO_TAB_NEEDED.has(cmd) && (!state.page || state.page.isClosed())) {
+  if (!NO_TAB_NEEDED.has(cmd) && needsTab(cmd, args) && (!state.page || state.page.isClosed())) {
     out.error('Error: No tab is selected; select one with tab <index|url-part>, or open one with tab new');
     return { status: 'error', cmd };
   }
   try {
-    await commands[cmd](args, all);
+    await run(args, all);
   } catch (e) {
     // Playwright colours its call log; the codes are noise anywhere but a terminal.
     e.message = String(e.message || '').replace(/\x1b\[[0-9;]*m/g, '');
@@ -83,6 +113,19 @@ async function executeCommand(text) {
   return { status: 'ok', cmd };
 }
 
+// A playwright-cli command that is several here, run in turn until one fails.
+async function runSteps({ steps, failed }) {
+  let result;
+  for (const [i, step] of steps.entries()) {
+    result = await executeCommand(step);
+    if (result.status !== 'ok') {
+      if (i && failed) out.error(failed);
+      return result;
+    }
+  }
+  return result;
+}
+
 // A quit does not wait for the running server command, which may never finish
 // once the browser is gone, so its sender is answered now. A read-only command
 // changed nothing; any other may or may not have done what it was sent to do.
@@ -98,12 +141,12 @@ function answerInterrupted() {
   flight.resolve({ status: 'error', output: output ? `${output}\n${note}` : note, uncertain: !known, interrupted: true });
 }
 
-async function handleLine(line) {
+async function handleLine(line, direct = false) {
   const input = parseInput(line);
   const done = status => { if (input.token) out.log(`[[pw-done:${input.token}:${status}]]`); };
   if (state.stopping) return done('error');
   if (/^quit(?:\s|$)/.test(input.text)) answerInterrupted();
-  const result = await execute(input.text);
+  const result = await execute(input.text, null, direct);
   done(result.status);
   if (result.cmd === 'quit') { await beforeExit(); process.exit(process.exitCode || 0); }
   if (!state.stopping) prompt();
@@ -112,7 +155,8 @@ async function handleLine(line) {
 // The prompt starts with the modes on in the selected tab: (watch network:off) pw>.
 function prompt(preserveCursor) {
   if (!state.rl) return;
-  const modes = state.page && !state.page.isClosed() ? activeModes(state.page) : [];
+  const page = clientRecord(null).page;
+  const modes = page && !page.isClosed() ? activeModes(page) : [];
   state.rl.setPrompt(`${modes.length ? `(${modes.join(' ')}) ` : ''}${state.promptBase}`);
   state.rl.prompt(preserveCursor);
 }
@@ -120,23 +164,24 @@ function prompt(preserveCursor) {
 // quit and dialog skip the queue: quit so it works while a long command runs,
 // dialog because the commands queued behind a dialog wait for its answer.
 function enqueue(line) {
-  const direct = /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\s+)?(?:quit|dialog)(?:\s|$)/.test(line.trim());
-  const run = () => handleLine(line);
-  if (direct) run().catch(e => out.error(`Error: ${e.message}`));
-  else queue = queue.then(run).catch(e => out.error(`Error: ${e.message}`));
+  const text = parseInput(line).text;
+  const direct = /^quit(?:\s|$)/.test(text) || DIALOG.test(text);
+  if (direct) handleLine(line, true).catch(e => out.error(`Error: ${e.message}`));
+  else queue = queue.then(() => handleLine(line)).catch(e => out.error(`Error: ${e.message}`));
 }
 
 // Server commands share the prompt's queue and are echoed to the pane, so
 // someone watching sees everything an agent does.
-function submit(text) {
-  if (/^dialog(?:\s|$)/.test(text)) return answerDialog(text);
+// client names the sender: its commands show as [server:<client>] and use its own selected tab.
+function submit(text, client = null) {
+  if (DIALOG.test(text)) return answerDialog(text, client);
   return new Promise(resolve => {
     queue = queue.then(async () => {
       if (state.stopping) return resolve({ status: 'error', output: 'The REPL is shutting down.' });
       // Printed above whatever the person at the prompt is typing, which is
       // redrawn afterwards rather than broken up.
       if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
-      out.log(`[server] ${text}`);
+      out.log(`[server${client ? `:${client}` : ''}] ${text}`);
       // So the person at the prompt can bring an agent's command back with up-arrow.
       if (state.rl?.history && state.rl.history[0] !== text) {
         state.rl.history.unshift(text);
@@ -149,7 +194,7 @@ function submit(text) {
         let result;
         const flight = { text, resolve, answered: false };
         inFlight = flight;
-        const output = await out.collect(async () => { result = await execute(text); });
+        const output = await out.collect(async () => { result = await execute(text, client); });
         if (inFlight === flight) inFlight = null;
         if (!flight.answered) resolve({ status: result.status, output, uncertain: result.uncertain });
       }
@@ -160,11 +205,14 @@ function submit(text) {
 
 // Outside the queue, and so outside out.collect, whose single sink belongs to
 // the command that is waiting on the dialog.
-async function answerDialog(text) {
-  console.log(`[server] ${text}`);
+async function answerDialog(text, client) {
+  console.log(`[server${client ? `:${client}` : ''}] ${text}`);
+  const translated = cliNames.translate(text);
+  const note = translated && explain(text, translated, client);
   let result;
-  try { result = { status: 'ok', output: await dialogCommand(text.slice(6)) }; }
+  try { result = { status: 'ok', output: await dialogCommand((translated?.text || text).slice(6), clientRecord(client).page) }; }
   catch (error) { result = { status: 'error', output: `Error: ${error.message}` }; }
+  if (note) result.output = `${note}\n${result.output}`;
   console.log(result.output);
   if (!state.stopping) prompt(true);
   return result;

package/lib/send.js

@@ -94,8 +94,12 @@ async function send(options) {
   if (/[\r\n]/.test(command)) return fail('the command must be a single line');
   const timeoutMs = options.timeout * 1000;
   const way = route(options);
+  const name = options.client || process.env.PW_CLIENT || null;
+  if (name && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(name)) return fail('a client name is 1-40 letters, digits, dots, dashes and underscores');
+  // The pane has one prompt, so a command typed there has no client of its own.
+  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);
+  const answer = await client.request(way.endpoint, command, timeoutMs, name);
   if (answer.result) {
     if (answer.result.output) console.log(answer.result.output);
     if (answer.result.unconfirmed) { console.error('completion not confirmed'); return 2; }
@@ -117,7 +121,8 @@ async function where(options) {
   // use, so a REPL that will not start can be told apart from one that is not running.
   const cdp = info?.browser || process.env.PW_CDP_URL || 'http://localhost:9222';
   const version = await fetch(`${cdp}/json/version`, { signal: AbortSignal.timeout(2000) }).then(r => r.json()).catch(() => null);
-  const whose = info?.launched ? ', launched by this REPL' : '';
+  // With no REPL running, it is only where one would connect, not a browser of a REPL that stopped.
+  const whose = info?.launched ? ', launched by this REPL' : info ? '' : '; run and serve connect here without --launch';
   console.log(version ? `browser: ${cdp} answers (${version.Browser}${whose})` : `browser: nothing answers at ${cdp}; pw-repl run says how to start one`);
   if (way.kind === 'server') {
     const name = client.describe(way.endpoint);

package/lib/server.js

@@ -6,9 +6,11 @@ const fs = require('fs');
 const out = require('./output');
 const runner = require('./runner');
 const { state, onShutdown, onBeforeExit } = require('./state');
-const { parseEndpoint, describe } = require('./client');
+const { parseEndpoint, describe, DEFAULT_SOCKET } = require('./client');
+const path = require('path');
 
 const MAX_BODY = 1024 * 1024;
+const CLIENT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/;
 const FLUSH_TIMEOUT = 1000;
 
 // Answers being written, so the REPL can let them reach their senders before it exits.
@@ -40,11 +42,15 @@ function handle(req, res) {
   });
   req.on('end', async () => {
     let command;
-    try { ({ command } = JSON.parse(body)); } catch {}
+    let client;
+    try { ({ command, client } = JSON.parse(body)); } catch {}
     if (typeof command !== 'string' || !command.trim() || /[\r\n]/.test(command)) {
-      return send(res, 400, { status: 'error', output: 'Body must be {"command": "<one line>"}' });
+      return send(res, 400, { status: 'error', output: 'Body must be {"command": "<one line>"}, with "client": "<name>" if it has one' });
     }
-    const result = await runner.submit(command.trim());
+    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' });
+    }
+    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.
     send(res, 200, { status: result.status, output: result.output, unconfirmed: true });
@@ -80,6 +86,7 @@ async function serve(endpointArg) {
   } finally {
     if (previousUmask !== null) process.umask(previousUmask);
   }
+  if (endpoint.socket && path.resolve(endpoint.socket) !== path.resolve(DEFAULT_SOCKET)) state.ownDir = path.dirname(path.resolve(endpoint.socket));
   const removeSocket = () => { if (endpoint.socket) try { fs.unlinkSync(endpoint.socket); } catch {} };
   onShutdown(() => { server.close(); removeSocket(); });
   process.on('exit', removeSocket);

package/lib/state.js

@@ -6,9 +6,9 @@ const SHUTDOWN_TIMEOUT = 5000;
 
 const state = {
   browser: null,
-  page: null,
-  previousPage: null,
-  tabListing: [],
+  // The client whose command runs now: null for the prompt and senders without
+  // a name, who share one selected tab, as before clients had names.
+  client: null,
   rl: null,
   promptBase: 'pw> ',
   // The browser the REPL is connected to, and whether --launch started it.
@@ -17,10 +17,31 @@ const state = {
   stopping: false,
   connectionLost: false,
   shutdownFailed: false,
-  previousCommandAt: 0,
-  currentCommandAt: 0,
+  // The folder of a socket of its own, where its screenshots go.
+  ownDir: null,
 };
 
+// What each client has selected and when its commands ran: state.page and the
+// rest read and write the running client's, so commands need not know.
+const PER_CLIENT = { page: null, previousPage: null, tabListing: [], previousCommandAt: 0, currentCommandAt: 0 };
+const clients = new Map();
+
+function clientRecord(name = state.client) {
+  if (!clients.has(name)) clients.set(name, { ...PER_CLIENT, tabListing: [] });
+  return clients.get(name);
+}
+
+for (const key of Object.keys(PER_CLIENT)) {
+  Object.defineProperty(state, key, { enumerable: true, get: () => clientRecord()[key], set: value => { clientRecord()[key] = value; } });
+}
+
+// Runs fn as the named client. Commands run one at a time, so this is safe.
+async function asClient(name, fn) {
+  const previous = state.client;
+  state.client = name || null;
+  try { return await fn(); } finally { state.client = previous; }
+}
+
 const cleanups = [];
 const exitWaits = [];
 let shutdownPromise = null;
@@ -62,4 +83,4 @@ async function shutdown() {
   return shutdownPromise;
 }
 
-module.exports = { state, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown };
+module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown };

package/lib/syntax.js

@@ -26,4 +26,25 @@ function splitSelector(args) {
   return { word, selector: toSelector(word), rest: match[4] };
 }
 
-module.exports = { SELECTOR_FIRST, toSelector, unquote, splitSelector };
+// Key names in any case, as playwright-cli's press takes them (arrowleft), in
+// the case Playwright needs (ArrowLeft); a single character is kept as it is.
+const KEY_NAMES = [
+  'Backquote', 'Minus', 'Equal', 'Backslash', 'Backspace', 'Tab', 'BracketLeft', 'BracketRight', 'CapsLock',
+  'Semicolon', 'Quote', 'Enter', 'Comma', 'Period', 'Slash', 'Space', 'Escape', 'Shift', 'ShiftLeft', 'ShiftRight',
+  'Control', 'ControlLeft', 'ControlRight', 'Meta', 'MetaLeft', 'MetaRight', 'Alt', 'AltLeft', 'AltRight',
+  'AltGraph', 'ControlOrMeta', 'ContextMenu', 'PrintScreen', 'ScrollLock', 'Pause', 'PageUp', 'PageDown',
+  'Insert', 'Delete', 'Home', 'End', 'ArrowLeft', 'ArrowUp', 'ArrowRight', 'ArrowDown', 'NumLock', 'Clear',
+  'NumpadDivide', 'NumpadMultiply', 'NumpadSubtract', 'NumpadAdd', 'NumpadDecimal', 'NumpadEnter',
+  'AudioVolumeMute', 'AudioVolumeDown', 'AudioVolumeUp', 'MediaTrackNext', 'MediaTrackPrevious', 'MediaPlayPause',
+  ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`),
+  ...Array.from({ length: 10 }, (_, i) => [`Digit${i}`, `Numpad${i}`]).flat(),
+  ...Array.from({ length: 26 }, (_, i) => `Key${String.fromCharCode(65 + i)}`),
+];
+const KEYS = new Map(KEY_NAMES.map(name => [name.toLowerCase(), name]));
+
+function keyName(key) {
+  // Control+Shift+ArrowLeft: each part, where + itself may be the last.
+  return key.split(/\+(?!$)/).map(part => (part.length > 1 ? KEYS.get(part.toLowerCase()) || part : part)).join('+');
+}
+
+module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, splitSelector, keyName };

package/package.json

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