pw-repl 0.9.0 → 0.10.0

package/README.md

@@ -100,7 +100,7 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | 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`               |
+| 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`                                                                        |
@@ -112,8 +112,8 @@ Everything else is in `help <topic>`; `help <command>` has usage and caveats.
 
 `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`.
+`emulate ...|emulate off`, `viewport <WxH>|viewport off`, `record on|off`, `highlight <selector>|highlight off`
+(and `highlight --labels on|off`), `cursor on|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.
 
@@ -125,7 +125,7 @@ their own show their state and what you can run next.
 [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.
 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.
@@ -133,6 +133,8 @@ pw-repl differs, it is because someone else may be using the browser:
 - There is no snapshot after every command, since a person 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.
+- `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

package/lib/cursor.js

@@ -316,13 +316,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) }));
     }

package/lib/elements.js

@@ -9,6 +9,7 @@ const { numbers, hints } = require('./util');
 const { tabState } = require('./tabstate');
 const { cursorOf, aiming, aimAt, glideTo, showClick, showSelect } = require('./cursor');
 const { recordingOf, stepTarget } = require('./record');
+const { settled } = require('./emulation');
 
 // The type a page sees for a file it is given, from its extension.
 const MIME_TYPES = {
@@ -282,7 +283,7 @@ async function hideHighlights(p, mine = false) {
   if (!highlights?.size) return 0;
   const hidden = [...highlights].filter(([, h]) => !mine || (h.owner ?? null) === (state.client ?? null));
   if (hidden.length === highlights.size) await p.hideHighlight();
-  else for (const [selector] of hidden) await p.locator(selector).hideHighlight();
+  else for (const [selector, h] of hidden) await (h.drawn || p.locator(selector)).hideHighlight();
   for (const [selector] of hidden) highlights.delete(selector);
   return hidden.length;
 }
@@ -293,6 +294,67 @@ onShutdown(async () => {
   await Promise.all(pages.map(p => hideHighlights(p).catch(() => {})));
 });
 
+// Playwright's highlight labels each box with its locator, which covers what is below it, and has
+// no option not to; highlights are drawn without it unless highlight --labels on. Its overlay is an
+// x-pw-glass element with a closed shadow root, which only CDP reaches: a stylesheet adopted there
+// hides the labels, under any CSP, and stays as Playwright redraws them. Playwright removes the
+// overlay with its last highlight, and the sheet with it, so it is applied again after each one.
+const LABELS_OFF = 'x-pw-tooltip:not([data-pw-repl])';
+// The clients told that the labels could not be hidden, each once.
+const labelsWarned = new Set();
+
+// Adds or removes the sheet in the main document's overlay, and says whether it worked: false when
+// there is an overlay but its labels are not hidden. Null when there is no overlay.
+async function applyLabels(p, hide) {
+  const session = await p.context().newCDPSession(p);
+  try {
+    const { root } = await session.send('DOM.getDocument', { depth: 0 });
+    const { nodeId } = await session.send('DOM.querySelector', { nodeId: root.nodeId, selector: 'x-pw-glass' });
+    if (!nodeId) return null;
+    const { node } = await session.send('DOM.describeNode', { nodeId, pierce: true });
+    const shadow = node.shadowRoots?.[0];
+    if (!shadow) return false;
+    const { object } = await session.send('DOM.resolveNode', { backendNodeId: shadow.backendNodeId });
+    const call = (fn, args) => session.send('Runtime.callFunctionOn', { objectId: object.objectId, functionDeclaration: fn.toString(), arguments: args.map(value => ({ value })), returnByValue: true });
+    await call(function (rule, hidden) {
+      const sheets = [...this.adoptedStyleSheets].filter(s => ![...s.cssRules].some(r => r.selectorText === rule));
+      if (hidden) {
+        const sheet = new CSSStyleSheet();
+        sheet.replaceSync(`${rule} { display: none !important; }`);
+        sheets.push(sheet);
+      }
+      this.adoptedStyleSheets = sheets;
+    }, [LABELS_OFF, hide]);
+    if (!hide) return true;
+    // Playwright draws its labels on a later frame.
+    await settled(p);
+    const { result } = await call(function (rule) {
+      const ours = [...this.adoptedStyleSheets].some(s => [...s.cssRules].some(r => r.selectorText === rule));
+      return ours && [...this.querySelectorAll('x-pw-tooltip')].every(t => getComputedStyle(t).display === 'none');
+    }, [LABELS_OFF]);
+    return result.value === true;
+  } finally {
+    await session.detach().catch(() => {});
+  }
+}
+
+// Hides the tab's labels unless they are on; says so once if that failed, and the highlight is drawn
+// with its label as Playwright draws it. A CDP call that fails, as one does when the tab navigates or
+// closes, says nothing of Playwright's overlay: only the check finding the labels shown does.
+async function keepLabels(p) {
+  if (tabState(p).labelsOn) return;
+  const worked = await applyLabels(p, true).catch(() => null);
+  const client = state.client ?? null;
+  if (worked !== false || labelsWarned.has(client)) return;
+  labelsWarned.add(client);
+  out.log(`highlight: could not hide the labels; Playwright's highlight has changed (playwright-core ${require('playwright-core/package.json').version}). The boxes are drawn with their labels.`);
+}
+
+async function setLabels(p, on) {
+  if (on) tabState(p).labelsOn = { owner: state.client }; else delete tabState(p).labelsOn;
+  if (on) await applyLabels(p, false); else await keepLabels(p);
+}
+
 const commands = {
   async click(args) {
     const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
@@ -313,15 +375,27 @@ const commands = {
   },
 
   async highlight(args) {
-    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | off]';
-    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag' });
+    const usage = 'Usage: highlight [<selector> [--style=<css>] | --hide [<selector>] | --labels off|on | off]';
+    const { found, rest } = takeOptions((args || '').trim(), { style: 'value', hide: 'flag', labels: 'value' });
     const style = found.find(o => o.name === 'style');
     const hide = found.some(o => o.name === 'hide');
+    const labels = found.find(o => o.name === 'labels');
     const highlights = highlightsOf(state.page);
+    // For the whole tab, with a highlight to draw or on its own.
+    if (labels) {
+      if (hide || rest === 'off' || !['off', 'on'].includes(labels.value)) throw new Error(usage);
+      await setLabels(state.page, labels.value === 'on');
+      out.log(labels.value === 'on'
+        ? 'Labels on in the selected tab: each highlight is labelled with its locator; highlight --labels off hides them'
+        : 'Labels off in the selected tab');
+      if (!rest) return;
+    }
     if (!rest && !found.length) {
       if (!highlights.size) { out.log(`Nothing is highlighted in the selected tab.\n${hints([['highlight <selector>', 'draw a box around it']])}`); return; }
-      for (const [selector, h] of highlights) out.log(`${selector}${h.style ? `  --style=${JSON.stringify(h.style)}` : ''}${h.owner ? `  (by ${h.owner})` : ''}`);
-      out.log(hints([['highlight --hide [<selector>]', 'hide one, or all']]));
+      for (const [selector, h] of highlights) out.log(`${selector}${h.drawn?.toString() !== state.page.locator(selector).toString() ? `  as ${h.drawn}` : ''}${h.style ? `  --style=${JSON.stringify(h.style)}` : ''}${h.owner ? `  (by ${h.owner})` : ''}`);
+      const on = tabState(state.page).labelsOn;
+      if (on) out.log(`Labels are on${on.owner ? ` (by ${on.owner})` : ''}.`);
+      out.log(hints([['highlight --hide [<selector>]', 'hide one, or all'], on ? ['highlight --labels off', 'hide their labels'] : ['highlight --labels on', 'label each with its locator']]));
       return;
     }
     if (rest === 'off' && !found.length || hide && !rest) {
@@ -334,7 +408,7 @@ const commands = {
     const locator = state.page.locator(selector);
     if (hide) {
       if (!highlights.has(selector)) throw new Error(`${rest} is not highlighted; highlight lists what is`);
-      await locator.hideHighlight();
+      await (highlights.get(selector).drawn || locator).hideHighlight();
       highlights.delete(selector);
       out.log(`Hid the highlight on ${rest}`);
       return;
@@ -342,9 +416,13 @@ const commands = {
     const count = await locator.count();
     if (!count) throw new Error(`No element matches ${rest}; nothing was highlighted`);
     // Drawn again, with its new style, rather than twice.
-    if (highlights.has(selector)) await locator.hideHighlight();
-    await locator.highlight(style ? { style: style.value } : {});
-    highlights.set(selector, { owner: state.client, style: style?.value || null });
+    if (highlights.has(selector)) await (highlights.get(selector).drawn || locator).hideHighlight();
+    // Playwright labels a box with the locator it is given, and a snapshot ref's (aria-ref=e5) finds
+    // nothing in the page's code: one is drawn with the locator Playwright makes for its element.
+    const drawn = REF.test(rest) ? await locator.normalize().catch(() => locator) : locator;
+    await drawn.highlight(style ? { style: style.value } : {});
+    await keepLabels(state.page);
+    highlights.set(selector, { owner: state.client, style: style?.value || null, drawn });
     out.log(`Highlighted ${rest}${count > 1 ? ` (all ${count} matches)` : ''}; highlight --hide ${rest} hides it`);
   },
 
@@ -511,4 +589,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, soleSelector, onElement, hideHighlights };
+module.exports = { commands, soleSelector, onElement, hideHighlights, setLabels };

package/lib/emulation.js

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

package/lib/help.js

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

package/lib/inspect.js

@@ -12,7 +12,7 @@ const { keptSession } = require('./cdp');
 const { CDP_REFUSED } = require('./dialogs');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
-const { deviceMetrics, viewportMetrics } = require('./emulation');
+const { deviceMetrics, viewportMetrics, reapplyMetrics } = require('./emulation');
 
 const SCREENSHOT_DELAY_MAX = 60;
 
@@ -51,6 +51,32 @@ async function deviceShot(device, { ref, full, type }) {
   return Buffer.from(data, 'base64');
 }
 
+// An element bigger than the viewport is taken with the page laid out again at its whole size, where
+// the page's scrollbar is gone and what was beside it moves over by its width, after the element was
+// measured: the shot came out shifted. Laid out without the scrollbar for the shot, by a stylesheet
+// adopted for it (under any CSP), the element is measured where it is taken. Someone looking at the
+// page sees its scrollbar go for a moment.
+const NO_SCROLLBAR = 'html:not([data-pw-repl])';
+async function elementShot(locator, type) {
+  const fits = await locator.evaluate(el => { const r = el.getBoundingClientRect(); return r.width <= innerWidth && r.height <= innerHeight; }, null, { timeout: 5000 });
+  if (fits) return locator.screenshot({ type, timeout: 5000 });
+  const sheet = hide => state.page.evaluate(([rule, on]) => {
+    const sheets = [...document.adoptedStyleSheets].filter(s => ![...s.cssRules].some(r => r.selectorText === rule));
+    if (on) {
+      const s = new CSSStyleSheet();
+      s.replaceSync(`${rule} { scrollbar-width: none !important; }`);
+      sheets.push(s);
+    }
+    document.adoptedStyleSheets = sheets;
+  }, [NO_SCROLLBAR, hide]);
+  await sheet(true);
+  try {
+    return await locator.screenshot({ type, timeout: 5000 });
+  } finally {
+    await sheet(false).catch(() => {});
+  }
+}
+
 // Unnamed generic nodes are layout wrappers (mostly divs): they add depth and
 // nothing to read. Drop them, lift their children, and drop cursor hints.
 function compactSnapshot(text) {
@@ -271,6 +297,8 @@ const commands = {
     // Chrome does not draw a tab that is not in front, and tabs open in the
     // background, so the tab is brought to the front for the shot.
     await state.page.bringToFront();
+    // A tab brought to the front before can be drawn at the window's size since its last navigation.
+    await reapplyMetrics(state.page);
     let image;
     const device = tabState(state.page).emulation?.device;
     try {
@@ -278,7 +306,7 @@ const commands = {
         image = await deviceShot(device, { ref, full, type });
       } else if (ref) {
         const selector = toSelector(ref);
-        image = await onElement(selector, () => state.page.locator(selector).screenshot({ type, timeout: 5000 }));
+        image = await onElement(selector, () => elementShot(state.page.locator(selector), type));
       } else {
         image = await state.page.screenshot({ fullPage: full, type });
       }

package/lib/modes.js

@@ -9,7 +9,7 @@ const { emulatedKinds, setEmulation, setViewport } = require('./emulation');
 const { recordingOf, finishRecording } = require('./record');
 const { currentCapture, endCapture } = require('./capture');
 const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
-const { hideHighlights } = require('./elements');
+const { hideHighlights, setLabels } = require('./elements');
 const { cursorOf, cursorOff } = require('./cursor');
 
 // The modes turned on in a tab, in the order the prompt shows them.
@@ -26,6 +26,7 @@ function activeModes(p) {
   if (routes) modes.push(`routes:${routes}`);
   const highlights = tabState(p).highlights?.size;
   if (highlights) modes.push(`highlight:${highlights}`);
+  if (tabState(p).labelsOn) modes.push('labels');
   if (cursorOf(p)) modes.push('cursor');
   if (currentCapture()?.page === p) modes.push('capture');
   if (recordingOf(p)) modes.push('record');
@@ -76,6 +77,8 @@ function modeOwners(p) {
   if (viewport) owners.push([viewport.owner ?? null, 'viewport']);
   for (const [glob, route] of tabState(p).routes || []) owners.push([route.owner ?? null, `route ${glob}`]);
   for (const [selector, h] of tabState(p).highlights || []) owners.push([h.owner ?? null, `highlight ${selector}`]);
+  const labels = tabState(p).labelsOn;
+  if (labels) owners.push([labels.owner ?? null, 'labels']);
   const cursor = cursorOf(p);
   if (cursor) owners.push([cursor.owner ?? null, 'cursor']);
   const capture = currentCapture();
@@ -114,6 +117,7 @@ async function allModesOff(mine = false) {
       if ('network' in tabState(p) && ours(tabState(p).network.owner)) { await setNetwork(p, null); done.push('network on'); }
       const hidden = await hideHighlights(p, mine);
       if (hidden) done.push(`${hidden} highlight${hidden === 1 ? '' : 's'} hidden`);
+      if (tabState(p).labelsOn && ours(tabState(p).labelsOn.owner)) { await setLabels(p, false); done.push('labels off'); }
       if (cursorOf(p) && ours(cursorOf(p).owner) && await cursorOff(p)) done.push('cursor off');
       // Before the page's size is reset, which the recording would otherwise end with.
       const recording = recordingOf(p);

package/lib/record.js

@@ -8,8 +8,7 @@ const out = require('./output');
 const { tabState } = require('./tabstate');
 const { clock, NO_TAB, STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
 const { shellWords, splitSelector } = require('./syntax');
-const { keptSession } = require('./cdp');
-const { deviceMetrics, viewportMetrics, settled } = require('./emulation');
+const { reapplyMetrics } = require('./emulation');
 
 const FPS = 25;
 const MAX_SECONDS = 3600;
@@ -134,13 +133,7 @@ function recordingOf(p) {
 
 async function restoreMetrics(p, rec) {
   if (rec?.finishing) return;
-  const tab = tabState(p);
-  if (!tab.viewport && !tab.emulation?.device) return;
-  const kept = await keptSession(p);
-  if (rec?.finishing) return;
-  if (tab.viewport) await viewportMetrics(kept, tab.viewport);
-  else if (tab.emulation?.device) await deviceMetrics(kept, tab.emulation.device);
-  await settled(p);
+  await reapplyMetrics(p);
 }
 
 // The tabs recording now, for the modes they count as.

package/package.json

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

package/skill/SKILL.md

@@ -15,16 +15,18 @@ shared session: a person can have their own tabs open in it and be using it whil
 `npx pw-repl@latest` in its place, in that same form for every command, so each one runs the same
 version; from a clone, `<clone>/bin/pw-repl.js`.
 
-`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. When that
-is not the skill named at the top of this file, tell the user before going on:
+`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. When
+that is not the skill named at the top of this file, tell the user once, in these words and in passing,
+with whatever else you are telling them, and carry on with the task:
 
-- if this file's pw-repl version is newer than that one, pw-repl is behind: say "⚠️ pw-repl is older
-  than this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
+- if this file's pw-repl version is newer than that one, pw-repl is behind: "🔄 pw-repl is older than
+  this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
   `npm install -g pw-repl` updates it."
-- otherwise, the skill is: ask "⚠️ This pw-repl skill is out of date (from pw-repl <this file's
-  version>; <that version> has a newer one). Update it? Everything but its Custom rules section will be
-  replaced." On a yes, save what `pw-repl skill` prints over this file, with this file's Custom rules
-  section in place of the new one's.
+- otherwise, the skill is: "🔄 This pw-repl skill is out of date (from pw-repl <this file's version>;
+  <that version> has a newer one). If you'd like me to update it, just ask: everything but its Custom
+  rules section would be replaced." Update it only when the user asks for that; a yes to something else
+  is not one. To update it, save what `pw-repl skill` prints over this file, with this file's Custom
+  rules section in place of the new one's.
 
 ## Arguments
 
@@ -34,11 +36,12 @@ the sections below are how to carry it out. With no args, get a REPL running and
 
 ## Start it
 
-`pw-repl where` says whether a REPL is running and how `send` reaches it, or that one is still starting
-(retry shortly; it exits 64 until the REPL serves, as when none is running). Right after you start one,
-for a moment before its process is up, it can still say none is there: retry for a few seconds before
-taking that as a failed start. There are three ways to run one; each takes an optional start URL, which
-opens in a new tab.
+Run `pw-repl where` first, before anything else (with `-e <socket>` for a REPL you were told is on one),
+and check the skill it names against the top of this file. It says whether a REPL is running and how
+`send` reaches it, or that one is still starting (retry shortly; it exits 64 until the REPL serves, as
+when none is running). Right after you start one, for a moment before its process is up, it can still
+say none is there: retry for a few seconds before taking that as a failed start. There are three ways to
+run one; each takes an optional start URL, which opens in a new tab.
 
 - `pw-repl serve --background` runs it detached, with a command server on `/tmp/playwright-repl.sock`
   (owner-only) and its output in `/tmp/playwright-repl.log`. `pw-repl attach` shows everything it does
@@ -212,8 +215,8 @@ pw-repl send -c <name> close                        # your modes off; tab close
   `modes off` turns off every mode in every tab.
 - Someone may be attached to the REPL's tmux session; killing the session ends it for them too.
 - To point something out, to the person or in a screenshot, `highlight <ref|selector>` draws a box over it
-  without changing the page (`--style=<css>` restyles it; `highlight off` hides them). Its label can
-  cover what is below it; `help highlight` says how to mark a screenshot without one.
+  without changing the page (`--style=<css>` restyles it; `highlight off` hides them), without
+  Playwright's locator label unless `highlight --labels on`.
 - For a video, `help video` says how: a take written as a file and sent with `send --file`, `record on`
   around it, `cursor on` for a pointer, and the pacing recording adds for the viewer; a screen recorder on
   the user's machine records what they see.