pw-repl 0.9.0 → 0.11.0

package/lib/elements.js

@@ -9,6 +9,7 @@ const { numbers, hints } = require('./util');
 const { tabState } = require('./tabstate');
 const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
 const { recordingOf, stepTarget } = require('./record');
+const { settled } = require('./emulation');
 
 // The type a page sees for a file it is given, from its extension.
 const MIME_TYPES = {
@@ -196,10 +197,16 @@ async function pointerAction(selector, act, options = {}, clicks = 0) {
       return '';
     }
     try {
+      // The first of several is named, as it may not be the one meant (a heading with a button's text);
+      // before acting, since a click may take the page away.
+      const what = chosen.position === 1
+        ? await chosen.handle.evaluate(el => `<${el.tagName.toLowerCase()}> ${(el.innerText || el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60)}`).catch(() => null)
+        : null;
       const point = await aimAt(state.page, chosen.handle, left());
       await onElement(selector, () => act(chosen.handle, null, { ...options, timeout: left() }));
       await landed(point, clicks);
-      return chosen.position === 1 ? '' : ` (match ${chosen.position} of ${chosen.count}; the ones before it are hidden or covered)`;
+      if (chosen.position !== 1) return ` (match ${chosen.position} of ${chosen.count}; the ones before it are hidden or covered)`;
+      return ` (the first of ${chosen.count} matches${what ? `: ${what}` : ''})`;
     } catch (error) {
       if (!/not attached/i.test(error.message) || Date.now() >= deadline) throw error;
     } finally {
@@ -282,7 +289,7 @@ async function hideHighlights(p, mine = false) {
   if (!highlights?.size) return 0;
   const hidden = [...highlights].filter(([, h]) => !mine || (h.owner ?? null) === (state.client ?? null));
   if (hidden.length === highlights.size) await p.hideHighlight();
-  else for (const [selector] of hidden) await p.locator(selector).hideHighlight();
+  else for (const [selector, h] of hidden) await (h.drawn || p.locator(selector)).hideHighlight();
   for (const [selector] of hidden) highlights.delete(selector);
   return hidden.length;
 }
@@ -293,6 +300,85 @@ onShutdown(async () => {
   await Promise.all(pages.map(p => hideHighlights(p).catch(() => {})));
 });
 
+// Playwright's highlight labels each box with its locator, which covers what is below it, and has
+// no option not to; highlights are drawn without it unless highlight --labels on. Its overlay is an
+// x-pw-glass element with a closed shadow root, which only CDP reaches: a stylesheet adopted there
+// hides the labels, under any CSP, and stays as Playwright redraws them. Playwright removes the
+// overlay with its last highlight, and the sheet with it, so it is applied again after each one.
+const LABELS_OFF = 'x-pw-tooltip:not([data-pw-repl])';
+// The clients told that the labels could not be hidden, each once.
+const labelsWarned = new Set();
+
+// Adds or removes the sheet in the main document's overlay, and says whether it worked: false when
+// there is an overlay but its labels are not hidden. Null when there is no overlay.
+async function applyLabels(p, hide) {
+  const session = await p.context().newCDPSession(p);
+  try {
+    const { root } = await session.send('DOM.getDocument', { depth: 0 });
+    const { nodeId } = await session.send('DOM.querySelector', { nodeId: root.nodeId, selector: 'x-pw-glass' });
+    if (!nodeId) return null;
+    const { node } = await session.send('DOM.describeNode', { nodeId, pierce: true });
+    const shadow = node.shadowRoots?.[0];
+    if (!shadow) return false;
+    const { object } = await session.send('DOM.resolveNode', { backendNodeId: shadow.backendNodeId });
+    const call = (fn, args) => session.send('Runtime.callFunctionOn', { objectId: object.objectId, functionDeclaration: fn.toString(), arguments: args.map(value => ({ value })), returnByValue: true });
+    await call(function (rule, hidden) {
+      const sheets = [...this.adoptedStyleSheets].filter(s => ![...s.cssRules].some(r => r.selectorText === rule));
+      if (hidden) {
+        const sheet = new CSSStyleSheet();
+        sheet.replaceSync(`${rule} { display: none !important; }`);
+        sheets.push(sheet);
+      }
+      this.adoptedStyleSheets = sheets;
+    }, [LABELS_OFF, hide]);
+    if (!hide) return true;
+    // Playwright draws its labels on a later frame.
+    await settled(p);
+    const { result } = await call(function (rule) {
+      const ours = [...this.adoptedStyleSheets].some(s => [...s.cssRules].some(r => r.selectorText === rule));
+      return ours && [...this.querySelectorAll('x-pw-tooltip')].every(t => getComputedStyle(t).display === 'none');
+    }, [LABELS_OFF]);
+    return result.value === true;
+  } finally {
+    await session.detach().catch(() => {});
+  }
+}
+
+// Hides the tab's labels unless they are on; says so once if that failed, and the highlight is drawn
+// with its label as Playwright draws it. A CDP call that fails, as one does when the tab navigates or
+// closes, says nothing of Playwright's overlay: only the check finding the labels shown does.
+async function keepLabels(p) {
+  if (tabState(p).labelsOn) return;
+  const worked = await applyLabels(p, true).catch(() => null);
+  const client = state.client ?? null;
+  if (worked !== false || labelsWarned.has(client)) return;
+  labelsWarned.add(client);
+  out.log(`highlight: could not hide the labels; Playwright's highlight has changed (playwright-core ${require('playwright-core/package.json').version}). The boxes are drawn with their labels.`);
+}
+
+async function setLabels(p, on) {
+  if (on) tabState(p).labelsOn = { owner: state.client }; else delete tabState(p).labelsOn;
+  if (on) await applyLabels(p, false); else await keepLabels(p);
+}
+
+// A date or time input takes keys part by part, in the order it shows them (10/02/2026 in en-US), so
+// its ISO form, typed, comes out empty or mangled; fill sets it from that.
+const DATE_INPUTS = {
+  date: [/^\d{4,}-\d\d-\d\d$/, '2026-10-02'],
+  time: [/^\d\d:\d\d(:\d\d(\.\d+)?)?$/, '14:30'],
+  'datetime-local': [/^\d{4,}-\d\d-\d\d[T ]\d\d:\d\d(:\d\d(\.\d+)?)?$/, '2026-10-02T14:30'],
+  month: [/^\d{4,}-\d\d$/, '2026-10'],
+  week: [/^\d{4,}-W\d\d$/, '2026-W40'],
+};
+function refuseIsoDate(kind, text, what, selector) {
+  if (DATE_INPUTS[kind]?.[0].test(text)) throw new Error(`${what} is a ${kind} input: typed, ${text} comes out mangled, since it takes keys part by part in the order it shows them. fill ${selector} ${text} sets it`);
+}
+function dateInputHolds(kind, value, what, selector) {
+  if (!DATE_INPUTS[kind]) return '';
+  if (!value) throw new Error(`${what}, a ${kind} input, is still empty: it takes keys part by part, in the order it shows them. fill sets it from its ISO form: fill ${selector} ${DATE_INPUTS[kind][1]}`);
+  return `, a ${kind} input, which now holds ${value}`;
+}
+
 const commands = {
   async click(args) {
     const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
@@ -313,15 +399,27 @@ const commands = {
   },
 
   async highlight(args) {
-    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | off]';
-    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag' });
+    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | --labels off|on | off]';
+    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag', labels: 'value' });
     const style = found.find(o => o.name === 'style');
     const hide = found.some(o => o.name === 'hide');
+    const labels = found.find(o => o.name === 'labels');
     const highlights = highlightsOf(state.page);
+    // For the whole tab, with a highlight to draw or on its own.
+    if (labels) {
+      if (hide || rest === 'off' || !['off', 'on'].includes(labels.value)) throw new Error(usage);
+      await setLabels(state.page, labels.value === 'on');
+      out.log(labels.value === 'on'
+        ? 'Labels on in the selected tab: each highlight is labelled with its locator; highlight --labels off hides them'
+        : 'Labels off in the selected tab');
+      if (!rest) return;
+    }
     if (!rest && !found.length) {
       if (!highlights.size) { out.log(`Nothing is highlighted in the selected tab.\n${hints([['highlight <selector>', 'draw a box around it']])}`); return; }
-      for (const [selector, h] of highlights) out.log(`${selector}${h.style ? `  --style=${JSON.stringify(h.style)}` : ''}${h.owner ? `  (by ${h.owner})` : ''}`);
-      out.log(hints([['highlight --hide [<selector>]', 'hide one, or all']]));
+      for (const [selector, h] of highlights) out.log(`${selector}${h.drawn?.toString() !== state.page.locator(selector).toString() ? `  as ${h.drawn}` : ''}${h.style ? `  --style=${JSON.stringify(h.style)}` : ''}${h.owner ? `  (by ${h.owner})` : ''}`);
+      const on = tabState(state.page).labelsOn;
+      if (on) out.log(`Labels are on${on.owner ? ` (by ${on.owner})` : ''}.`);
+      out.log(hints([['highlight --hide [<selector>]', 'hide one, or all'], on ? ['highlight --labels off', 'hide their labels'] : ['highlight --labels on', 'label each with its locator']]));
       return;
     }
     if (rest === 'off' && !found.length || hide && !rest) {
@@ -334,7 +432,7 @@ const commands = {
     const locator = state.page.locator(selector);
     if (hide) {
       if (!highlights.has(selector)) throw new Error(`${rest} is not highlighted; highlight lists what is`);
-      await locator.hideHighlight();
+      await (highlights.get(selector).drawn || locator).hideHighlight();
       highlights.delete(selector);
       out.log(`Hid the highlight on ${rest}`);
       return;
@@ -342,9 +440,13 @@ const commands = {
     const count = await locator.count();
     if (!count) throw new Error(`No element matches ${rest}; nothing was highlighted`);
     // Drawn again, with its new style, rather than twice.
-    if (highlights.has(selector)) await locator.hideHighlight();
-    await locator.highlight(style ? { style: style.value } : {});
-    highlights.set(selector, { owner: state.client, style: style?.value || null });
+    if (highlights.has(selector)) await (highlights.get(selector).drawn || locator).hideHighlight();
+    // Playwright labels a box with the locator it is given, and a snapshot ref's (aria-ref=e5) finds
+    // nothing in the page's code: one is drawn with the locator Playwright makes for its element.
+    const drawn = REF.test(rest) ? await locator.normalize().catch(() => locator) : locator;
+    await drawn.highlight(style ? { style: style.value } : {});
+    await keepLabels(state.page);
+    highlights.set(selector, { owner: state.client, style: style?.value || null, drawn });
     out.log(`Highlighted ${rest}${count > 1 ? ` (all ${count} matches)` : ''}; highlight --hide ${rest} hides it`);
   },
 
@@ -404,25 +506,34 @@ const commands = {
     if (sole && sole.rest === undefined) {
       // Named, since it may not be the element meant; one that takes no text is refused.
       const focused = await state.page.evaluate(() => {
-        const el = document.activeElement;
+        let el = document.activeElement;
+        while (el?.shadowRoot?.activeElement) el = el.shadowRoot.activeElement;
         if (!el || el === document.body || el === document.documentElement) return null;
         const editable = el.isContentEditable || el.matches('textarea, input:not([type=checkbox],[type=radio],[type=button],[type=submit],[type=reset],[type=image],[type=file],[type=range],[type=color],[type=hidden])');
         const id = el.id ? `#${el.id}` : el.name ? `[name=${el.name}]` : el.placeholder ? `[placeholder="${el.placeholder}"]` : '';
-        return { editable, name: `${el.tagName.toLowerCase()}${id}` };
+        return { editable, name: `${el.tagName.toLowerCase()}${id}`, type: el.type };
       });
       const usage = 'type <selector> <text> types into an element, e.g. type #search garden hose';
       if (!focused) throw new Error(`Nothing on the page has focus: ${usage}`);
       if (!focused.editable) throw new Error(`The focused element, ${focused.name}, takes no text: ${usage}`);
+      refuseIsoDate(focused.type, sole.word, `The focused ${focused.name}`, '<selector>');
       await state.page.keyboard.type(sole.word, { delay: delay() });
+      const held = DATE_INPUTS[focused.type] ? dateInputHolds(focused.type, await state.page.evaluate(() => {
+        let el = document.activeElement;
+        while (el?.shadowRoot?.activeElement) el = el.shadowRoot.activeElement;
+        return el?.value;
+      }), `The focused ${focused.name}`, '<selector>') : '';
       if (submit) await state.page.keyboard.press('Enter');
-      out.log(`Typed into the focused ${focused.name}${submit ? ', and submitted' : ''}`);
+      out.log(`Typed into the focused ${focused.name}${held}${submit ? ', and submitted' : ''}`);
       return;
     }
     const { selector, value, shown } = selectorAndValue(args, 'type [<selector>] <text> [--submit]', 'type #search garden hose');
     const timeout = await aimFor(selector);
     // Typed after what the field already holds, as someone clicking into it
     // at the end would; focusing it alone leaves the caret at the start.
-    await onElement(selector, () => state.page.locator(selector).first().evaluate(el => {
+    const kind = await onElement(selector, () => state.page.locator(selector).first().evaluate((el, dateKinds) => {
+      // Focused again, so a date input already focused takes keys from its first part, not where it was left.
+      if (dateKinds.includes(el.type) && el.matches(':focus')) el.blur();
       el.focus();
       if (typeof el.value === 'string' && typeof el.setSelectionRange === 'function') {
         try { el.setSelectionRange(el.value.length, el.value.length); } catch {}
@@ -433,10 +544,14 @@ const commands = {
         getSelection().removeAllRanges();
         getSelection().addRange(range);
       }
-    }, null, { timeout }));
+      return el.type;
+    }, Object.keys(DATE_INPUTS), { timeout }));
+    const quoted = /\s/.test(shown) ? `"${shown}"` : shown;
+    refuseIsoDate(kind, value, shown, quoted);
     await state.page.keyboard.type(value, { delay: delay() });
+    const held = DATE_INPUTS[kind] ? dateInputHolds(kind, await onElement(selector, () => state.page.locator(selector).first().evaluate(el => el.value, null, { timeout: 5000 })), shown, quoted) : '';
     if (submit) await state.page.keyboard.press('Enter');
-    out.log(`Typed into${submit ? ' and submitted' : ''}: ${shown}`);
+    out.log(`Typed into${submit ? ' and submitted' : ''}: ${shown}${held}`);
   },
 
   async press(args) {
@@ -483,7 +598,7 @@ const commands = {
   async upload(args) {
     const parsed = splitSelector(args);
     // playwright-cli's upload <file> answers a file picker a click opened. Here
-    // the input is named instead: catching pickers would catch the person's too.
+    // the input is named instead: catching pickers would catch the user's too.
     const usage = 'Usage: upload <selector> <file>..., naming the file input (or the button that opens it) first, e.g. upload e12 ./doc.pdf; quote a path with spaces';
     if (!parsed || parsed.rest === undefined) throw new Error(usage);
     // A path, not a selector; // starts an XPath.
@@ -511,4 +626,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, soleSelector, onElement, hideHighlights };
+module.exports = { commands, soleSelector, onElement, hideHighlights, setLabels };

package/lib/emulation.js

@@ -66,6 +66,18 @@ function settled(p) {
   ]);
 }
 
+// Bringing a tab to the front can leave Chrome capturing it at the window's size after its next
+// navigation, although the page is still laid out at its viewport's or phone's: sending the same
+// metrics again, on the kept session, has it draw at them.
+async function reapplyMetrics(p) {
+  const tab = tabState(p);
+  if (!tab.viewport && !tab.emulation?.device) return;
+  const session = await keptSession(p);
+  if (tab.viewport) await viewportMetrics(session, tab.viewport);
+  else if (tab.emulation?.device) await deviceMetrics(session, tab.emulation.device);
+  await settled(p);
+}
+
 async function setViewport(p, size) {
   const session = await keptSession(p);
   if (size) {
@@ -220,4 +232,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, viewportMetrics, setEmulation, setViewport, settled };
+module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, viewportMetrics, setEmulation, setViewport, settled, reapplyMetrics };

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 }}", which pw-repl send --file fills in from its environment: PW_PASSWORD=... pw-repl
+send --file login.txt. 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',
@@ -359,26 +395,37 @@ Playwright adds to window as it acts are left out, and it says how many.`,
   links: { usage: 'links [--all]', summary: 'links on the page (text and href)' },
   inputs: { usage: 'inputs [--all]', summary: 'form controls on the page; values are omitted' },
   highlight: {
-    usage: 'highlight [<selector> [--style=<css>] | off]',
+    usage: 'highlight [<selector> | off] [options]',
     summary: 'draw a box over elements, for the user or a screenshot',
     args: [
-      ['<selector>', 'draws Playwright\'s highlight over every match, as playwright-cli\'s does: a tinted box labelled with its locator, that follows the element as the page scrolls or changes, and is in screenshots.'],
+      ['<selector>', 'draws Playwright\'s highlight over every match, as playwright-cli\'s does: a tinted box that follows the element as the page scrolls or changes, and is in screenshots.'],
       ['(none)', 'lists the selected tab\'s highlights.'],
       ['off', 'hides them all, as highlight --hide does.'],
     ],
     options: [
       ['--style=<css>', 'CSS added to the box, quoted if it has spaces: highlight e5 --style="outline: 3px solid blue; border-radius: 50%" circles e5 in blue.'],
       ['--hide <selector>', 'hides one.'],
+      ['--labels on|off', 'labels every box in the selected tab with its locator, as Playwright does, or not: those drawn already too. With a selector or on its own (highlight --labels on). Default: off.'],
     ],
     detail: `A highlight is a mode of its tab: modes shows it, modes off hides it, and the REPL hides every one as
 it stops. Loading a new page drops them; a page that changes its route without loading keeps them.
 
 The box is drawn over the page, in an element of Playwright's own added to it (x-pw-glass); the page's
-own elements are not changed, and clicks and typing reach them as before. Playwright always labels the
-box, and the label can cover what is just below it.`,
-    moreAbout: 'marking a screenshot without the label',
-    more: `For a screenshot without the label, eval can outline the element itself (with border-radius: 50% for
-a circle). That changes the page, so put it back afterwards, as it was if it had a style of its own:
+own elements are not changed, and clicks and typing reach them as before.
+
+Labels (--labels): Playwright labels each box with its locator, which covers what is just below it and
+shows selectors in a screenshot or a video, so the REPL hides the labels unless they are on. On is a mode
+of the tab, until --labels off or modes off. A box is labelled with the selector it was drawn from, e.g.
+locator('role=button[name="Pay"]'); one drawn from a snapshot ref, with the locator Playwright makes for
+its element, e.g. getByRole('button', { name: 'Pay' }), as the ref's own is not in the page's code.`,
+    moreAbout: 'labels inside a frame, and when they cannot be hidden',
+    more: `A highlight on an element inside an iframe is drawn in the frame's own document, and keeps its label.
+
+The REPL hides the labels by reaching into Playwright's overlay, which a new Playwright could change: if
+it cannot, it tells each client once, and the boxes are drawn with their labels.
+
+For a screenshot without one then, eval can outline the element itself (with border-radius: 50% for a
+circle). That changes the page, so put it back afterwards, as it was if it had a style of its own:
   eval document.querySelector("#rate-3").style.outline = "3px solid blue"
   eval document.querySelector("#rate-3").style.outline = ""`,
   },
@@ -399,14 +446,45 @@ else in /tmp.
 
 It brings the tab to the front of its window first: Chrome draws only the tab in front. The image is
 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.`,
+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]',
     summary: 'draw a pointer where the REPL acts, for videos',
     args: [
       ['on', 'fades it in where the mouse last went, or the middle.'],
-      ['on <selector>', 'fades it in on the element (a video\'s first, say), scrolled into view; when it is on already, glides it there.'],
+      ['on <selector>', 'fades it in on the element (a video\'s first, say); when it is on already, glides it there. An element partly in view is pointed at where it shows, without scrolling, so one the page cuts off still looks cut off; one out of view is scrolled to.'],
       ['on <x> <y>', 'the same, at a point in the viewport.'],
       ['off', 'fades it out.'],
       ['(none)', 'says whether it is on, and where.'],
@@ -511,7 +589,8 @@ goes on recording. There is no --mp4 or --webm: the file's ending picks the form
       ['(none)', 'shows what is on.'],
     ],
     detail: `Per tab, until turned off or the REPL exits; emulate mobile <device> while another is on switches to
-it. While mobile is on, viewport refuses: the device sets the size.
+it. Mobile and viewport both set the screen size, so each refuses while the other is on: viewport off before
+emulate mobile, and emulate mobile off before viewport.
 
 The page sees the user agent, touch and navigator.languages from its next load: reload after turning
 mobile or locale on or off. Touch means the page sees a touch screen; click still clicks with the
@@ -793,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