pw-repl 0.9.0 → 0.11.0

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

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,10 +98,12 @@ 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)                            |
-| point something out on the page      | `highlight <ref>` (`--style=<css>` to restyle it), then `highlight off`               |
+| 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>`                              |
 | slow the whole network               | `network slow`                                                                        |
@@ -110,29 +113,33 @@ 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`,
-`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 because someone else may be using the browser:
+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.
 
 For a browser of its own per agent, isolated sessions, traces, video, PDFs or generated test code,
 playwright-cli is the better fit. `record on` records a tab's page, and `cursor on` draws a pointer where the
@@ -144,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

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,16 @@ 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 the variable PW_NAME from send's environment,
+e.g. a password kept out of the file and the REPL's log. 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
+fills it in 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 +97,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;
 }
 
@@ -316,13 +289,25 @@ const commands = {
     } else if (where) {
       const target = p.locator(toSelector(unquote(where))).first();
       try {
-        await target.scrollIntoViewIfNeeded({ timeout: 5000 });
+        await target.waitFor({ state: 'visible', timeout: 5000 });
       } catch {
         throw new Error(`No element matches ${where} that can be shown (waited 5s); ${still}`);
       }
-      const box = await target.boundingBox();
+      // Only pointing: an element partly in view is pointed at where it shows, not scrolled, so that
+      // one the page cuts off still looks cut off (a bug in a video). One wholly out of view is scrolled to.
+      const view = await p.evaluate(() => ({ width: innerWidth, height: innerHeight }));
+      const inView = b => b && b.x < view.width && b.y < view.height && b.x + b.width > 0 && b.y + b.height > 0;
+      let box = await target.boundingBox();
+      if (!inView(box)) {
+        await target.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => {});
+        box = await target.boundingBox();
+      }
       if (!box) throw new Error(`${where} is not on the page to show the cursor at; ${still}`);
-      at = { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) };
+      const left = Math.max(box.x, 0);
+      const top = Math.max(box.y, 0);
+      const right = Math.min(box.x + box.width, view.width);
+      const bottom = Math.min(box.y + box.height, view.height);
+      at = { x: Math.round((left + right) / 2), y: Math.round((top + bottom) / 2) };
     } else {
       at = tabState(p).mouseAt || await p.evaluate(() => ({ x: Math.round(innerWidth / 2), y: Math.round(innerHeight / 2) }));
     }
@@ -332,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`);
   },
 };