pw-repl 0.10.0 → 0.11.1

package/lib/help.js

@@ -23,7 +23,7 @@ function wrap(text, width = WIDTH) {
 }
 
 const OVERVIEW = wrap(`playwright-repl drives Chromium over CDP. Commands act on the selected tab (\`tab\` shows which).
-The browser may be a shared session, with other people's tabs open in it.
+The browser may be a shared session, with other users' tabs open in it.
 
 Common tasks:
   where am I?                       tab, info
@@ -85,8 +85,9 @@ the selectors it needs (#id, text=..., role=...), not snapshot refs: the take st
 page, where the refs are stale.
 
 2. Write the take, one command per line, then run it: pw-repl send --file take.txt (pw-repl help, outside
-the REPL, has the rest). Its first line puts the page back as it was before the rehearsal (goto <url>),
-so the take does not start from the rehearsal's end.
+the REPL, has the rest). Its first lines put the page back as it was before the rehearsal (goto <url>),
+so the take does not start from the rehearsal's end. A toast, the cursor and highlights stay up across
+page loads: turn off any the rehearsal left (toast off, cursor off, highlight off) before record on.
 
     goto https://shop.example/support/new
     record on clip.webm
@@ -100,7 +101,8 @@ so the take does not start from the rehearsal's end.
 3. While it records, pw-repl paces it for a viewer (help record): type types at a readable pace (use it,
 not fill, for text the viewer should see typed), each action is followed by a pause, an element out of
 view is scrolled to smoothly, and the video starts and ends on a still page. highlight <selector> draws a
-box to point at something. After a step that loads a page, wait for text only the result shows (wait
+box to point at something, and toast <text> a line of text saying what is happening, up for as long as
+the viewer needs to read it. After a step that loads a page, wait for text only the result shows (wait
 text ...), not a heading the page always has, and not wait load: a single-page app loads nothing.
 
 record on --steps also saves when and where each step ran, in the video's seconds and pixels, for
@@ -109,7 +111,7 @@ editing it afterwards.
 The user's own screen, with their real pointer, takes a screen recorder they run (OBS, ffmpeg -f
 x11grab, macOS screencapture -v): ask first. playwright-cli itself is a separate tool that records a
 clean browser of its own (here, its video-start is record on).`,
-    commands: ['record', 'cursor'],
+    commands: ['record', 'cursor', 'toast'],
   },
   network: {
     intro: `requests and console record all the time; a capture records only while it runs.`,
@@ -150,14 +152,21 @@ const COMMANDS = {
     usage: 'tab [<index>|<url-part>|new [url]|close [url-part]]',
     summary: 'list tabs (* is selected); select, open or close one',
     args: [
-      ['(none)', 'lists the tabs: * marks the selected one, and each says who opened it with tab new.'],
+      ['(none)', 'lists the tabs: * marks the selected one, (in front) the one the browser shows, and each says who opened it with tab new.'],
       ['<index>', 'selects by the number in your latest listing (each client has its own); numbers change when tabs open or close.'],
       ['<url-part>', 'selects the one tab whose URL contains it; refused if none or several do.'],
       ['new [url]', 'opens a tab behind the one in front, so it does not take the window from whoever is using it, and selects it. The URL is read as goto reads it.'],
       ['close [url-part]', 'closes the selected tab, or the one matching url-part.'],
     ],
     detail: `Closing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is
-selected, and commands that need one refuse until one is.`,
+selected, and commands that need one refuse until one is.
+
+In front: (in front) marks the tab the browser shows in its window, the one the user sees; (in front,
+focused) when its window has the keyboard too, and it is not in the address bar. A tab a client has
+selected or opened is never marked: pw-repl tells it that it is in front, so that it keeps drawing and
+clicks in it work while it is behind another, and so cannot ask it. The user's other tabs are told
+nothing, and say truly whether they are seen. Each window has a tab in front, so with several windows
+(an incognito one, say) several tabs are marked; focused is the one with the keyboard.`,
   },
   goto: {
     usage: 'goto <url>',
@@ -190,7 +199,8 @@ afresh.`,
       ['--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,
-and it says which it used: Clicked: text=Buy (match 3 of 4; ...). If none can be clicked within 5s, it
+and it says which it used: Clicked: text=Buy (match 3 of 4; ...), or names the first when it was the
+one: (the first of 2 matches: <h1> Buy), as it may not be the one meant. If none can be clicked within 5s, it
 says why for each and does nothing. A ref, or a single match, is clicked as it is, waiting up to 5s for
 it to be ready.
 
@@ -252,7 +262,11 @@ once, even while recording: type shows it being typed.`,
 The whole text takes its length times the gap, and send waits 20s by default: about 300 characters at
 60ms need a longer send -t, or a shorter --delay. --delay is a gap between keys, not a wait before
 starting like screenshot's. A page that reacts to each key, such as search as you type, may react to
-each one.`,
+each one.
+
+Date and time inputs: they take keys part by part, in the order they show them (10/02/2026 in en-US),
+from the first part with a selector, or from the part a click landed on. type says what the input then
+holds. Their ISO form (2026-10-02) is refused, since typed it comes out mangled: fill sets it.`,
   },
   press: { usage: 'press <key> | press <selector> <key>', summary: 'press a key (Enter, Escape, Control+A; any case), maybe on an element' },
   select: {
@@ -299,21 +313,28 @@ new snapshot after it does.
 ref of the element holding it, so snapshot <that ref> shows what sits beside it, such as the value next
 to the label.
 
+Passwords: a password field's value is shown as (a password: not shown), --full too, as is that of a
+field whose autocomplete is for a password, a one-time code or a card number; html and attrs show its
+value attribute so too. A field a Show password button made plain text, with no such autocomplete,
+shows its value.
+
 Output over 60 lines ends with a line count.`,
   },
   watch: {
-    usage: 'watch on [--changes] [--live] | off | [n|new]',
-    summary: 'record what happens in the tab; show the last n steps',
+    usage: 'watch on [options] | off | [n|new] | save <file>',
+    summary: 'record what happens in the tab; show or save the steps',
     args: [
       ['on', 'starts recording the tab\'s steps; after watch off, a new recording.'],
       ['off', 'stops it; anyone\'s watch off stops it, since a watch belongs to the tab.'],
       ['(none) | <n>', 'says whether it is on, and shows the last 20 steps, or the last n.'],
       ['new', 'only the steps not shown yet, and requests that have since arrived for the last one.'],
+      ['save <file>', 'writes the steps as commands, a file that pw-repl send --file <file> runs again; it refuses a file that exists.'],
     ],
     optionsFor: 'watch on',
     options: [
       ['--changes', 'also what each step changed on the page once it settled, in up to 5 lines: + added, - removed, ~ changed.'],
       ['--live', 'also prints each step in the REPL window once it settles (never in a command\'s answer), marked [watch], or [watch <url>] for a tab that is not the selected one.'],
+      ['--no-values', 'records that something was typed, not what.'],
       ['--next-tab [part]', 'returns at once, then watches the next tab someone opens, or the next whose URL contains part, from its first page, and selects it for you. tab new, a client\'s own, does not count.'],
     ],
     detail: `What a step is: a click, typing (once it pauses), Enter or Escape, a form change, a submit or a
@@ -322,11 +343,22 @@ each with its status as in requests (body <#> for one), leaving out scripts and
 REPL's own fill shows as type. A double-click shows as two clicks; hovering and moving the mouse are not
 recorded.
 
-Privacy: typed values are not recorded, and password fields not at all; --changes leaves out field
-values, but what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.
+Privacy: what is typed is recorded, and watch and watch save show it, except in a password field: one
+that was ever type=password, or whose autocomplete is for a password, a one-time code or a card number.
+--no-values leaves out every value. --changes leaves out field values, but what the page itself shows
+(e.g. "Hello <name>") is shown. watch save's file can be read by its owner only.
+
+Saving (watch save): a goto to where the watch started, then each step as a command, under a # line
+describing it: click, fill, select, check, press, and wait load after a step that loaded a page. An
+element is found by its id, data-testid or name, its text, or else its place in the page, which a change
+to the page can break. A select step chooses the option by its value. What was typed into a password
+field (or any field, with --no-values) is a variable named after the field, e.g. fill '#password'
+"{{ PW_PASSWORD }}": run it with PW_PASSWORD=... pw-repl send --file login.txt, and send passes the
+value along for the REPL to put in, which shows the line as written. A step that cannot be a command (a value with a line break, an element in a frame, or
+one no selector finds alone) stays a comment saying why, and the save says how many there are.
 
 Shared: every client sees the same steps, and watch new's place is shared.`,
-    moreAbout: 'bodies kept, --live timing, what --changes misses, and one --next-tab at a time',
+    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.
 
@@ -336,13 +368,17 @@ under the next step.
 --changes: each element once, with the first names inside it. Not for navigations: what a page changes
 on its own after a step settles (data arriving later) shows under the next step.
 
---next-tab: it takes --changes and --live too; watch off stops waiting, and modes lists it. One tab is
+--next-tab: it takes --changes, --live and --no-values too; watch off stops waiting, and modes lists it. One tab is
 waited for at a time: while one client waits, another's watch on --next-tab is refused, and its watch
-off leaves the wait on.`,
+off leaves the wait on.
+
+watch save: a submit is left out, since the click or Enter that caused it is there. So is a URL the app
+changed without loading a page (history.pushState), as a comment: the step before it changes it again.
+In an open shadow root, an element's selector is its host's, then its own; a closed one is out of reach.`,
   },
   text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
-  html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match' },
-  attrs: { usage: 'attrs [--all] <selector>', summary: 'attributes of the first match' },
+  html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match; no password values' },
+  attrs: { usage: 'attrs [--all] <selector>', summary: 'attributes of the first match; no password values' },
   listeners: {
     usage: 'listeners <selector>|document|window',
     summary: 'the page\'s event listeners on an element',
@@ -412,6 +448,36 @@ It brings the tab to the front of its window first: Chrome draws only the tab in
 at CSS pixel size, one image pixel per CSS pixel. While emulate mobile is on, it is what the phone
 shows: a page laid out wider than the phone (no viewport meta tag) comes out shrunk to fit. An element bigger
 than the viewport is taken with the page's scrollbar hidden for a moment, so that it does not move over.`,
+  },
+  toast: {
+    usage: 'toast <text> [options] | toast off',
+    summary: 'show a line of text over the page, to narrate a video',
+    args: [
+      ['<text>', 'the rest of the line, quotes around all of it removed; it wraps at 80% of the page\'s width.'],
+      ['off', 'fades it out.'],
+      ['(none)', 'says whether one is up, and what it says.'],
+    ],
+    options: [
+      ['--duration=<time>', 'hides it after that long: 3s, 1.5s, or milliseconds (1500). Default: stays until toast off or the next toast.'],
+      ['--read-time=<time>', 'while the tab records, the least time it stays up (below). Default: 300ms a word, at least 1.5s; 0 none.'],
+      ['--position=<where>', 'top, center or bottom. Default: bottom.'],
+      ['--size=<px>', 'the text\'s size. Default: 24.'],
+      ['--align=<how>', 'left, center or right, for text over more than one line. Default: center.'],
+      ['--color=<css>', 'the text\'s color. Default: #fff.'],
+      ['--background=<css>', 'its box\'s color. Default: rgba(20, 20, 20, .85).'],
+      ['--opacity=<0-1>', 'of the whole toast. Default: 1.'],
+    ],
+    detail: `It stays up until toast off or the next toast, which replaces it: the old one fades out, then the new
+one fades in. It returns once it has faded in, so a screenshot right after it shows it whole. The
+commands after it run while it is up, so it can say what they are doing.
+
+Read time (--read-time): while the tab records, a toast stays up for its read time before the next
+toast, toast off or record off takes it down; each waits out what is left of it, and says so. toast
+says what its read time is, and past 15s, the send -t the command that takes it down needs: send waits
+20s by default. A toast with --duration has none: it ends by itself. Not recording, nothing waits.
+
+It is a mode of its tab: modes lists it and modes off turns it off. It stays up across page loads, and
+shows in screenshots and recordings. Selectors, snapshot and text don't see it, and it takes no clicks.`,
   },
   cursor: {
     usage: 'cursor [on [<selector> | <x> <y>] | off]',
@@ -806,7 +872,7 @@ Names both have (goto, click, fill, snapshot, eval, ...) take playwright-cli's f
 Its other options are refused, never read as part of a selector or a value.
 
 Different on purpose, since the browser may be someone else's too:
-  routes, network and emulation     per tab, not the whole browser, so other people's tabs are untouched
+  routes, network and emulation     per tab, not the whole browser, so other users' tabs are untouched
   close                             turns off your modes; tabs stay open (tab close <url-part> closes one)
   upload <selector> <file>          names the input: file pickers are not caught, as the user's would be
   no snapshot after each command    the user reads the pane too; snapshot when you need one

package/lib/inspect.js

@@ -77,6 +77,24 @@ async function elementShot(locator, type) {
   }
 }
 
+// A password field's value shows in a snapshot as typed, and in html and attrs as its value attribute,
+// which some pages (React's) keep in step with it. It is left out, as watch leaves it out, so a password
+// filled in with {{ PW_PASSWORD }} stays out of the pane and the log too. These are the fields
+// watch counts as secret, but one only shown as text for now (Show password) unless its autocomplete
+// says so. A field that cannot be checked any more is taken to be one.
+const SECRET_FIELD = ['input[type=password]', ...['current-password', 'new-password', 'one-time-code', 'cc-number', 'cc-csc']
+  .map(kind => `[autocomplete~="${kind}"]`)].join(',');
+async function hideSecrets(page, text) {
+  const lines = text.split('\n');
+  for (const [i, line] of lines.entries()) {
+    const field = /^(\s*- (?:textbox|searchbox|spinbutton|combobox)\b.*\[ref=(\w+)\][^:]*): .+$/.exec(line);
+    if (!field) continue;
+    const secret = await page.locator(`aria-ref=${field[2]}`).evaluate((el, selector) => el.matches(selector), SECRET_FIELD, { timeout: 1000 }).catch(() => true);
+    if (secret) lines[i] = `${field[1]}: (a password: not shown)`;
+  }
+  return lines.join('\n');
+}
+
 // Unnamed generic nodes are layout wrappers (mostly divs): they add depth and
 // nothing to read. Drop them, lift their children, and drop cursor hints.
 function compactSnapshot(text) {
@@ -160,16 +178,23 @@ const commands = {
 
   async html(args, all) {
     const selector = soleSelector(args, 'html <selector>');
-    printOutput(await onElement(selector, () => state.page.$eval(selector, el => el.outerHTML)), all);
+    // A copy in a document of its own, where the page's code (a custom element's) does not run.
+    printOutput(await onElement(selector, () => state.page.$eval(selector, (el, secret) => {
+      const copy = document.implementation.createHTMLDocument('').importNode(el, true);
+      for (const field of [copy, ...copy.querySelectorAll('*')]) {
+        if (field.matches(secret) && field.hasAttribute('value')) field.setAttribute('value', '(a password: not shown)');
+      }
+      return copy.outerHTML;
+    }, SECRET_FIELD)), all);
   },
 
   async attrs(args, all) {
     const selector = soleSelector(args, 'attrs <selector>');
-    const result = await onElement(selector, () => state.page.$eval(selector, el => {
+    const result = await onElement(selector, () => state.page.$eval(selector, (el, secret) => {
       const out = {};
-      for (const attr of el.attributes) out[attr.name] = attr.value;
+      for (const attr of el.attributes) out[attr.name] = attr.name === 'value' && el.matches(secret) ? '(a password: not shown)' : attr.value;
       return out;
-    }));
+    }, SECRET_FIELD));
     printOutput(result, all);
   },
 
@@ -358,6 +383,7 @@ const commands = {
     } else {
       raw = await state.page.ariaSnapshot({ mode: 'ai', timeout: 5000 });
     }
+    raw = await hideSecrets(state.page, raw);
     const text = full ? raw : compactSnapshot(raw);
     if (needle !== null) {
       const hits = grepSnapshot(text, needle);
@@ -452,6 +478,11 @@ const commands = {
     const value = await withTimeout(state.page.evaluate(expression), 'Page evaluation', COMMAND_TIMEOUT);
     // An empty string is shown as one, not as no output at all.
     printOutput(value === '' ? '""' : value, all);
+    // Quotes around the whole of it, as a shell's quoting sent on, make it a string, not code to run:
+    // one plain literal only, not "a" + b or a template with ${...} in it, which ran.
+    if (typeof value === 'string' && value && /^(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\$]|\\.|\$(?!\{))*`)$/s.test(args.trim())) {
+      out.log('(That is a string: the JavaScript was in quotes, which eval keeps. Without them, it runs: eval document.title)');
+    }
   },
 
   async cdp(args, all) {

package/lib/modes.js

@@ -11,6 +11,7 @@ const { currentCapture, endCapture } = require('./capture');
 const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
 const { hideHighlights, setLabels } = require('./elements');
 const { cursorOf, cursorOff } = require('./cursor');
+const { toastOf, toastOff } = require('./toast');
 
 // The modes turned on in a tab, in the order the prompt shows them.
 function activeModes(p) {
@@ -28,6 +29,7 @@ function activeModes(p) {
   if (highlights) modes.push(`highlight:${highlights}`);
   if (tabState(p).labelsOn) modes.push('labels');
   if (cursorOf(p)) modes.push('cursor');
+  if (toastOf(p)) modes.push('toast');
   if (currentCapture()?.page === p) modes.push('capture');
   if (recordingOf(p)) modes.push('record');
   return modes;
@@ -43,7 +45,7 @@ function listModes() {
   if (!on.length) {
     out.log('No modes are on in any tab.');
     out.log(hints([
-      ['watch on', 'record what the person at the browser does'],
+      ['watch on', 'record what the user at the browser does'],
       ['capture on', 'record requests and console messages together'],
       ['route <url-glob> <status> <json-body>', 'fake a response'],
       ['network off', 'cut the tab\'s network'],
@@ -81,6 +83,8 @@ function modeOwners(p) {
   if (labels) owners.push([labels.owner ?? null, 'labels']);
   const cursor = cursorOf(p);
   if (cursor) owners.push([cursor.owner ?? null, 'cursor']);
+  const toast = toastOf(p);
+  if (toast) owners.push([toast.owner ?? null, 'toast']);
   const capture = currentCapture();
   if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
   const recording = recordingOf(p);
@@ -119,6 +123,7 @@ async function allModesOff(mine = false) {
       if (hidden) done.push(`${hidden} highlight${hidden === 1 ? '' : 's'} hidden`);
       if (tabState(p).labelsOn && ours(tabState(p).labelsOn.owner)) { await setLabels(p, false); done.push('labels off'); }
       if (cursorOf(p) && ours(cursorOf(p).owner) && await cursorOff(p)) done.push('cursor off');
+      if (toastOf(p) && ours(toastOf(p).owner) && await toastOff(p)) done.push('toast off');
       // Before the page's size is reset, which the recording would otherwise end with.
       const recording = recordingOf(p);
       if (recording && ours(recording.owner)) done.push(`record off (${(await finishRecording(recording)).replace(/\n/g, '; ')})`);

package/lib/output.js

@@ -58,7 +58,7 @@ function notice(text, page = null) {
   else log(text);
 }
 
-// Like notice, but never part of a command's answer: for what the person at
+// Like notice, but never part of a command's answer: for what the user at
 // the browser does, which is not the output of the command running now.
 function aside(text) {
   if (!sink && idlePrinter && idlePrinter.idle()) idlePrinter.print(String(text));

package/lib/overlay.js

@@ -0,0 +1,79 @@
+// What the REPL draws over a page (the cursor, a toast), each as a layer of one element of its own.
+const { tabState } = require('./tabstate');
+
+// Runs in the page. An element under <html>, not <body>, which frameworks replace, with a closed shadow
+// root, so the page's selectors, the snapshot and text do not find what is in it. It takes no pointer
+// events, so what is under it is clicked, and it is built with the DOM and inline styles, which a page's
+// Trusted Types or style-src rules do not block. It is shown as a popover, in the top layer, above the
+// page's own dialogs, as Playwright's highlight is. Kept on the document under a symbol, so each call
+// finds it again, and one the page removed is drawn again. Each layer is a box over the whole viewport,
+// in a fixed order (the cursor above a toast), whatever order they were drawn in; the element goes with
+// its last layer.
+function pageOverlay(create) {
+  const KEY = Symbol.for('pw-repl-overlay');
+  const ORDER = ['toast', 'cursor'];
+  // Important on the element in the page, whose own rules could reach it; inside, the page's cannot, and
+  // an important transform would win over an animation.
+  const set = (el, styles, important = '') => { for (const [name, value] of Object.entries(styles)) el.style.setProperty(name, value, important); };
+  let overlay = document[KEY];
+  if (!overlay || !overlay.host.isConnected) {
+    if (!create) return null;
+    const host = document.createElement('pw-repl-overlay');
+    host.setAttribute('aria-hidden', 'true');
+    host.setAttribute('popover', 'manual');
+    set(host, {
+      display: 'block', position: 'fixed', inset: '0', width: '100%', height: '100%', 'max-width': 'none',
+      'max-height': 'none', margin: '0', padding: '0', border: 'none', background: 'transparent',
+      overflow: 'visible', 'pointer-events': 'none', 'z-index': '2147483647',
+    }, 'important');
+    const root = host.attachShadow({ mode: 'closed' });
+    document.documentElement.append(host);
+    const layers = {};
+    overlay = document[KEY] = {
+      host,
+      set,
+      // A layer's box, made the first time it is asked for.
+      layer(name) {
+        if (layers[name]) return layers[name];
+        const box = document.createElement('div');
+        set(box, { position: 'absolute', inset: '0', overflow: 'visible' });
+        const after = ORDER.slice(ORDER.indexOf(name) + 1).map(n => layers[n]).find(Boolean);
+        root.insertBefore(box, after || null);
+        return (layers[name] = box);
+      },
+      has: name => !!layers[name],
+      drop(name) {
+        layers[name]?.remove();
+        delete layers[name];
+        if (Object.keys(layers).length) return;
+        host.remove();
+        delete document[KEY];
+      },
+    };
+  }
+  // Shown again, so it is above a dialog the page opened since.
+  try { overlay.host.hidePopover(); overlay.host.showPopover(); } catch {}
+  return overlay;
+}
+
+// Runs fn(overlay, args) in the page, fn a function of its own that uses nothing from here. A string,
+// so the two functions go to the page as one call; evaluated over CDP, it is not the page's own eval,
+// which a page's script-src may forbid. With create false, nothing is drawn if the overlay is not there.
+function inOverlay(p, fn, args = null, create = true) {
+  return p.evaluate(`(() => { const overlay = (${pageOverlay})(${create}); return overlay ? (${fn})(overlay, ${JSON.stringify(args)}) : undefined; })()`);
+}
+
+// A new document drops the overlay: each layer kept on the tab is drawn again by its redraw.
+function keepAcrossPages(p, name, redraw) {
+  if (!tabState(p).overlayKept) {
+    tabState(p).overlayKept = new Map();
+    p.on('domcontentloaded', () => { for (const again of tabState(p).overlayKept.values()) again().catch(() => {}); });
+  }
+  tabState(p).overlayKept.set(name, redraw);
+}
+
+function forget(p, name) {
+  tabState(p).overlayKept?.delete(name);
+}
+
+module.exports = { inOverlay, keepAcrossPages, forget };

package/lib/record.js

@@ -401,6 +401,8 @@ function stepLabel(cmd, args) {
     const parsed = /^mouse/.test(cmd) ? 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.
+  if (cmd === 'toast') return `toast ${args.trim()}`.trim();
   if (!TARGET_FIRST.has(cmd)) return cmd;
   const rest = cmd === 'type' ? args.replace(/^\s*--delay(?:=|\s+)\S*\s*/, '') : args;
   const parsed = splitSelector(rest);
@@ -448,6 +450,13 @@ function cursorStep(p, what, point, ms) {
   rec.steps.push({ rec, t0, t1: t0 + ms / 1000, command: what.replace(/-?\d+(?:\.\d+)?/g, n => String(Math.round(Number(n) * rec.scale))), box: null, point: { x: scaled, y: Math.round(point.y * rec.scale) }, offSize: rec.resizedAt !== null, failed: false });
 }
 
+// Run by record off before it ends a recording, each with the recorded tab: for what the video must
+// still show first. Registered by the modules that know, which record cannot require.
+const beforeEnding = [];
+function beforeRecordingEnds(wait) {
+  beforeEnding.push(wait);
+}
+
 // The pause after an action on a recording tab, for its result to be seen (record on --pause).
 const ACTIONS = new Set([...WHOLE, ...TARGET_FIRST]);
 async function pauseAfter(p, cmd) {
@@ -616,7 +625,9 @@ const commands = {
       // Any client with the tab selected stops it, as it turns off any mode; both are told whose it was.
       const other = (rec.owner ?? null) !== (state.client ?? null);
       const clientName = c => c ?? 'the unnamed client';
-      // The tail: still page after the last action. Only record off has one; the seconds limit is a hard stop.
+      // What must be seen before the end (a toast's read time), then the tail: still page after the last
+      // action. Only record off has them; the seconds limit is a hard stop.
+      if (!rec.finishing) for (const wait of beforeEnding) await wait(state.page);
       if (!rec.finishing) await sleep(rec.pacing.tail);
       const text = await finishRecording(rec, other ? `${clientName(state.client)}'s record off ended ${clientName(rec.owner)}'s recording` : null);
       if (rec.failed) { lastEnded.get(rec.owner ?? null).reported = true; throw new Error(text); }
@@ -681,4 +692,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, recordingOf, stepsOf, pauseAfter, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };
+module.exports = { commands, recordingOf, beforeRecordingEnds, stepsOf, pauseAfter, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };

package/lib/runner.js

@@ -9,6 +9,7 @@ const { activeModes } = require('./modes');
 const { NO_TAB } = require('./util');
 const { stepStarted, stepEnded, stepLabel, pauseAfter } = require('./record');
 const cliNames = require('./cli-names');
+const { expandVariables } = require('./syntax');
 
 // playwright-cli names already explained, per client: each client is told once.
 const explained = new Set();
@@ -186,8 +187,14 @@ function enqueue(line) {
 // Server commands share the prompt's queue and are echoed to the pane, so
 // someone watching sees everything an agent does.
 // client names the sender: its commands show as [server:<client>] and use its own selected tab.
-function submit(text, client = null) {
-  if (DIALOG.test(text)) return answerDialog(text, client);
+// vars: values for the {{ PW_NAME }} variables in text (from send), filled in to run it; text is shown
+// as written, so a password in one is not in the command as the pane, the log and the prompt's history show it.
+function submit(text, client = null, vars = null) {
+  let run = text;
+  if (vars) {
+    try { run = expandVariables(text, vars); } catch (error) { return Promise.resolve({ status: 'error', output: `Error: ${error.message}` }); }
+  }
+  if (DIALOG.test(run)) return answerDialog(text, client, run);
   if (CDP_ANSWER.test(text)) {
     console.log(`[server${client ? `:${client}` : ''}] ${text}\nError: ${CDP_REFUSED}`);
     return Promise.resolve({ status: 'error', output: `Error: ${CDP_REFUSED}` });
@@ -195,11 +202,11 @@ function submit(text, client = null) {
   return new Promise(resolve => {
     queue = queue.then(async () => {
       if (state.stopping) return resolve({ status: 'error', output: 'The REPL is shutting down.' });
-      // Printed above whatever the person at the prompt is typing, which is
+      // Printed above whatever the user at the prompt is typing, which is
       // redrawn afterwards rather than broken up.
       if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
       out.log(`[server${client ? `:${client}` : ''}] ${text}`);
-      // So the person at the prompt can bring an agent's command back with up-arrow.
+      // So the user at the prompt can bring an agent's command back with up-arrow.
       if (state.rl?.history && state.rl.history[0] !== text) {
         state.rl.history.unshift(text);
         state.rl.history.length = Math.min(state.rl.history.length, 1000);
@@ -211,7 +218,7 @@ function submit(text, client = null) {
         let result;
         const flight = { text, resolve, answered: false };
         inFlight = flight;
-        const output = await out.collect(async () => { result = await execute(text, client); });
+        const output = await out.collect(async () => { result = await execute(run, client); });
         if (inFlight === flight) inFlight = null;
         if (!flight.answered) resolve({ status: result.status, output, uncertain: result.uncertain });
       }
@@ -222,12 +229,12 @@ function submit(text, client = null) {
 
 // Outside the queue, and so outside out.collect, whose single sink belongs to
 // the command that is waiting on the dialog.
-async function answerDialog(text, client) {
+async function answerDialog(text, client, run = text) {
   console.log(`[server${client ? `:${client}` : ''}] ${text}`);
-  const translated = cliNames.translate(text);
-  const note = translated && explain(text, translated, client);
+  const translated = cliNames.translate(run);
+  const note = translated && explain(run, translated, client);
   let result;
-  try { result = { status: 'ok', output: await dialogCommand((translated?.text || text).slice(6), clientRecord(client).page) }; }
+  try { result = { status: 'ok', output: await dialogCommand((translated?.text || run).slice(6), clientRecord(client).page) }; }
   catch (error) { result = { status: 'error', output: `Error: ${error.message}` }; }
   if (note) result.output = `${note}\n${result.output}`;
   console.log(result.output);

package/lib/send.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const client = require('./client');
-const { shellWords } = require('./syntax');
+const { shellWords, variablesIn } = require('./syntax');
 
 // The prompt, after the modes on in the selected tab if any: (watch network:off) pw[serve]>
 const PROMPT = /^(?:\([^()]*\) )?pw(\[serve\])?>\s*$/;
@@ -113,6 +113,8 @@ function commandLine(words) {
       return words[n - 1] === '--filename' || !/^(?:\d+|-.*)$/.test(w) ? resolve(w) : w;
     });
   }
+  // watch save writes its file.
+  if (words[0] === 'watch' && words[1] === 'save' && words.length > 2) resolved = ['watch', 'save', resolve(words.slice(2).join(' '))];
   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));
   }
@@ -128,7 +130,18 @@ function commandLine(words) {
 
 // A file of commands, one per line, run in turn until one fails. A recording it started and did not
 // stop is still on: the next take would fail to start, so it says so.
-const PATHS = /^(?:upload|record|video-start|video-stop|screenshot)$/;
+const PATHS = /^(?:upload|record|video-start|video-stop|screenshot|watch)$/;
+// The values of the {{ PW_NAME }} variables in a command, from send's environment: { vars }, null with
+// none, or { error } for one that is not set or has a line break.
+function variablesFor(command) {
+  const names = variablesIn(command);
+  const unset = names.filter(name => process.env[name] === undefined);
+  const broken = names.filter(name => /[\r\n]/.test(process.env[name] || ''));
+  if (unset.length) return { error: `${unset.join(', ')} ${unset.length === 1 ? 'is' : 'are'} not set; set ${unset.length === 1 ? 'it' : 'them'} for send (${unset[0]}=... pw-repl send ...), or --no-vars sends {{ ${unset[0]} }} as it is` };
+  if (broken.length) return { error: `${broken.join(', ')} ${broken.length === 1 ? 'has' : 'have'} a line break, which a line cannot hold` };
+  return names.length ? { vars: Object.fromEntries(names.map(name => [name, process.env[name]])) } : null;
+}
+
 async function sendFile(options) {
   let text;
   try { text = fs.readFileSync(options.file, 'utf8'); } catch (error) { return fail(`cannot read ${options.file} (${error.code || error.message})`); }
@@ -141,7 +154,9 @@ async function sendFile(options) {
     // 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;
-    const status = await send({ ...options, file: null, command });
+    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 });
     if (status !== 0) {
       console.error(`pw-repl: stopped at line ${i + 1} of ${options.file} (${line}), exit status ${status}`);
       if (recording) console.error('pw-repl: record off was not reached, so the recording is still on; pw-repl send record off ends it');
@@ -159,14 +174,22 @@ async function send(options) {
   if (!command) return fail('no command given');
   // A newline would reach the REPL as a second, unmarked command.
   if (/[\r\n]/.test(command)) return fail('the command must be a single line');
+  // A command of its own, not a file's line, which sendFile has read its variables for already.
+  if (options.vars === undefined && !options.noVars) {
+    const found = variablesFor(command);
+    if (found?.error) return fail(found.error);
+    options = { ...options, vars: found?.vars || null };
+  }
   const timeoutMs = options.timeout * 1000;
   const way = route(options);
   const name = options.client || process.env.PW_CLIENT || null;
   if (name && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(name)) return fail('a client name is 1-40 letters, digits, dots, dashes and underscores');
   // The pane has one prompt, so a command typed there has no client of its own.
   if (way.kind === 'tmux' && options.client) return fail('-c needs the command server (pw-repl serve); a REPL in tmux has no clients');
+  // Typed into the pane, a variable's value would be on screen and in its scrollback.
+  if (way.kind === 'tmux' && options.vars) return fail(`{{ ${Object.keys(options.vars)[0]} }} needs the command server (pw-repl serve), which fills it in without showing it; --no-vars sends it as it is`);
   if (way.kind === 'tmux') return viaTmux(way.session, command, timeoutMs);
-  const answer = await client.request(way.endpoint, command, timeoutMs, name);
+  const answer = await client.request(way.endpoint, command, timeoutMs, name, options.vars || null);
   if (answer.result?.starting) return fail(`${answer.result.output} (pw-repl where says when it serves)`);
   if (answer.result) {
     if (answer.result.output) console.log(answer.result.output);