pw-repl 0.10.0 → 0.11.1

package/AGENTS.md

@@ -14,7 +14,8 @@ If you hit a limitation or write a workaround, consider adding the capability to
   `READ_ONLY` or `INSPECTION`, and one that takes fixed words in `complete` (`lib/commands.js`).
 - The modules, one per facility, each with its commands: `lib/tabs.js` (tabs, navigating),
   `lib/elements.js` (choosing a match; the interact and mouse commands; highlight), `lib/cursor.js` (the pointer
-  drawn over the page, which the element and mouse commands glide first), `lib/inspect.js` (reading the
+  drawn over the page, which the element and mouse commands glide first), `lib/toast.js` (a line of text
+  over the page), `lib/overlay.js` (the element the cursor and toast are drawn in, one layer each), `lib/inspect.js` (reading the
   page, screenshots, eval, CDP, waits), `lib/watch.js`, `lib/requestlog.js` (requests, bodies, console),
   `lib/routes.js`, `lib/network.js`, `lib/emulation.js` (and viewport), `lib/capture.js`, `lib/record.js`
   (video, through ffmpeg, and the steps file saved with it), `lib/dialogs.js` and `lib/modes.js`. Beneath them, `lib/tabstate.js` is the one record kept per tab, `lib/cdp.js` the CDP
@@ -24,7 +25,7 @@ If you hit a limitation or write a workaround, consider adding the capability to
   runs commands one at a time (`quit` and `dialog` skip its queue); `lib/server.js` is the command
   server; `lib/send.js` and `lib/client.js` are `send` and `where`; `lib/background.js` is
   `serve --background`, `attach` and `stop`; `lib/launch.js` is `--launch`; `lib/syntax.js` is how a
-  command line's words are read, shared with `send`; `lib/cli-names.js` maps playwright-cli's command
+  command line's words are read, shared with `send`, and its `{{ PW_NAME }}` variables; `lib/cli-names.js` maps playwright-cli's command
   names to these; `lib/state.js` holds the session state, with each client's selected tab;
   `lib/output.js` routes all output so the server can return it; `lib/skill.js` stamps the skill
   `pw-repl skill` prints, and gives `where` its hash.

package/README.md

@@ -1,7 +1,7 @@
 # playwright-repl
 
 A command REPL for a Chromium you are already using, shared by you and your agents. It connects over CDP
-through Playwright; people click in the browser and type at the prompt, agents send the same commands,
+through Playwright; users click in the browser and type at the prompt, agents send the same commands,
 and every command shows in the REPL, so each sees what the other does.
 
 ## Why use it
@@ -13,7 +13,8 @@ For working on a web page together with an agent, in the browser you already use
 - **One session, seen by everyone.** You and any number of agents drive the same browser, each with a
   selected tab of its own, and every command shows in the REPL, whoever sent it.
 - **What you did, for an agent to read.** `watch` records each step you take in a tab, with the requests
-  it caused, so you can reproduce a bug by hand and the agent can see exactly what happened.
+  it caused, so you can reproduce a bug by hand and the agent can see exactly what happened; `watch save`
+  keeps the steps as a file of commands that runs them again.
 - **Breaking things on purpose.** Fake, patch, delay or fail responses, cut or slow the network, emulate a
   phone, a locale or a timezone, all per tab, so your other tabs are left alone.
 
@@ -87,7 +88,7 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 
 | I want to…                           | Commands                                                                              |
 | ------------------------------------ | ------------------------------------------------------------------------------------- |
-| see where I am                       | `tab`, `info`                                                                         |
+| see where I am                       | `tab` (it marks the tab you are looking at `(in front)`), `info`                      |
 | see what is on the page              | `snapshot`, `screenshot`                                                              |
 | do something on it                   | `click`, `fill`, `press`                                                              |
 | wait for a page or element           | `wait load`, `wait <selector>`, `wait <selector> --gone`                              |
@@ -97,9 +98,11 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | see console messages and errors      | `console`                                                                             |
 | show an agent what I do              | `watch on`, click around in the browser, then `watch`                                 |
 | see each step as I click             | `watch on --live`                                                                     |
+| replay what I clicked through        | `watch on`, click around, `watch save flow.txt`, then `pw-repl send --file flow.txt`  |
 | record requests and console together | `capture on`, then `capture off`                                                      |
 | record a video of the page           | `record on`, then `record off` (`help video` for a take with a pointer)               |
 | show a pointer where the agent acts  | `cursor on`, then `cursor off` (in screenshots and videos)                            |
+| say what is happening on screen      | `toast <text>`, then `toast off` (`--duration=3s` hides it by itself)                 |
 | point something out on the page      | `highlight <ref>`: a box, unlabelled unless `--labels on`; `highlight off` hides it   |
 | break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `route <glob> abort`, `network off` |
 | change or slow an API response       | `route <glob> patch <json>`, `route <glob> delay <secs>`                              |
@@ -110,29 +113,31 @@ Everything else is in `help <topic>`; `help <command>` has usage and caveats.
 
 ### Modes
 
-`watch`, `capture`, `route`, `network off` or `slow`, `emulate`, `viewport`, `record`, `highlight` and `cursor`
-stay on until you turn them off: `watch on|off`, `capture on|off`, `route ...|route off`, `network off|slow|on`,
-`emulate ...|emulate off`, `viewport <WxH>|viewport off`, `record on|off`, `highlight <selector>|highlight off`
-(and `highlight --labels on|off`), `cursor on|off`.
+`watch`, `capture`, `route`, `network off` or `slow`, `emulate`, `viewport`, `record`, `highlight`, `cursor`
+and `toast` stay on until you turn them off: `watch on|off`, `capture on|off`, `route ...|route off`,
+`network off|slow|on`, `emulate ...|emulate off`, `viewport <WxH>|viewport off`, `record on|off`,
+`highlight <selector>|highlight off` (and `highlight --labels on|off`), `cursor on|off`,
+`toast <text>|toast off`.
 While any are on in the selected tab, the prompt shows them: `(watch network:off routes:2) pw>`. `modes`
 lists them for every tab, and `modes off` turns them all off.
 
-`tab`, `watch`, `capture`, `route`, `network`, `emulate`, `viewport`, `record`, `highlight`, `cursor` and `modes` on
-their own show their state and what you can run next.
+`tab`, `watch`, `capture`, `route`, `network`, `emulate`, `viewport`, `record`, `highlight`, `cursor`, `toast`
+and `modes` on their own show their state and what you can run next.
 
 ## How it differs from playwright-cli
 
 [playwright-cli](https://github.com/microsoft/playwright-cli) is Microsoft's command line for agents. It
-gives each agent a browser session of its own; pw-repl shares one browser between a person and agents.
+gives each agent a browser session of its own; pw-repl shares one browser between users and agents.
 Its command names and most of their options work here too (`help playwright-cli` lists them), and where
 pw-repl differs, it is mostly because someone else may be using the browser:
 
 - `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
 - Routes, network and emulation apply to one tab, not the whole browser.
-- File pickers are not caught, since they may be the person's: `upload` names the input instead.
-- There is no snapshot after every command, since a person reads the REPL too; `snapshot` shows one.
+- File pickers are not caught, since they may be the user's: `upload` names the input instead.
+- There is no snapshot after every command, since the user reads the REPL too; `snapshot` shows one.
 - Instead of `-s=<session>`, an agent is a client of its own (`send -c <name>`).
-- `watch` records what a person does as steps with their requests, not as generated code.
+- `watch` records what the user does as steps with their requests, and `watch save` writes them as
+  pw-repl commands to run again, not as Playwright code.
 - `highlight` draws its box without Playwright's locator label, which covers what is below it and puts
   selectors in screenshots and videos; `highlight --labels on` shows it.
 
@@ -146,7 +151,7 @@ agent acts; for the shared browser as you see it, use a screen recorder (`ffmpeg
 ### A skill for agents
 
 `pw-repl skill` prints an agent skill (`SKILL.md`) that teaches an agent to use the REPL: how to start
-it, send commands, and share the browser with a person. Save it as `pw-repl/SKILL.md` in the folder
+it, send commands, and share the browser with the user. Save it as `pw-repl/SKILL.md` in the folder
 your agent reads skills from:
 
 ```bash
@@ -174,6 +179,14 @@ Several agents can share one REPL: `pw-repl send -c <name>` (or `PW_CLIENT=<name
 selected tab of its own, shown in the pane as `[server:<name>]`. `modes` says which client turned each mode on,
 and `modes off --mine` turns off only the sender's own.
 
+A password can be typed as a variable: `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}"`,
+or the same line in a file run with `send --file`, as `watch save` writes it. `send` takes the value of
+`{{ PW_NAME }}` from its own environment and passes it along with the command; the REPL puts it in only as
+it runs the command, so the file, and the command as the pane, the log and the prompt's history show it,
+never hold it. Output that reads it back can: `snapshot`, `html` and `attrs` hide a password field's value,
+but `eval` reading the field, a field a Show password button made plain text (`help snapshot`), or page
+text that repeats it do not. Only `PW_` names are variables (`pw-repl --help` has the rest).
+
 ### The HTTP protocol
 
 With `pw-repl serve`, the server speaks HTTP with JSON, for clients of your own:
@@ -183,11 +196,12 @@ curl --unix-socket /tmp/playwright-repl.sock -H 'Content-Type: application/json'
   -d '{"command": "info"}' http://localhost/run
 ```
 
-It returns `{"status": "ok" | "error", "output": "..."}`, plus `"unconfirmed": true` when the command may or
-may not have done what it was sent to do (it timed out, or the REPL quit while it ran and it was not
-read-only). While the REPL starts, `/run` answers 503 with `"starting": true`: retry. `GET /health` says
-`"status": "starting"` until it serves, then `"ok"`. `pw-repl serve <port>` serves TCP on 127.0.0.1
-instead; other addresses are refused.
+The body may also have `"client": "<name>"`, and `"vars": {"PW_NAME": "<value>"}` with the values of the
+`{{ PW_NAME }}` variables in the command, one line each (else 400). It returns `{"status": "ok" | "error", "output": "..."}`, plus
+`"unconfirmed": true` when the command may or may not have done what it was sent to do (it timed out, or
+the REPL quit while it ran and it was not read-only). While the REPL starts, `/run` answers 503 with
+`"starting": true`: retry. `GET /health` says `"status": "starting"` until it serves, then `"ok"`.
+`pw-repl serve <port>` serves TCP on 127.0.0.1 instead; other addresses are refused.
 
 ## Tests
 

package/bin/pw-repl.js

@@ -17,7 +17,7 @@ const USAGE = `Usage:
   pw-repl stop [-e endpoint]
       stop a background REPL, and say what became of each recording it ended
 
-  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] <command...> | --file <file>
+  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] [--no-vars] <command...> | --file <file>
       run one command in a running REPL and print its output; --file runs a file of them, one per line
 
   pw-repl where [-e endpoint | -s session]
@@ -45,6 +45,17 @@ folder, as on send's command line, and # comments and blank lines skipped. It st
 command that fails, saying its line, with its exit status. -t is each command's own limit. Other
 clients' commands can run between its lines, on their own tabs.
 
+A {{ PW_NAME }} in a command, or in a line of the file, is a variable: send takes its value from its own
+environment (PW_NAME) and passes it along with the command, not in it, e.g. a password kept out of the
+file and out of the command as the REPL logs it. In a file: fill '#password' "{{ PW_PASSWORD }}",
+run with PW_PASSWORD=... pw-repl send --file login.txt; or one command: PW_PASSWORD=... pw-repl send
+fill '#password' "{{ PW_PASSWORD }}". Only names starting PW_ are variables: any other {{ ... }}, as in a
+page's template text, is sent as written. In a file, put it in double quotes: there its value is
+escaped as they read it (in single quotes, which escape nothing, a value with a ' is refused). The REPL
+puts it in only as it runs the command, and its pane and log show the command as written. A variable that
+is not set stops the command, or the file at that line, before it is sent. --no-vars sends
+{{ PW_NAME }} as it is. Variables need the command server (pw-repl serve), not the tmux pane.
+
 The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
 
 --launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
@@ -87,6 +98,7 @@ function parseSendArgs(args, allowCommand) {
       options.file = require('path').resolve(args[++i]);
       continue;
     }
+    if (arg === '--no-vars') { options.noVars = true; continue; }
     if (arg === '-e' || arg === '-s' || arg === '-c' || arg === '-t') {
       const value = args[++i];
       if (value === undefined) usage();

package/lib/background.js

@@ -69,13 +69,23 @@ function claimPidFile(pidFile) {
   });
 }
 
+// Why a REPL cannot serve on an endpoint another one serves on, and what to do instead; null if none does.
+async function alreadyServing(endpoint) {
+  const name = client.describe(endpoint);
+  const another = `; to start another, give it a socket of its own: -e /tmp/<name>.sock`;
+  const background = runningPid(filesFor(endpoint).pidFile);
+  if (background) return `a background REPL is already serving on ${name} (pid ${background}): pw-repl attach uses it, pw-repl stop stops it${another}`;
+  const info = await client.healthInfo(endpoint, 2000);
+  if (!info) return null;
+  return `a REPL is already serving on ${name}${info.pid ? ` (pid ${info.pid})` : ''}, in a terminal: pw-repl send uses it, and quit at its prompt stops it${another}`;
+}
+
 async function start(options) {
   const endpoint = client.parseEndpoint(options.endpoint);
   const name = client.describe(endpoint);
   const { pidFile, logFile } = filesFor(endpoint);
-  const running = runningPid(pidFile);
-  if (running) return fail(`a background REPL is already serving on ${name} (pid ${running}); pw-repl attach uses it, pw-repl stop stops it`);
-  if (await client.health(endpoint, 2000)) return fail(`a REPL is already serving on ${name}, in a terminal; pw-repl where says more`);
+  const serving = await alreadyServing(endpoint);
+  if (serving) return fail(serving);
   // Appended to, so an earlier run's log stays; each run is marked where it starts and stops. One grown
   // past LOG_LIMIT is moved to <log>.1 first, replacing the one there.
   try { if (fs.statSync(logFile).size > LOG_LIMIT) fs.renameSync(logFile, `${logFile}.1`); } catch {}
@@ -234,4 +244,4 @@ function describeBackground(endpoint) {
   return `background: pid ${pid}${since}; log ${logFile} (pw-repl attach${e}, pw-repl stop${e})`;
 }
 
-module.exports = { filesFor, endpointFlag, markStopInLog, claimPidFile, start, stop, attach, describeBackground };
+module.exports = { alreadyServing, filesFor, endpointFlag, markStopInLog, claimPidFile, start, stop, attach, describeBackground };

package/lib/cdp.js

@@ -20,6 +20,12 @@ async function keepDrawing(p) {
   tabState(p).drawing = true;
   try {
     const session = await keptSession(p);
+    // A tab behind another draws no frames, and Playwright's actions wait for frames: told it is in
+    // front and focused, it draws, and clicks in it work. Only in tabs the REPL uses (the browser is
+    // connected without Playwright's own, which would tell every tab, the user's too), so the user's
+    // tabs say truly whether they are in front.
+    await session.send('Emulation.setFocusEmulationEnabled', { enabled: true });
+    tabState(p).focusEmulated = true;
     session.on('Page.screencastFrame', frame => session.send('Page.screencastFrameAck', { sessionId: frame.sessionId }).catch(() => {}));
     await session.send('Page.startScreencast', { format: 'jpeg', quality: 1, maxWidth: 8, maxHeight: 8, everyNthFrame: 60 });
   } catch {

package/lib/cli-names.js

@@ -91,7 +91,7 @@ for (const what of ['reduced-motion', 'forced-colors', 'contrast', 'media']) {
   NEAREST[`clear-${what}`] = 'not here yet; emulate dark|light sets the color scheme';
 }
 for (const name of ['request-headers', 'response-headers', 'request-body']) NEAREST[name] = 'not here yet; body <#> shows the response body';
-NEAREST['video-chapter'] = 'not here: record on|off records a video, without chapters';
+NEAREST['video-chapter'] = 'not here: toast <text> --duration=3s shows a title over the page instead, in the video';
 // Theirs labels each action and pauses on it; the cursor is a pointer that moves to each action instead.
 NEAREST['video-show-actions'] = 'not here; cursor on draws a pointer that moves to each action, without labels';
 NEAREST['video-hide-actions'] = 'not here; cursor off hides the pointer cursor on draws';

package/lib/client.js

@@ -61,9 +61,10 @@ async function ready(endpoint, timeoutMs) {
 // One command. Resolves to { result }, { timeout: true }, { dropped: reason }
 // (the connection closed after the command was sent, so it may have run) or
 // { unreachable: reason } (it was never sent).
-function request(endpoint, command, timeoutMs, client = null) {
+// vars: the values of the {{ PW_NAME }} variables in command, which the REPL fills in as it runs it.
+function request(endpoint, command, timeoutMs, client = null, vars = null) {
   return new Promise(resolve => {
-    const body = JSON.stringify(client ? { command, client } : { command });
+    const body = JSON.stringify({ command, ...(client ? { client } : {}), ...(vars ? { vars } : {}) });
     let connected = false;
     const req = http.request({
       ...target(endpoint),

package/lib/commands.js

@@ -7,6 +7,7 @@ const { tabState } = require('./tabstate');
 const { commands: dialogsCommands, ensureDialogHandler } = require('./dialogs');
 const { commands: elementsCommands } = require('./elements');
 const { commands: cursorCommands } = require('./cursor');
+const { commands: toastCommands } = require('./toast');
 const { commands: requestlogCommands, ensureRecentLog } = require('./requestlog');
 const { commands: routesCommands, routesFor } = require('./routes');
 const { commands: networkCommands } = require('./network');
@@ -23,6 +24,7 @@ const commands = {
   ...tabsCommands,
   ...elementsCommands,
   ...cursorCommands,
+  ...toastCommands,
   ...inspectCommands,
   ...watchCommands,
   ...requestlogCommands,
@@ -116,6 +118,7 @@ function complete(line) {
     if (command === 'capture') return match(['on', 'off']);
     if (command === 'record') return match(['on', 'off']);
     if (command === 'cursor') return match(['on', 'off']);
+    if (command === 'toast') return match(['off']);
     if (command === 'viewport') return match(['off']);
     if (command === 'route') return match(['off']);
   }

package/lib/cursor.js

@@ -7,6 +7,7 @@ const out = require('./output');
 const { tabState } = require('./tabstate');
 const { unquote, toSelector } = require('./syntax');
 const { recordingOf, stepTarget, cursorStep } = require('./record');
+const { inOverlay, keepAcrossPages, forget } = require('./overlay');
 
 // Scaled with the distance, so a short hop is quick and a long one does not drag. Slower while the tab
 // records, so a viewer can follow it.
@@ -19,37 +20,21 @@ const glideTime = (distance, recording) => {
   return Math.round(Math.min(max, Math.max(min, base + distance * perPixel)));
 };
 
-// Runs in the page. Its own 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.
-function pageCursor({ x, y, action, ms, count, fade, box, items, index }) {
-  const KEY = Symbol.for('pw-repl-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 the glide's animation.
-  const set = (el, styles, important = '') => { for (const [name, value] of Object.entries(styles)) el.style.setProperty(name, value, important); };
+// Runs in the page, as the overlay's cursor layer (lib/overlay.js).
+function pageCursor(overlay, { x, y, action, ms, count, fade, box, items, index }) {
+  const { set } = overlay;
   const place = (el, px, py) => set(el, { transform: `translate(${px}px, ${py}px)` });
-  let cursor = document[KEY];
+  let cursor = overlay.cursor;
   if (action === 'remove') {
     if (!cursor) return;
-    delete document[KEY];
-    if (!fade || !cursor.host.isConnected) { cursor.host.remove(); return; }
+    delete overlay.cursor;
+    if (!fade) { overlay.drop('cursor'); return; }
     // Waited on, as a glide is, but not past its time in a tab that draws no frames.
     const fading = cursor.arrow.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 200, fill: 'forwards' });
-    return Promise.race([fading.finished, new Promise(resolve => setTimeout(resolve, 500))]).then(() => cursor.host.remove(), () => cursor.host.remove());
+    return Promise.race([fading.finished, new Promise(resolve => setTimeout(resolve, 500))]).then(() => overlay.drop('cursor'), () => overlay.drop('cursor'));
   }
-  if (!cursor || !cursor.host.isConnected) {
-    const host = document.createElement('pw-repl-cursor');
-    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' });
+  if (!cursor || !overlay.has('cursor')) {
+    const root = overlay.layer('cursor');
     const NS = 'http://www.w3.org/2000/svg';
     const arrow = document.createElementNS(NS, 'svg');
     arrow.setAttribute('width', '20');
@@ -65,14 +50,11 @@ function pageCursor({ x, y, action, ms, count, fade, box, items, index }) {
     shape.setAttribute('stroke-linejoin', 'round');
     arrow.append(shape);
     root.append(arrow);
-    document.documentElement.append(host);
-    cursor = document[KEY] = { host, root, arrow, x, y };
+    cursor = overlay.cursor = { root, arrow, x, y };
     place(arrow, x, y);
     // Faded in when turned on; drawn again on a new page, it is there at once, as it was.
     if (fade) arrow.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 200 });
   }
-  // Shown again, so it is above a dialog the page opened since.
-  try { cursor.host.hidePopover(); cursor.host.showPopover(); } catch {}
   if (action === 'move') {
     const from = `translate(${cursor.x}px, ${cursor.y}px)`;
     const to = `translate(${x}px, ${y}px)`;
@@ -143,16 +125,6 @@ function cursorOf(p) {
   return tabState(p).cursor || null;
 }
 
-// A new document drops the cursor: it is drawn again where it was.
-function keepAcrossPages(p) {
-  if (tabState(p).cursorKept) return;
-  tabState(p).cursorKept = true;
-  p.on('domcontentloaded', () => {
-    const cursor = cursorOf(p);
-    if (cursor) p.evaluate(pageCursor, { x: cursor.x, y: cursor.y, action: 'draw' }).catch(() => {});
-  });
-}
-
 // Glides the tab's cursor to a point, if it is on, and waits for it to get there.
 async function glideTo(p, x, y) {
   const cursor = cursorOf(p);
@@ -162,7 +134,7 @@ async function glideTo(p, x, y) {
   if (ms) cursorStep(p, `(cursor from ${cursor.x} ${cursor.y})`, { x, y }, ms);
   cursor.x = x;
   cursor.y = y;
-  await p.evaluate(pageCursor, { x, y, action: 'move', ms }).catch(() => {});
+  await inOverlay(p, pageCursor, { x, y, action: 'move', ms }).catch(() => {});
 }
 
 // Whether a command should find its element first: to glide the cursor there, or, while recording, to
@@ -235,7 +207,7 @@ async function aimAt(p, target, timeout) {
 async function showClick(p, count = 1) {
   const cursor = cursorOf(p);
   if (!cursor) return;
-  await p.evaluate(pageCursor, { x: cursor.x, y: cursor.y, action: 'click', count }).catch(() => {});
+  await inOverlay(p, pageCursor, { x: cursor.x, y: cursor.y, action: 'click', count }).catch(() => {});
 }
 
 // select with the cursor on: a native select's list opens outside the page, where no recording (or
@@ -257,17 +229,17 @@ async function showSelect(p, target, value, act) {
   if (!before || before.chosen < 0 || before.chosen >= 10) return act();
   const pace = recordingOf(p) ? 1 : 0.5;
   await showClick(p);
-  const opened = await p.evaluate(pageCursor, { action: 'pickerOpen', box, items: before.items, index: before.index }).catch(() => null);
+  const opened = await inOverlay(p, pageCursor, { action: 'pickerOpen', box, items: before.items, index: before.index }).catch(() => null);
   if (!opened) return act();
   await sleep(350 * pace);
   await glideTo(p, Math.round(cursor.x), Math.round(opened.rowY + before.chosen * opened.rowHeight));
-  await p.evaluate(pageCursor, { action: 'pickerChoose', index: before.chosen }).catch(() => {});
+  await inOverlay(p, pageCursor, { action: 'pickerChoose', index: before.chosen }).catch(() => {});
   await showClick(p);
   try {
     return await act();
   } finally {
     await sleep(250 * pace);
-    await p.evaluate(pageCursor, { action: 'pickerClose' }).catch(() => {});
+    await inOverlay(p, pageCursor, { action: 'pickerClose' }).catch(() => {});
   }
 }
 
@@ -276,7 +248,8 @@ async function cursorOff(p) {
   const { x, y } = cursorOf(p);
   delete tabState(p).cursor;
   cursorStep(p, '(cursor off)', { x, y }, 0);
-  await p.evaluate(pageCursor, { action: 'remove', fade: true }).catch(() => {});
+  forget(p, 'cursor');
+  await inOverlay(p, pageCursor, { action: 'remove', fade: true }, false).catch(() => {});
   return true;
 }
 
@@ -344,10 +317,11 @@ const commands = {
       out.log(`The cursor moved to ${at.x}, ${at.y}`);
       return;
     }
-    await p.evaluate(pageCursor, { x: at.x, y: at.y, action: 'draw', fade: true });
+    await inOverlay(p, pageCursor, { x: at.x, y: at.y, action: 'draw', fade: true });
     tabState(p).cursor = { owner: state.client, x: at.x, y: at.y };
     cursorStep(p, '(cursor on)', at, 0);
-    keepAcrossPages(p);
+    // A new document drops it: it is drawn again where it was.
+    keepAcrossPages(p, 'cursor', async () => { const c = cursorOf(p); if (c) await inOverlay(p, pageCursor, { x: c.x, y: c.y, action: 'draw' }); });
     out.log(`The cursor is on, at ${at.x}, ${at.y}: commands on elements and the mouse glide it there first, and clicks show where they land; cursor off hides it`);
   },
 };

package/lib/elements.js

@@ -197,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 {
@@ -355,6 +361,24 @@ async function setLabels(p, on) {
   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>]]');
@@ -482,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 {}
@@ -511,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) {
@@ -561,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.