pw-repl 0.12.7 → 0.12.8

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,13 +669,15 @@ 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.
 
-The window's size here is the size of the page in it. Chromium's --window-size flag sizes the whole
+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: {
@@ -832,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
@@ -990,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') {
@@ -1020,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

@@ -484,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)) {

package/lib/runner.js

@@ -38,6 +38,8 @@ const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'profile', 'record', '
 // Commands that accept --all, right after the command or at the end, to lift the output limit.
 const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'profile', 'body', 'console', 'snapshot', 'watch'];
 
+const SUBCOMMANDS = ['run', 'serve', 'attach', 'stop', 'send', 'where', 'skill'];
+
 let queue = Promise.resolve();
 // The server command running now, so a quit at the prompt can answer it.
 let inFlight = null;
@@ -100,6 +102,11 @@ async function executeCommand(text) {
   state.currentCommandAt = Date.now();
   const run = Object.hasOwn(commands, cmd) ? commands[cmd] : translated && Object.hasOwn(cliCommands, cmd) ? cliCommands[cmd] : null;
   if (!run) {
+    // An agent fresh from the skill tries send where; those are the command line's, not the REPL's.
+    if (SUBCOMMANDS.includes(cmd)) {
+      out.error(`Error: ${cmd} is a pw-repl subcommand, run at the shell: pw-repl ${cmd}${args ? ' ...' : ''}`);
+      return { status: 'error', cmd };
+    }
     out.log(`Unknown command: ${cmd}. Type 'help' for commands.`);
     return { status: 'error', cmd };
   }
@@ -117,6 +124,10 @@ async function executeCommand(text) {
     stepEnded(step, true);
     // Playwright colours its call log; the codes are noise anywhere but a terminal.
     e.message = String(e.message || '').replace(/\x1b\[[0-9;]*m/g, '');
+    // A page's own error (eval's SyntaxError, a cdp method not found) without Playwright's method name
+    // or the stack of its injected script, which point at Playwright, not at the line that was sent.
+    e.message = e.message.split('\n').filter(line => !/^\s+at /.test(line)).join('\n')
+      .replace(/^(?:page|frame|elementHandle|jsHandle|cdpSession)\.(?:evaluate|evaluateHandle|send): /, '');
     out.error(`Error: ${e.message}`);
     const uncertain = !READ_ONLY.has(cmd) && isUncertain(e);
     if (uncertain) out.error('Outcome unknown: it timed out after it began acting on the page. Check the page before trying again.');

package/lib/send.js

@@ -88,6 +88,11 @@ async function viaTmux(session, command, timeoutMs) {
   return 2;
 }
 
+// A word in double quotes, as the REPL reads them (unescapeDouble): every other character goes as it is.
+function doubleQuote(word) {
+  return `"${word.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
+}
+
 // A command's words as send was given them, made into the line the REPL reads: quoted again where the
 // shell had kept a word whole, and with the files it reads or writes made absolute from the sender's
 // folder, since the REPL's may be another.
@@ -100,7 +105,7 @@ function commandLine(words) {
   // So does playwright-cli's storage key (localstorage-set "my key" v).
   // And record's file, which may have spaces in it, and wait's text, whose last word would otherwise be
   // taken as the seconds when it is a number (wait text 'Showing 1').
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || words[0] === 'wait' || /^video-(?:start|stop)$/.test(words[0]));
+  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || words[0] === 'drag' || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || words[0] === 'wait' || /^video-(?:start|stop)$/.test(words[0]));
   // An empty word (fill #name "") is the empty value.
   // upload's files are read by the REPL, whose folder may not be this one.
   // So are the files upload reads and screenshot --filename writes.
@@ -117,15 +122,21 @@ function commandLine(words) {
   // watch save and profile save write their files.
   if (words[0] === 'profile' && words[1] === 'save' && words.length > 2) resolved = ['profile', 'save', resolve(words.slice(2).join(' '))];
   if (words[0] === 'watch' && words[1] === 'save' && words.length > 2) resolved = ['watch', 'save', resolve(words.slice(2).join(' '))];
+  // So does the file eval --file reads.
+  if (words[0] === 'eval' && /^--file(?:=|$)/.test(words[1] || '')) {
+    // As one word, --file=<path>, which is quoted below when the path has spaces.
+    const [file, rest] = words[1] === '--file' ? [words[2], words.slice(3)] : [words[1].slice(7), words.slice(2)];
+    if (file) resolved = ['eval', `--file=${resolve(file)}`, ...rest];
+  }
   if (words[0] === 'screenshot') {
     resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : w));
   }
-  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
+  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? doubleQuote(w) : w)) : resolved;
   // An option's value the shell kept whole stays whole too: --device='iPhone 15'.
   // Single quotes escape nothing, so a backslash (a regexp's \d) reaches it as typed.
   for (const [n, w] of quoted.entries()) {
     const option = /^(--[A-Za-z][\w-]*=)([\s\S]*\s[\s\S]*)$/.exec(w);
-    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? JSON.stringify(option[2]) : `'${option[2]}'`}`;
+    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? doubleQuote(option[2]) : `'${option[2]}'`}`;
   }
   return quoted.join(' ').trim();
 }
@@ -155,7 +166,8 @@ async function sendFile(options) {
     console.log(`> ${line}`);
     // Read as the prompt reads it; a file it reads or writes is the sender's, as on send's command line.
     const words = shellWords(line);
-    const command = PATHS.test(words[0]) ? commandLine(words) : line;
+    // eval's own line keeps its quotes; only eval --file names a file.
+    const command = PATHS.test(words[0]) || (words[0] === 'eval' && /^--file(?:=|$)/.test(words[1] || '')) ? commandLine(words) : line;
     const found = options.noVars ? null : variablesFor(command);
     if (found?.error) { console.error(`pw-repl: stopped at line ${i + 1} of ${options.file} (${line}): ${found.error}`); return 1; }
     const status = await send({ ...options, file: null, command, vars: found?.vars || null });

package/lib/start.js

@@ -5,6 +5,7 @@ const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./st
 const out = require('./output');
 const { watchPage, complete } = require('./commands');
 const { listTabs, openTab, markStartTab } = require('./tabs');
+const { tabState } = require('./tabstate');
 const runner = require('./runner');
 
 // A browser --launch starts has its own address instead.
@@ -88,10 +89,14 @@ async function start(options) {
 
   if (START_URL) {
     state.startingStep = 'opening the start URL';
-    state.page = await openTab();
+    // A Chromium the REPL launched has only its first blank tab, which nobody else is using: the start
+    // URL goes there, rather than into a second tab behind a blank one.
+    const first = state.launched && pages.length === 1 && pages[0].url() === 'about:blank' ? pages[0] : null;
+    if (first) Object.assign(tabState(first), { opened: true, owner: state.client });
+    state.page = first || await openTab();
     markStartTab(state.page);
     await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
-    out.log(`Opened ${state.page.url()} in a new tab`);
+    out.log(`Opened ${state.page.url()}${first ? '' : ' in a new tab'}`);
   }
 
   out.log('');

package/lib/syntax.js

@@ -11,25 +11,31 @@ function toSelector(word) {
   return REF.test(word) ? `aria-ref=${word}` : word;
 }
 
-// Quotes around the whole of a value are removed; \" inside double quotes is a quote.
+// Inside double quotes, \n, \t and \r are a newline, tab and carriage return, so a value send quotes
+// keeps them on one line; any other \X is X (\" a quote, \\ a backslash).
+function unescapeDouble(text) {
+  return text.replace(/\\(.)/g, (_, c) => (c === 'n' ? '\n' : c === 't' ? '\t' : c === 'r' ? '\r' : c));
+}
+
+// Quotes around the whole of a value are removed.
 function unquote(text) {
   const match = /^"((?:[^"\\]|\\.)*)"$|^'([^']*)'$/.exec(text);
   if (!match) return text;
-  return match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2];
+  return match[1] !== undefined ? unescapeDouble(match[1]) : match[2];
 }
 
 // The words of a line as a shell reads them: quoted parts may hold spaces, and lose their quotes
 // (--filename="my dir/a.webm" is one word, --filename=my dir/a.webm).
 function shellWords(text) {
   return [...(text || '').matchAll(/(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']+|["'])+/g)]
-    .map(m => m[0].replace(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g, (_, double, single) => (double !== undefined ? double.replace(/\\(.)/g, '$1') : single)));
+    .map(m => m[0].replace(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g, (_, double, single) => (double !== undefined ? unescapeDouble(double) : single)));
 }
 
 // The first word of args, or a quoted selector with spaces in it, and the rest of the line.
 function splitSelector(args) {
   const match = /^(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+))(?:\s+([\s\S]*))?$/.exec((args || '').trim());
   if (!match) return null;
-  const word = match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2] !== undefined ? match[2] : match[3];
+  const word = match[1] !== undefined ? unescapeDouble(match[1]) : match[2] !== undefined ? match[2] : match[3];
   return { word, selector: toSelector(word), rest: match[4] };
 }
 
@@ -83,4 +89,4 @@ function expandVariables(line, values) {
   });
 }
 
-module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };
+module.exports = { SELECTOR_FIRST, REF, toSelector, unescapeDouble, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };

package/package.json

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