pw-repl 0.14.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;

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

@@ -439,6 +439,84 @@ 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>]] [--force]', true);
@@ -545,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).`,
@@ -244,61 +245,51 @@ sent, as when the page stops answering, the outcome is unknown.`,
     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]',
@@ -594,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
@@ -629,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
@@ -1103,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.
@@ -1124,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/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/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.14.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