pw-repl 0.12.6 → 0.12.8

package/lib/elements.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const { state, onShutdown } = require('./state');
 const out = require('./output');
 const { takeOptions } = require('./cli-names');
-const { unquote, toSelector, keyName, splitSelector, REF } = require('./syntax');
+const { unquote, unescapeDouble, toSelector, keyName, splitSelector, REF } = require('./syntax');
 const { numbers, hints, BUSY_PAGE } = require('./util');
 const { tabState } = require('./tabstate');
 const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
@@ -35,18 +35,37 @@ const MODIFIERS = ['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift'];
 
 // click <selector> [button] [--modifiers=<keys>], as playwright-cli's click
 // takes them. The button is read only after a ref or a quoted selector, so
-// click text=Turn right is still one selector.
-function clickArgs(args, usage) {
+// click text=Turn right is still one selector; --button=right, as Playwright's option, after any.
+// click takes --click-count too; dblclick is click's count of 2.
+function clickArgs(args, usage, counts = false) {
   // Found outside quotes only, so a quoted selector keeps whatever is in it.
-  const { found, rest: text } = takeOptions((args || '').trim(), { modifiers: 'value' });
-  const modifiers = found.flatMap(o => (o.value || '').split(',').filter(Boolean).map(keyName));
+  const { found, rest: text } = takeOptions((args || '').trim(), { modifiers: 'value', button: 'value', 'click-count': 'value' });
+  if (!counts && found.some(o => o.name === 'click-count')) throw new Error('dblclick is a click count of 2; for another count, click --click-count=<n>');
+  const clickCount = clickCountOf(found, usage);
+  const modifiers = found.filter(o => o.name === 'modifiers').flatMap(o => (o.value || '').split(',').filter(Boolean).map(keyName));
   const unknown = modifiers.find(m => !MODIFIERS.includes(m));
   if (unknown) throw new Error(`Not a modifier: ${unknown}; they are ${MODIFIERS.join(', ')}`);
   const parsed = splitSelector(text);
-  const button = parsed && /^(?:left|right|middle)$/.test(parsed.rest || '') && (REF.test(parsed.word) || /^["']/.test(text)) ? parsed.rest : null;
-  const selector = button ? parsed.selector : soleSelector(text, usage);
-  const options = { ...(button ? { button } : {}), ...(modifiers.length ? { modifiers } : {}) };
-  return { selector, shown: args.trim(), options };
+  const positional = parsed && /^(?:left|right|middle)$/.test(parsed.rest || '') && (REF.test(parsed.word) || /^["']/.test(text)) ? parsed.rest : null;
+  const button = chooseButton(found, positional, usage);
+  const selector = positional ? parsed.selector : soleSelector(text, usage);
+  const options = { ...(button ? { button } : {}), ...(modifiers.length ? { modifiers } : {}), ...(clickCount > 1 ? { clickCount } : {}) };
+  // The selector as written, then the kind of click, so an option never reads as part of the selector.
+  const kind = [
+    ...(button && button !== 'left' ? [`${button} button`] : []),
+    ...(clickCount > 1 ? [`${clickCount} times`] : []),
+    ...(modifiers.length ? [`with ${modifiers.join('+')}`] : []),
+  ];
+  return { selector, shown: [positional ? parsed.word : unquote(text), ...kind].join(', '), options };
+}
+
+// --click-count=<n>, as Playwright's clickCount: 3 selects a line or a field's text. Past 3 a browser
+// does nothing more.
+function clickCountOf(found, usage) {
+  const given = found.filter(o => o.name === 'click-count');
+  if (!given.length) return 1;
+  if (given.length > 1 || !/^[1-3]$/.test(given[0].value || '')) throw new Error(`Usage: ${usage}; --click-count is 1, 2 or 3, once (2 is a double-click, 3 a triple-click)`);
+  return Number(given[0].value);
 }
 
 // A trailing --submit, as playwright-cli's fill and type take: Enter afterwards.
@@ -177,9 +196,30 @@ async function chooseMatch(selector, timeout) {
   throw error;
 }
 
+// The button, from a word (click e5 right) or --button=right, as Playwright's option is named; not both.
+function chooseButton(found, positional, usage) {
+  const named = found.filter(o => o.name === 'button');
+  if (named.length > 1 || (named.length && !/^(?:left|right|middle)$/.test(named[0].value || ''))) throw new Error(`Usage: ${usage}; --button is left, right or middle, once`);
+  if (positional && named.length) throw new Error(`Usage: ${usage}; the button goes once, as a word or as --button, not both`);
+  return positional || named[0]?.value || null;
+}
+
+// A mouse command's words, its button (a last word, or --button) and its options. Any other --option is
+// refused before a mouse event is sent.
+function mouseArgs(line, usage, spec = {}) {
+  const { found, rest } = takeOptions((line || '').trim(), { button: 'value', ...spec });
+  const words = rest.split(/\s+/).filter(Boolean);
+  const unknown = words.find(w => w.startsWith('--'));
+  if (unknown) throw new Error(`Usage: ${usage}; ${unknown.split('=')[0]} is not one of its options`);
+  const last = /^[a-z]+$/.test(words[words.length - 1] || '') ? words.pop() : null;
+  if (last && !/^(?:left|right|middle)$/.test(last)) throw new Error(`Usage: ${usage}`);
+  return { words, found, button: chooseButton(found, last, usage) || 'left' };
+}
+
 function mouseButton(args, name) {
-  const button = (args || '').trim() || 'left';
-  if (!/^(?:left|right|middle)$/.test(button)) throw new Error(`Usage: ${name} [left|right|middle]`);
+  const usage = `${name} [left|right|middle]`;
+  const { words, button } = mouseArgs(args, usage);
+  if (words.length) throw new Error(`Usage: ${usage}`);
   return button;
 }
 
@@ -386,17 +426,48 @@ function dateInputHolds(kind, value, what, selector) {
 
 const commands = {
   async click(args) {
-    const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
-    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.click(sel, o) : on.click(o)), options, 1);
+    const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--button=<button>] [--click-count=<n>] [--modifiers=<key>[,<key>]]', true);
+    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.click(sel, o) : on.click(o)), options, options.clickCount || 1);
     out.log(`Clicked: ${shown}${which}`);
   },
 
   async dblclick(args) {
-    const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
+    const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--button=<button>] [--modifiers=<key>[,<key>]]');
     const which = await pointerAction(selector, (on, sel, o) => (sel ? on.dblclick(sel, o) : on.dblclick(o)), options, 2);
     out.log(`Double-clicked: ${shown}${which}`);
   },
 
+  // drag <from> <to>, as playwright-cli's drag: Playwright's locator.dragTo, in its steps (hover the
+  // 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 from = splitSelector(args);
+    const to = from?.rest !== undefined ? splitSelector(from.rest) : null;
+    if (!to || to.rest !== undefined) throw new Error(usage);
+    const TIMEOUT = 5000;
+    const deadline = Date.now() + TIMEOUT;
+    const left = () => Math.max(1000, deadline - Date.now());
+    const source = state.page.locator(from.selector).first();
+    const target = state.page.locator(to.selector).first();
+    await onElement(from.selector, () => aimAt(state.page, source, left()));
+    await onElement(from.selector, () => source.hover({ timeout: left() }));
+    await state.page.mouse.down();
+    // 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 onElement(to.selector, () => aimAt(state.page, target, left()));
+      await onElement(to.selector, () => target.hover({ timeout: left() }));
+    } catch (error) {
+      await state.page.mouse.up().catch(() => {});
+      throw error;
+    }
+    await state.page.mouse.up();
+    const box = await target.boundingBox({ timeout: 1000 }).catch(() => null);
+    tabState(state.page).mouseAt = box ? { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) } : null;
+    out.log(`Dragged ${from.word} to ${to.word}`);
+  },
+
   async hover(args) {
     const selector = soleSelector(args, 'hover <selector>');
     const which = await pointerAction(selector, (on, sel, o) => (sel ? on.hover(sel, o) : on.hover(o)));
@@ -472,23 +543,41 @@ const commands = {
 
   // 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] [--delay=<ms>]';
-    const held = /(?:^|\s)--delay(?:=|\s+)(\S*)(?=\s|$)/.exec(line || '');
-    if (held && !/^\d+$/.test(held[1])) throw new Error(`Usage: ${usage}, the ms between press and release, e.g. mouseclick 400 300 --delay=500`);
-    const words = (held ? line.replace(held[0], ' ') : line || '').trim().split(/\s+/).filter(Boolean);
-    const button = /^[a-z]+$/.test(words[words.length - 1] || '') ? mouseButton(words.pop(), 'mouseclick <x> <y>') : 'left';
+    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 };
-    // The ring shows at the press, as mousedown's does, while a --delay holds the button.
-    await state.page.mouse.down({ button });
-    await showClick(state.page);
-    if (held) await new Promise(resolve => setTimeout(resolve, Number(held[1])));
-    await state.page.mouse.up({ button });
-    out.log(`Clicked the ${button} button at ${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) {
@@ -633,7 +722,7 @@ const commands = {
     if (!parsed || parsed.rest === undefined) throw new Error(usage);
     // A path, not a selector; // starts an XPath.
     if (/^(?:\.{1,2}\/|\/(?!\/)|~)/.test(parsed.word) || (!REF.test(parsed.word) && fs.statSync(path.resolve(parsed.word), { throwIfNoEntry: false })?.isFile())) throw new Error(`${parsed.word} is a file, not the input: ${usage.slice(7)}`);
-    const files = [...parsed.rest.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+)/g)].map(m => path.resolve(m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1') : m[2] ?? m[3]));
+    const files = [...parsed.rest.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+)/g)].map(m => path.resolve(m[1] !== undefined ? unescapeDouble(m[1]) : m[2] ?? m[3]));
     const payloads = files.map(file => {
       let buffer;
       try { buffer = fs.readFileSync(file); } catch (error) { throw new Error(`Cannot read ${file}: ${error.code === 'ENOENT' ? 'no such file' : error.code === 'EISDIR' ? 'it is a folder' : error.message}`); }

package/lib/emulation.js

@@ -20,7 +20,8 @@ async function viewportText() {
   const set = tabState(state.page).viewport;
   if (set) return `${set.width}x${set.height} (set with viewport)`;
   const size = await state.page.evaluate(() => `${innerWidth}x${innerHeight}`).catch(() => null);
-  return size ? `${size} (the window's size)` : 'unknown';
+  // The window less its frame (headless Chromium counts one too: a 1280x800 window has a 1280x657 page).
+  return size ? `${size} (the window's page area)` : 'unknown';
 }
 
 const DEFAULT_DEVICE = 'Pixel 7';
@@ -175,9 +176,10 @@ const commands = {
       out.log(`Viewport off: ${await viewportText()}`);
       return;
     }
-    const match = /^(\d+)x(\d+)$/.exec(arg);
+    const match = /^(\d+)x(\d+)$/i.exec(arg);
     const [w, h] = match ? [Number(match[1]), Number(match[2])] : [];
-    if (!w || !h) throw new Error('Usage: viewport [<width>x<height> | off]');
+    if (!match) throw new Error(`A size is <width>x<height>, e.g. viewport 1280x900 (got ${arg}). Usage: viewport [<width>x<height> | off]`);
+    if (!w || !h) throw new Error(`A width and a height are 1 or more (got ${arg})`);
     // Both set the screen size; whichever came last would win without saying so.
     if (tabState(state.page).emulation?.device) throw new Error('emulate mobile sets the size of the selected tab; emulate mobile off first');
     await setViewport(state.page, { width: w, height: h });

package/lib/help.js

@@ -22,36 +22,50 @@ function wrap(text, width = WIDTH) {
   }).join('\n\n');
 }
 
+// The common tasks, as the README's table lists them too (a unit test keeps the two the same).
+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>'],
+  ['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'],
+  ['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'],
+  ['see each step as I click', 'watch on --live'],
+  ['watch a tab someone will open', 'watch on --next-tab [url-part]'],
+  ['replay what I clicked through', 'watch save flow.txt, then pw-repl send --file flow.txt'],
+  ['record requests and console together', 'capture on, then capture off'],
+  ['find what makes the page slow', 'profile on, then profile off; profile reload for a load'],
+  ['fake a backend response', 'route <glob> <status> <json>, route <glob> abort'],
+  ['change or slow an API response', 'route <glob> patch <json>, route <glob> delay <secs>'],
+  ['cut or slow the whole network', 'network off, network slow, then network on'],
+  ['record a video of the page', 'record on, then record off (help video for a take)'],
+  ['show a pointer where the agent acts', 'cursor on, then cursor off'],
+  ['say what is happening on screen', 'toast <text>, then toast off'],
+  ['point something out on the page', 'highlight <ref>, then highlight off'],
+  ['clean up', 'modes off'],
+];
+
+// The commands that turn on a mode, as the README lists them too.
+const MODES = 'watch, capture, profile, record, route, network off or slow, emulate, viewport, highlight, cursor and toast';
+
 const OVERVIEW = wrap(`pw-repl drives Chromium over CDP. Commands act on the selected tab (\`tab\` shows which).
 The browser may be a shared session, with other users' tabs open in it.
 
 Common tasks:
-  where am I?                       tab, info
-  what is on the page?              snapshot, screenshot
-  do something on it                click, fill, press
-  wait for a page or element        wait load, wait <selector>, wait <selector> --gone
-  choose a file in a file input     upload <selector> <file>
-  see it as a phone, or dark        emulate mobile, emulate dark
-  what did the page request?        requests, then body <#> for what one got back
-  console messages and errors       console
-  show an agent what I do           watch on, click around, then watch
-  see each step as I click          watch on --live
-  watch a tab someone will open     watch on --next-tab [url-part]
-  requests and console together     capture on, then capture off
-  a video of what I do              help video
-  break the backend on purpose      route <glob> <status> <json>, route <glob> abort, network off
-  change or slow an API response    route <glob> patch <json>, route <glob> delay <secs>
-  slow the whole network            network slow
-  clean up                          modes off
-
-Modes (watch, capture, record, route, network off or slow, emulate, viewport) stay on until turned off;
-the prompt shows the selected tab's: (watch routes:1) pw>. tab, watch, capture, record, route, network,
-emulate and modes on their own show their state and what you can run next.
+${TASKS.map(([task, commands]) => `  ${task.padEnd(38)}  ${commands}`).join('\n')}
+
+Modes (${MODES}) stay on until turned off; the prompt shows the selected tab's: (watch routes:1) pw>.
+Each of them on its own, and modes, shows its state and what you can run next.
 
 Topics (help <topic>):
   tabs      open, select, close, navigate        network   requests, bodies, console, fakes, network off
   interact  click, fill, type, press, select     devtools  eval, CDP commands, cookie and storage names
-  inspect   snapshot, watch, text, screenshots   session   modes, markers, server, quitting
+  inspect   snapshot, watch, wait, screenshots   session   modes, server, clients, quitting
   video     record a take, with a pointer
 
 help <command> for usage and caveats (e.g. help route), help <command> --all for all of it; help --all
@@ -71,7 +85,7 @@ tab on its own lists them all.`,
 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
 scrolls its element into view first, as Playwright does; profile counts that scroll in the action's step.`,
-    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mousemove', 'mouseclick', 'mousedown', 'mouseup', 'mousewheel'],
+    commands: ['click', 'dblclick', 'hover', 'drag', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload', 'mousemove', 'mouseclick', 'mousedblclick', 'mousedown', 'mouseup', 'mousewheel'],
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
@@ -124,12 +138,7 @@ still show sensitive data (cdp Network.getCookies shows cookie values).`,
     commands: ['eval', 'cdp', 'cookies', 'storage'],
   },
   session: {
-    intro: `Completion: @<id> <command> makes the REPL print [[pw-done:<id>:ok|error]] when it finishes.
-
-Unknown outcome: a command that timed out after it began acting on the page may or may not have done
-it. It says so (pw-repl send exits 2), and the REPL carries on.
-
-Server: pw-repl serve also takes commands on /tmp/pw-repl.sock; they show here as [server] lines.
+    intro: `Server: pw-repl serve also takes commands on /tmp/pw-repl.sock; they show here as [server] lines.
 
 Clients: pw-repl send -c <name> (or $PW_CLIENT) sends as a client of its own. It has a selected tab of
 its own, so clients do not move each other's; its commands show as [server:<name>] lines. modes and tab
@@ -143,7 +152,12 @@ selected tab, if any: (watch network:off routes:2 capture) pw>. modes lists them
 
 Times (requests, console, watch) are local, with their UTC offset: 18:16:15.721-06:00.
 
-Dialogs are reported and never answered on their own; dialog accept or dismiss answers one, from any client, whoever opened it.`,
+Dialogs are reported and never answered on their own; dialog accept or dismiss answers one, from any client, whoever opened it.
+
+Unknown outcome: a command that timed out after it began acting on the page may or may not have done
+it. It says so (pw-repl send exits 2), and the REPL carries on.
+
+Completion: @<id> <command> makes the REPL print [[pw-done:<id>:ok|error]] when it finishes.`,
     commands: ['modes', 'dialog', 'help', 'quit'],
   },
 };
@@ -197,6 +211,8 @@ afresh.`,
       ['[button]', 'left, right or middle, after a ref or a quoted selector: click e5 right. Default: left.'],
     ],
     options: [
+      ['--button=<button>', 'the button, after any selector: click #menu --button=right. Over send, the shell takes the quotes, so pw-repl send click \'#menu\' right clicks a selector "#menu right": use --button, or quote it twice (\'"#menu"\').'],
+      ['--click-count=<n>', 'clicks this many times at once, as Playwright\'s clickCount: 2 is a double-click (as dblclick), 3 a triple-click, which selects a line of text or all of a field\'s. 1 to 3. Default: 1.'],
       ['--modifiers=<keys>', 'keys held down meanwhile, comma-separated: Alt, Control, ControlOrMeta, Meta, Shift.'],
     ],
     detail: `Several matches: hidden ones and ones covered by something else (a dialog's overlay) are passed over,
@@ -208,8 +224,23 @@ it to be ready.
 Timed out after it began acting, it says what stopped it (e.g. <div class="overlay"> intercepts pointer
 events) and that the outcome is unknown; Playwright's full call log goes to the REPL's pane or log.`,
   },
-  dblclick: { usage: 'dblclick <selector> [button]', summary: 'double-click, choosing the match as click does' },
+  dblclick: {
+    usage: 'dblclick <selector> [button]',
+    summary: 'double-click, as click does, with its options',
+    detail: `click --click-count=2, as Playwright's dblclick is. For a triple-click: click --click-count=3.`,
+  },
   hover: { usage: 'hover <selector>', summary: 'hover, choosing the match as click does' },
+  drag: {
+    usage: 'drag <from> <to>',
+    summary: 'drag one element onto another',
+    args: [
+      ['<from> <to>', 'selectors or snapshot refs, each quoted if it has spaces: drag e5 e9, drag "text=Item 1" "#done ul".'],
+    ],
+    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.`,
+  },
   mousemove: {
     usage: 'mousemove <x> <y>',
     summary: 'move the mouse to a point in the viewport',
@@ -220,7 +251,7 @@ events) and that the outcome is unknown; Playwright's full call log goes to the
 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 drag: mousedown, then mousemove to another point, then mouseup.`,
+A click at a point: mouseclick <x> <y>; a double-click: mousedblclick <x> <y>. A drag: mousedown, then mousemove to another point, then mouseup.`,
   },
   mouseclick: {
     usage: 'mouseclick <x> <y> [button]',
@@ -230,14 +261,30 @@ A click at a point: mouseclick <x> <y>. A drag: mousedown, then mousemove to ano
       ['[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.'],
     ],
     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.`,
   },
-  mousedown: { usage: 'mousedown [button]', summary: 'press a mouse button at the mouse (left, right, middle)' },
-  mouseup: { usage: 'mouseup [button]', summary: 'release a mouse button where the mouse is' },
+  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',
@@ -259,14 +306,19 @@ scrolled or redrawn. While recording, it scrolls in eased steps over up to 1s (h
       ['--submit', 'at the end: presses Enter in it afterwards.'],
     ],
     detail: `Examples: fill #name Ada Lovelace, fill "text=Your name" Ada, fill e7 Ada. It sets the whole value at
-once, even while recording: type shows it being typed.`,
+once, even while recording: type shows it being typed.
+
+At the prompt and in a send --file line, \\n, \\t and \\r in double quotes are a newline, a tab and a
+carriage return (fill #notes "line 1\\nline 2"), and \\\\ is a backslash. Over send, the shell's quoting comes
+first, and its "a\\nb" is a literal \\n, typed as a backslash and an n: give it a real newline, as
+$'line 1\\nline 2'.`,
   },
   type: {
     usage: 'type [--delay=<ms>] [<selector>] <text> [--submit]',
     summary: 'type key by key after what the field holds',
     args: [
       ['[<selector>]', 'as for fill. Without it (one word, or one quoted), into what has focus: type "garden hose".'],
-      ['<text>', 'the rest of the line, as fill\'s value.'],
+      ['<text>', 'the rest of the line, as fill\'s value: a newline in it presses Enter, which in a textarea starts a new line (help fill says how to give one).'],
     ],
     options: [
       ['--delay=<ms>', 'right after type: the gap between keys. Default: none, or 60 while the tab records.'],
@@ -324,6 +376,9 @@ all.`,
 to the tab whose snapshot gave it, and can change when the page changes (e102 may become f4e98): take a
 new snapshot after it does.
 
+Quotes: some names and text are quoted, YAML-style, as one with a quote mark in it is, and their quotes
+are escaped: paragraph: "Say \\"hi\\"" is the text Say "hi" on the page, with no backslashes.
+
 --grep: a hit with no named element around it prints without a path. A hit on text (a label) keeps the
 ref of the element holding it, so snapshot <that ref> shows what sits beside it, such as the value next
 to the label.
@@ -381,7 +436,14 @@ one no selector finds alone) stays a comment saying why, and the save says how m
 ends with the last step, not with what it brought: to end on a result that comes later (search results
 loading), add a wait for it at the end (wait text ...).
 
-Shared: every client sees the same steps, and watch new's place is shared.`,
+Watching someone: read a response body over 100 KB that matters as soon as it shows in requests, since
+the browser drops it once the tab navigates. watch leaves out images and other static files, failed ones
+too; console error and requests --all show what failed. Without a url-part, --next-tab takes the first
+tab anyone opens: check tab and info once it fires, since another tab opening later does not show in
+watch.
+
+Shared: every client sees the same steps, and watch new's place is shared: when another client watches
+the tab too, read it with watch <n>, since each one's watch new would hide steps from the other.`,
     moreAbout: 'bodies kept, --live timing, what --changes misses, one --next-tab at a time, and what watch save leaves out',
     more: `From its first watch on, a tab keeps response bodies of up to 100 KB, so body <#> still shows one
 after the tab navigates, even when the page navigates as soon as the request answers.
@@ -526,9 +588,9 @@ 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, fill, type <selector>, press <selector>, select, check,
-uncheck, upload, mousemove and mouseclick. 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, mousedown, and upload
+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
 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
@@ -607,10 +669,16 @@ goes on recording. There is no --mp4 or --webm: the file's ending picks the form
     summary: 'show, set or unset the viewport size',
     args: [
       ['<W>x<H>', 'sets the selected tab\'s page to that size, until viewport off, modes off or the REPL exits. The window is not resized.'],
-      ['off', 'back to the window\'s size.'],
-      ['(none)', 'shows the size, and whether it was set or is the window\'s.'],
+      ['off', 'back to the window\'s page area.'],
+      ['(none)', 'shows the size, and whether it was set or is the window\'s page area.'],
     ],
-    detail: `emulate mobile sets a phone's size instead, and each refuses while the other is on.`,
+    detail: `emulate mobile sets a phone's size instead, and each refuses while the other is on.
+
+The window's page area is the page's size without a viewport set. Chromium's --window-size flag sizes the whole
+window, frame included, so the page is smaller: --window-size=1280,900 gives 1280x757 in a headless one.
+--launch starts its Chromium at --window-size=1280,800 (a page of 1280x657 headless), unless the flags
+after -- give one; a profile it was given and has used before may keep its own last size.
+For a page of an exact size, use viewport <W>x<H>.`,
   },
   emulate: {
     usage: 'emulate [<what> [off] | off]',
@@ -828,9 +896,10 @@ in front of it usually holds the request open, so the page spins instead of fail
     summary: 'evaluate JavaScript in the selected tab and print the result',
     args: [
       ['<JavaScript>', 'the rest of the line. Promises are awaited, await works at the top level, and a function (() => document.title) is called.'],
-      ['<function> <ref>', 'calls it with that element: eval "el => el.textContent" e5.'],
+      ['<function> <ref>', 'calls it with that element: eval "el => el.textContent" e5. Quoted, its \\n is a newline and its \\" a quote: write \\\\n for a JS string\'s \\n.'],
     ],
     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.'],
       ['--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
@@ -986,9 +1055,11 @@ Different on purpose, since the browser may be someone else's too:
   if (Object.hasOwn(TOPICS, topicOrCommand)) {
     const topic = TOPICS[topicOrCommand];
     const text = [topic.intro, '', ...commandLines(topic.commands)].join('\n');
-    // A topic can share its name with a command (network); both are shown.
-    return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${renderCommand(topicOrCommand)}` : text;
+    // A topic can share its name with a command (network): the topic, and where the command's help is.
+    return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${topicOrCommand} is also a command: help ${topicOrCommand} --command` : text;
   }
+  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') {
@@ -1016,4 +1087,4 @@ function notFound(topic) {
   return `No help for ${topic}. Topics: ${Object.keys(TOPICS).join(', ')}`;
 }
 
-module.exports = { render, notFound, TOPICS, COMMANDS };
+module.exports = { render, notFound, TOPICS, COMMANDS, TASKS, MODES };

package/lib/inspect.js

@@ -442,7 +442,12 @@ const commands = {
     const onlyWhat = (tokens[0] === 'text' || tokens[0] === 'request') && tokens.length === 2;
     const tookSeconds = tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1]);
     if (tookSeconds) seconds = Number(tokens.pop());
-    if (!tokens.length || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
+    if (!tokens.length) throw new Error(`${usage} (1-${WAIT_MAX})`);
+    if (seconds < 1 || seconds > WAIT_MAX) {
+      // Most likely text that ends in a number, not seconds at all.
+      const text = tokens[0] === 'text' && !/^["']/.test(tokens[1]) ? `; for text that ends in a number, quote it: wait text "${tokens.slice(1).join(' ')} ${seconds}"` : '';
+      throw new Error(`wait takes 1-${WAIT_MAX} seconds (got ${seconds})${text}`);
+    }
     const timeout = seconds * 1000;
     // Said plainly, not as Playwright's call log.
     const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };
@@ -479,15 +484,32 @@ const commands = {
 
   async eval(args, all) {
     if (!args) throw new Error('Usage: eval <js-expression>');
-    // 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]))) {
-      const selector = toSelector(onRef[2]);
+    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' : ''}`);
+      }
+      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(unquote(onRef[1])));
+        const fn = await evaluated((await el.ownerFrame()).evaluateHandle(args));
         try {
           printOutput(await el.evaluate((e, f) => f(e), fn), all);
         } finally {

package/lib/launch.js

@@ -139,7 +139,9 @@ async function launch({ headed = false, extraArgs = [] }) {
   const onExit = () => { if (group) killGroup(group); try { removeProfile(); } catch {} };
   process.on('exit', onExit);
   const onSpawn = proc => { group = proc.pid; };
-  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', ...(given ? [] : [`--user-data-dir=${profile}`]),
+  // A laptop's window, rather than Chromium's headless 800x600 or so, unless the flags after -- size it.
+  const sized = extraArgs.some(a => a.startsWith('--window-size=')) ? [] : ['--window-size=1280,800'];
+  const ours = [...(headed ? [] : ['--headless=new']), ...sized, '--remote-debugging-port=0', ...(given ? [] : [`--user-data-dir=${profile}`]),
     '--no-first-run', '--no-default-browser-check', ...(smallShm() ? ['--disable-dev-shm-usage'] : [])];
   // A profile already used has tabs to restore; a blank tab of its own each time would pile up there.
   // Local State is written at its root on the first run, whichever --profile-directory is used.

package/lib/record.js

@@ -391,7 +391,7 @@ 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', 'check', 'uncheck', 'mousemove', 'mouseclick', 'mousedown', 'mouseup', 'mousewheel']);
+const WHOLE = new Set(['click', 'dblclick', 'hover', 'drag', 'check', 'uncheck', 'mousemove', 'mouseclick', 'mousedblclick', 'mousedown', 'mouseup', 'mousewheel']);
 const TARGET_FIRST = new Set(['fill', 'type', 'select', 'press', 'upload']);
 function stepLabel(cmd, args) {
   if (WHOLE.has(cmd)) {