pw-repl 0.11.2 → 0.11.5

package/AGENTS.md

@@ -4,6 +4,9 @@ How to use the REPL is in the skill `bin/pw-repl.js skill` prints (from `skill/S
 its version and hash). Read it first. In this clone, `pw-repl` there means `bin/pw-repl.js` (from the
 folder this file is in) when it is not installed globally.
 
+If there is a local agent file (e.g. `AGENTS.LOCAL.md`) next to this file, read it too.
+They add to the rules in this file, and where the two differ, the local file wins.
+
 ## Contributing
 
 If you hit a limitation or write a workaround, consider adding the capability to the REPL instead.

package/lib/elements.js

@@ -8,7 +8,7 @@ const { unquote, toSelector, keyName, splitSelector, REF } = require('./syntax')
 const { numbers, hints } = require('./util');
 const { tabState } = require('./tabstate');
 const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
-const { recordingOf, stepTarget } = require('./record');
+const { recordingOf, stepTarget, pauseToShow } = require('./record');
 const { settled } = require('./emulation');
 
 // The type a page sees for a file it is given, from its extension.
@@ -448,6 +448,10 @@ const commands = {
     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`);
+    // Recording, its steps say where the box is (the first match's), and it is shown before the next
+    // command, which may take it away.
+    if (recordingOf(state.page)) stepTarget(state.page, await locator.first().boundingBox({ timeout: 1000 }).catch(() => null), null);
+    pauseToShow(state.page);
   },
 
   // At a point, in CSS pixels from the top left of the tab's viewport, as playwright-cli's are.

package/lib/help.js

@@ -99,7 +99,7 @@ page loads: turn off any the rehearsal left (toast off, cursor off, highlight of
     record off
 
 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
+not fill, for text the viewer should see typed), each action and each highlight 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, 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
@@ -156,7 +156,7 @@ const COMMANDS = {
       ['<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.'],
+      ['close [url-part]', 'closes the selected tab, or the one matching url-part; of several, the one you opened, if exactly one of them is, and refused otherwise.'],
     ],
     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.
@@ -316,7 +316,8 @@ 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.
+shows its value. Every other field shows what it holds (textbox "Name": Ada), and a select its chosen
+option: inputs lists the fields without what they hold.
 
 Output over 60 lines ends with a line count.`,
   },
@@ -341,7 +342,8 @@ Output over 60 lines ends with a line count.`,
 navigation, described by role and name as in snapshot, with up to 5 of the requests it caused under it,
 each with its status as in requests (body <#> for one), leaving out scripts and what requests hides. The
 REPL's own fill shows as type. A double-click shows as two clicks; hovering and moving the mouse are not
-recorded.
+recorded. When other elements are described alike (cards that repeat their buttons), the step says which
+one: (under "<its nearest heading>"), with n of N where the heading does not settle it.
 
 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.
@@ -350,12 +352,18 @@ that was ever type=password, or whose autocomplete is for a password, a one-time
 
 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
+element is found by its data-testid, its role and a piece of its name (role=button[name*="Save"]), its id,
+name attribute or text; else by an id a framework made up, which another render can number
+differently, or its place in the page, which a change to the page can break. A field changed again before
+anything else was done (a date picker stepping through days) is filled once, with its last value. After
+the app changed its URL without loading a page, the next step waits up to 30s for its element first, as
+the new view may take longer to draw than an action waits. 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.
+one no selector finds alone) stays a comment saying why, and the save says how many there are. The file
+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.`,
     moreAbout: 'bodies kept, --live timing, what --changes misses, one --next-tab at a time, and what watch save leaves out',
@@ -373,7 +381,10 @@ waited for at a time: while one client waits, another's watch on --next-tab is r
 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.
+changed without loading a page (history.pushState or replaceState), as a comment: the step before it
+changes it again. A click on a label that holds its control is the control's click, as it passes it on;
+one on a label that names its control with for= is the label's, since that can be a control anywhere
+(the first of a page's repeated ids), and a for= label on a checkbox toggles it rather than checks it.
 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' },
@@ -393,7 +404,15 @@ Playwright adds to window as it acts are left out, and it says how many.`,
   count: { usage: 'count <selector>', summary: 'number of matches' },
   visible: { usage: 'visible <selector>', summary: 'whether the first match is visible' },
   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' },
+  inputs: {
+    usage: 'inputs [--all]',
+    summary: 'form controls, native and ARIA; values are omitted',
+    detail: `Each control as JSON: tag, role, type, name, id, label, placeholder, disabled (by its own attribute,
+a disabled fieldset around it, or aria-disabled), readonly, checked for a checkbox, radio or switch (true,
+false or "mixed"), and autocomplete. An ARIA control is an element with role checkbox, radio, switch, combobox, listbox, textbox,
+searchbox, slider or spinbutton, as Radix and the like draw them (a button that is a radio); its role
+says what it is, and type is a native control's own. What a field holds is never shown.`,
+  },
   highlight: {
     usage: 'highlight [<selector> | off] [options]',
     summary: 'draw a box over elements, for the user or a screenshot',
@@ -516,7 +535,7 @@ takes no clicks, and it points at elements inside frames too.`,
     optionsFor: 'record on',
     options: [
       ['--steps', 'also save clip.steps.txt next to clip.webm: when and where each command ran (Steps, below). Default: off.'],
-      ['--pause=<ms>', 'a pause after each action, so the viewer sees what it did. Default: 750; 0 none.'],
+      ['--pause=<ms>', 'a pause after each action, and each highlight drawn, so the viewer sees it. Default: 750; 0 none.'],
       ['--lead=<ms>', 'still page recorded before record on returns. Default: 1000; counts toward the seconds.'],
       ['--tail=<ms>', 'still page recorded after record off, before it stops. Default: 1000; none when it stops at its seconds.'],
       ['--filename=<file>', 'the file, as playwright-cli writes it.'],
@@ -528,13 +547,13 @@ owner-only, as a screenshot is, and never replaces one. One recording per tab; a
 tab selected can stop it, and both are told whose it was.
 
 While recording: type types at a pace the video can show (help type), mousewheel scrolls in eased steps,
-an element out of view is scrolled to smoothly, each action is followed by --pause, and with the cursor
+an element out of view is scrolled to smoothly, each action and each highlight drawn is followed by --pause, and with the cursor
 on it rests 300ms on the element before acting. fill still sets a value at once: use type for text the
 viewer should see typed. Send the take as a file of commands (pw-repl send --file take.txt), or the time
 between commands is in the video. help video has the whole way through.
 
 Steps (--steps): one line per command run on the tab while it recorded: when it began and ended, in
-seconds into the video, and the element or point it acted on, in the video's pixels. Use it to find a
+seconds into the video, and the element or point it acted on (or highlighted), in the video's pixels. Use it to find a
 moment in the video ("at 0:12 it clicked Save"), to add captions or cuts in an editor, or to check what
 ran. It names the command and what it acted on, never what it typed or chose, the code it ran or a URL.
 A (page) line marks each new page, loaded or routed to by a single-page app. It is renamed with the
@@ -602,7 +621,7 @@ drew with them (times, colors set by its script) changes only when it reloads.`,
     summary: 'wait for an element, text, a response or a load (10s)',
     args: [
       ['<selector>', 'for a matching element to be visible.'],
-      ['text <text>', 'for text to be visible: any part of an element\'s text, any case.'],
+      ['text <text>', 'for text to be visible: any part of an element\'s text, any case. Quote text that ends in a number, or the number is taken as the seconds: wait text "Showing 1".'],
       ['request <part>', 'for a matching response (a URL part or a glob), counting one that finished since the previous command began, or is still under way: click, then wait request, does not miss it.'],
       ['load', 'for the page to finish loading (its load event), counting a navigation that began since the previous command began: click a link, then wait load.'],
       ['[secs]', 'how long, up to 120. Default: 10.'],

package/lib/inspect.js

@@ -15,6 +15,8 @@ const { waitForLoad, waitForRequest } = require('./requestlog');
 const { deviceMetrics, viewportMetrics, reapplyMetrics } = require('./emulation');
 
 const SCREENSHOT_DELAY_MAX = 60;
+// What inputs lists: native form controls, and elements that are one by their ARIA role.
+const INPUTS = ['input', 'select', 'textarea', ...['checkbox', 'radio', 'switch', 'combobox', 'listbox', 'textbox', 'searchbox', 'slider', 'spinbutton'].map(role => `[role=${role}]`)].join(', ');
 
 function nextScreenshotPath(name) {
   const filename = name ? `screenshot-${name}` : `screenshot-${Date.now()}`;
@@ -262,18 +264,46 @@ const commands = {
     printOutput(links, all);
   },
 
+  // Native controls and ARIA ones (a button with role=radio, as Radix draws them), each with what names
+  // it and, for a checkbox, radio or switch, whether it is checked: true, false or "mixed" for both.
   async inputs(_args, all) {
-    const inputs = await state.page.$$eval('input, select, textarea', els =>
-      els.map(e => ({
+    const inputs = await state.page.$$eval(INPUTS, els => {
+      const plain = text => (text || '').replace(/\s+/g, ' ').trim().slice(0, 60);
+      // A label's own words, without what the fields inside it hold.
+      const labelText = label => {
+        const copy = label.cloneNode(true);
+        copy.querySelectorAll('select, textarea, input, button').forEach(n => n.remove());
+        return copy.textContent;
+      };
+      const labelOf = e => {
+        const byIds = (e.getAttribute('aria-labelledby') || '').split(/\s+/).map(id => id && document.getElementById(id)).filter(Boolean);
+        if (byIds.length) return plain(byIds.map(n => n.textContent).join(' '));
+        return plain(e.getAttribute('aria-label')) || plain([...(e.labels || [])].map(labelText).join(' ')) || plain(e.getAttribute('title'));
+      };
+      const native = e => e.matches('input, select, textarea');
+      const checkedOf = e => {
+        if (native(e) && /^(?:checkbox|radio)$/.test(e.type)) return e.indeterminate ? 'mixed' : e.checked;
+        if (!/^(?:checkbox|radio|switch)$/.test(e.getAttribute('role'))) return undefined;
+        const state = e.getAttribute('aria-checked');
+        return state === 'mixed' ? 'mixed' : state === 'true';
+      };
+      return els.map(e => ({
         tag: e.tagName.toLowerCase(),
-        type: e.type || '',
-        name: e.name || '',
+        role: e.getAttribute('role') || '',
+        // A button's own type (submit) is not what kind of control it is: its role says that.
+        type: native(e) ? e.type : '',
+        name: e.getAttribute('name') || '',
         id: e.id || '',
-        placeholder: e.placeholder || '',
-        disabled: e.disabled,
-        autocomplete: e.autocomplete || ''
-      }))
-    );
+        label: labelOf(e),
+        placeholder: e.getAttribute('placeholder') || '',
+        // By its own attribute (a button that is a radio, as Radix does it), a disabled fieldset around it,
+        // or aria-disabled.
+        disabled: e.matches(':disabled') || e.getAttribute('aria-disabled') === 'true',
+        readonly: e.matches('input, textarea') ? e.readOnly : e.getAttribute('aria-readonly') === 'true',
+        checked: checkedOf(e),
+        autocomplete: native(e) ? e.autocomplete || '' : ''
+      }));
+    });
     if (!inputs.length) { out.log('No inputs found'); return; }
     printOutput(inputs, all);
   },
@@ -403,7 +433,8 @@ const commands = {
     let seconds = WAIT_DEFAULT;
     // A number last is the seconds, unless it is all there is to wait for: wait text 990.
     const onlyWhat = (tokens[0] === 'text' || tokens[0] === 'request') && tokens.length === 2;
-    if (tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1])) seconds = Number(tokens.pop());
+    const tookSeconds = tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1]);
+    if (tookSeconds) seconds = Number(tokens.pop());
     if (!tokens.length || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
     const timeout = seconds * 1000;
     // Said plainly, not as Playwright's call log.
@@ -420,7 +451,9 @@ const commands = {
         return waitForRequest(what, timeout);
       }
       if (gone) return waitGone(state.page.getByText(what), what, timeout);
-      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${seconds}s`));
+      // Text that ends in a number gives it up as the seconds, unless quoted: said when it times out.
+      const quote = tookSeconds && !/^["']/.test(tokens[1]) ? ` (${seconds} was taken as the seconds: wait text "${what} ${seconds}" waits for that text)` : '';
+      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${seconds}s${quote}`));
       out.log(`Visible: ${what}`);
       return;
     }

package/lib/record.js

@@ -403,6 +403,8 @@ function stepLabel(cmd, args) {
   }
   // A toast's text is what it said in the video, for whoever edits it.
   if (cmd === 'toast') return `toast ${args.trim()}`.trim();
+  // A highlight's selector, or off: which box came and went, without its style.
+  if (cmd === 'highlight') return `highlight ${args.replace(/\s*--style=(?:"(?:[^"\\]|\\.)*"|'[^']*'|\S+)/, '').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);
@@ -457,11 +459,20 @@ function beforeRecordingEnds(wait) {
   beforeEnding.push(wait);
 }
 
-// The pause after an action on a recording tab, for its result to be seen (record on --pause).
+// The pause after an action on a recording tab, for its result to be seen (record on --pause), and
+// after a command that drew something to be seen (pauseToShow), as highlight does. After the command's
+// step ends, as an action's does.
 const ACTIONS = new Set([...WHOLE, ...TARGET_FIRST]);
+function pauseToShow(p) {
+  const rec = recordingOf(p);
+  if (rec) rec.showing = true;
+}
 async function pauseAfter(p, cmd) {
   const rec = p && !p.isClosed() ? recordingOf(p) : null;
-  if (rec && !rec.finishing && rec.pacing.pause && ACTIONS.has(cmd)) await sleep(rec.pacing.pause);
+  if (!rec) return;
+  const show = rec.showing;
+  rec.showing = false;
+  if (!rec.finishing && rec.pacing.pause && (show || ACTIONS.has(cmd))) await sleep(rec.pacing.pause);
 }
 
 function stepsPath(file) {
@@ -692,4 +703,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, recordingOf, beforeRecordingEnds, stepsOf, pauseAfter, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };
+module.exports = { commands, recordingOf, beforeRecordingEnds, stepsOf, pauseAfter, pauseToShow, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };

package/lib/send.js

@@ -98,8 +98,9 @@ function commandLine(words) {
   // words are joined as they are.
   const { SELECTOR_FIRST } = require('./syntax');
   // So does playwright-cli's storage key (localstorage-set "my key" v).
-  // And record's file, which may have spaces in it.
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0]));
+  // 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]));
   // 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.

package/lib/tabs.js

@@ -164,11 +164,13 @@ const commands = {
       ensureDialogHandler(p);
       await keepDrawing(p);
     };
-    const byUrl = part => {
+    // Opened by this client, with tab new: the prompt's and nameless senders' are theirs together.
+    const mine = p => 'opened' in tabState(p) && tabState(p).owner === state.client;
+    const byUrl = (part, closing = false) => {
       const matches = all.filter(p => p.url().includes(part));
       if (matches.length === 1) return matches[0];
       if (!matches.length) throw new Error(`No tab URL contains "${part}"`);
-      throw new Error(`${matches.length} tabs match "${part}"; use a longer part:\n${matches.map(p => `  ${p.url()}`).join('\n')}`);
+      throw new Error(`${matches.length} tabs match "${part}"; use a longer part, or tab <index> from tab's listing${closing ? ', then tab close' : ''}:\n${matches.map(p => `  ${p.url()}${mine(p) ? '  (opened by you)' : ''}`).join('\n')}`);
     };
     if (/^\d+$/.test(subcommand)) {
       if (parts.length) throw new Error(usage);
@@ -196,7 +198,11 @@ const commands = {
       return listTabs();
     }
     if (subcommand === 'close') {
-      const target = parts.length ? byUrl(parts.join(' ')) : state.page;
+      const part = parts.join(' ');
+      const matches = part ? all.filter(p => p.url().includes(part)) : [];
+      // Of several, the one tab you opened is the one to close: the others may be someone else's.
+      const yours = matches.length > 1 && matches.filter(mine).length === 1 ? matches.find(mine) : null;
+      const target = yours || (part ? byUrl(part, true) : state.page);
       if (!target || target.isClosed() || !all.includes(target)) throw new Error('Selected tab is unavailable. Run tab again.');
       if (all.length <= 1) throw new Error('Refusing to close the last tab');
       const url = target.url();
@@ -208,7 +214,7 @@ const commands = {
         state.page = back && !back.isClosed() && 'opened' in tabState(back) ? back : null;
         state.previousPage = null;
       }
-      out.log(`Closed ${url}${wasSelected && !state.page ? '; no tab is selected now' : ''}`);
+      out.log(`Closed ${url}${yours ? `, the one you opened; ${matches.length - 1} other ${matches.length === 2 ? 'tab matches' : 'tabs match'} "${part}"` : ''}${wasSelected && !state.page ? '; no tab is selected now' : ''}`);
       if (recording) out.log(await endedByTabClose(recording));
       return listTabs();
     }

package/lib/watch.js

@@ -22,6 +22,8 @@ const PW_SETTINGS = ['PW_CDP_URL', 'PW_CHROME', 'PW_CLIENT', 'PW_ENDPOINT', 'PW_
   'PW_SOCKET', 'PW_START_URL', 'PW_TEST_CHROME', 'PW_TMUX_SESSION'];
 const PAGE_ACTIONS = new Set(['click', 'check', 'uncheck', 'select', 'fill', 'type', 'press', 'submit']);
 const WATCH_BINDING = '__pwReplWatch';
+// Seconds a saved step waits for its element after the app's own routing (watch save).
+const ROUTE_WAIT = 30;
 
 // Runs in the page. Describes elements the way snapshot does: role and name.
 const WATCH_SCRIPT = `(() => {
@@ -62,6 +64,30 @@ const WATCH_SCRIPT = `(() => {
       || el.getAttribute('placeholder') || el.getAttribute('title') || (typedInto(el) || hasEditable(el) ? '' : el.innerText));
   };
   const describe = el => { const name = nameOf(el); return roleOf(el) + (name ? ' ' + JSON.stringify(name) : ''); };
+  // Which of the elements described alike this one is: under its nearest heading, and n of N where that
+  // does not settle it (cards that repeat a heading). Empty when nothing else is described as it is.
+  const HEADING = 'h1,h2,h3,h4,h5,h6,[role=heading]';
+  const headingOf = el => {
+    for (let at = el.parentElement; at; at = at.parentElement) {
+      const heading = at.querySelector(HEADING);
+      if (heading && !heading.contains(el)) return clip(heading.innerText);
+    }
+    return '';
+  };
+  // Run before the page's own handlers, so only elements of its kind are compared: a page can have
+  // thousands of divs. One with no name is alike every other of its role, and n of N says nothing.
+  const contextOf = el => {
+    if (el.getRootNode() !== document || !nameOf(el)) return '';
+    const role = roleOf(el);
+    const me = describe(el);
+    const kind = el.hasAttribute('role') ? '[role]' : el.localName + ',[role]';
+    const alike = [...document.querySelectorAll(kind)].filter(other => other === el || (roleOf(other) === role && describe(other) === me));
+    if (alike.length < 2) return '';
+    const heading = headingOf(el);
+    const peers = heading ? alike.filter(other => headingOf(other) === heading) : alike;
+    const which = peers.length > 1 ? (peers.indexOf(el) + 1) + ' of ' + peers.length : '';
+    return [heading && 'under ' + JSON.stringify(heading), which].filter(Boolean).join(', ');
+  };
   // A field that was a password field while watched stays one when a "show password" button makes it
   // text; and some take secrets under another type. Their values never leave the page.
   const secrets = new WeakSet();
@@ -81,13 +107,96 @@ const WATCH_SCRIPT = `(() => {
   };
   const textOf = el => (el.textContent || '').replace(/\\s+/g, ' ').trim();
   const cssString = text => '"' + text.replace(/\\\\/g, '\\\\\\\\').replace(/"/g, '\\\\"') + '"';
+  // An id a framework made up (radix-vue-combobox-option-v-0-17-4, :r1:), which another render or build
+  // numbers differently: used only when nothing else finds the element.
+  const madeUpId = id => /:|\\d+\\D+\\d|\\d{3}/.test(id) || /^(?:radix|reka|headlessui|mui|react-aria|downshift)-/.test(id);
+  // Roles as Playwright's role selector reads them, for the elements a step acts on.
+  const WIDGET_ROLES = new Set(['button', 'checkbox', 'combobox', 'link', 'listbox', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'radio', 'searchbox', 'slider', 'spinbutton', 'switch', 'tab', 'textbox', 'treeitem']);
+  const INPUT_ROLES = { checkbox: 'checkbox', radio: 'radio', button: 'button', submit: 'button', reset: 'button', image: 'button', file: 'button', range: 'slider', number: 'spinbutton', search: 'searchbox', hidden: null };
+  const widgetRole = el => {
+    if (el.hasAttribute('role')) {
+      const role = el.getAttribute('role').trim().split(/\\s+/)[0];
+      return WIDGET_ROLES.has(role) ? role : null;
+    }
+    const tag = el.localName;
+    if ((tag === 'a' || tag === 'area') && el.hasAttribute('href')) return 'link';
+    if (tag === 'button') return 'button';
+    if (tag === 'textarea') return 'textbox';
+    if (tag === 'option') return 'option';
+    if (tag === 'select') return el.multiple || el.size > 1 ? 'listbox' : 'combobox';
+    if (tag !== 'input') return null;
+    if (el.list && /^(?:email|search|tel|text|url)$/.test(el.type)) return 'combobox';
+    return el.type in INPUT_ROLES ? INPUT_ROLES[el.type] : 'textbox';
+  };
+  // Pieces of its accessible name that Playwright's is sure to hold, longest first: an attribute that
+  // names it, or the text nodes it is named from (its label's, or its own), one at a time. Put together,
+  // they could be spaced as Playwright's are not: it sets a child apart by spaces by how it is laid out.
+  const plain = text => (text || '').replace(/\\s+/g, ' ').trim();
+  const NAMED_BY_TEXT = new Set(['button', 'checkbox', 'link', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'radio', 'switch', 'tab', 'treeitem']);
+  // Text Playwright leaves out of a name, or names another way: hidden text, and text in an element
+  // named by an attribute, in a control, in an SVG or in the element a label names.
+  const textPieces = (root, el, hiddenToo) => {
+    const pieces = [];
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      const text = plain(node.data);
+      let at = node.parentElement;
+      if (!text || !at || (!hiddenToo && !at.checkVisibility({ visibilityProperty: true }))) continue;
+      for (; at && at !== root; at = at.parentElement) if (at === el || at.matches('[aria-hidden=true],[aria-label],[aria-labelledby],select,textarea,button,svg')) break;
+      if (at === root) pieces.push(text);
+    }
+    return pieces;
+  };
+  const namePieces = el => {
+    // Ids that name nothing are passed over, as Playwright passes them over.
+    const labelledBy = (el.getAttribute('aria-labelledby') || '').split(/\\s+/).map(id => id && document.getElementById(id)).filter(Boolean);
+    if (labelledBy.length) return labelledBy.flatMap(part => textPieces(part, null, true));
+    if (plain(el.getAttribute('aria-label'))) return [plain(el.getAttribute('aria-label'))];
+    if (el.labels && el.labels.length) return [...el.labels].flatMap(label => textPieces(label, el, false));
+    const role = widgetRole(el);
+    const own = NAMED_BY_TEXT.has(role) ? textPieces(el, null, false) : [];
+    if (own.length) return own;
+    // An input's title and placeholder: Playwright takes one or the other, so only one there is.
+    const named = [el.getAttribute('title'), typedInto(el) ? el.getAttribute('placeholder') : null].map(plain).filter(Boolean);
+    return named.length === 1 ? named : [];
+  };
+  // Everything an element's name could hold, without spaces, for whether another element's name could
+  // hold a piece of this one's: more than it does, never less.
+  const squash = text => (text || '').replace(/\\s+/g, '').toLowerCase();
+  // An input that is a button is named by its value (Submit or Reset without one), or as an image its alt.
+  const inputButtonName = el => el.localName === 'input' && /^(?:submit|button|reset|image)$/.test(el.type)
+    ? [el.value, { submit: 'Submit', reset: 'Reset' }[el.type], el.getAttribute('alt')].join(' ') : '';
+  const nameHay = el => squash([el.getAttribute('aria-label'), el.getAttribute('title'), el.getAttribute('placeholder'), el.textContent, inputButtonName(el),
+    ...(el.getAttribute('aria-labelledby') || '').split(/\\s+/).map(id => id && document.getElementById(id)?.textContent),
+    ...[...(el.labels || [])].map(label => label.textContent),
+    ...[...el.querySelectorAll('[alt],[aria-label],[title]')].map(n => [n.getAttribute('alt'), n.getAttribute('aria-label'), n.getAttribute('title')].join(' '))].join(' '));
+  // role=<role>[name*="<piece>"], with the first piece of its name that finds it and no other: *= finds
+  // the piece anywhere in an element's name, in any case, so every element of the role whose name could
+  // hold it is counted.
+  const roleSelector = el => {
+    const role = widgetRole(el);
+    if (!role) return null;
+    // A long piece by its first words, which Playwright still finds. A count or a price alone would not
+    // find it again.
+    const pieces = [...new Set(namePieces(el).filter(piece => /\\p{L}/u.test(piece)).map(piece => piece.length <= 60 ? piece : piece.slice(0, 61).replace(/\\s+\\S*$/, '')))];
+    pieces.sort((a, b) => b.length - a.length);
+    const others = [];
+    for (const r of shadowRoots(document)) for (const other of r.querySelectorAll('*')) if (other !== el && widgetRole(other) === role) others.push(nameHay(other));
+    const piece = pieces.slice(0, 5).find(piece => !others.some(hay => hay.includes(squash(piece))));
+    return piece ? 'role=' + role + '[name*=' + cssString(piece) + ']' : null;
+  };
   const selectorIn = (el, scope) => {
     const roots = shadowRoots(scope);
     const count = sel => { let n = 0; for (const r of roots) n += r.querySelectorAll(sel).length; return n; };
+    const ownId = at => at.id && count('#' + CSS.escape(at.id)) === 1;
     const tag = el.localName;
-    if (el.id && count('#' + CSS.escape(el.id)) === 1) return '#' + CSS.escape(el.id);
     const testid = el.getAttribute('data-testid');
     if (testid && count('[data-testid=' + cssString(testid) + ']') === 1) return '[data-testid=' + cssString(testid) + ']';
+    // Before an id, as Playwright's own locators are: an id can be a counter's that looks written by hand.
+    // Playwright's role selector goes into shadow roots, but takes no CSS before it: in the document only.
+    const byRole = scope === document && roleSelector(el);
+    if (byRole) return byRole;
+    if (ownId(el) && !madeUpId(el.id)) return '#' + CSS.escape(el.id);
     const name = el.getAttribute('name');
     if (name && /^(?:input|select|textarea)$/.test(tag) && count(tag + '[name=' + cssString(name) + ']') === 1) return tag + '[name=' + cssString(name) + ']';
     const text = textOf(el);
@@ -96,10 +205,11 @@ const WATCH_SCRIPT = `(() => {
       for (const r of roots) for (const other of r.querySelectorAll(tag)) if (textOf(other) === text) same++;
       if (same === 1) return tag + ':text-is(' + cssString(text) + ')';
     }
+    if (ownId(el)) return '#' + CSS.escape(el.id);
     // Its place: the path down from the nearest ancestor with an id of its own, or from the top.
     const steps = [];
     for (let at = el; at && at.parentNode; at = at.parentNode) {
-      if (at !== el && at.id && count('#' + CSS.escape(at.id)) === 1) { steps.unshift('#' + CSS.escape(at.id)); break; }
+      if (at !== el && ownId(at) && !madeUpId(at.id)) { steps.unshift('#' + CSS.escape(at.id)); break; }
       if (at.localName === 'body') { steps.unshift('body'); break; }
       const same = [...at.parentNode.children].filter(c => c.localName === at.localName);
       steps.unshift(same.length > 1 ? at.localName + ':nth-of-type(' + (same.indexOf(at) + 1) + ')' : at.localName);
@@ -134,6 +244,8 @@ const WATCH_SCRIPT = `(() => {
     if (window !== window.top) return null;
     const parts = partsOf(el);
     if (!parts) return null;
+    // Counted as Playwright matches it already, which el.matches cannot.
+    if (parts[0].startsWith('role=')) return parts[0];
     let n = 0;
     for (const r of shadowRoots(document)) for (const other of r.querySelectorAll('*')) if (matchesParts(other, parts) && ++n > 1) return null;
     return n === 1 ? parts.join(' ') : null;
@@ -145,21 +257,34 @@ const WATCH_SCRIPT = `(() => {
     if (typeof window.__pwReplWatch !== 'function') return;
     let selector = null;
     try { selector = el ? selectorOf(el) : null; } catch {}
+    let context = '';
+    try { context = el ? contextOf(el) : ''; } catch {}
     const typed = (action === 'type' || action === 'fill') && el;
     const secret = typed && isSecret(el);
     const option = action === 'select' ? el.value : null;
-    window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', extra: extra || '', since: since || 0, selector, secret, value: typed && !secret ? valueOf(el) : null, option }));
+    window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', context, extra: extra || '', since: since || 0, selector, secret, value: typed && !secret ? valueOf(el) : null, option }));
   };
   // The element itself, not its component's host, when it is inside an open shadow root.
   const targetOf = e => (e.composedPath && e.composedPath()[0]) || e.target;
   // Enter in a form's field submits it with a click on its submit button, which is the Enter's doing:
   // recorded too, it would submit the form again when the steps run again.
   let enteredForm = null;
+  let labelled = null;
   document.addEventListener('click', e => {
     const t = targetOf(e);
     const el = t.closest ? (t.closest(INTERACTIVE) || t) : t;
     if (!el.matches || el.matches('input[type=checkbox],input[type=radio],select') || isPassword(el)) return;
     if (e.detail === 0 && enteredForm && el.form === enteredForm) return;
+    // A click on a label is passed on to its control as a click of its own, in the same task; one of them
+    // is recorded, or a replay would toggle a checkbox twice. A label that holds its control passes it on
+    // inside what was clicked: the control's click is recorded (or the check its change records), and
+    // found by its role. A label's for= can name a control anywhere, even another card's where ids
+    // repeat: the label is what was clicked, and the passed-on click and its change are left out.
+    if (el.localName === 'label' && el.control) {
+      if (el.contains(el.control)) return;
+      labelled = el.control;
+      setTimeout(() => { labelled = null; });
+    } else if (el === labelled) return;
     send('click', el);
   }, true);
   // Typing is recorded once it pauses, not on change, so a typeahead's requests
@@ -204,7 +329,7 @@ const WATCH_SCRIPT = `(() => {
   }, true);
   document.addEventListener('change', e => {
     const el = targetOf(e);
-    if (!el.matches) return;
+    if (!el.matches || el === labelled) return;
     if (el.matches('input[type=checkbox],input[type=radio]')) return send(el.checked ? 'check' : 'uncheck', el);
     if (el.matches('select')) return send('select', el, JSON.stringify(clip(el.selectedOptions[0]?.text)));
     if (pending.has(el)) { flushTyping(el); typed.delete(el); return; }
@@ -369,7 +494,7 @@ async function startWatching(p, changes = false, live = false, values = true) {
       if (!created.on) return;
       const previous = created.events[created.events.length - 1];
       const t = Math.max(Date.now() - Math.min(Math.max(Number(since) || 0, 0), TYPING_BACKDATE_MAX), previous ? previous.t : 0);
-      const step = { seq: created.nextSeq++, t, action, target: clipText(target), extra: clipText(extra), selector: more.selector || null, secret: !!more.secret, url: more.url };
+      const step = { seq: created.nextSeq++, t, action, target: clipText(target), context: clipText(more.context || ''), extra: clipText(extra), selector: more.selector || null, secret: !!more.secret, url: more.url, loaded: !!more.loaded };
       if (typeof more.option === 'string') step.option = more.option;
       if (typeof more.value === 'string' && created.values) step.value = more.value;
       keep(created.events, step);
@@ -392,7 +517,7 @@ async function startWatching(p, changes = false, live = false, values = true) {
         try { event = JSON.parse(payload); } catch { return; }
         if (event && PAGE_ACTIONS.has(event.action)) {
           binding.record(event.action, String(event.target || ''), String(event.extra || ''), event.since,
-            { selector: typeof event.selector === 'string' ? event.selector : null, secret: !!event.secret, value: event.value, option: event.option });
+            { selector: typeof event.selector === 'string' ? event.selector : null, secret: !!event.secret, value: event.value, option: event.option, context: String(event.context || '') });
         }
       });
       // Calls are reported only to a session with Runtime on.
@@ -402,7 +527,15 @@ async function startWatching(p, changes = false, live = false, values = true) {
     }
     tabState(p).watchBinding.record = record;
     await p.addInitScript(WATCH_SCRIPT);
-    p.on('framenavigated', frame => { if (frame === p.mainFrame()) record('navigate', frame.url(), '', 0, { url: frame.url() }); });
+    // Whether it loaded a document is read now, while the request log still has the request: a page's
+    // document is requested before it commits, after the step before it.
+    p.on('framenavigated', frame => {
+      if (frame !== p.mainFrame()) return;
+      const url = frame.url();
+      const since = created.events[created.events.length - 1]?.t ?? 0;
+      const loaded = (tabState(p).log || []).some(r => r.navigation && r.url === url && r.t >= since);
+      record('navigate', url, '', 0, { url, loaded });
+    });
     // Only now: a failed first attempt must leave nothing half set up to retry against.
     tabState(p).watch = created;
     watch = created;
@@ -520,7 +653,7 @@ function requestsByStep(watch, p = state.page) {
 
 function stepLines(e, caused, note = '', withChanges = true) {
   const typed = e.secret ? ' (a password: not recorded)' : typeof e.value === 'string' ? ` ${JSON.stringify(clipText(e.value))}` : '';
-  const lines = [`${clock(e.t)} ${e.action} ${e.target}${typed}${e.extra ? ` ${e.extra}` : ''}${note}`];
+  const lines = [`${clock(e.t)} ${e.action} ${e.target}${e.context ? ` (${e.context})` : ''}${typed}${e.extra ? ` ${e.extra}` : ''}${note}`];
   const indent = ' '.repeat(clock(e.t).length + 1);
   for (const r of caused.slice(0, WATCH_REQUESTS_SHOWN)) lines.push(`${indent}#${r.id} ${r.method} ${r.status} ${r.url}`);
   if (caused.length > WATCH_REQUESTS_SHOWN) lines.push(`${indent}… ${caused.length - WATCH_REQUESTS_SHOWN} more (requests)`);
@@ -559,7 +692,6 @@ function showWatch(watch, all) {
 function savedCommands(watch, p) {
   const sel = text => (text.includes("'") ? `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` : `'${text}'`);
   const value = text => `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-  const documents = (tabState(p).log || []).filter(r => r.navigation);
   const events = watch.events.slice();
   const first = events[0]?.action === 'navigate' ? events.shift().url : watch.startUrl;
   const lines = [`goto ${first}`];
@@ -577,20 +709,32 @@ function savedCommands(watch, p) {
     return name;
   };
   const comment = (e, why) => { skipped += 1; lines[lines.length - 1] += `: ${why}`; };
+  // A field changed again before anything else was done (a date picker stepping through days, typing
+  // that paused) is filled once, with its last value.
+  const changedAgain = i => {
+    const e = events[i];
+    if ((e.action !== 'type' && e.action !== 'fill') || !e.selector) return false;
+    const next = events.slice(i + 1).find(n => !(n.action === 'navigate' && !n.loaded));
+    return !!next && (next.action === 'type' || next.action === 'fill') && next.selector === e.selector;
+  };
+  // After the app's own routing, the next step waits for its element: the new view can take longer to
+  // draw than an action waits.
+  let routed = false;
   for (const [i, e] of events.entries()) {
     const previous = events[i - 1];
     if (e.action === 'navigate') {
-      // The page an action led to: waited for if it loaded a document, not if the app only changed its URL.
-      if (previous && previous.action !== 'navigate') {
-        const loaded = documents.some(r => r.url === e.url && r.t >= previous.t && r.t <= e.t + 1000);
-        lines.push(loaded ? `wait load` : `# the app went to ${e.url} without loading a page`);
-      } else {
-        lines.push(`goto ${e.url}`);
-      }
+      // One that loaded no document was the app's own routing (the history API), which the step before
+      // it does again when the steps run: never a goto, or the steps would go there twice. One that
+      // loaded a document is waited for after an action, and gone to otherwise.
+      routed = !e.loaded;
+      if (!e.loaded) lines.push(`# the app went to ${e.url} without loading a page`);
+      else lines.push(previous && previous.action !== 'navigate' ? 'wait load' : `goto ${e.url}`);
       continue;
     }
-    if (e.action === 'submit') continue;
-    lines.push(`# ${e.action} ${e.target}${e.extra ? ` ${e.extra}` : ''}`);
+    if (e.action === 'submit' || changedAgain(i)) continue;
+    if (routed && e.selector) lines.push(`wait ${sel(e.selector)} ${ROUTE_WAIT}`);
+    routed = false;
+    lines.push(`# ${e.action} ${e.target}${e.context ? ` (${e.context})` : ''}${e.extra ? ` ${e.extra}` : ''}`);
     if (!e.selector && !(e.action === 'press' && e.target === 'page')) { comment(e, 'no selector finds it alone: it is in a frame or a closed shadow root, or its place matches others too'); continue; }
     if (e.action === 'click' || e.action === 'check' || e.action === 'uncheck') lines.push(`${e.action} ${sel(e.selector)}`);
     else if (e.action === 'select' && typeof e.option !== 'string') comment(e, 'the option was not recorded');

package/package.json

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

package/skill/SKILL.md

@@ -109,8 +109,8 @@ pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
 
 Always send commands with `pw-repl send`; don't type into the pane yourself, except `quit` at the prompt
 of a REPL of your own, which `send` refuses. The words after `send` are the command. For `fill`, `type`,
-`select`, `press` and `upload`, a word quoted in your shell stays one word
-(`pw-repl send fill "text=Your name" Ada`); other commands get the words as they are, joined by
+`select`, `press`, `upload` and `wait`, a word quoted in your shell stays one word
+(`pw-repl send fill "text=Your name" Ada`, `pw-repl send wait text "Showing 1"`); other commands get the words as they are, joined by
 spaces (`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the
 whole line, spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL was
 started:
@@ -224,6 +224,10 @@ pw-repl send -c <name> close                        # your modes off; tab close
   `tab <index>`. Closing a tab the REPL opened goes back to the tab before it, if the REPL opened that
   one too; otherwise no tab is selected. Tab numbers change when tabs open or close; `tab <url-part>`
   and `tab close <url-part>` pick a tab by its URL and refuse if it is ambiguous.
+- A login form in the user's browser may be filled by its password manager, which can keep what it
+  filled from the page until someone clicks in the field or picks from its dropdown: a field that looks
+  filled can read as empty. Check a password field by its length (`eval` on its `value.length`), never
+  read or print it; if it stays empty, ask the user to fill it.
 - You can answer any dialog yourself, one you opened included: `dialog` shows it, and `dialog accept` or
   `dialog dismiss` answers it. Nothing answers one on its own, and while one is open its page and the
   commands that read it wait. One answered in the browser is gone from `dialog` too.