pw-repl 0.14.0 → 0.15.1

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;

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`                        |

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

@@ -9,7 +9,7 @@ const { numbers, hints, BUSY_PAGE } = require('./util');
 const { tabState } = require('./tabstate');
 const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
 const { recordingOf, stepTarget, pauseToShow } = require('./record');
-const { settled } = require('./emulation');
+const { settled, outsideViewport, IN_VIEW } = require('./emulation');
 
 // The type a page sees for a file it is given, from its extension.
 const MIME_TYPES = {
@@ -439,6 +439,135 @@ function dateInputHolds(kind, value, what, selector) {
   return `, a ${kind} input, which now holds ${value}`;
 }
 
+// drag <x1> <y1> <x2> <y2>: for what has no element to drag by, such as a canvas or a map's pan. Moved in
+// steps, as a page that tracks the pointer needs moves between the two points, not one jump.
+const DRAG_STEPS = 10;
+
+async function dragBetween(x1, y1, x2, y2) {
+  await refuseOutside(x1, y1, 'dragged');
+  stepTarget(state.page, null, { x: x1, y: y1 });
+  await glideTo(state.page, x1, y1);
+  await state.page.mouse.move(x1, y1);
+  await state.page.mouse.down();
+  tabState(state.page).mouseAt = { x: x1, y: y1 };
+  // Pressed from here on: a failure would leave the button down, which the page would take as a drag still going.
+  try {
+    await showClick(state.page);
+    await glideTo(state.page, x2, y2);
+    await state.page.mouse.move(x2, y2, { steps: DRAG_STEPS });
+  } catch (error) {
+    await state.page.mouse.up().catch(() => {});
+    throw error;
+  }
+  await state.page.mouse.up();
+  tabState(state.page).mouseAt = { x: x2, y: y2 };
+  out.log(`Dragged from ${x1}, ${y1} to ${x2}, ${y2}${await outsideNote(x2, y2)}`);
+}
+
+// mouse's actions.
+// Playwright's mouse starts at the top left.
+const mouseAt = () => tabState(state.page).mouseAt || { x: 0, y: 0 };
+
+// A press outside the viewport reaches nothing, so it is refused rather than reported done.
+async function refuseOutside(x, y, nothing) {
+  const outside = await outsideViewport(x, y);
+  if (outside) throw new Error(`${x}, ${y} is outside the viewport (${outside}); nothing was ${nothing}. ${IN_VIEW}`);
+}
+
+// mouse down and wheel act where the mouse is.
+async function refuseMouseOutside(nothing) {
+  const { x, y } = mouseAt();
+  const outside = await outsideViewport(x, y);
+  if (outside) throw new Error(`The mouse is at ${x}, ${y}, outside the viewport (${outside}); nothing was ${nothing}. mouse move to a point inside it first, or scroll what you want into view`);
+}
+
+// A move or a release may go outside it, as a drag the page holds on to can.
+async function outsideNote(x, y) {
+  const outside = await outsideViewport(x, y);
+  return outside ? ` (outside the viewport, ${outside})` : '';
+}
+
+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}${await outsideNote(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`);
+    await refuseOutside(x, y, 'clicked');
+    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`);
+    await refuseOutside(x, y, 'clicked');
+    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 refuseMouseOutside('pressed');
+    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${await outsideNote(mouseAt().x, mouseAt().y)}`);
+  },
+
+  // 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 refuseMouseOutside('scrolled');
+    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>]] [--force]', true);
@@ -456,7 +585,9 @@ const commands = {
   // source, press, hover the target, release), so the cursor can glide to each in turn. Chromium turns
   // the moves into an HTML5 drag when the source is draggable.
   async drag(args) {
-    const usage = 'Usage: drag <from> <to>, each a selector or a ref, quoted if it has spaces: drag e5 e9, drag "text=Item 1" "#list li"';
+    const usage = 'Usage: drag <from> <to>, each a selector or a ref, quoted if it has spaces: drag e5 e9, drag "text=Item 1" "#list li"; or drag <x1> <y1> <x2> <y2>, points in the viewport';
+    const words = (args || '').trim().split(/\s+/);
+    if (words.length === 4 && words.every(w => /^-?\d+(?:\.\d+)?$/.test(w))) return dragBetween(...words.map(Number));
     const from = splitSelector(args);
     const to = from?.rest !== undefined ? splitSelector(from.rest) : null;
     if (!to || to.rest !== undefined) throw new Error(usage);
@@ -545,79 +676,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/emulation.js

@@ -24,6 +24,25 @@ async function viewportText() {
   return size ? `${size} (the window's page area)` : 'unknown';
 }
 
+// The viewport's size, in the CSS pixels mouse and touch points are given in: a phone's, a size set
+// with viewport, or else the page's (a tab attached over CDP has none set, so Playwright knows none).
+async function viewportSize() {
+  const device = tabState(state.page).emulation?.device;
+  if (device) return devices[device].viewport;
+  const set = tabState(state.page).viewport;
+  if (set) return set;
+  return state.page.evaluate(() => ({ width: innerWidth, height: innerHeight })).catch(() => null);
+}
+
+// The viewport's size (1280x657) when a point is outside it; null when it is inside, or the size is unknown.
+async function outsideViewport(x, y) {
+  const size = await viewportSize();
+  if (!size || x >= 0 && y >= 0 && x < size.width && y < size.height) return null;
+  return `${size.width}x${size.height}`;
+}
+
+const IN_VIEW = 'A point is in CSS pixels from the top left of the viewport: scroll what you want into view (eval document.querySelector(<selector>).scrollIntoView(), or mouse wheel), then measure it again';
+
 const DEFAULT_DEVICE = 'Pixel 7';
 const EMULATE_KINDS = ['mobile', 'dark', 'light', 'locale', 'timezone'];
 
@@ -234,4 +253,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, viewportMetrics, setEmulation, setViewport, settled, reapplyMetrics };
+module.exports = { commands, viewportText, outsideViewport, IN_VIEW, EMULATE_KINDS, emulatedKinds, deviceMetrics, viewportMetrics, setEmulation, setViewport, settled, reapplyMetrics };

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).`,
@@ -236,69 +237,62 @@ sent, as when the page stops answering, the outcome is unknown.`,
   },
   hover: { usage: 'hover <selector>', summary: 'hover, choosing the match as click does' },
   drag: {
-    usage: 'drag <from> <to>',
-    summary: 'drag one element onto another',
+    usage: 'drag <from> <to> | <x1> <y1> <x2> <y2>',
+    summary: 'drag an element onto another, or between points',
     args: [
       ['<from> <to>', 'selectors or snapshot refs, each quoted if it has spaces: drag e5 e9, drag "text=Item 1" "#done ul".'],
+      ['<x1> <y1> <x2> <y2>', 'points, as for mouse commands: presses the left button at the first, moves to the second in 10 steps, and releases. For what has no element to drag by: a canvas, panning a map. The first point must be in the viewport; the second may be outside it.'],
     ],
     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 more points than two: mouse move, mouse down, mouse move as often as needed, 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. A finger put down outside the
+viewport is refused; a swipe may end outside it. 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. From one point to another, drag <x1> <y1> <x2> <y2> drags; through more: mouse down, mouse move to each 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. A click, or a mouse down or wheel, outside the viewport is refused: nothing there gets
+it. mouse move and mouse up go there and say so, as a drag the page holds on to can. 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]',
@@ -594,14 +588,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
@@ -629,7 +623,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
@@ -905,10 +899,12 @@ in front of it usually holds the request open, so the page spins instead of fail
     ],
     options: [
       ['--file=<path>', 'the JavaScript is the file\'s text: anything the line takes, over many lines and with // comments. With a ref or a selector after the path, it is a function called with that element (the first match). Over send, a relative path is from your shell\'s current folder.'],
-      ['--timeout=<time>', 'how long the page has to answer, before --file. Default: 15s. Past 20s, give send time too, or it gives up first and cancels the eval: pw-repl send -t 70s eval --timeout=60s ...'],
+      ['--timeout=<time>', 'how long the page has to answer. Default: 15s. Past 20s, give send time too, or it gives up first and cancels the eval: pw-repl send -t 70s eval --timeout=60s ...'],
       ['--all', 'the whole result, not capped.'],
     ],
-    detail: `eval fetch(...) sends a new request, which can change state on the server; it cannot read one that
+    detail: `Its options go before the JavaScript, in any order; --all may also go at the very end, after it.
+
+eval fetch(...) sends a new request, which can change state on the server; it cannot read one that
 already happened (requests lists those).
 
 Long work (--timeout): every other command waits while an eval runs, the other clients' too. For work of
@@ -1103,11 +1099,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.
@@ -1124,9 +1115,20 @@ 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' };
+
+// An action of mouse or touch (help swipe) is found under its command; one that is a command itself (click) has its own help.
+function actionOf(topic) {
+  return ['mouse', 'touch'].find(command => COMMANDS[command].args.some(([usage]) => usage.split(' | ').some(u => u.split(' ')[0] === topic)));
+}
+
 function notFound(topic) {
+  if (Object.hasOwn(RENAMED, topic)) return `${topic} is now ${RENAMED[topic]}: help ${RENAMED[topic].split(' ')[0]}`;
+  const command = actionOf(topic);
+  if (command) return `${topic} is ${command} ${topic}: help ${command}`;
   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

@@ -493,75 +493,96 @@ const commands = {
 
   async eval(args, all) {
     if (!args) throw new Error('Usage: eval <js-expression>');
-    // eval --timeout=<time> [--file=...] <JavaScript>: how long the page has to answer.
+    // Its options, in any order, before the JavaScript; once that starts, nothing is an option (x --all is JavaScript).
+    // --timeout=<time>: how long the page has to answer. --file=<path>: the JavaScript is the file's text.
     let timeout = COMMAND_TIMEOUT;
-    const timed = /^--timeout(?:=|\s+)(\S+)(?:\s+([\s\S]*))?$/.exec(args.trim());
-    if (/^--timeout(?:[=\s]|$)/.test(args.trim())) {
-      timeout = parseDuration(timed?.[1]);
-      if (!timeout) throw new Error('Usage: eval --timeout=<time> <JavaScript>, a time in ms or with s: eval --timeout=60s ...');
-      args = timed[2] || '';
-      if (!args.trim()) throw new Error('Usage: eval --timeout=<time> <JavaScript>');
-    }
-    let ref = null;
-    // eval --file=<path> [<ref or selector>]: the file's text is what the line would be, over as many lines as
-    // it likes. The rest of the line can only be the element, so any selector goes there, not only a ref.
-    const fromFile = /^--file(?:=|\s+)("(?:[^"\\]|\\.)*"|'[^']*'|\S+)(?:\s+([\s\S]*))?$/.exec(args.trim());
-    if (/^--file(?:[=\s]|$)/.test(args.trim())) {
-      if (!fromFile) throw new Error('Usage: eval --file=<path> [<ref or selector>]: the JavaScript is in the file');
-      const file = path.resolve(unquote(fromFile[1]));
-      const target = fromFile[2]?.trim() || null;
-      try { args = fs.readFileSync(file, 'utf8').trim(); } catch (error) {
-        // eval --file=my dir/x.js reads "my" as the file and "dir/x.js" as the element.
-        throw new Error(`eval --file: cannot read ${file} (${error.code || error.message})${target ? '; quote a path with spaces' : ''}`);
+    let file = null;
+    args = args.trim();
+    for (let option; (option = /^--(all|timeout|file)(?=[=\s]|$)/.exec(args));) {
+      if (option[1] === 'all') {
+        if (!/^--all(?:\s|$)/.test(args)) break;
+        all = true;
+        args = args.slice(5).trimStart();
+      } else if (option[1] === 'timeout') {
+        const timed = /^--timeout(?:=|\s+)(\S+)(?:\s+|$)/.exec(args);
+        timeout = parseDuration(timed?.[1]);
+        if (!timeout) throw new Error('Usage: eval --timeout=<time> <JavaScript>, a time in ms or with s: eval --timeout=60s ...');
+        args = args.slice(timed[0].length);
+      } else {
+        const named = /^--file(?:=|\s+)("(?:[^"\\]|\\.)*"|'[^']*'|\S+)(?:\s+|$)/.exec(args);
+        if (!named) throw new Error('Usage: eval --file=<path> [<ref or selector>]: the JavaScript is in the file');
+        file = path.resolve(unquote(named[1]));
+        args = args.slice(named[0].length);
       }
-      if (!args) throw new Error(`eval --file: ${file} is empty`);
-      ref = target && unquote(target);
-    } else {
-      // eval <function> <ref> calls the function with that element, as playwright-cli's eval does.
-      const onRef = /^([\s\S]+?)\s+((?:f\d+)?e\d+)$/.exec(args.trim());
-      if (onRef && isFunctionText(unquote(onRef[1]))) [args, ref] = [unquote(onRef[1]), onRef[2]];
     }
-    if (ref) {
-      const selector = toSelector(ref);
-      const el = await onElement(selector, () => state.page.locator(selector).first().elementHandle({ timeout: 5000 }));
-      try {
-        // Made from its text by the debugger, as eval is, so a page's CSP cannot
-        // refuse it, and in the element's own frame, which may be an iframe.
-        const fn = await evaluated((await el.ownerFrame()).evaluateHandle(args), timeout);
+    // An option after the JavaScript is JavaScript to the page; a SyntaxError from it says so.
+    const late = !file && /(?:^|\s)(--(?:timeout|file|all))(?=[=\s]|$)/.exec(args)?.[1];
+    const run = async () => {
+      let ref = null;
+      // eval --file=<path> [<ref or selector>]: the file's text is what the line would be, over as many lines as
+      // it likes. The rest of the line can only be the element, so any selector goes there, not only a ref.
+      if (file) {
+        const target = args || null;
+        try { args = fs.readFileSync(file, 'utf8').trim(); } catch (error) {
+          // eval --file=my dir/x.js reads "my" as the file and "dir/x.js" as the element.
+          throw new Error(`eval --file: cannot read ${file} (${error.code || error.message})${target ? '; quote a path with spaces' : ''}`);
+        }
+        if (!args) throw new Error(`eval --file: ${file} is empty`);
+        ref = target && unquote(target);
+      } else {
+        if (!args) throw new Error('Usage: eval [--all] [--timeout=<time>] <JavaScript>');
+        // eval <function> <ref> calls the function with that element, as playwright-cli's eval does.
+        const onRef = /^([\s\S]+?)\s+((?:f\d+)?e\d+)$/.exec(args);
+        if (onRef && isFunctionText(unquote(onRef[1]))) [args, ref] = [unquote(onRef[1]), onRef[2]];
+      }
+      if (ref) {
+        const selector = toSelector(ref);
+        const el = await onElement(selector, () => state.page.locator(selector).first().elementHandle({ timeout: 5000 }));
         try {
-          printOutput(await evaluated(el.evaluate((e, f) => f(e), fn), timeout), all);
+          // Made from its text by the debugger, as eval is, so a page's CSP cannot
+          // refuse it, and in the element's own frame, which may be an iframe.
+          const fn = await evaluated((await el.ownerFrame()).evaluateHandle(args), timeout);
+          try {
+            printOutput(await evaluated(el.evaluate((e, f) => f(e), fn), timeout), all);
+          } finally {
+            await fn.dispose().catch(() => {});
+          }
         } finally {
-          await fn.dispose().catch(() => {});
+          await el.dispose().catch(() => {});
         }
-      } finally {
-        await el.dispose().catch(() => {});
+        return;
       }
-      return;
-    }
-    // A function, as playwright-cli's eval takes, is called rather than returned.
-    // Only a single expression can be one; statements are evaluated as they are.
-    // await at the top level: one expression is run as an async function; statements as DevTools'
-    // console runs them (replMode), which gives back the last one's value.
-    const compiles = (Kind, body) => { try { new Kind(body); return true; } catch { return false; } };
-    const AsyncFunction = (async () => {}).constructor;
-    const awaits = /\bawait\b/.test(args) && !compiles(Function, `return (${args}\n);`);
-    const single = compiles(awaits ? AsyncFunction : Function, `return (${args}\n);`);
-    const call = `const value = (${args}\n); return typeof value === 'function' ? value() : value;`;
-    if (awaits && !single && compiles(AsyncFunction, args)) {
-      const session = await keptSession(state.page);
-      const { result, exceptionDetails } = await evaluated(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }), timeout);
-      if (exceptionDetails) throw new Error(exceptionDetails.exception?.description || exceptionDetails.text);
-      printOutput(result.value !== undefined ? result.value : result.description ?? 'undefined', all);
-      return;
-    }
-    const expression = single ? `(${awaits ? 'async ' : ''}() => { ${call} })()` : args;
-    const value = await evaluated(state.page.evaluate(expression), timeout);
-    // An empty string is shown as one, not as no output at all.
-    printOutput(value === '' ? '""' : value, all);
-    // Quotes around the whole of it, as a shell's quoting sent on, make it a string, not code to run:
-    // one plain literal only, not "a" + b or a template with ${...} in it, which ran.
-    if (typeof value === 'string' && value && /^(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\$]|\\.|\$(?!\{))*`)$/s.test(args.trim())) {
-      out.log('(That is a string: the JavaScript was in quotes, which eval keeps. Without them, it runs: eval document.title)');
+      // A function, as playwright-cli's eval takes, is called rather than returned.
+      // Only a single expression can be one; statements are evaluated as they are.
+      // await at the top level: one expression is run as an async function; statements as DevTools'
+      // console runs them (replMode), which gives back the last one's value.
+      const compiles = (Kind, body) => { try { new Kind(body); return true; } catch { return false; } };
+      const AsyncFunction = (async () => {}).constructor;
+      const awaits = /\bawait\b/.test(args) && !compiles(Function, `return (${args}\n);`);
+      const single = compiles(awaits ? AsyncFunction : Function, `return (${args}\n);`);
+      const call = `const value = (${args}\n); return typeof value === 'function' ? value() : value;`;
+      if (awaits && !single && compiles(AsyncFunction, args)) {
+        const session = await keptSession(state.page);
+        const { result, exceptionDetails } = await evaluated(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }), timeout);
+        if (exceptionDetails) throw new Error(exceptionDetails.exception?.description || exceptionDetails.text);
+        printOutput(result.value !== undefined ? result.value : result.description ?? 'undefined', all);
+        return;
+      }
+      const expression = single ? `(${awaits ? 'async ' : ''}() => { ${call} })()` : args;
+      const value = await evaluated(state.page.evaluate(expression), timeout);
+      // An empty string is shown as one, not as no output at all.
+      printOutput(value === '' ? '""' : value, all);
+      // Quotes around the whole of it, as a shell's quoting sent on, make it a string, not code to run:
+      // one plain literal only, not "a" + b or a template with ${...} in it, which ran.
+      if (typeof value === 'string' && value && /^(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\$]|\\.|\$(?!\{))*`)$/s.test(args.trim())) {
+        out.log('(That is a string: the JavaScript was in quotes, which eval keeps. Without them, it runs: eval document.title)');
+      }
+    };
+    try {
+      await run();
+    } catch (error) {
+      if (late && /SyntaxError/.test(error.message)) error.message += `\n(${late} after the JavaScript is read as JavaScript: eval's options go before it)`;
+      throw error;
     }
   },
 

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

@@ -93,12 +93,15 @@ function doubleQuote(word) {
   return `"${word.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
 }
 
-// Where eval's --file is, after its --timeout if it has one; -1 when it has none.
+// Where eval's --file is, among its options before the JavaScript (--all, --timeout); -1 when it has none.
 function evalFileAt(words) {
   if (words[0] !== 'eval') return -1;
   let at = 1;
-  if (/^--timeout=/.test(words[at] || '')) at += 1;
-  else if (words[at] === '--timeout') at += 2;
+  for (;;) {
+    if (words[at] === '--all' || /^--timeout=/.test(words[at] || '')) at += 1;
+    else if (words[at] === '--timeout') at += 2;
+    else break;
+  }
   return /^--file(?:=|$)/.test(words[at] || '') ? at : -1;
 }
 

package/lib/touch.js

@@ -0,0 +1,97 @@
+// 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 { outsideViewport, IN_VIEW } = require('./emulation');
+
+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;
+    // A finger put down outside the viewport touches nothing; a swipe may still end outside it.
+    const outside = await outsideViewport(x, y);
+    if (outside) throw new Error(`${x}, ${y} is outside the viewport (${outside}); nothing was touched. ${IN_VIEW}`);
+    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.14.0",
+  "version": "0.15.1",
   "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:*)
 ---
 
@@ -53,14 +53,15 @@ first tab).
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
   `pw[serve]>`. It stops at that prompt (`quit`, or Ctrl-C); `pw-repl stop` is for a background one.
 - Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
-  own instead of connecting to one: headless unless `--headed`, in a 1280x800 window, in a temporary
-  profile, on a free port of its own (never 9222). It stops with the REPL, Ctrl-C while it starts
-  included, and `stop` returns once it has exited. It prints the command it ran; flags after `--` are
-  passed to that Chromium (only flags: a start URL goes before `--`), and a `--user-data-dir=<dir>`
-  among them is used instead of the temporary profile, and kept. Started again in a kept profile,
-  Chromium picks up where it left off, as it would for the user, headless too: its tabs come back, and
-  session cookies with them, so a login stays. They start loading before the REPL is attached, so
-  `requests` and `console` have only what came after, often nothing: `reload` for a full record.
+  own instead of connecting to one: headless unless `--headed`, in a 1280x800 window (a 1280x657 page
+  headless; info shows the viewport mouse points are in), in a temporary profile, on a free port of its
+  own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns once it
+  has exited. It prints the command it ran; flags after `--` are passed to that Chromium (only flags: a
+  start URL goes before `--`), and a `--user-data-dir=<dir>` among them is used instead of the temporary
+  profile, and kept. Started again in a kept profile, Chromium picks up where it left off, as it would for
+  the user, headless too: its tabs come back, and session cookies with them, so a login stays. They start
+  loading before the REPL is attached, so `requests` and `console` have only what came after, often
+  nothing: `reload` for a full record.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
   the tmux session `pw-repl`:
 
@@ -183,8 +184,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