pw-repl 0.13.0 → 0.15.0

package/AGENTS.md

@@ -17,7 +17,7 @@ If you hit a limitation or write a workaround, consider adding the capability to
   `READ_ONLY` or `INSPECTION`, and one that takes fixed words in `complete` (`lib/commands.js`).
 - The modules, one per facility, each with its commands: `lib/tabs.js` (tabs, navigating),
   `lib/elements.js` (choosing a match; the interact and mouse commands; highlight), `lib/cursor.js` (the pointer
-  drawn over the page, which the element and mouse commands glide first), `lib/toast.js` (a line of text
+  drawn over the page, which the element and mouse commands glide first), `lib/touch.js` (touch gestures, under emulate mobile), `lib/toast.js` (a line of text
   over the page), `lib/overlay.js` (the element the cursor and toast are drawn in, one layer each), `lib/inspect.js` (reading the
   page, screenshots, eval, CDP, waits), `lib/watch.js`, `lib/requestlog.js` (requests, bodies, console),
   `lib/routes.js`, `lib/network.js`, `lib/emulation.js` (and viewport), `lib/capture.js`, `lib/profile.js` (performance traces;
@@ -56,48 +56,24 @@ If you hit a limitation or write a workaround, consider adding the capability to
   after an intended change to it, save it again (the command is in `test/units.test.js`). The common
   tasks and modes on help's front page (`TASKS` and `MODES`) are the README's too: change both, as a
   unit test compares them.
-- Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`).
-  Compare with the last commit that has one (`git log --grep='npm test:'`): a run that grew by more than
-  a few seconds means a slow test crept in, usually one waiting out a real timeout (5s for a click).
+- Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`),
+  with the load average (`uptime`) when it is high. Compare with the last commit that has one (`git log
+  --grep='npm test:'`): a run that grew by more than a few seconds, at a like load (a busy machine slows
+  every test), means a slow test crept in, usually one waiting out a real timeout (5s for a click).
   Find it (each test prints its time) and make it faster, or say why it can't be, before committing.
 - Don't race the clock in a test: a page that changes on a timer, or a command timed against a budget,
   fails on a busy machine. Have the page change when the test asks (eval), or measure the thing itself
   (frames drawn, not clicks timed). A click waits for its element to hold still for two frames.
 - For anything the tests can't reach, exercise the change in a running REPL of your own: on a socket of
   your own, with `--launch` unless the change needs the user's browser, and then in a tab of your own.
+  One started before a change to `lib/` runs the old code: restart it after a change. Stop a process by
+  its pid, after checking what it is; a broad `pkill -f` pattern can match your own shell, or a REPL
+  someone else is using.
 - `skill/SKILL.md` is how agents learn to use the REPL: keep it in step with a change to how it is
   used, and leave its Custom rules section empty. Keep its `<!-- pw-repl skill stamp -->` line: `pw-repl
   skill` replaces it with the version and a hash of the skill's text, which `where` reports, so agents
   can tell a saved copy is out of date.
 
-## Waves
-
-Work goes in waves, and each one ends with a release that is ready to push.
-
-1. Build what was asked, with tests, and try it in a running REPL. For anything the user will look at
-   (a cursor, an overlay, a video), show them a demo while it is still a prototype (a recording or
-   screenshots they can open) and get their go-ahead on how it looks before writing tests or
-   building on it.
-2. Try it on a fresh agent that has not seen the code or the change (a guinea pig), on something real: a
-   small local page whose planted bugs need the change to find.
-   - Brief it with goals only: what to find out or do in the browser, never the commands.
-   - First it reads back its plan, learned from `pw-repl skill` and help alone: the commands, where it
-     found them, and what is unclear. It runs nothing yet.
-   - A wrong or unsure plan means the docs or the brief were unclear: find out which, fix that, then
-     ask again.
-   - Then it carries the plan out, in a browser and on a socket of its own, and reports as it goes:
-     above all, where the tool did something other than what the docs led it to expect.
-   - Once it has confirmed the fixes work, it reviews them as a second pair of eyes: anything important
-     they miss or get wrong, not nitpicks.
-3. Triage what it reports. Fix what matters, and what is small and useful; don't put off something
-   useful for later. Leave trivia alone, and say why.
-4. Repeat 2 and 3, with a fresh agent each time, until a pass comes back clean: no real bugs, and
-   nothing unclear in the docs or the brief that changed the plan. A pass after fixes tries the fixes,
-   and something not tried yet.
-5. Only then cut the release (Releasing, steps 1-3), and say it is ready. The maintainer pushes and
-   publishes it, and the next wave starts from what they find. A release cut too early and not pushed
-   yet is undone (its commit and tag) and cut again after the fixes.
-
 ## Releasing
 
 Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`,
@@ -106,9 +82,9 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 
 1. `npm test` passes and the working tree is clean.
 2. `npm outdated` and `npm audit` show nothing that needs doing first. Dependencies are always the newest
-   stable release, never pinned back (user ruling). When the newest breaks a test, fix it in our code;
-   only a regression of the dependency's own, with the fix already in its next release, keeps the version
-   before it, until that release ships. playwright-core stays at 1.63 for that reason: on 1.64.1 a click
+   stable release, never pinned back. When the newest breaks a test, fix it in our code; only a
+   regression of the dependency's own, with the fix already in its next release, keeps the version before
+   it, until that release ships. playwright-core stays at 1.63 for that reason: on 1.64.1 a click
    on a link to a 204 hangs at "waiting for scheduled navigations to finish" until its timeout, in plain
    Playwright too (chromium.launch, a page with a link to a 204, page.click on it); 1.65's alphas fix it.
    The test "waits for the page to load, counting a navigation that just began" shows it: move up once it
@@ -118,4 +94,6 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 4. `git push --follow-tags` pushes the commits and the tag.
 5. `npm publish` publishes it; `prepublishOnly` runs the tests again first.
 
+A release cut too early and not pushed yet is undone (its commit and tag) and cut again after the fixes.
+
 Pushing and publishing need the maintainer's GitHub and npm credentials.

package/README.md

@@ -140,11 +140,12 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | see where I am                        | `tab`, `info`                                                 |
 | see what is on the page               | `snapshot`, `screenshot`                                      |
 | do something on it                    | `click`, `fill`, `type`, `press`, `drag`                      |
-| click what has no selector (a canvas) | `mouseclick <x> <y>`, `mousedblclick <x> <y>`                 |
+| click what has no selector (a canvas) | `mouse click <x> <y>`, `mouse dblclick <x> <y>`               |
 | run some JavaScript in the page       | `eval document.title`; `eval --file=check.js` for a long one  |
 | wait for a page or element            | `wait load`, `wait <selector> [--gone]`, `wait text <text>`   |
 | choose a file in a file input         | `upload <selector> <file>`                                    |
 | see it as a phone, or in dark mode    | `emulate mobile`, `emulate dark`                              |
+| tap, swipe or pinch as a finger       | `touch tap <x> <y>`, `touch pinch <x> <y> <scale>`            |
 | see what the page requested           | `requests`, then `body <#>` for what one got back             |
 | see console messages and errors       | `console`                                                     |
 | show an agent what I do               | `watch on`, click around, then `watch`                        |
@@ -199,7 +200,10 @@ pw-repl where           # which REPL send would reach
 
 `pw-repl send` sends one command and prints its result, through the server when one is running, and
 through the `pw-repl` tmux session otherwise. Chain several in the shell: `&&` stops at the first that
-fails or is not confirmed (exit 1 or 2), and `;` carries on.
+fails or is not confirmed (exit 1 or 2), and `;` carries on. `-t` is how long it waits for the answer
+(default 20s). Times, there and in every command, are in milliseconds, as in Playwright, or in seconds
+with an `s`: `-t 90000` or `-t 90s`. A send that gives up cancels its command: one still queued never
+runs, and one running is no longer waited for.
 
 Several agents can share one REPL. `pw-repl send -c <name>` (or `PW_CLIENT=<name>`) sends as a client
 with a selected tab of its own, shown in the REPL as `[server:<name>]`. `modes` says which client turned
@@ -227,7 +231,8 @@ The body may also have `"client": "<name>"`, and `"vars": {"PW_NAME": "<value>"}
 "error", "output": "..."}`, plus `"unconfirmed": true` when the command may or may not have done what it
 was sent to do (it timed out, or the REPL quit while it ran and it was not read-only). While the REPL
 starts, `/run` answers 503 with `"starting": true`: retry. `GET /health` says `"status": "starting"` until
-it serves, then `"ok"`. `pw-repl serve <port>` serves TCP on 127.0.0.1; other addresses are refused.
+it serves, then `"ok"`. A client that closes its connection before the answer cancels the command, as
+`send` does when it gives up. `pw-repl serve <port>` serves TCP on 127.0.0.1; other addresses are refused.
 
 ## How it differs from playwright-cli
 
@@ -237,6 +242,7 @@ playwright-cli's command names and most of their options work here too (`help pl
 them). Where pw-repl differs, it is mostly because someone else may be using the browser:
 
 - `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
+  `close` also lists the files you wrote that are still there.
 - Routes, network and emulation apply to one tab, not the whole browser.
 - File pickers are not caught, since they may be the user's: `upload` names the input instead.
 - There is no snapshot after every command, since the user reads the REPL too; `snapshot` shows one.

package/lib/cli-names.js

@@ -17,6 +17,10 @@ const NAMES = {
   // It ends playwright-cli's own browser; this one is shared, so tabs stay open.
   close: [() => 'close', 'modes off --mine; tabs stay open; lists the files you wrote'],
   'go-back': [() => 'back', 'back'],
+  mousemove: [a => `mouse move ${a}`, 'mouse move <x> <y>'],
+  mousedown: [a => `mouse down ${a}`.trim(), 'mouse down [button]'],
+  mouseup: [a => `mouse up ${a}`.trim(), 'mouse up [button]'],
+  mousewheel: [a => `mouse wheel ${a}`, 'mouse wheel <dx> <dy>'],
   'go-forward': [() => 'forward', 'forward'],
   find: [a => `snapshot --grep ${a}`, 'snapshot --grep <text>'],
   'dialog-accept': [a => `dialog accept ${a}`.trim(), 'dialog accept [text]'],

package/lib/commands.js

@@ -8,6 +8,7 @@ const { tabState } = require('./tabstate');
 const { commands: dialogsCommands, ensureDialogHandler } = require('./dialogs');
 const { commands: elementsCommands } = require('./elements');
 const { commands: cursorCommands } = require('./cursor');
+const { commands: touchCommands, GESTURES } = require('./touch');
 const { commands: toastCommands } = require('./toast');
 const { commands: requestlogCommands, ensureRecentLog } = require('./requestlog');
 const { commands: routesCommands, routesFor } = require('./routes');
@@ -26,6 +27,7 @@ const commands = {
   ...tabsCommands,
   ...elementsCommands,
   ...cursorCommands,
+  ...touchCommands,
   ...toastCommands,
   ...inspectCommands,
   ...watchCommands,
@@ -114,6 +116,8 @@ function complete(line) {
   if (words.length === 2) {
     if (command === 'help') return match(['--all', ...Object.keys(HELP.TOPICS), ...Object.keys(HELP.COMMANDS).sort()]);
     if (command === 'tab') return match(['new', 'close']);
+    if (command === 'touch') return match(GESTURES);
+    if (command === 'mouse') return match(['move', 'click', 'dblclick', 'down', 'up', 'wheel']);
     if (command === 'network') return match(['on', 'off', 'slow']);
     if (command === 'emulate') return match([...EMULATE_KINDS, 'off']);
     if (command === 'wait') return match(['text', 'request', 'load']);

package/lib/elements.js

@@ -39,7 +39,7 @@ const MODIFIERS = ['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift'];
 // click takes --click-count too; dblclick is click's count of 2.
 function clickArgs(args, usage, counts = false) {
   // Found outside quotes only, so a quoted selector keeps whatever is in it.
-  const { found, rest: text } = takeOptions((args || '').trim(), { modifiers: 'value', button: 'value', 'click-count': 'value' });
+  const { found, rest: text } = takeOptions((args || '').trim(), { modifiers: 'value', button: 'value', 'click-count': 'value', force: 'flag' });
   if (!counts && found.some(o => o.name === 'click-count')) throw new Error('dblclick is a click count of 2; for another count, click --click-count=<n>');
   const clickCount = clickCountOf(found, usage);
   const modifiers = found.filter(o => o.name === 'modifiers').flatMap(o => (o.value || '').split(',').filter(Boolean).map(keyName));
@@ -49,12 +49,14 @@ function clickArgs(args, usage, counts = false) {
   const positional = parsed && /^(?:left|right|middle)$/.test(parsed.rest || '') && (REF.test(parsed.word) || /^["']/.test(text)) ? parsed.rest : null;
   const button = chooseButton(found, positional, usage);
   const selector = positional ? parsed.selector : soleSelector(text, usage);
-  const options = { ...(button ? { button } : {}), ...(modifiers.length ? { modifiers } : {}), ...(clickCount > 1 ? { clickCount } : {}) };
+  const force = found.some(o => o.name === 'force');
+  const options = { ...(button ? { button } : {}), ...(modifiers.length ? { modifiers } : {}), ...(clickCount > 1 ? { clickCount } : {}), ...(force ? { force } : {}) };
   // The selector as written, then the kind of click, so an option never reads as part of the selector.
   const kind = [
     ...(button && button !== 'left' ? [`${button} button`] : []),
     ...(clickCount > 1 ? [`${clickCount} times`] : []),
     ...(modifiers.length ? [`with ${modifiers.join('+')}`] : []),
+    ...(force ? ['forced'] : []),
   ];
   return { selector, shown: [positional ? parsed.word : unquote(text), ...kind].join(', '), options };
 }
@@ -104,8 +106,9 @@ async function onElement(selector, action, budget = 5000) {
     console.error(`Playwright's call log:\n${message}`);
     // Found, so the ref is not stale: no hint.
     const summary = new Error(`Timed out after ${budget / 1000}s on ${ref || selector}: ${lastBlocker(message)} (its call log is in the REPL's pane or log)`);
-    // Worked out from the whole log: the summary no longer says whether the element was found.
-    summary.uncertain = !/waiting for locator/.test(message) || /resolved to/.test(message);
+    // Unknown only once input was sent, in any retry. Playwright's checks (visible, enabled, stable, and
+    // an element covering the point) come before it logs "performing <x> action" and sends it.
+    summary.uncertain = /performing \w+ action/.test(message);
     throw summary;
   }
 }
@@ -227,6 +230,18 @@ function mouseButton(args, name) {
 // A page that renders the chosen element again (as React lists do) replaces it before it is
 // acted on; it is chosen again then, as Playwright finds a locator's element again.
 async function pointerAction(selector, act, options = {}, clicks = 0) {
+  try {
+    return await choosingPointerAction(selector, act, options, clicks);
+  } catch (error) {
+    // Playwright counts aria-disabled as disabled, though a page may keep such an element clickable.
+    if (clicks && !options.force && /: element is not enabled \(/.test(error.message)) {
+      error.message += '\nIt may be aria-disabled, which counts as disabled; --force clicks it anyway (help click).';
+    }
+    throw error;
+  }
+}
+
+async function choosingPointerAction(selector, act, options, clicks) {
   const TIMEOUT = 5000;
   const deadline = Date.now() + TIMEOUT;
   const left = () => Math.max(1000, deadline - Date.now());
@@ -424,15 +439,93 @@ function dateInputHolds(kind, value, what, selector) {
   return `, a ${kind} input, which now holds ${value}`;
 }
 
+// mouse's actions.
+const MOUSE = {
+  // At a point, in CSS pixels from the top left of the tab's viewport, as playwright-cli's are.
+  async move(args) {
+    const [x, y, extra] = numbers(args, 'mouse move <x> <y>');
+    if (y === undefined || extra !== undefined) throw new Error('Usage: mouse move <x> <y>, in CSS pixels from the top left of the viewport');
+    stepTarget(state.page, null, { x, y });
+    await glideTo(state.page, x, y);
+    await state.page.mouse.move(x, y);
+    tabState(state.page).mouseAt = { x, y };
+    out.log(`Moved the mouse to ${x}, ${y}`);
+  },
+
+  // A click at a point, as Playwright's mouse.click: for what has no selector, such as a marker drawn on a canvas.
+  async click(line) {
+    const usage = 'mouse click <x> <y> [left|right|middle] [--button=<button>] [--click-count=<n>] [--delay=<ms>]';
+    const { words, found, button } = mouseArgs(line, usage, { 'click-count': 'value', delay: 'value' });
+    const clickCount = clickCountOf(found, usage);
+    const delay = found.find(o => o.name === 'delay');
+    if (delay && !/^\d+$/.test(delay.value || '')) throw new Error(`Usage: ${usage}, the ms between press and release, e.g. mouse click 400 300 --delay=500`);
+    const held = delay ? Number(delay.value) : 0;
+    const [x, y, extra] = numbers(words.join(' '), usage);
+    if (y === undefined || extra !== undefined) throw new Error(`Usage: ${usage}, in CSS pixels from the top left of the viewport`);
+    stepTarget(state.page, null, { x, y });
+    await glideTo(state.page, x, y);
+    await state.page.mouse.move(x, y);
+    tabState(state.page).mouseAt = { x, y };
+    // Each press counts up, as Playwright's mouse.click does it. The ring shows at the first press, as
+    // mouse down's does, while a --delay holds the button.
+    for (let count = 1; count <= clickCount; count += 1) {
+      await state.page.mouse.down({ button, clickCount: count });
+      if (count === 1) await showClick(state.page, clickCount);
+      if (held) await new Promise(resolve => setTimeout(resolve, held));
+      await state.page.mouse.up({ button, clickCount: count });
+    }
+    out.log(`Clicked the ${button} button at ${x}, ${y}${clickCount > 1 ? ` ${clickCount} times` : ''}`);
+  },
+
+  // Two mouse clicks are two single clicks (each event's detail is 1), so no dblclick fires: this is one.
+  async dblclick(line) {
+    const usage = 'mouse dblclick <x> <y> [left|right|middle] [--button=<button>]';
+    const { words, button } = mouseArgs(line, usage);
+    const [x, y, extra] = numbers(words.join(' '), usage);
+    if (y === undefined || extra !== undefined) throw new Error(`Usage: ${usage}, in CSS pixels from the top left of the viewport`);
+    stepTarget(state.page, null, { x, y });
+    await glideTo(state.page, x, y);
+    await state.page.mouse.dblclick(x, y, { button });
+    tabState(state.page).mouseAt = { x, y };
+    await showClick(state.page, 2);
+    out.log(`Double-clicked the ${button} button at ${x}, ${y}`);
+  },
+
+  async down(args) {
+    const button = mouseButton(args, 'mouse down');
+    await glideToMouse();
+    await state.page.mouse.down({ button });
+    await showClick(state.page);
+    out.log(`Pressed the ${button} button`);
+  },
+
+  async up(args) {
+    const button = mouseButton(args, 'mouse up');
+    await glideToMouse();
+    await state.page.mouse.up({ button });
+    out.log(`Released the ${button} button`);
+  },
+
+  // Wheel events where the mouse is (mouse move puts it there): a map zooms around that point.
+  async wheel(args) {
+    const [dx, dy, extra] = numbers(args, 'mouse wheel <dx> <dy>');
+    if (dy === undefined || extra !== undefined) throw new Error('Usage: mouse wheel <dx> <dy>, e.g. mouse wheel 0 300 scrolls down (negative dy up)');
+    await glideToMouse();
+    if (recordingOf(state.page)) await smoothWheel(dx, dy);
+    else await state.page.mouse.wheel(dx, dy);
+    out.log(`Turned the wheel by ${dx}, ${dy}`);
+  },
+};
+
 const commands = {
   async click(args) {
-    const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--button=<button>] [--click-count=<n>] [--modifiers=<key>[,<key>]]', true);
+    const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--button=<button>] [--click-count=<n>] [--modifiers=<key>[,<key>]] [--force]', true);
     const which = await pointerAction(selector, (on, sel, o) => (sel ? on.click(sel, o) : on.click(o)), options, options.clickCount || 1);
     out.log(`Clicked: ${shown}${which}`);
   },
 
   async dblclick(args) {
-    const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--button=<button>] [--modifiers=<key>[,<key>]]');
+    const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--button=<button>] [--modifiers=<key>[,<key>]] [--force]');
     const which = await pointerAction(selector, (on, sel, o) => (sel ? on.dblclick(sel, o) : on.dblclick(o)), options, 2);
     out.log(`Double-clicked: ${shown}${which}`);
   },
@@ -530,79 +623,11 @@ const commands = {
     pauseToShow(state.page);
   },
 
-  // At a point, in CSS pixels from the top left of the tab's viewport, as playwright-cli's are.
-  async mousemove(args) {
-    const [x, y, extra] = numbers(args, 'mousemove <x> <y>');
-    if (y === undefined || extra !== undefined) throw new Error('Usage: mousemove <x> <y>, in CSS pixels from the top left of the viewport');
-    stepTarget(state.page, null, { x, y });
-    await glideTo(state.page, x, y);
-    await state.page.mouse.move(x, y);
-    tabState(state.page).mouseAt = { x, y };
-    out.log(`Moved the mouse to ${x}, ${y}`);
-  },
-
-  // A click at a point, as Playwright's mouse.click: for what has no selector, such as a marker drawn on a canvas.
-  async mouseclick(line) {
-    const usage = 'mouseclick <x> <y> [left|right|middle] [--button=<button>] [--click-count=<n>] [--delay=<ms>]';
-    const { words, found, button } = mouseArgs(line, usage, { 'click-count': 'value', delay: 'value' });
-    const clickCount = clickCountOf(found, usage);
-    const delay = found.find(o => o.name === 'delay');
-    if (delay && !/^\d+$/.test(delay.value || '')) throw new Error(`Usage: ${usage}, the ms between press and release, e.g. mouseclick 400 300 --delay=500`);
-    const held = delay ? Number(delay.value) : 0;
-    const [x, y, extra] = numbers(words.join(' '), usage);
-    if (y === undefined || extra !== undefined) throw new Error(`Usage: ${usage}, in CSS pixels from the top left of the viewport`);
-    stepTarget(state.page, null, { x, y });
-    await glideTo(state.page, x, y);
-    await state.page.mouse.move(x, y);
-    tabState(state.page).mouseAt = { x, y };
-    // Each press counts up, as Playwright's mouse.click does it. The ring shows at the first press, as
-    // mousedown's does, while a --delay holds the button.
-    for (let count = 1; count <= clickCount; count += 1) {
-      await state.page.mouse.down({ button, clickCount: count });
-      if (count === 1) await showClick(state.page, clickCount);
-      if (held) await new Promise(resolve => setTimeout(resolve, held));
-      await state.page.mouse.up({ button, clickCount: count });
-    }
-    out.log(`Clicked the ${button} button at ${x}, ${y}${clickCount > 1 ? ` ${clickCount} times` : ''}`);
-  },
-
-  // Two mouseclicks are two single clicks (each event's detail is 1), so no dblclick fires: this is one.
-  async mousedblclick(line) {
-    const usage = 'mousedblclick <x> <y> [left|right|middle] [--button=<button>]';
-    const { words, button } = mouseArgs(line, usage);
-    const [x, y, extra] = numbers(words.join(' '), usage);
-    if (y === undefined || extra !== undefined) throw new Error(`Usage: ${usage}, in CSS pixels from the top left of the viewport`);
-    stepTarget(state.page, null, { x, y });
-    await glideTo(state.page, x, y);
-    await state.page.mouse.dblclick(x, y, { button });
-    tabState(state.page).mouseAt = { x, y };
-    await showClick(state.page, 2);
-    out.log(`Double-clicked the ${button} button at ${x}, ${y}`);
-  },
-
-  async mousedown(args) {
-    const button = mouseButton(args, 'mousedown');
-    await glideToMouse();
-    await state.page.mouse.down({ button });
-    await showClick(state.page);
-    out.log(`Pressed the ${button} button`);
-  },
-
-  async mouseup(args) {
-    const button = mouseButton(args, 'mouseup');
-    await glideToMouse();
-    await state.page.mouse.up({ button });
-    out.log(`Released the ${button} button`);
-  },
-
-  // Wheel events where the mouse is (mousemove puts it there): a map zooms around that point.
-  async mousewheel(args) {
-    const [dx, dy, extra] = numbers(args, 'mousewheel <dx> <dy>');
-    if (dy === undefined || extra !== undefined) throw new Error('Usage: mousewheel <dx> <dy>, e.g. mousewheel 0 300 scrolls down (negative dy up)');
-    await glideToMouse();
-    if (recordingOf(state.page)) await smoothWheel(dx, dy);
-    else await state.page.mouse.wheel(dx, dy);
-    out.log(`Turned the wheel by ${dx}, ${dy}`);
+  // mouse <action>, as Playwright's page.mouse: at a point, or where the mouse is.
+  async mouse(line) {
+    const [action, ...rest] = (line || '').trim().split(/\s+/);
+    if (!Object.hasOwn(MOUSE, action)) throw new Error(`Usage: mouse ${Object.keys(MOUSE).join('|')} ...; help mouse says what each takes`);
+    await MOUSE[action](rest.join(' '));
   },
 
   async fill(line) {

package/lib/help.js

@@ -27,11 +27,12 @@ const TASKS = [
   ['see where I am', 'tab, info'],
   ['see what is on the page', 'snapshot, screenshot'],
   ['do something on it', 'click, fill, type, press, drag'],
-  ['click what has no selector (a canvas)', 'mouseclick <x> <y>, mousedblclick <x> <y>'],
+  ['click what has no selector (a canvas)', 'mouse click <x> <y>, mouse dblclick <x> <y>'],
   ['run some JavaScript in the page', 'eval document.title; eval --file=check.js for a long one'],
   ['wait for a page or element', 'wait load, wait <selector> [--gone], wait text <text>'],
   ['choose a file in a file input', 'upload <selector> <file>'],
   ['see it as a phone, or in dark mode', 'emulate mobile, emulate dark'],
+  ['tap, swipe or pinch as a finger', 'touch tap <x> <y>, touch pinch <x> <y> <scale>'],
   ['see what the page requested', 'requests, then body <#> for what one got back'],
   ['see console messages and errors', 'console'],
   ['show an agent what I do', 'watch on, click around, then watch'],
@@ -85,9 +86,9 @@ tab on its own lists them all.`,
   interact: {
     intro: `Selectors are Playwright selectors (CSS, text=..., role=...) or snapshot refs such as e5.
 Commands use the first match (click, dblclick and hover the first they can use: help click); see help
-fill for selectors with spaces. mousemove and the other mouse commands act at a point instead. An action
+fill for selectors with spaces. mouse and touch act at a point instead. An action
 scrolls its element into view first, as Playwright does; profile counts that scroll in the action's step.`,
-    commands: ['click', 'dblclick', 'hover', 'drag', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mousemove', 'mouseclick', 'mousedblclick', 'mousedown', 'mouseup', 'mousewheel'],
+    commands: ['click', 'dblclick', 'hover', 'drag', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mouse', 'touch'],
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
@@ -216,6 +217,7 @@ afresh.`,
       ['--button=<button>', 'the button, after any selector: click #menu --button=right. Over send, the shell takes the quotes, so pw-repl send click \'#menu\' right clicks a selector "#menu right": use --button, or quote it twice (\'"#menu"\').'],
       ['--click-count=<n>', 'clicks this many times at once, as Playwright\'s clickCount: 2 is a double-click (as dblclick), 3 a triple-click, which selects a line of text or all of a field\'s. 1 to 3. Default: 1.'],
       ['--modifiers=<keys>', 'keys held down meanwhile, comma-separated: Alt, Control, ControlOrMeta, Meta, Shift.'],
+      ['--force', 'skips Playwright\'s actionability checks (enabled, stable, not covered), as Playwright\'s force. For an element marked aria-disabled, which Playwright counts as disabled, that a page keeps clickable (a greyed menu item that says why). Several matches are still chosen from as below; a covered ref or single match is clicked where it is, so what covers it gets the click.'],
     ],
     detail: `Several matches: hidden ones and ones covered by something else (a dialog's overlay) are passed over,
 and it says which it used: Clicked: text=Buy (match 3 of 4; ...), or names the first when it was the
@@ -223,8 +225,10 @@ one: (the first of 2 matches: <h1> Buy), as it may not be the one meant. If none
 says why for each and does nothing. A ref, or a single match, is clicked as it is, waiting up to 5s for
 it to be ready.
 
-Timed out after it began acting, it says what stopped it (e.g. <div class="overlay"> intercepts pointer
-events) and that the outcome is unknown; Playwright's full call log goes to the REPL's pane or log.`,
+Timed out, it says what stopped it, and Playwright's full call log goes to the REPL's pane or log. Stopped by
+one of Playwright's checks before the click is sent, it did nothing: the element is not visible, enabled
+or stable, or <div class="overlay"> intercepts pointer events (something covers it). Stopped after it was
+sent, as when the page stops answering, the outcome is unknown.`,
   },
   dblclick: {
     usage: 'dblclick <selector> [button]',
@@ -241,61 +245,51 @@ events) and that the outcome is unknown; Playwright's full call log goes to the
     detail: `As Playwright's dragTo: it hovers the first match of <from>, presses the left button, hovers the
 first match of <to>, and releases, waiting up to 5s in all for each to be ready. An HTML5 drag (a
 draggable element) gets dragstart, dragover and drop; any other gets pointer and mouse events. A drag
-through points of its own: mousemove, mousedown, mousemove, mouseup.`,
+through points of its own: mouse move, mouse down, mouse move, mouse up.`,
   },
-  mousemove: {
-    usage: 'mousemove <x> <y>',
-    summary: 'move the mouse to a point in the viewport',
+  touch: {
+    usage: 'touch <gesture> <x> <y> ...',
+    summary: 'tap, swipe or pinch at a point, as a finger',
     args: [
-      ['<x> <y>', 'CSS pixels from the top left of the tab\'s viewport (not the page), as mouse events have them.'],
+      ['tap <x> <y>', 'a tap: the page gets pointer and touch events, then click.'],
+      ['doubletap <x> <y>', 'two taps: a dblclick after them.'],
+      ['longpress <x> <y> [time]', 'held down this long, then lifted. Default: 800ms. In headless Chromium it is still a tap, with click and no contextmenu; a page\'s own timer on pointerdown sees it held.'],
+      ['swipe <x> <y> <dx> <dy>', 'one finger down at x,y, moved by dx,dy in small steps about a frame apart, then lifted.'],
+      ['pinch <x> <y> <scale>', 'two fingers side by side about x,y, 100px apart, moved apart until they are scale times that far apart, then lifted: 2 zooms in, under 1 (0.5) pinches in.'],
     ],
-    detail: `A snapshot has no coordinates; eval of getBoundingClientRect gives an element's centre:
-eval (r => [r.x + r.width / 2, r.y + r.height / 2])(document.querySelector("#map")
-  .getBoundingClientRect())
-
-A click at a point: mouseclick <x> <y>; a double-click: mousedblclick <x> <y>. A drag: mousedown, then mousemove to another point, then mouseup.`,
+    detail: `<x> <y> are CSS pixels from the top left of the viewport, as for mouse commands. It needs a touch screen:
+emulate mobile, then reload, so the page sees one; without it, touch refuses.
+
+Chromium takes a tap sent soon after a swipe or pinch as part of it, with no click: up to a few seconds
+after (sleep 3s). A page that pans or zooms itself on touch (no touch-action: none) ends a swipe with
+pointercancel, not pointerup, as it would for a finger.
+
+For what these do not make, cdp Input.dispatchTouchEvent, one event at a time (help cdp). Each finger has an id,
+and touchEnd lists the fingers lifted; the others stay down. One finger lifted mid-pinch, the other moving on:
+a touchStart with two points (ids 0 and 1), then cdp Input.dispatchTouchEvent
+{"type":"touchEnd","touchPoints":[{"x":150,"y":300,"id":0}]}, then touchMove listing only id 1, then touchEnd
+with no points, which lifts the rest.`,
   },
-  mouseclick: {
-    usage: 'mouseclick <x> <y> [button]',
-    summary: 'click at a point in the viewport',
+  mouse: {
+    usage: 'mouse <action> ...',
+    summary: 'move, click or press at a point, or turn the wheel',
     args: [
-      ['<x> <y>', 'CSS pixels from the top left of the tab\'s viewport, as for mousemove.'],
-      ['[button]', 'left, right or middle. Default: left.'],
-    ],
-    options: [
-      ['--button=<button>', 'the button, as click\'s: mouseclick 400 300 --button=right.'],
-      ['--click-count=<n>', 'as click\'s: 2 is a double-click (as mousedblclick), 3 a triple-click. 1 to 3. Default: 1.'],
-      ['--delay=<ms>', 'holds the button down this long between press and release, as Playwright\'s mouse.click delay. Default: 0.'],
+      ['move <x> <y>', 'moves the mouse there: CSS pixels from the top left of the tab\'s viewport (not the page), as mouse events have them.'],
+      ['click <x> <y> [button]', 'clicks there: left, right or middle (Default: left), or --button=<button>; --click-count=<n> as click\'s (2 a double-click, 3 a triple-click); --delay=<ms> holds the button that long, as Playwright\'s mouse.click delay.'],
+      ['dblclick <x> <y> [button]', 'mouse click --click-count=2, as Playwright\'s mouse.dblclick: two clicks and a dblclick. Two mouse clicks are two single clicks, which fire no dblclick.'],
+      ['down [button] | up [button]', 'presses or releases a button where the mouse is. A drag: mouse down, mouse move to another point, mouse up.'],
+      ['wheel <dx> <dy>', 'turns the wheel where the mouse is; positive dy scrolls down. A map zooms around the mouse: mouse move 400 300, then mouse wheel 0 -300 zooms in. It returns once the events are sent, not once the page has redrawn; while recording, it scrolls in eased steps over up to 1s (help record).'],
     ],
     detail: `For what has no selector, such as a marker drawn on a canvas; anything a selector finds is better
-clicked with click, which waits for it. help mousemove shows how to find a point. The mouse stays at the point, for a mousewheel or mousedown after
-it. The cursor (help cursor) moves there first and shows a ring at the press.`,
-  },
-  mousedblclick: {
-    usage: 'mousedblclick <x> <y> [button]',
-    summary: 'double-click at a point in the viewport',
-    args: [
-      ['<x> <y>', 'CSS pixels from the top left of the tab\'s viewport, as for mousemove.'],
-      ['[button]', 'left, right or middle. Default: left.'],
-    ],
-    options: [
-      ['--button=<button>', 'the button, as click\'s.'],
-    ],
-    detail: `mouseclick --click-count=2, as Playwright's mouse.dblclick is: the page gets two clicks and a
-dblclick. Two mouseclicks are two single clicks, which fire no dblclick. For a triple-click: mouseclick
-<x> <y> --click-count=3.`,
-  },
-  mousedown: { usage: 'mousedown [button]', summary: 'press a mouse button at the mouse (left, right, middle)', detail: 'The button is a word or --button=<button>, as for mouseclick.' },
-  mouseup: { usage: 'mouseup [button]', summary: 'release a mouse button where the mouse is', detail: 'The button is a word or --button=<button>, as for mouseclick.' },
-  mousewheel: {
-    usage: 'mousewheel <dx> <dy>',
-    summary: 'turn the wheel where the mouse is',
-    args: [
-      ['<dx> <dy>', 'CSS pixels; positive dy scrolls down.'],
-    ],
-    detail: `The events go to the mouse's point (mousemove puts it there): a map zooms around it, so mousemove 400
-300, then mousewheel 0 -300 zooms in. It returns once the events are sent, not once the page has
-scrolled or redrawn. While recording, it scrolls in eased steps over up to 1s (help record).`,
+clicked with click, which waits for it. The mouse stays where it went, for a mouse wheel or mouse down
+after it. The cursor (help cursor) moves there first and shows a ring at a press. Under emulate mobile it is
+still the mouse; touch sends a finger's events (help touch).
+
+A snapshot has no coordinates; eval of getBoundingClientRect gives an element's centre:
+eval (r => [r.x + r.width / 2, r.y + r.height / 2])(document.querySelector("#map")
+  .getBoundingClientRect())
+
+playwright-cli's mouse move, mouse down, mouse up and mouse wheel run these.`,
   },
   fill: {
     usage: 'fill <selector> <value> [--submit]',
@@ -533,7 +527,7 @@ circle). That changes the page, so put it back afterwards, as it was if it had a
     summary: 'save a PNG of the viewport, --full page or an element',
     args: [
       ['[<ref>]', 'only that element, from a snapshot ref: screenshot e5.'],
-      ['[name]', 'saved as screenshot-<name>.png; letters, digits, underscores and hyphens. Default: a timestamp.'],
+      ['[name]', 'saved as screenshot-<name>.png; letters, digits, underscores and hyphens. Default: a timestamp. A word with a / or ending in .png, .jpg or .jpeg is a file instead, as --filename: x.png is the file x.png, not screenshot-x.png. At the prompt, a path with a space goes in --filename="<file>"; through pw-repl send, either works.'],
     ],
     options: [
       ['--full', 'the whole page, not only the viewport; --full-page too.'],
@@ -591,14 +585,14 @@ shows in screenshots and recordings. Selectors, snapshot and text don't see it,
     detail: `The REPL's clicks and typing don't move a pointer on screen, so a recording shows things happening
 with nothing pointing at them. With the cursor on, these commands move it smoothly to their element or
 point before they act: click, dblclick, hover, drag (to each end), fill, type <selector>, press <selector>, select, check,
-uncheck, upload, mousemove, mouseclick and mousedblclick. Each move takes 150 to 600ms by distance (300 to 1000ms while the tab
-records), and the command waits for it. Clicks (click, dblclick, check, uncheck, mouseclick, mousedblclick, mousedown, and upload
+uncheck, upload, mouse move, mouse click and mouse dblclick. Each move takes 150 to 600ms by distance (300 to 1000ms while the tab
+records), and the command waits for it. Clicks (click, dblclick, check, uncheck, mouse click, mouse dblclick, mouse down, and upload
 when it clicks a button) show a ring where they land.
 
 Only the drawing moves: no mouse events are sent along the way, so the page gets the same input as with
 the cursor off. It shows only the REPL's input, from every client, never the user's own mouse. fill,
-select and the like move the drawing but leave the real mouse where it was; mousedown, mouseup and
-mousewheel act at the real mouse, so the pointer moves back there first.
+select and the like move the drawing but leave the real mouse where it was; mouse down, mouse up and
+mouse wheel act at the real mouse, so the pointer moves back there first.
 
 It is a mode of its tab: modes lists it and modes off turns it off. It stays on across page loads, at
 the same spot, and shows in screenshots and recordings. Selectors, snapshot and text don't see it, it
@@ -626,7 +620,7 @@ or headless tab keeps recording. It brings the tab to the front first, as screen
 owner-only, as a screenshot is, and never replaces one. One recording per tab; another client with the
 tab selected can stop it, and both are told whose it was.
 
-While recording: type types at a pace the video can show (help type), mousewheel scrolls in eased steps,
+While recording: type types at a pace the video can show (help type), mouse wheel scrolls in eased steps,
 an element out of view is scrolled to smoothly, each action and each highlight drawn is followed by --pause, and with the cursor
 on it rests 300ms on the element before acting. fill still sets a value at once: use type for text the
 viewer should see typed. Send the take as a file of commands (pw-repl send --file take.txt), or the time
@@ -915,7 +909,7 @@ window.__done until it is set.`,
   },
   cdp: {
     usage: 'cdp [--all] <method> <JSON object>',
-    summary: 'send one CDP command through a temporary session',
+    summary: 'send one CDP command to the selected tab',
     args: [
       ['<method>', 'a CDP method: Network.getCookies.'],
       ['<JSON object>', 'its parameters: {} for none.'],
@@ -923,8 +917,21 @@ window.__done until it is set.`,
     options: [
       ['--all', 'the whole result, not capped.'],
     ],
-    detail: `The session is detached afterwards, so subscriptions and settings do not persist. Browser.close and
-Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog answers one.`,
+    detail: `A command goes through a temporary session, detached afterwards, so subscriptions and settings do not
+persist (input aside, below). Browser.close and Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog
+answers one.
+
+Input (Input.dispatchTouchEvent, dispatchMouseEvent, the synthesize gestures): through a session kept for
+the tab, so a sequence sent one call at a time stays one sequence (Chrome drops it when the session that
+began it detaches). End one before other commands (touchEnd, or touchCancel to drop it): left open, the
+next click lands mid-touch. Input.setIgnoreInputEvents and setInterceptDrags go through a temporary session,
+as they would otherwise stay on and break later clicks.
+
+Touch (under emulate mobile, for pointerType touch): touchStart and touchEnd sent this way make a tap, with
+click, and two in a row a dblclick; held, it is still a tap, with no contextmenu. Chrome takes a tap sent
+soon after another gesture as part of it, with no click: up to a few seconds after a drag (sleep 3s). The synthesize gestures
+(Input.synthesizeTapGesture, synthesizePinchGesture, synthesizeScrollGesture) send pointer and touch events
+but no click, dblclick or contextmenu.`,
   },
   clipboard: {
     usage: 'clipboard [--all] [--shared-clipboard]',
@@ -1087,11 +1094,6 @@ Different on purpose, since the browser may be someone else's too:
   const asCommand = /^(\S+)\s+--command$/.exec(topicOrCommand);
   if (asCommand && Object.hasOwn(COMMANDS, asCommand[1])) return renderCommand(asCommand[1]);
   if (Object.hasOwn(COMMANDS, topicOrCommand)) return renderCommand(topicOrCommand);
-  // Not a topic: the mouse commands are in interact, with the others that act on the page.
-  if (topicOrCommand === 'mouse') {
-    const mice = TOPICS.interact.commands.filter(c => c.startsWith('mouse'));
-    return ['The mouse commands, which act at a point (part of help interact):', '', ...commandLines(mice)].join('\n');
-  }
   const full = /^(\S+)\s+--all$/.exec(topicOrCommand);
   if (full && Object.hasOwn(COMMANDS, full[1])) return renderCommand(full[1], true);
   // A playwright-cli name: what it runs here, with that command's help.
@@ -1108,9 +1110,13 @@ Different on purpose, since the browser may be someone else's too:
 // pw-repl's own commands are run at the shell, so their help is the usage.
 const SHELL_COMMANDS = new Set(['run', 'serve', 'send', 'attach', 'stop', 'where', 'skill']);
 
+// Commands that were renamed, so the old name says where it went.
+const RENAMED = { mouseclick: 'mouse click', mousedblclick: 'mouse dblclick' };
+
 function notFound(topic) {
+  if (Object.hasOwn(RENAMED, topic)) return `${topic} is now ${RENAMED[topic]}: help ${RENAMED[topic].split(' ')[0]}`;
   if (SHELL_COMMANDS.has(topic)) return `${topic} is run at the shell (pw-repl ${topic}), not in the REPL; pw-repl --help has its options`;
   return `No help for ${topic}. Topics: ${Object.keys(TOPICS).join(', ')}`;
 }
 
-module.exports = { render, notFound, TOPICS, COMMANDS, TASKS, MODES };
+module.exports = { render, notFound, TOPICS, COMMANDS, TASKS, MODES, RENAMED };

package/lib/inspect.js

@@ -5,7 +5,7 @@ const { state, withTimeout } = require('./state');
 const out = require('./output');
 const { printOutput } = out;
 const { devices } = require('playwright-core');
-const { toSelector, REF, unquote } = require('./syntax');
+const { toSelector, REF, SCREENSHOT_FILE, unquote } = require('./syntax');
 const { regexOf, COMMAND_TIMEOUT, BUSY_PAGE, TIME, parseDuration, durationText } = require('./util');
 const { tabState } = require('./tabstate');
 const { noteWritten } = require('./written');
@@ -316,7 +316,7 @@ const commands = {
   },
 
   async screenshot(args) {
-    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <time>] [name | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens.';
+    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <time>] [name | <file> | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens; a word with a / or ending in .png, .jpg or .jpeg is a file.';
     // The file first: a path may be quoted, with spaces in it.
     let file = null;
     const rest = (args || '').replace(/(?:^|\s)--filename(?:=|\s+)("(?:[^"\\]|\\.)*"|'[^']*'|\S+)/, (_, value) => { file = unquote(value); return ' '; });
@@ -339,6 +339,11 @@ const commands = {
         if (delay === null || delay > SCREENSHOT_DELAY_MAX) throw new Error(`Usage: screenshot --delay <time> (ms, or 5s; at most ${durationText(SCREENSHOT_DELAY_MAX)})`);
         continue;
       }
+      if (SCREENSHOT_FILE.test(token)) {
+        if (file) throw new Error(usage);
+        file = token;
+        continue;
+      }
       names.push(token);
     }
     if (names.length > 1 || (names[0] && !/^[a-zA-Z0-9_-]+$/.test(names[0])) || (file && names.length) || (ref && full)) throw new Error(usage);
@@ -599,6 +604,13 @@ const commands = {
     if (match[1] === 'Page.handleJavaScriptDialog') throw new Error(CDP_REFUSED);
     const params = JSON.parse(match[2]);
     if (!params || Array.isArray(params) || typeof params !== 'object') throw new Error('Parameters must be a JSON object');
+    // Input sent through the tab's kept session: Chrome drops a touch or mouse sequence when the session
+    // that began it detaches. Not Input's two switches, which would stay on and break later clicks.
+    if (/^Input\./.test(match[1]) && !['Input.setIgnoreInputEvents', 'Input.setInterceptDrags'].includes(match[1])) {
+      const kept = await keptSession(state.page);
+      printOutput(await withTimeout(kept.send(match[1], params), 'CDP operation', COMMAND_TIMEOUT), all);
+      return;
+    }
     const operation = async () => {
       const cdp = await state.page.context().newCDPSession(state.page);
       try {

package/lib/record.js

@@ -393,13 +393,13 @@ function videoTime(rec) {
 // What a step is, for its line: the command and what it acts on, never what it types or chooses, the
 // code it runs or the URL it goes to, which can hold a password or a token. A steps file goes where the
 // video goes, and the video shows a password as dots.
-const WHOLE = new Set(['click', 'dblclick', 'hover', 'drag', 'check', 'uncheck', 'mousemove', 'mouseclick', 'mousedblclick', 'mousedown', 'mouseup', 'mousewheel']);
+const WHOLE = new Set(['click', 'dblclick', 'hover', 'drag', 'check', 'uncheck', 'mouse']);
 const TARGET_FIRST = new Set(['fill', 'type', 'select', 'press', 'upload']);
 function stepLabel(cmd, args) {
   if (WHOLE.has(cmd)) {
     const words = args.replace(/\s+--modifiers=\S+/, '').trim();
     // An element's selector as written, without the quotes it needed on the command line (click's button after it).
-    const parsed = /^mouse/.test(cmd) ? null : splitSelector(words);
+    const parsed = cmd === 'mouse' ? null : splitSelector(words);
     return `${cmd} ${parsed ? [parsed.word, parsed.rest].filter(Boolean).join(' ') : words}`.trim();
   }
   // A toast's text is what it said in the video, for whoever edits it.

package/lib/runner.js

@@ -7,6 +7,7 @@ const { commands, cliCommands, needsTab } = require('./commands');
 const { dialogCommand, CDP_ANSWER, CDP_REFUSED } = require('./dialogs');
 const { activeModes } = require('./modes');
 const { NO_TAB } = require('./util');
+const { RENAMED } = require('./help');
 const { stepStarted, stepEnded, stepLabel, pauseAfter } = require('./record');
 const cliNames = require('./cli-names');
 const { expandVariables } = require('./syntax');
@@ -108,6 +109,10 @@ async function executeCommand(text) {
       out.error(`Error: ${cmd} is a pw-repl subcommand, run at the shell: pw-repl ${cmd}${args ? ' ...' : ''}`);
       return { status: 'error', cmd };
     }
+    if (Object.hasOwn(RENAMED, cmd)) {
+      out.error(`Error: ${cmd} is now ${RENAMED[cmd]}: help ${RENAMED[cmd].split(' ')[0]}`);
+      return { status: 'error', cmd };
+    }
     out.log(`Unknown command: ${cmd}. Type 'help' for commands.`);
     return { status: 'error', cmd };
   }

package/lib/send.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const client = require('./client');
-const { shellWords, variablesIn } = require('./syntax');
+const { shellWords, variablesIn, SCREENSHOT_FILE } = require('./syntax');
 
 // The prompt, after the modes on in the selected tab if any: (watch network:off) pw[serve]>
 const PROMPT = /^(?:\([^()]*\) )?pw(\[serve\])?>\s*$/;
@@ -139,7 +139,8 @@ function commandLine(words) {
     if (file) resolved = [...words.slice(0, at), `--file=${resolve(file)}`, ...rest];
   }
   if (words[0] === 'screenshot') {
-    resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : w));
+    // A file as a word of its own is sent as --filename, so a space in it stays in it.
+    resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : n && !w.startsWith('-') && SCREENSHOT_FILE.test(w) ? `--filename=${resolve(w)}` : w));
   }
   const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? doubleQuote(w) : w)) : resolved;
   // An option's value the shell kept whole stays whole too: --device='iPhone 15'.

package/lib/syntax.js

@@ -89,4 +89,7 @@ function expandVariables(line, values) {
   });
 }
 
-module.exports = { SELECTOR_FIRST, REF, toSelector, unescapeDouble, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };
+// A screenshot's file given as a word of its own: a name has neither a / nor an extension.
+const SCREENSHOT_FILE = /\/|\.(?:png|jpe?g)$/i;
+
+module.exports = { SELECTOR_FIRST, REF, SCREENSHOT_FILE, toSelector, unescapeDouble, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };

package/lib/tabs.js

@@ -21,6 +21,12 @@ async function navigating(go) {
     for (let waited = 0; !find() && waited < 1000; waited += 50) await new Promise(resolve => setTimeout(resolve, 50));
     const navigation = find();
     if (!navigation) throw error;
+    // Chrome commits its error page just after the request fails: waited for, so info right after reads it.
+    // Capped at 1s, for a failure with no error page; a tab already on one matches at once, which info
+    // still reads right, from the log.
+    if (!stayedPut(navigation) && !/ERR_ABORTED/.test(`${navigation.status} ${navigation.failed}`)) {
+      for (let waited = 0; !state.page.url().startsWith('chrome-error://') && waited < 1000; waited += 50) await new Promise(resolve => setTimeout(resolve, 50));
+    }
     throw new Error(notLoaded(navigation));
   }
 }

package/lib/touch.js

@@ -0,0 +1,93 @@
+// touch: gestures at points in the viewport, as a finger makes them, for a tab under emulate mobile.
+// Raw touch events through the tab's kept CDP session, not Chrome's synthesize gestures, which send
+// no click or dblclick.
+const { state } = require('./state');
+const out = require('./output');
+const { numbers, parseDuration, durationText } = require('./util');
+const { tabState } = require('./tabstate');
+const { keptSession } = require('./cdp');
+
+const GESTURES = ['tap', 'doubletap', 'longpress', 'swipe', 'pinch'];
+const LONGPRESS = 800;
+// A move every frame or so: one jump would read as no swipe to a page that measures its speed.
+const STEP_MS = 16;
+const STEPS = 12;
+// Where pinch's two fingers start: this far apart, side by side about the point.
+const PINCH_SPAN = 100;
+
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+async function send(type, points) {
+  const session = await keptSession(state.page);
+  await session.send('Input.dispatchTouchEvent', { type, touchPoints: points.map(([x, y], id) => ({ x, y, id })) });
+}
+
+async function tap(x, y) {
+  await send('touchStart', [[x, y]]);
+  await send('touchEnd', []);
+}
+
+function usageOf(gesture) {
+  return {
+    tap: 'touch tap <x> <y>',
+    doubletap: 'touch doubletap <x> <y>',
+    longpress: 'touch longpress <x> <y> [time]',
+    swipe: 'touch swipe <x> <y> <dx> <dy>',
+    pinch: 'touch pinch <x> <y> <scale>',
+  }[gesture];
+}
+
+const commands = {
+  async touch(args) {
+    const [gesture, ...rest] = (args || '').trim().split(/\s+/);
+    if (!GESTURES.includes(gesture)) throw new Error(`Usage: touch ${GESTURES.join('|')} <x> <y> ...; help touch says what each takes`);
+    const usage = `Usage: ${usageOf(gesture)}`;
+    // Without it the page gets touch events but no touch screen: pointerType and the like say otherwise.
+    if (!tabState(state.page).emulation?.device) throw new Error('touch needs a touch screen: emulate mobile first, then reload');
+    const counts = { tap: 2, doubletap: 2, longpress: 3, swipe: 4, pinch: 3 }[gesture];
+    if (gesture === 'longpress' && rest.length === 3) {
+      const held = parseDuration(rest[2]);
+      if (held === null) throw new Error(`${usage}, the time in ms or seconds (1.5s)`);
+      rest[2] = String(held);
+    }
+    const values = numbers(rest.join(' '), usageOf(gesture));
+    if (values.length < (gesture === 'longpress' ? 2 : counts) || values.length > counts) throw new Error(usage);
+    const [x, y] = values;
+    if (gesture === 'tap') {
+      await tap(x, y);
+      out.log(`Tapped at ${x}, ${y}`);
+    } else if (gesture === 'doubletap') {
+      await tap(x, y);
+      await tap(x, y);
+      out.log(`Double-tapped at ${x}, ${y}`);
+    } else if (gesture === 'longpress') {
+      const held = values[2] ?? LONGPRESS;
+      await send('touchStart', [[x, y]]);
+      await wait(held);
+      await send('touchEnd', []);
+      out.log(`Long-pressed at ${x}, ${y} for ${durationText(held)}`);
+    } else if (gesture === 'swipe') {
+      const [, , dx, dy] = values;
+      await send('touchStart', [[x, y]]);
+      for (let i = 1; i <= STEPS; i++) {
+        await wait(STEP_MS);
+        await send('touchMove', [[x + dx * i / STEPS, y + dy * i / STEPS]]);
+      }
+      await send('touchEnd', []);
+      out.log(`Swiped from ${x}, ${y} to ${x + dx}, ${y + dy}`);
+    } else {
+      const scale = values[2];
+      if (!(scale > 0)) throw new Error(`${usage}: a scale above 0; under 1 pinches in`);
+      const fingers = span => [[x - span / 2, y], [x + span / 2, y]];
+      await send('touchStart', fingers(PINCH_SPAN));
+      for (let i = 1; i <= STEPS; i++) {
+        await wait(STEP_MS);
+        await send('touchMove', fingers(PINCH_SPAN * (1 + (scale - 1) * i / STEPS)));
+      }
+      await send('touchEnd', []);
+      out.log(`Pinched at ${x}, ${y} to ${scale}x`);
+    }
+  },
+};
+
+module.exports = { commands, GESTURES };

package/package.json

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

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, what a page copied to the clipboard, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, recording what the user does, profiling what makes a page slow (long tasks, forced layouts, input delay, dropped frames), and recording a video of a tab, with a pointer and on-screen captions. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
+description: Inspect and drive a Chromium browser, possibly one the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), touch gestures on an emulated phone (tap, swipe, pinch), requests and their bodies, console messages, what a page copied to the clipboard, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, recording what the user does, profiling what makes a page slow (long tasks, forced layouts, input delay, dropped frames), and recording a video of a tab, with a pointer and on-screen captions. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
 allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 ---
 
@@ -183,8 +183,9 @@ blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --hel
 Run `pw-repl send help`. It lists seven topics; `help <topic>` lists their commands, `help <command>`
 gives usage and caveats: read it before you use a command, since this file does not repeat them. When a
 command fails or does something you did not expect, read its `help <command>` before working around it.
-`help --all` prints everything at once. pw-repl answers help itself: it needs no running REPL, and never
-reaches one. If you know playwright-cli, its command names work too (`help playwright-cli` lists them).
+`help --all` prints everything, tens of kilobytes: a last resort, when the topics and commands have not
+answered. pw-repl answers help itself: it needs no running REPL, and never reaches one. If you know
+playwright-cli, its command names work too (`help playwright-cli` lists them).
 
 ### Coming from playwright-cli