pw-repl 0.4.1 → 0.5.0

package/lib/commands.js

@@ -146,19 +146,41 @@ async function dialogCommand(args, selected = state.page) {
 // the window's; it is read from the page.
 async function viewportText() {
   const device = emulations.get(state.page)?.device;
-  if (device) return `${devices[device].viewport.width}x${devices[device].viewport.height} (emulate mobile: ${device})`;
+  if (device) {
+    const { width, height } = devices[device].viewport;
+    // A page with no viewport meta tag is laid out as on a desktop, and the phone shows it shrunk.
+    const laidOut = await state.page.evaluate(() => innerWidth).catch(() => null);
+    const wider = laidOut && laidOut > width ? `; the page lays out ${laidOut} wide, shown shrunk: it has no viewport meta tag` : '';
+    return `${width}x${height} (emulate mobile: ${device}${wider})`;
+  }
   const set = state.page.viewportSize();
   if (set) return `${set.width}x${set.height} (set with viewport)`;
   const size = await state.page.evaluate(() => `${innerWidth}x${innerHeight}`).catch(() => null);
   return size ? `${size} (the window's size)` : 'unknown';
 }
 
+// A navigation that does not load is said as wait load says it, from its request, rather than as
+// Playwright's net:: error and call log.
+async function navigating(go) {
+  const started = Date.now();
+  try {
+    return await go();
+  } catch (error) {
+    if (!/net::ERR_/.test(error.message)) throw error;
+    const find = () => (recentLogs.get(state.page) || []).filter(e => e.navigation && e.t >= started && e.failed && e.status !== 'pending').pop();
+    for (let waited = 0; !find() && waited < 1000; waited += 50) await new Promise(resolve => setTimeout(resolve, 50));
+    const navigation = find();
+    if (!navigation) throw error;
+    throw new Error(notLoaded(navigation));
+  }
+}
+
 // A page restored from the back/forward cache never fires its load events
 // again, so back and forward wait only for the navigation, then briefly for
 // the document to be parsed, which a restored one already is.
 async function historyStep(go, direction) {
   const before = state.page.url();
-  const response = await go();
+  const response = await navigating(go);
   if (response === null && state.page.url() === before) throw new Error(`No page to go ${direction} to`);
   await state.page.waitForFunction(() => document.readyState !== 'loading', null, { timeout: 3000 }).catch(() => {});
 }
@@ -255,6 +277,35 @@ function deviceText(name) {
   return `${name}, ${d.viewport.width}x${d.viewport.height} at ${d.deviceScaleFactor}x${d.hasTouch ? ', touch' : ''}`;
 }
 
+// A screenshot of an emulated phone, taken by Chrome as it draws it. Playwright's own sizes the page
+// again for the shot, and a page with no viewport meta tag, laid out wider than the phone and shown
+// shrunk, comes out drawn small in a corner of a mostly blank image. One image pixel per CSS pixel.
+async function deviceShot(device, { ref, full, type }) {
+  const session = await keptSession(state.page);
+  let clip = null;
+  if (ref) {
+    const selector = toSelector(ref);
+    const box = await onElement(selector, async () => {
+      const locator = state.page.locator(selector);
+      await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
+      return locator.evaluate(el => { const r = el.getBoundingClientRect(); return { x: r.x + scrollX, y: r.y + scrollY, width: r.width, height: r.height }; });
+    });
+    clip = box;
+  }
+  // Measured after scrolling to the element, if any.
+  const { cssVisualViewport: view, cssContentSize: content } = await session.send('Page.getLayoutMetrics');
+  // At the size the phone shows it: a page laid out wider than the phone is shown shrunk (view.scale).
+  const scale = view.scale / devices[device].deviceScaleFactor;
+  if (clip) clip = { ...clip, scale };
+  if (full) clip = { x: 0, y: 0, width: content.width, height: content.height, scale };
+  if (!clip) clip = { x: view.pageX, y: view.pageY, width: view.clientWidth, height: view.clientHeight, scale };
+  // Beyond the visible area, Chrome lays the page out again at its whole size for the shot, which
+  // someone looking at it would see move: only for --full, and an element that does not fit.
+  const inView = clip.x >= view.pageX && clip.y >= view.pageY && clip.x + clip.width <= view.pageX + view.clientWidth && clip.y + clip.height <= view.pageY + view.clientHeight;
+  const { data } = await session.send('Page.captureScreenshot', { format: type, clip, captureBeyondViewport: full || (!!ref && !inView) });
+  return Buffer.from(data, 'base64');
+}
+
 // Sends only what changed. Chrome takes the user agent and the languages
 // together, so a change to either sends both.
 function deviceMetrics(session, name) {
@@ -385,8 +436,8 @@ function routeKind(how, rest, usage) {
   }
   if (how === 'patch') {
     if (!rest) throw new Error(usage);
+    // Anything but an object replaces the whole body, as RFC 7386 has it: the way to change an array.
     const patch = parseJson(rest, 'Patch');
-    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('Patch must be a JSON object, e.g. {"total": 0}');
     return {
       text: `patch ${rest.length > ROUTE_PREVIEW ? `${rest.slice(0, ROUTE_PREVIEW)}…` : rest}`,
       async handle(r, req, tag) {
@@ -477,6 +528,13 @@ const BODY_TIMEOUT = 15000;
 const RECENT_HIDDEN_TYPES = new Set(['image', 'font', 'stylesheet', 'media']);
 // The bodies body prints; any other is binary.
 const TEXT_BODY = /json|^text\/|javascript|xml|html|x-www-form-urlencoded/;
+
+// UTF-8 with no control characters but tabs and line breaks.
+function looksLikeText(buffer) {
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(buffer); } catch { return false; }
+  return !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text);
+}
 // A watched tab keeps each body watch shows as it arrives, since the browser
 // drops them once the tab navigates, often before anyone has read them.
 const KEPT_BODY_MAX = 100 * 1024;
@@ -491,6 +549,8 @@ const loadedAt = new WeakMap();
 const openedTabs = new WeakSet();
 // page -> the client that opened it (null: the prompt, or a sender without a name).
 const tabOwners = new WeakMap();
+// The tab the REPL opened for its start URL, which tab marks: in a kept profile it sits among restored tabs.
+const startTabs = new WeakSet();
 
 function clipText(text) {
   return text.length > MAX_EVENT_TEXT ? `${text.slice(0, MAX_EVENT_TEXT)}…` : text;
@@ -516,7 +576,14 @@ function consoleLevel(type) {
 
 function keep(log, entry) {
   log.push(entry);
-  if (log.length > RECENT_MAX) log.shift();
+  if (log.length > RECENT_MAX) { log.shift(); log.dropped = true; }
+}
+
+// Said when a listing leaves some out, or it looks complete: a busy page makes more than the
+// default in one load, and the log itself keeps only the last RECENT_MAX.
+function cutNote(what, shown, total, dropped, command) {
+  if (shown < total) return `(last ${shown} of ${total} kept; ${command(Math.min(total, RECENT_MAX))} shows them all${dropped ? `; older ${what} are no longer kept` : ''})`;
+  return dropped ? `(older ${what} are no longer kept: only the last ${RECENT_MAX} of every kind are)` : null;
 }
 
 function ensureRecentLog(p) {
@@ -552,10 +619,22 @@ function ensureRecentLog(p) {
     finish(req, changedRequests.has(req) ? `${status} ${changedRequests.get(req)}` : status, res);
     keepBody(p, requestEntries.get(req), res);
   });
-  p.on('requestfailed', req => {
-    finish(req, `failed: ${req.failure()?.errorText || 'unknown'}`);
+  p.on('requestfailed', async req => {
     // A page that never loaded: the app's next route change is not a load either.
     if (requestEntries.get(req)?.navigation) newDocument = false;
+    const reason = req.failure()?.errorText || 'unknown';
+    // Whatever its status says: wait load must know at once that this one will never load.
+    const entry = requestEntries.get(req);
+    if (entry) entry.failed = reason;
+    // Chrome reports a response that has no body (204, 205, 304) as aborted once it has arrived: the
+    // page got its answer. Any other answered one failed while its body came in, and says so.
+    const res = await req.response().catch(() => null);
+    if (res) {
+      const status = changedRequests.has(req) ? `${res.status()} ${changedRequests.get(req)}` : String(res.status());
+      finish(req, [204, 205, 304].includes(res.status()) ? status : `${status}, then failed: ${reason}`, res);
+    } else {
+      finish(req, `failed: ${reason}`);
+    }
   });
   p.on('load', () => loadedAt.set(p, Date.now()));
   // A page load, marked among the messages it comes between; it ages out with them. Only a new
@@ -1185,19 +1264,146 @@ function selectorAndValue(args, usage, example) {
 }
 
 // An element that never appeared is said plainly, not as Playwright's call
-// log. A ref that no longer matches usually means the page changed since the
-// snapshot it came from.
+// log, and so is one that timed out: its call log (dozens of lines of retries) goes
+// to the REPL's pane and log only. A ref that no longer matches usually means the page
+// changed since the snapshot it came from.
 async function onElement(selector, action) {
   try {
     return await action();
   } catch (error) {
-    if (/resolved to/.test(error.message)) throw error;
+    const message = String(error.message || '').replace(/\x1b\[[0-9;]*m/g, '');
+    if (/strict mode violation/.test(message)) throw error;
     const ref = selector.startsWith('aria-ref=') ? selector.slice(9) : null;
     const staleRef = ref ? `\n${ref} is a snapshot ref; if the page changed since that snapshot, take a new one.` : '';
-    const waited = /Timeout (\d+)ms exceeded[\s\S]*waiting for locator/.exec(error.message);
-    if (waited) throw new Error(`No element matches ${ref || selector} (waited ${waited[1] / 1000}s)${staleRef}`);
-    error.message += staleRef;
-    throw error;
+    const timeout = /Timeout (\d+)ms exceeded/.exec(message);
+    if (timeout && /waiting for locator/.test(message) && !/resolved to/.test(message)) {
+      throw new Error(`No element matches ${ref || selector} (waited ${timeout[1] / 1000}s)${staleRef}`);
+    }
+    if (!timeout) { error.message += staleRef; throw error; }
+    console.error(`Playwright's call log:\n${message}`);
+    // Found, so the ref is not stale: no hint.
+    const summary = new Error(`Timed out after ${timeout[1] / 1000}s on ${ref || selector}: ${lastBlocker(message)} (its call log is in the REPL's pane or log)`);
+    // Worked out from the whole log: the summary no longer says whether the element was found.
+    summary.uncertain = !/waiting for locator/.test(message) || /resolved to/.test(message);
+    throw summary;
+  }
+}
+
+// What last stopped the action, from Playwright's call log: the element that took the click,
+// or the check the element kept failing.
+function lastBlocker(log) {
+  const lines = log.split('\n').map(line => line.trim().replace(/^-\s*/, ''));
+  const line = lines.reverse().find(l => /intercepts pointer events|element is not |element is outside|not attached|detached/.test(l));
+  if (!line) return 'it never became ready to act on';
+  return line.length > 240 ? `${line.slice(0, 240)}…` : line;
+}
+
+// Where a match stands for a click: hidden elements are left out before this. Tested in
+// its own frame, at its centre, and only when that is in view: scrolling each one to test
+// it would move a page someone may be looking at.
+function hitTest(el) {
+  if (window !== window.top) return { kind: 'unchecked' };
+  const r = el.getBoundingClientRect();
+  const x = r.left + r.width / 2;
+  const y = r.top + r.height / 2;
+  if (x < 0 || y < 0 || x >= innerWidth || y >= innerHeight) return { kind: 'unchecked' };
+  let top = document.elementFromPoint(x, y);
+  while (top?.shadowRoot) {
+    const inner = top.shadowRoot.elementFromPoint(x, y);
+    if (!inner || inner === top) break;
+    top = inner;
+  }
+  for (let n = top; n; n = n.parentNode || n.host) if (n === el) return { kind: 'hit' };
+  const name = e => {
+    const classes = typeof e.className === 'string' ? e.className.trim().split(/\s+/).filter(Boolean).slice(0, 3) : [];
+    return `<${e.tagName.toLowerCase()}${e.id ? `#${e.id}` : ''}${classes.map(c => `.${c}`).join('')}>`;
+  };
+  return { kind: 'covered', by: top ? name(top) : 'nothing (off the page)' };
+}
+
+// Playwright acts on the first match and retries it until it times out, even when that one is
+// hidden or under an overlay and a later one could be used. With several matches, this picks
+// the first visible one that is not covered (or not checkable here, which Playwright then
+// checks as it acts), waiting for one as Playwright waits; with none it fails before acting,
+// saying why. The chosen element's handle is what is acted on, so the list changing
+// meanwhile cannot shift the choice. Null: a ref or a single match, left to Playwright.
+async function chooseMatch(selector, timeout) {
+  if (selector.startsWith('aria-ref=')) return null;
+  const locator = state.page.locator(selector);
+  if (await locator.count() <= 1) return null;
+  const deadline = Date.now() + timeout;
+  let seen = { count: 0, handles: [], results: [] };
+  for (;;) {
+    const count = await locator.count();
+    if (count <= 1 && !seen.handles.length) return null;
+    const handles = await locator.filter({ visible: true }).elementHandles();
+    const results = await Promise.all(handles.map(h => h.evaluate(hitTest).catch(() => ({ kind: 'gone' }))));
+    // In page order: a later match in view must not win over an earlier one Playwright can scroll to.
+    const index = results.findIndex(r => r.kind === 'hit' || r.kind === 'unchecked');
+    if (index !== -1) {
+      await Promise.all(seen.handles.concat(handles.filter((_, i) => i !== index)).map(h => h.dispose().catch(() => {})));
+      const all = await locator.elementHandles();
+      const position = (await Promise.all(all.map(h => h.evaluate((a, b) => a === b, handles[index])))).indexOf(true);
+      await Promise.all(all.map(h => h.dispose().catch(() => {})));
+      return { handle: handles[index], position: position + 1, count };
+    }
+    await Promise.all(seen.handles.map(h => h.dispose().catch(() => {})));
+    seen = { count, handles, results };
+    if (Date.now() >= deadline) break;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  const listed = await Promise.all(seen.handles.slice(0, 5).map(async (h, i) => {
+    const text = await h.evaluate(el => `<${el.tagName.toLowerCase()}> ${(el.innerText || el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60)}`).catch(() => '(gone)');
+    const r = seen.results[i];
+    return `  ${text}: ${r.kind === 'covered' ? `covered by ${r.by}` : 'gone from the page'}`;
+  }));
+  await Promise.all(seen.handles.map(h => h.dispose().catch(() => {})));
+  const hidden = seen.count - seen.handles.length;
+  const error = new Error([
+    `None of the ${seen.count} matches for ${selector} could be acted on after ${timeout / 1000}s, so nothing was done:`,
+    ...listed,
+    ...(seen.handles.length > 5 ? [`  and ${seen.handles.length - 5} more like these`] : []),
+    ...(hidden ? [`  ${hidden} hidden`] : []),
+    'A more specific selector, or a ref from snapshot, picks one; covered ones may be under a dialog or overlay.',
+  ].join('\n'));
+  error.uncertain = false;
+  throw error;
+}
+
+function numbers(args, usage) {
+  const words = (args || '').trim().split(/\s+/).filter(Boolean);
+  if (words.some(w => !/^-?\d+(?:\.\d+)?$/.test(w))) throw new Error(`Usage: ${usage}, in numbers of CSS pixels`);
+  return words.map(Number);
+}
+
+function mouseButton(args, name) {
+  const button = (args || '').trim() || 'left';
+  if (!/^(?:left|right|middle)$/.test(button)) throw new Error(`Usage: ${name} [left|right|middle]`);
+  return button;
+}
+
+// click, dblclick and hover: on the match chooseMatch picks, or as Playwright does.
+// A page that renders the chosen element again (as React lists do) replaces it before it is
+// acted on; it is chosen again then, as Playwright finds a locator's element again.
+async function pointerAction(selector, act, options = {}) {
+  const TIMEOUT = 5000;
+  const deadline = Date.now() + TIMEOUT;
+  const left = () => Math.max(1000, deadline - Date.now());
+  for (;;) {
+    const chosen = await onElement(selector, () => chooseMatch(selector, left()));
+    if (!chosen) {
+      // Only counted so far, so the whole time is Playwright's, as it was before.
+      await onElement(selector, () => act(state.page, selector, { ...options, timeout: TIMEOUT }));
+      return '';
+    }
+    try {
+      await onElement(selector, () => act(chosen.handle, null, { ...options, timeout: left() }));
+      return chosen.position === 1 ? '' : ` (match ${chosen.position} of ${chosen.count}; the ones before it are hidden or covered)`;
+    } catch (error) {
+      if (!/not attached/i.test(error.message) || Date.now() >= deadline) throw error;
+    } finally {
+      await chosen.handle.dispose().catch(() => {});
+    }
   }
 }
 
@@ -1224,13 +1430,29 @@ async function waitForRequest(pattern, timeout) {
   const since = state.previousCommandAt || 0;
   const deadline = Date.now() + timeout;
   for (;;) {
-    const entry = (recentLogs.get(state.page) || []).find(e => e.t >= since && matches(e.url));
-    if (entry && entry.status !== 'pending') return printRequest(entry);
+    // Begun since the previous command, or finished since, or still going: one begun earlier (a
+    // reload two commands ago) can still be the one waited for. A finished one first, so a request
+    // that never ends (a long poll) does not hide one that has.
+    const found = (recentLogs.get(state.page) || []).filter(e => matches(e.url) && (e.t >= since || e.ms === null || e.t + e.ms >= since));
+    const done = found.find(e => e.status !== 'pending');
+    if (done) return printRequest(done);
+    const entry = found[0];
     if (Date.now() >= deadline) throw new Error(`No response matching ${pattern} within ${timeout / 1000}s${entry ? ` (#${entry.id} is still pending)` : ''}`);
     await new Promise(resolve => setTimeout(resolve, 50));
   }
 }
 
+// Why a navigation that failed did not load, from its request.
+function notLoaded(navigation) {
+  const why = stayedPut(navigation) ? `${navigation.status} (no page to show, so the tab stays where it was)` : navigation.status.startsWith('failed') ? navigation.status : `${navigation.status}, then failed: ${navigation.failed}`;
+  return `The page did not load: #${navigation.id} ${navigation.url} ${why}`;
+}
+
+// Answered with no page (204, 205): Chrome leaves the tab on the page it was on.
+function stayedPut(entry) {
+  return !!entry.failed && /^(?:204|205)\b/.test(entry.status);
+}
+
 // Done once the page has loaded: after the latest navigation of the tab that
 // began since the previous command did (the click on a link, say), or, with
 // none, the document there now. Waiting on Playwright's load state alone would
@@ -1241,8 +1463,14 @@ async function waitForLoad(timeout) {
   const deadline = Date.now() + timeout;
   for (;;) {
     const navigation = (recentLogs.get(p) || []).filter(e => e.navigation && e.t >= since).pop();
-    if (navigation && navigation.status.startsWith('failed')) throw new Error(`The page did not load: #${navigation.id} ${navigation.url} ${navigation.status}`);
+    if (navigation?.failed && navigation.status !== 'pending') throw new Error(notLoaded(navigation));
     const loaded = navigation ? (loadedAt.get(p) || 0) >= navigation.t : await p.evaluate(() => document.readyState === 'complete').catch(() => false);
+    if (loaded && !navigation && (loadedAt.get(p) || 0) < since) {
+      // Nothing loaded since the previous command: a page that changes its URL itself (pushState) does not
+      // load, and may not have changed it yet.
+      out.log(`Loaded before the previous command, nothing since: ${p.url()} — ${await p.title().catch(() => '')}\n(A page that changes its own URL does not load: wait <selector> or wait text waits for its new view.)`);
+      return;
+    }
     if (loaded) { out.log(`Loaded: ${p.url()} — ${await p.title().catch(() => '')}`); return; }
     if (Date.now() >= deadline) throw new Error(`${p.url()} did not finish loading within ${timeout / 1000}s`);
     await new Promise(resolve => setTimeout(resolve, 50));
@@ -1408,17 +1636,31 @@ async function listTabs() {
     // URL first on its own line: it is what distinguishes otherwise
     // identically titled tabs, and titles wrap less badly when indented.
     if (i) out.log('');
-    out.log(`${marker} [${i}] ${p.url()}${tabOwners.get(p) ? `  (opened by ${tabOwners.get(p)})` : ''}`);
+    const notes = [startTabs.has(p) && 'the start URL', tabOwners.get(p) && `opened by ${tabOwners.get(p)}`].filter(Boolean);
+    out.log(`${marker} [${i}] ${p.url()}${notes.length ? `  (${notes.join(', ')})` : ''}`);
     out.log(`        ${JSON.stringify(title)}`);
   }
 }
 
 // A function written out (el => ..., function (el) {...}), as one expression.
 function isFunctionText(text) {
+  // Wrapped in parentheses, as (el => el.id) is often written: only when the first one closes at the end.
+  const wrapped = /^\s*\(([\s\S]*)\)\s*$/.exec(text);
+  if (wrapped && closesAtEnd(text.trim()) && isFunctionText(wrapped[1])) return true;
   if (!/^\s*(?:async\s+)?(?:function\b|\([^)]*\)\s*=>|[\w$]+\s*=>)/.test(text)) return false;
   try { new Function(`return (${text}\n);`); return true; } catch { return false; }
 }
 
+// Whether the opening parenthesis is matched by the last character, not earlier: (a)(b) is a call.
+function closesAtEnd(text) {
+  let depth = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] === '(') depth += 1;
+    else if (text[i] === ')') { depth -= 1; if (depth === 0) return i === text.length - 1; }
+  }
+  return false;
+}
+
 const commands = {
   async tab(args) {
     const trimmed = (args || '').trim();
@@ -1455,8 +1697,15 @@ const commands = {
       if (parts.length) throw new Error(usage);
       const target = state.tabListing[Number(subcommand)];
       if (target && all.includes(target)) { select(target); return commands.info(); }
+      // Not read as part of a URL instead: that could land in someone else's tab without a word.
+      if (target) throw new Error(`Tab [${subcommand}] has closed since the latest listing. Run tab to list them again.`);
       // A number that is not a tab in the listing may be part of a URL (a port).
-      if (!all.some(p => p.url().includes(subcommand))) throw new Error(`No tab [${subcommand}] in the latest listing, and no tab URL contains ${subcommand}. Run tab to list them.`);
+      const containing = all.filter(p => p.url().includes(subcommand)).length;
+      if (!containing) throw new Error(`No tab [${subcommand}] in the latest listing, and no tab URL contains ${subcommand}. Run tab to list them.`);
+      if (containing > 1) {
+        const listing = state.tabListing.length ? 'the latest listing' : 'a listing yet: each client has its own, from tab';
+        throw new Error(`No tab [${subcommand}] in ${listing}. As part of a URL, ${subcommand} is in ${containing} tabs. Run tab, then tab <index>.`);
+      }
     }
     if (subcommand === 'new') {
       select(await openTab());
@@ -1494,7 +1743,7 @@ const commands = {
     // As a browser's address bar does: a local dev server is almost always plain http.
     const local = /^(?:localhost|127(?:\.\d+){3}|\[::1\]|0\.0\.0\.0)(?:[:/?#]|$)/i.test(url);
     if (!/^[a-z][a-z\d+.-]*:\/\//i.test(url) && !/^(about|data|file|javascript):/i.test(url)) url = `${local ? 'http' : 'https'}://${url}`;
-    await state.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 });
+    await navigating(() => state.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 }));
     out.log(`${state.page.url()} — ${await state.page.title()}`);
   },
 
@@ -1509,32 +1758,65 @@ const commands = {
   },
 
   async reload() {
-    await state.page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 });
+    await navigating(() => state.page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 }));
     out.log(`Reloaded: ${state.page.url()}`);
   },
 
   async info() {
     out.log(`  URL:   ${state.page.url()}`);
+    // Chrome's error page has a URL of its own; the one that failed is in the request log.
+    if (state.page.url().startsWith('chrome-error://')) {
+      const failed = (recentLogs.get(state.page) || []).filter(e => e.navigation && e.failed && !stayedPut(e)).pop();
+      if (failed) out.log(`  Error: Chrome's error page, for #${failed.id} ${failed.url} ${failed.status}`);
+    }
     out.log(`  Title: ${await state.page.title()}`);
     out.log(`  Viewport: ${await viewportText()}`);
   },
 
   async click(args) {
     const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
-    await onElement(selector, () => state.page.click(selector, { ...options, timeout: 5000 }));
-    out.log(`Clicked: ${shown}`);
+    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.click(sel, o) : on.click(o)), options);
+    out.log(`Clicked: ${shown}${which}`);
   },
 
   async dblclick(args) {
     const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
-    await onElement(selector, () => state.page.dblclick(selector, { ...options, timeout: 5000 }));
-    out.log(`Double-clicked: ${shown}`);
+    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.dblclick(sel, o) : on.dblclick(o)), options);
+    out.log(`Double-clicked: ${shown}${which}`);
   },
 
   async hover(args) {
     const selector = soleSelector(args, 'hover <selector>');
-    await onElement(selector, () => state.page.hover(selector, { timeout: 5000 }));
-    out.log(`Hovered: ${args.trim()}`);
+    const which = await pointerAction(selector, (on, sel, o) => (sel ? on.hover(sel, o) : on.hover(o)));
+    out.log(`Hovered: ${args.trim()}${which}`);
+  },
+
+  // At a point, in CSS pixels from the top left of the tab's viewport, as playwright-cli's are.
+  async mousemove(args) {
+    const [x, y, extra] = numbers(args, 'mousemove <x> <y>');
+    if (y === undefined || extra !== undefined) throw new Error('Usage: mousemove <x> <y>, in CSS pixels from the top left of the viewport');
+    await state.page.mouse.move(x, y);
+    out.log(`Moved the mouse to ${x}, ${y}`);
+  },
+
+  async mousedown(args) {
+    const button = mouseButton(args, 'mousedown');
+    await state.page.mouse.down({ button });
+    out.log(`Pressed the ${button} button`);
+  },
+
+  async mouseup(args) {
+    const button = mouseButton(args, 'mouseup');
+    await state.page.mouse.up({ button });
+    out.log(`Released the ${button} button`);
+  },
+
+  // Wheel events where the mouse is (mousemove puts it there): a map zooms around that point.
+  async mousewheel(args) {
+    const [dx, dy, extra] = numbers(args, 'mousewheel <dx> <dy>');
+    if (dy === undefined || extra !== undefined) throw new Error('Usage: mousewheel <dx> <dy>, e.g. mousewheel 0 300 scrolls down (negative dy up)');
+    await state.page.mouse.wheel(dx, dy);
+    out.log(`Turned the wheel by ${dx}, ${dy}`);
   },
 
   async fill(line) {
@@ -1683,14 +1965,26 @@ const commands = {
       // Chrome includes each handler's source only for an object in a named group.
       const { result } = await cdp.send('Runtime.evaluate', { expression: which || 'window.__pwReplListenersOf', objectGroup: 'pw-repl-listeners' });
       if (!result.objectId) throw new Error(`No element matches ${text}`);
-      const { listeners } = await cdp.send('DOMDebugger.getEventListeners', { objectId: result.objectId });
-      if (!listeners.length) { out.log(`No event listeners on ${text}`); return; }
+      const { listeners: found } = await cdp.send('DOMDebugger.getEventListeners', { objectId: result.objectId });
+      // Playwright adds its own to window once it has acted on the page; they are not the page's.
+      // Told by the script they come from, the one its hit-target check is in.
+      const own = new Set(found.filter(l => /^__playwright_/.test(l.type) || /_hitTargetInterceptor/.test(l.handler?.description || '')).map(l => l.scriptId));
+      const listeners = found.filter(l => !own.has(l.scriptId));
+      const note = found.length > listeners.length ? ` (${found.length - listeners.length} of Playwright's own left out)` : '';
+      if (!listeners.length) { out.log(`No event listeners on ${text}${note}`); return; }
       const lines = listeners.map(l => {
         const how = [l.useCapture && 'capture', l.once && 'once', l.passive && 'passive'].filter(Boolean).join(', ');
-        const handler = (l.handler?.description || '').replace(/\s+/g, ' ').slice(0, 100);
+        const source = l.handler?.description || '';
+        // Whole, as written, with its lines indented; or its start on one line, where ↵ marks each
+        // line break, so a // comment is seen to end there.
+        const text = all
+          ? source.split('\n').map((line, i) => (i ? `    ${line}` : line)).join('\n')
+          : source.replace(/[ \t]*\r?\n\s*/g, ' ↵ ').replace(/[ \t]+/g, ' ');
+        const handler = all || text.length <= 100 ? text : `${text.slice(0, 100)}…`;
         return `${l.type}${how ? ` (${how})` : ''}: ${handler} (line ${l.lineNumber + 1})`;
       });
       printOutput(lines.join('\n'), all);
+      if (note) out.log(note.trim());
     } finally {
       await cdp.send('Runtime.evaluate', { expression: 'delete window.__pwReplListenersOf' }).catch(() => {});
       await cdp.send('Runtime.releaseObjectGroup', { objectGroup: 'pw-repl-listeners' }).catch(() => {});
@@ -1781,8 +2075,11 @@ const commands = {
     // background, so the tab is brought to the front for the shot.
     await state.page.bringToFront();
     let image;
+    const device = emulations.get(state.page)?.device;
     try {
-      if (ref) {
+      if (device) {
+        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 }));
       } else {
@@ -1791,7 +2088,6 @@ const commands = {
     } finally {
       // Playwright's screenshot resets the screen size and pixel ratio it
       // finds; an emulated phone's are set again.
-      const device = emulations.get(state.page)?.device;
       if (device) {
         const session = await keptSession(state.page);
         await session.send('Emulation.clearDeviceMetricsOverride');
@@ -1821,8 +2117,21 @@ const commands = {
     }
     // Playwright's labels are e5, or frame-prefixed like f1e5 in newer versions.
     const selector = toSelector(rest);
-    const target = selector ? state.page.locator(selector).first() : state.page;
-    const raw = selector ? await onElement(selector, () => target.ariaSnapshot({ mode: 'ai', timeout: 5000 })) : await target.ariaSnapshot({ mode: 'ai', timeout: 5000 });
+    let raw;
+    // A snapshot of one element gives the page new refs, and those of the last whole-page snapshot
+    // stop working; so a ref's part is cut from a whole-page snapshot, which keeps them.
+    if (REF.test(rest)) {
+      const lines = (await state.page.ariaSnapshot({ mode: 'ai', timeout: 5000 })).split('\n');
+      const at = lines.findIndex(line => line.includes(`[ref=${rest}]`));
+      if (at === -1) throw new Error(`No element matches ${rest}\n${rest} is a snapshot ref; if the page changed since that snapshot, take a new one.`);
+      const indent = line => line.length - line.trimStart().length;
+      const end = lines.findIndex((line, i) => i > at && indent(line) <= indent(lines[at]));
+      raw = lines.slice(at, end === -1 ? undefined : end).map(line => line.slice(indent(lines[at]))).join('\n');
+    } else if (selector) {
+      raw = await onElement(selector, () => state.page.locator(selector).first().ariaSnapshot({ mode: 'ai', timeout: 5000 }));
+    } else {
+      raw = await state.page.ariaSnapshot({ mode: 'ai', timeout: 5000 });
+    }
     const text = full ? raw : compactSnapshot(raw);
     if (needle !== null) {
       const hits = grepSnapshot(text, needle);
@@ -1895,7 +2204,9 @@ const commands = {
     const gone = tokens.includes('--gone');
     tokens = tokens.filter(t => t !== '--gone');
     let seconds = WAIT_DEFAULT;
-    if (tokens.length > 1 && /^\d+$/.test(tokens[tokens.length - 1])) seconds = Number(tokens.pop());
+    // A number last is the seconds, unless it is all there is to wait for: wait text 990.
+    const onlyWhat = (tokens[0] === 'text' || tokens[0] === 'request') && tokens.length === 2;
+    if (tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1])) seconds = Number(tokens.pop());
     if (!tokens.length || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
     const timeout = seconds * 1000;
     // Said plainly, not as Playwright's call log.
@@ -1925,7 +2236,8 @@ const commands = {
   async sleep(args) {
     if (!args || !/^\d+$/.test(args) || Number(args) > 3600000) throw new Error('Usage: sleep <ms> (maximum 3600000)');
     await state.page.waitForTimeout(Number(args));
-    out.log(`Slept ${args}ms`);
+    // sleep 3 is easily meant as seconds.
+    out.log(Number(args) < 100 ? `Slept ${args}ms (sleep takes milliseconds: sleep ${args}000 is ${args}s)` : `Slept ${args}ms`);
   },
 
   // A stopped upstream does not reach the browser as a failure: the dev proxy
@@ -1992,9 +2304,11 @@ const commands = {
   async requests(args) {
     // --regex <pattern> takes the rest of the line.
     let regex = null;
+    let regexArg = null;
     const text = (args || '').replace(/(?:^|\s)--regex(?:\s+([\s\S]*))?$/, (_, pattern) => {
       if (!pattern?.trim()) throw new Error('Usage: requests [--all] [n] --regex <pattern>');
-      regex = regexOf(patternText(pattern.trim()));
+      regexArg = pattern.trim();
+      regex = regexOf(patternText(regexArg));
       return '';
     });
     const tokens = text.trim().split(/\s+/).filter(Boolean);
@@ -2007,12 +2321,25 @@ const commands = {
     const wanted = regex ? url => regex.test(url) : url => !filter || url.includes(filter);
     const log = recentLogs.get(state.page) || [];
     const shown = everything ? log : log.filter(e => !RECENT_HIDDEN_TYPES.has(e.type) && !e.url.startsWith('chrome-extension://'));
-    const matches = shown.filter(e => wanted(e.url)).slice(-count);
+    const kept = shown.filter(e => wanted(e.url));
+    const matches = kept.slice(-count);
+    const cut = cutNote('requests', matches.length, kept.length, log.dropped, n => `requests${everything ? ' --all' : ''} ${n}${regex ? ` --regex ${regexArg}` : filter ? ` ${filter}` : ''}`);
+    // First, so the list is not read as complete, and its last line is still the latest request.
+    if (cut) out.log(cut);
     if (!matches.length) { out.log(filter ? `No requests matching ${filter}` : 'No requests on the selected tab'); return; }
+    // Where each page load starts, as console marks it, so the requests of one load can be told
+    // apart; from the load the first one shown came from, and whether or not the filter matches it.
+    // Not one answered with no page: the tab stayed on the page it was on.
+    const loads = log.filter(e => e.navigation && !stayedPut(e));
+    let load = loads.filter(e => e.id <= matches[0].id).pop();
     for (const e of matches) {
+      for (const next of loads.filter(n => (!load || n.id > load.id) && n.id <= e.id)) load = next;
+      if (load && !load.marked) out.log(`${clock(load.t)} --- the page loads ${load.url}`);
+      if (load) load.marked = true;
       const ms = e.ms === null ? '-' : `${e.ms}ms`;
-      out.log(`#${e.id} ${clock(e.t)} ${e.method} ${e.status} ${ms} ${e.url}`);
+      out.log(`#${e.id} ${clock(e.t)} ${e.method} ${e.status} ${ms} ${e.type} ${e.url}`);
     }
+    for (const e of loads) delete e.marked;
     // The numbers skip what is hidden; say so, or they look like requests went missing.
     const first = matches[0].id;
     const last = matches[matches.length - 1].id;
@@ -2049,7 +2376,8 @@ const commands = {
     const type = entry.response.headers()['content-type'] || '';
     out.log(`#${id} ${entry.method} ${entry.status} ${entry.url} (${type || 'no content type'}, ${buffer.length} bytes)`);
     if (!buffer.length) return;
-    if (!TEXT_BODY.test(type)) { out.log('[binary body not shown]'); return; }
+    // With no content type, text is told by its bytes: an error page's "not found" often has none.
+    if (!TEXT_BODY.test(type) && (type || !looksLikeText(buffer))) { out.log('[binary body not shown]'); return; }
     let text = buffer.toString('utf8');
     if (/json/.test(type)) { try { text = JSON.stringify(JSON.parse(text), null, 2); } catch {} }
     printOutput(text, all);
@@ -2066,7 +2394,10 @@ const commands = {
       ? e => !filter || e.type.includes(filter) || e.text.includes(filter)
       : e => CONSOLE_LEVELS.indexOf(consoleLevel(e.type)) <= level;
     const logs = consoleLogs.get(state.page) || [];
-    const matches = logs.filter(e => e.type !== 'load' && shown(e)).slice(-count);
+    const kept = logs.filter(e => e.type !== 'load' && shown(e));
+    const matches = kept.slice(-count);
+    const cut = cutNote('messages', matches.length, kept.length, logs.dropped, n => `console ${n}${filter ? ` ${filter}` : ''}`);
+    if (cut) out.log(cut);
     if (!matches.length) { out.log(filter ? `No console messages matching ${filter}` : 'No console messages on the selected tab'); return; }
     // Where the page loaded again, so a message from an earlier load does not read as the current one's.
     // From the load the first message shown came from, if it is still kept.
@@ -2345,4 +2676,4 @@ function complete(line) {
   return [[], current];
 }
 
-module.exports = { commands, cliCommands, needsTab, dialogCommand, listTabs, openTab, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };
+module.exports = { commands, cliCommands, needsTab, dialogCommand, listTabs, openTab, startTabs, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };