pw-repl 0.4.2 → 0.6.0

package/lib/dialogs.js

@@ -0,0 +1,58 @@
+// Dialogs: each tab's handler, and answering one ahead of the command queue.
+const { state } = require('./state');
+const out = require('./output');
+const { OUTPUT_LIMIT } = out;
+const { unquote } = require('./syntax');
+const { hints } = require('./util');
+const { tabState } = require('./tabstate');
+
+// page -> its open dialog. The page, and every command that reads it, waits
+// until the dialog is answered, in the browser or with the dialog command.
+const openDialogs = new Map();
+
+function ensureDialogHandler(p) {
+  if ('dialogHandled' in tabState(p)) return;
+  tabState(p).dialogHandled = true;
+  p.on('dialog', dialog => {
+    openDialogs.set(p, dialog);
+    out.notice(`Dialog [${dialog.type()}]: ${String(dialog.message()).slice(0, OUTPUT_LIMIT)}`, p);
+    out.notice('It waits to be answered in the browser, or with dialog accept [text] | dialog dismiss; until then the page, and commands that read it, wait too.', p);
+  });
+  p.on('close', () => openDialogs.delete(p));
+}
+
+// Runs ahead of the command queue (see runner.js), so it still works while
+// commands wait on the dialog; it returns its output rather than printing it.
+async function dialogCommand(args, selected = state.page) {
+  const [action, ...rest] = (args || '').trim().split(/\s+/).filter(Boolean);
+  const pages = state.browser.contexts().flatMap(c => c.pages());
+  for (const p of openDialogs.keys()) if (p.isClosed() || !pages.includes(p)) openDialogs.delete(p);
+  const describe = (p, d) => `[${pages.indexOf(p)}] ${p.url()}: ${d.type()} ${JSON.stringify(String(d.message()).slice(0, 200))}`;
+  if (!action) {
+    if (!openDialogs.size) return 'No dialog is open.';
+    return [...[...openDialogs].map(([p, d]) => describe(p, d)), hints([['dialog accept [text]', 'accept it (text answers a prompt)'], ['dialog dismiss', 'dismiss it']])].join('\n');
+  }
+  if (action !== 'accept' && action !== 'dismiss') throw new Error('Usage: dialog [accept [text] | dismiss]');
+  // The selected tab's dialog, or the only one open.
+  const page = openDialogs.has(selected) ? selected : openDialogs.size === 1 ? [...openDialogs.keys()][0] : null;
+  if (!page) throw new Error(openDialogs.size ? 'Several tabs have a dialog open; select one with tab <index|url-part> first' : 'No dialog is open.');
+  const dialog = openDialogs.get(page);
+  openDialogs.delete(page);
+  const line = describe(page, dialog);
+  try {
+    if (action === 'accept') await dialog.accept(rest.length ? unquote(rest.join(' ')) : undefined);
+    else await dialog.dismiss();
+  } catch (error) {
+    // Answered in the browser meanwhile.
+    return `No dialog is open (${error.message.split('\n')[0]})`;
+  }
+  return `${action === 'accept' ? 'Accepted' : 'Dismissed'}: ${line}`;
+}
+
+const commands = {
+  async dialog(args) {
+    out.log(await dialogCommand(args));
+  },
+};
+
+module.exports = { commands, ensureDialogHandler, dialogCommand };

package/lib/elements.js

@@ -0,0 +1,360 @@
+// Elements and the mouse: finding the match to act on, and the commands that click, type and choose.
+const path = require('path');
+const fs = require('fs');
+const { state } = require('./state');
+const out = require('./output');
+const { takeOptions } = require('./cli-names');
+const { unquote, toSelector, keyName, splitSelector, REF } = require('./syntax');
+const { numbers } = require('./util');
+
+// The type a page sees for a file it is given, from its extension.
+const MIME_TYPES = {
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml',
+  pdf: 'application/pdf', txt: 'text/plain', csv: 'text/csv', json: 'application/json', html: 'text/html',
+  xml: 'application/xml', zip: 'application/zip', mp4: 'video/mp4', webm: 'video/webm', mp3: 'audio/mpeg',
+  wav: 'audio/wav', doc: 'application/msword', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+};
+
+function mimeType(file) {
+  return MIME_TYPES[path.extname(file).slice(1).toLowerCase()] || 'application/octet-stream';
+}
+
+// Commands that take only a selector take the whole line, spaces and all.
+function soleSelector(args, usage) {
+  const text = unquote((args || '').trim());
+  if (!text) throw new Error(`Usage: ${usage}`);
+  return toSelector(text);
+}
+
+const MODIFIERS = ['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift'];
+
+// click <selector> [button] [--modifiers=<keys>], as playwright-cli's click
+// takes them. The button is read only after a ref or a quoted selector, so
+// click text=Turn right is still one selector.
+function clickArgs(args, usage) {
+  // Found outside quotes only, so a quoted selector keeps whatever is in it.
+  const { found, rest: text } = takeOptions((args || '').trim(), { modifiers: 'value' });
+  const modifiers = found.flatMap(o => (o.value || '').split(',').filter(Boolean).map(keyName));
+  const unknown = modifiers.find(m => !MODIFIERS.includes(m));
+  if (unknown) throw new Error(`Not a modifier: ${unknown}; they are ${MODIFIERS.join(', ')}`);
+  const parsed = splitSelector(text);
+  const button = parsed && /^(?:left|right|middle)$/.test(parsed.rest || '') && (REF.test(parsed.word) || /^["']/.test(text)) ? parsed.rest : null;
+  const selector = button ? parsed.selector : soleSelector(text, usage);
+  const options = { ...(button ? { button } : {}), ...(modifiers.length ? { modifiers } : {}) };
+  return { selector, shown: args.trim(), options };
+}
+
+// A trailing --submit, as playwright-cli's fill and type take: Enter afterwards.
+function submitFlag(args) {
+  if (/(?:^|\s)--submit\s/.test((args || '').trim())) throw new Error('--submit goes at the end of the line');
+  const match = /^([\s\S]*?)\s+--submit$/.exec((args || '').trim());
+  return match ? { args: match[1], submit: true } : { args, submit: false };
+}
+
+function selectorAndValue(args, usage, example) {
+  const parsed = splitSelector(args);
+  if (!parsed || parsed.rest === undefined) {
+    throw new Error(`Usage: ${usage}, e.g. ${example}; quote a selector with spaces: "text=Your name"`);
+  }
+  return { selector: parsed.selector, value: unquote(parsed.rest), shown: parsed.word };
+}
+
+// An element that never appeared is said plainly, not as Playwright's call
+// 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) {
+    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 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 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(() => {});
+    }
+  }
+}
+
+const commands = {
+  async click(args) {
+    const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--modifiers=<key>[,<key>]]');
+    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>]]');
+    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>');
+    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) {
+    const { args, submit } = submitFlag(line);
+    const { selector, value, shown } = selectorAndValue(args, 'fill <selector> <value> [--submit]', 'fill #name Ada Lovelace');
+    await onElement(selector, () => state.page.fill(selector, value, { timeout: 5000 }));
+    if (submit) await state.page.press(selector, 'Enter', { timeout: 5000 });
+    out.log(`Filled${submit ? ' and submitted' : ''}: ${shown}`);
+  },
+
+  async type(line) {
+    const { args, submit } = submitFlag(line);
+    // One word, or one quoted, is typed into the focused element, as playwright-cli's type does.
+    const sole = splitSelector(args);
+    if (sole && sole.rest === undefined) {
+      // Named, since it may not be the element meant; one that takes no text is refused.
+      const focused = await state.page.evaluate(() => {
+        const el = document.activeElement;
+        if (!el || el === document.body || el === document.documentElement) return null;
+        const editable = el.isContentEditable || el.matches('textarea, input:not([type=checkbox],[type=radio],[type=button],[type=submit],[type=reset],[type=image],[type=file],[type=range],[type=color],[type=hidden])');
+        const id = el.id ? `#${el.id}` : el.name ? `[name=${el.name}]` : el.placeholder ? `[placeholder="${el.placeholder}"]` : '';
+        return { editable, name: `${el.tagName.toLowerCase()}${id}` };
+      });
+      const usage = 'type <selector> <text> types into an element, e.g. type #search garden hose';
+      if (!focused) throw new Error(`Nothing on the page has focus: ${usage}`);
+      if (!focused.editable) throw new Error(`The focused element, ${focused.name}, takes no text: ${usage}`);
+      await state.page.keyboard.type(sole.word);
+      if (submit) await state.page.keyboard.press('Enter');
+      out.log(`Typed into the focused ${focused.name}${submit ? ', and submitted' : ''}`);
+      return;
+    }
+    const { selector, value, shown } = selectorAndValue(args, 'type [<selector>] <text> [--submit]', 'type #search garden hose');
+    // Typed after what the field already holds, as someone clicking into it
+    // at the end would; focusing it alone leaves the caret at the start.
+    await onElement(selector, () => state.page.locator(selector).first().evaluate(el => {
+      el.focus();
+      if (typeof el.value === 'string' && typeof el.setSelectionRange === 'function') {
+        try { el.setSelectionRange(el.value.length, el.value.length); } catch {}
+      } else if (el.isContentEditable) {
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        range.collapse(false);
+        getSelection().removeAllRanges();
+        getSelection().addRange(range);
+      }
+    }, null, { timeout: 5000 }));
+    await state.page.keyboard.type(value);
+    if (submit) await state.page.keyboard.press('Enter');
+    out.log(`Typed into${submit ? ' and submitted' : ''}: ${shown}`);
+  },
+
+  async press(args) {
+    const parsed = splitSelector(args);
+    if (!parsed) throw new Error('Usage: press <key> | press <selector> <key>, e.g. press Enter or press #name Enter');
+    if (parsed.rest === undefined) {
+      await state.page.keyboard.press(keyName(parsed.word));
+      out.log(`Pressed: ${keyName(parsed.word)}`);
+      return;
+    }
+    const key = keyName(unquote(parsed.rest));
+    await onElement(parsed.selector, () => state.page.press(parsed.selector, key, { timeout: 5000 }));
+    out.log(`Pressed ${key} on ${parsed.word}`);
+  },
+
+  async select(args) {
+    const { selector, value, shown } = selectorAndValue(args, 'select <selector> <value>', 'select #country Canada');
+    await onElement(selector, () => state.page.selectOption(selector, value, { timeout: 5000 }));
+    out.log(`Selected "${value}" in ${shown}`);
+  },
+
+  async check(args) {
+    const selector = soleSelector(args, 'check <selector>');
+    await onElement(selector, () => state.page.check(selector, { timeout: 5000 }));
+    out.log(`Checked: ${args.trim()}`);
+  },
+
+  async uncheck(args) {
+    const selector = soleSelector(args, 'uncheck <selector>');
+    await onElement(selector, () => state.page.uncheck(selector, { timeout: 5000 }));
+    out.log(`Unchecked: ${args.trim()}`);
+  },
+
+  // The files are read here and handed to the page as their contents, not
+  // their paths: the browser may run on another machine, or in another
+  // container, where the paths mean nothing.
+  async upload(args) {
+    const parsed = splitSelector(args);
+    // playwright-cli's upload <file> answers a file picker a click opened. Here
+    // the input is named instead: catching pickers would catch the person's too.
+    const usage = 'Usage: upload <selector> <file>..., naming the file input (or the button that opens it) first, e.g. upload e12 ./doc.pdf; quote a path with spaces';
+    if (!parsed || parsed.rest === undefined) throw new Error(usage);
+    // A path, not a selector; // starts an XPath.
+    if (/^(?:\.{1,2}\/|\/(?!\/)|~)/.test(parsed.word) || (!REF.test(parsed.word) && fs.statSync(path.resolve(parsed.word), { throwIfNoEntry: false })?.isFile())) throw new Error(`${parsed.word} is a file, not the input: ${usage.slice(7)}`);
+    const files = [...parsed.rest.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+)/g)].map(m => path.resolve(m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1') : m[2] ?? m[3]));
+    const payloads = files.map(file => {
+      let buffer;
+      try { buffer = fs.readFileSync(file); } catch (error) { throw new Error(`Cannot read ${file}: ${error.code === 'ENOENT' ? 'no such file' : error.code === 'EISDIR' ? 'it is a folder' : error.message}`); }
+      return { name: path.basename(file), mimeType: mimeType(file), buffer };
+    });
+    const { selector } = parsed;
+    await onElement(selector, async () => {
+      try {
+        await state.page.setInputFiles(selector, payloads, { timeout: 5000 });
+      } catch (error) {
+        if (!/not an HTMLInputElement/.test(error.message)) throw error;
+        // A button that opens the file picker itself: click it, and answer the picker.
+        const [chooser] = await Promise.all([state.page.waitForEvent('filechooser', { timeout: 5000 }), state.page.click(selector, { timeout: 5000 })]);
+        await chooser.setFiles(payloads);
+      }
+    });
+    out.log(`Chose ${files.length === 1 ? 'a file' : `${files.length} files`} in ${parsed.word}: ${files.join(', ')}`);
+  },
+};
+
+module.exports = { commands, soleSelector, onElement };

package/lib/emulation.js

@@ -0,0 +1,180 @@
+// Emulating a phone, a color scheme, a locale or a timezone in a tab, and its viewport.
+const { state, onShutdown } = require('./state');
+const out = require('./output');
+const { devices } = require('playwright-core');
+const { hints } = require('./util');
+const { tabState } = require('./tabstate');
+const { keptSession } = require('./cdp');
+
+// A tab in a browser the REPL connected to has no viewport set, so its size is
+// the window's; it is read from the page.
+async function viewportText() {
+  const device = tabState(state.page).emulation?.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';
+}
+
+const DEFAULT_DEVICE = 'Pixel 7';
+const EMULATE_KINDS = ['mobile', 'dark', 'light', 'locale', 'timezone'];
+
+function emulatedKinds(e) {
+  return [e?.device && 'mobile', e?.scheme, e?.locale && 'locale', e?.timezone && 'timezone'].filter(Boolean);
+}
+
+const DEVICES_SHOWN = 20;
+
+function deviceNamed(name) {
+  const names = Object.keys(devices);
+  const found = names.find(d => d.toLowerCase() === name.toLowerCase());
+  if (found) return found;
+  // The names that have every word typed, so a near miss finds the exact name.
+  const words = name.toLowerCase().split(/\s+/);
+  const close = names.filter(d => !/ landscape$/.test(d) && words.every(w => d.toLowerCase().includes(w)));
+  if (!close.length) throw new Error(`No device ${JSON.stringify(name)}; names are Playwright's, e.g. Pixel 7, iPhone 13, iPad Mini, Galaxy S9+`);
+  const more = close.length > DEVICES_SHOWN ? `, and ${close.length - DEVICES_SHOWN} more` : '';
+  throw new Error(`No device ${JSON.stringify(name)}; matching: ${close.slice(0, DEVICES_SHOWN).join(', ')}${more} (each also as "<name> landscape")`);
+}
+
+function deviceText(name) {
+  const d = devices[name];
+  return `${name}, ${d.viewport.width}x${d.viewport.height} at ${d.deviceScaleFactor}x${d.hasTouch ? ', touch' : ''}`;
+}
+
+// Sends only what changed. Chrome takes the user agent and the languages
+// together, so a change to either sends both.
+function deviceMetrics(session, name) {
+  const d = devices[name];
+  return session.send('Emulation.setDeviceMetricsOverride', {
+    width: d.viewport.width, height: d.viewport.height, deviceScaleFactor: d.deviceScaleFactor, mobile: d.isMobile,
+    screenWidth: d.screen?.width || d.viewport.width, screenHeight: d.screen?.height || d.viewport.height,
+  });
+}
+
+async function setEmulation(p, next) {
+  const session = await keptSession(p);
+  const previous = tabState(p).emulation || {};
+  const send = (method, params) => session.send(method, params);
+  if (next.device !== previous.device) {
+    const d = devices[next.device];
+    if (d) {
+      await deviceMetrics(session, next.device);
+    } else {
+      await send('Emulation.clearDeviceMetricsOverride');
+    }
+    await send('Emulation.setTouchEmulationEnabled', d?.hasTouch ? { enabled: true, maxTouchPoints: 5 } : { enabled: false });
+  }
+  if (next.device !== previous.device || next.locale !== previous.locale) {
+    if (next.device || next.locale) {
+      const userAgent = next.device ? devices[next.device].userAgent : (await send('Browser.getVersion')).userAgent;
+      await send('Emulation.setUserAgentOverride', { userAgent, ...(next.locale ? { acceptLanguage: next.locale } : {}) });
+    } else {
+      // An empty user agent ends the override.
+      await send('Emulation.setUserAgentOverride', { userAgent: '' });
+    }
+  }
+  if (next.locale !== previous.locale) await send('Emulation.setLocaleOverride', next.locale ? { locale: next.locale } : {});
+  if (next.timezone !== previous.timezone) await send('Emulation.setTimezoneOverride', { timezoneId: next.timezone || '' });
+  if (next.scheme !== previous.scheme) await send('Emulation.setEmulatedMedia', { features: next.scheme ? [{ name: 'prefers-color-scheme', value: next.scheme }] : [] });
+  if (emulatedKinds(next).length) tabState(p).emulation = { ...next, owner: state.client }; else delete tabState(p).emulation;
+}
+
+function showEmulation() {
+  const e = tabState(state.page).emulation;
+  const forms = [
+    ['emulate mobile [device]', `a phone's screen, touch and user agent (default ${DEFAULT_DEVICE})`],
+    ['emulate dark | light', 'the color scheme the page sees'],
+    ['emulate locale <tag>', 'its language and formats, e.g. fr-FR'],
+    ['emulate timezone <zone>', 'e.g. Asia/Tokyo'],
+  ];
+  if (!e) {
+    out.log('Nothing is emulated in the selected tab.');
+    out.log(hints(forms));
+    return;
+  }
+  out.log('Emulated in the selected tab:');
+  const rows = [
+    e.device && ['mobile', deviceText(e.device)],
+    e.scheme && ['color scheme', e.scheme],
+    e.locale && ['locale', e.locale],
+    e.timezone && ['timezone', e.timezone],
+  ].filter(Boolean);
+  for (const [what, value] of rows) out.log(`  ${what.padEnd(12)}  ${value}`);
+  out.log(hints([...forms, ['emulate <what> off | emulate off', 'stop one, or all']]));
+}
+
+// Resets every tab's emulation, which detaching would only partly undo.
+async function resetEmulations() {
+  if (!state.browser || state.connectionLost) return;
+  const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => 'emulation' in tabState(p) && !p.isClosed());
+  await Promise.all(pages.map(p => setEmulation(p, {}).catch(() => {})));
+}
+
+onShutdown(resetEmulations);
+
+const commands = {
+  async viewport(args) {
+    if (!args) { out.log(await viewportText()); return; }
+    const [w, h] = args.split('x').map(Number);
+    if (!w || !h) throw new Error('Usage: viewport <width>x<height>');
+    // Both set the screen size; whichever came last would win without saying so.
+    if (tabState(state.page).emulation?.device) throw new Error('emulate mobile sets the size of the selected tab; emulate mobile off first');
+    await state.page.setViewportSize({ width: w, height: h });
+    out.log(`Viewport set to ${w}x${h}`);
+  },
+
+  // Per tab, like network: the settings live in the tab's kept CDP session.
+  async emulate(args) {
+    const words = (args || '').trim().split(/\s+/).filter(Boolean);
+    if (!words.length) return showEmulation();
+    const usage = 'Usage: emulate [mobile [device] | dark | light | locale <tag> | timezone <zone>], emulate <what> off, emulate off';
+    const [what, ...rest] = words;
+    const value = rest.join(' ');
+    const current = tabState(state.page).emulation || {};
+    if (what === 'off' && !rest.length) {
+      const was = emulatedKinds(current);
+      await setEmulation(state.page, {});
+      out.log(was.length ? `Stopped emulating in the selected tab: ${was.join(', ')}` : 'Nothing was emulated in the selected tab.');
+      return;
+    }
+    if (!EMULATE_KINDS.includes(what)) throw new Error(usage);
+    const key = { mobile: 'device', dark: 'scheme', light: 'scheme', locale: 'locale', timezone: 'timezone' }[what];
+    if (value === 'off') {
+      await setEmulation(state.page, { ...current, [key]: undefined });
+      out.log(`Stopped emulating ${key === 'scheme' ? 'the color scheme' : what} in the selected tab`);
+      // As when turned on: the page keeps what it read at load until it loads again.
+      if ((what === 'mobile' || what === 'locale') && state.page.url() !== 'about:blank') out.log('The page sees its own user agent, touch and languages again from its next load: reload to see all of it.');
+      return;
+    }
+    let next;
+    if (what === 'mobile') {
+      next = deviceNamed(value || DEFAULT_DEVICE);
+    } else if (what === 'dark' || what === 'light') {
+      if (value) throw new Error(usage);
+      next = what;
+    } else if (!value || rest.length > 1) {
+      throw new Error(`Usage: emulate ${what} ${what === 'locale' ? '<tag>, e.g. fr-FR' : '<zone>, e.g. Asia/Tokyo'}`);
+    } else if (what === 'locale') {
+      try { next = Intl.getCanonicalLocales(value)[0]; } catch { throw new Error(`Not a locale: ${value}; e.g. fr-FR, de, pt-BR`); }
+    } else {
+      // Checked, but kept as given: Node's names can be older ones (Asia/Calcutta for Asia/Kolkata).
+      try { new Intl.DateTimeFormat('en-US', { timeZone: value }); } catch { throw new Error(`Not a timezone: ${value}; e.g. Asia/Tokyo, America/New_York, UTC`); }
+      next = value;
+    }
+    await setEmulation(state.page, { ...current, [key]: next });
+    const shown = what === 'mobile' ? `mobile (${deviceText(next)})` : what === 'dark' || what === 'light' ? `${what} mode` : `${what} ${next}`;
+    out.log(`Emulating ${shown} in the selected tab`);
+    // The page reads these when it loads; the rest applies at once. A blank tab has nothing to reload.
+    if ((what === 'mobile' || what === 'locale') && state.page.url() !== 'about:blank') out.log('The page sees its user agent, touch and languages from its next load: reload to see all of it.');
+  },
+};
+
+module.exports = { commands, viewportText, EMULATE_KINDS, emulatedKinds, deviceMetrics, setEmulation };