pw-repl 0.2.2 → 0.3.1

package/lib/commands.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const { state, withTimeout, onShutdown, shutdown } = require('./state');
 const out = require('./output');
 const HELP = require('./help');
+const { devices } = require('playwright-core');
 const { toSelector, unquote, splitSelector } = require('./syntax');
 
 const { printOutput, OUTPUT_LIMIT } = out;
@@ -143,6 +144,8 @@ async function dialogCommand(args) {
 // 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 = emulations.get(state.page)?.device;
+  if (device) return `${devices[device].viewport.width}x${devices[device].viewport.height} (emulate mobile: ${device})`;
   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);
@@ -166,25 +169,122 @@ function nextScreenshotPath(name) {
   return path.join(SCREENSHOT_DIR, `${filename}.png`);
 }
 
-// Per page: emulation applies to the page its CDP session is attached to.
-const offlineSessions = new WeakMap();
-// Pages whose network is cut.
-const networkCut = new WeakSet();
+// Per page: a CDP session's emulation applies to the page it is attached to
+// and resets, in part, when it detaches, so one is kept for each tab.
+const keptSessions = new WeakMap();
 
-async function setNetwork(p, on) {
-  let session = offlineSessions.get(p);
-  if (!session) {
-    session = await p.context().newCDPSession(p);
-    await session.send('Network.enable');
-    offlineSessions.set(p, session);
-  }
+function keptSession(p) {
+  if (!keptSessions.has(p)) keptSessions.set(p, p.context().newCDPSession(p).catch(error => { keptSessions.delete(p); throw error; }));
+  return keptSessions.get(p);
+}
+
+const networkEnabled = new WeakSet();
+// page -> how its network is changed: { offline: true }, or slowed { latency, down, up } (ms, kbps).
+const networkChanged = new WeakMap();
+// DevTools' "Slow 4G".
+const SLOW_DEFAULT = { latency: 563, down: 1440, up: 675 };
+const SLOW_LATENCY_MAX = 10000;
+
+// setting null restores the network.
+async function setNetwork(p, setting) {
+  const session = await keptSession(p);
+  if (!networkEnabled.has(p)) { await session.send('Network.enable'); networkEnabled.add(p); }
   await session.send('Network.emulateNetworkConditions', {
-    offline: !on,
-    latency: 0,
-    downloadThroughput: -1,
-    uploadThroughput: -1,
+    offline: !!setting?.offline,
+    latency: setting?.latency || 0,
+    // kbps to bytes per second; -1 is no limit.
+    downloadThroughput: setting?.down ? setting.down * 125 : -1,
+    uploadThroughput: setting?.up ? setting.up * 125 : -1,
   });
-  if (on) networkCut.delete(p); else networkCut.add(p);
+  if (setting) networkChanged.set(p, setting); else networkChanged.delete(p);
+}
+
+function networkText(setting) {
+  return setting.offline ? 'off (offline)' : `slow (${setting.latency}ms latency, ${setting.down} kbps down, ${setting.up} kbps up)`;
+}
+
+// page -> what emulate changed: { device, scheme, locale, timezone }, each unset when off.
+const emulations = new WeakMap();
+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);
+}
+
+function deviceNamed(name) {
+  const found = Object.keys(devices).find(d => d.toLowerCase() === name.toLowerCase());
+  if (!found) throw new Error(`No device ${JSON.stringify(name)}; names are Playwright's, e.g. Pixel 7, iPhone 13, iPad Mini, Galaxy S9+`);
+  return found;
+}
+
+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.
+async function setEmulation(p, next) {
+  const session = await keptSession(p);
+  const previous = emulations.get(p) || {};
+  const send = (method, params) => session.send(method, params);
+  if (next.device !== previous.device) {
+    const d = devices[next.device];
+    if (d) {
+      await 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,
+      });
+    } 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) emulations.set(p, next); else emulations.delete(p);
+}
+
+function showEmulation() {
+  const e = emulations.get(state.page);
+  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 => emulations.has(p) && !p.isClosed());
+  await Promise.all(pages.map(p => setEmulation(p, {}).catch(() => {})));
 }
 
 // page -> Map(glob -> { status, body, handler }). Playwright routes are
@@ -197,23 +297,108 @@ function routesFor(p) {
   return pageRoutes.get(p);
 }
 
+const ROUTE_DELAY_MAX = 120;
+
+// Marks a request a route answered, now: the browser reports it finished only later.
+function markChanged(req, status, how) {
+  changedRequests.set(req, how);
+  const entry = requestEntries.get(req);
+  if (entry) { entry.status = `${status} ${how}`; entry.ms = Date.now() - entry.t; }
+}
+
+// A JSON Merge Patch (RFC 7386): objects merge, null removes a key, anything else replaces.
+function mergePatch(target, patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return patch;
+  const result = target && typeof target === 'object' && !Array.isArray(target) ? { ...target } : {};
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) delete result[key];
+    else result[key] = mergePatch(result[key], value);
+  }
+  return result;
+}
+
+function parseJson(text, what) {
+  try { return JSON.parse(text); } catch (error) { throw new Error(`${what} is not valid JSON: ${error.message}`); }
+}
+
+// How a route treats the requests it matches: its text for listing, and what it does to each one.
+function routeKind(how, rest, usage) {
+  if (/^\d{3}$/.test(how)) {
+    const status = Number(how);
+    if (status < 200 || status > 599) throw new Error('Status must be from 200 to 599');
+    if (!rest) throw new Error(usage);
+    parseJson(rest, 'Body');
+    const preview = rest.length > ROUTE_PREVIEW ? `${rest.slice(0, ROUTE_PREVIEW)}…` : rest;
+    return {
+      text: `${status} ${preview}`,
+      async handle(r, req, tag) {
+        markChanged(req, status, 'faked');
+        await r.fulfill({ status, contentType: 'application/json', body: rest });
+        out.notice(`Faked: ${tag()} -> ${status}`);
+      },
+    };
+  }
+  if (how === 'patch') {
+    if (!rest) throw new Error(usage);
+    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) {
+        const response = await r.fetch();
+        let body;
+        try { body = await response.json(); } catch {
+          await r.fulfill({ response });
+          out.notice(`Not patched: ${tag()} — its response is not JSON, so it went through unchanged`);
+          return;
+        }
+        markChanged(req, response.status(), 'patched');
+        await r.fulfill({ response, json: mergePatch(body, patch) });
+        out.notice(`Patched: ${tag()} -> ${response.status()}`);
+      },
+    };
+  }
+  if (how === 'delay') {
+    const seconds = Number(rest);
+    if (!/^\d+(?:\.\d+)?$/.test(rest || '') || seconds <= 0 || seconds > ROUTE_DELAY_MAX) throw new Error(`Usage: route <url-glob> delay <seconds> (up to ${ROUTE_DELAY_MAX})`);
+    return {
+      text: `delay ${seconds}s`,
+      async handle(r, req, tag) {
+        await new Promise(resolve => setTimeout(resolve, seconds * 1000));
+        await r.continue();
+        out.notice(`Delayed ${seconds}s: ${tag()}`);
+      },
+    };
+  }
+  if (how === 'abort' && !rest) {
+    return {
+      text: 'abort',
+      async handle(r, req, tag) {
+        await r.abort('failed');
+        out.notice(`Aborted: ${tag()}`);
+      },
+    };
+  }
+  throw new Error(usage);
+}
+
 function listRoutes() {
   const routes = routesFor(state.page);
+  const forms = [
+    ['route <url-glob> <status> <json-body>', 'answer it with this status and JSON'],
+    ['route <url-glob> patch <json>', 'let it through, then change its JSON'],
+    ['route <url-glob> delay <seconds>', 'hold it, then let it through'],
+    ['route <url-glob> abort', 'fail it as if the connection broke'],
+  ];
   if (!routes.size) {
-    out.log('No fake responses on the selected tab.');
-    out.log(hints([['route <url-glob> <status> <json-body>', 'add one']]));
+    out.log('No routes on the selected tab.');
+    out.log(hints(forms));
     return;
   }
-  out.log(`Fake responses on the selected tab (${routes.size}):`);
+  out.log(`Routes on the selected tab (${routes.size}):`);
   const width = Math.max(...[...routes.keys()].map(glob => glob.length));
-  for (const [glob, { status, body }] of routes) {
-    const preview = body.length > ROUTE_PREVIEW ? `${body.slice(0, ROUTE_PREVIEW)}…` : body;
-    out.log(`  ${glob.padEnd(width)}  ${status}  ${preview}`);
-  }
-  out.log(hints([
-    ['route <url-glob> <status> <json-body>', 'add one, or replace the one for that glob'],
-    ['route off <url-glob> | route off --all', 'remove'],
-  ]));
+  for (const [glob, { text }] of routes) out.log(`  ${glob.padEnd(width)}  ${text}`);
+  out.log(hints([...forms, ['route off <url-glob> | route off --all', 'remove']]));
 }
 
 async function removeRoutes(glob) {
@@ -222,7 +407,7 @@ async function removeRoutes(glob) {
   if (glob !== '--all' && !routes.has(glob)) throw new Error(`No route for ${glob} on the selected tab`);
   const removed = await unroute(state.page, glob === '--all' ? [...routes.keys()] : [glob]);
   for (const g of removed) out.log(`Removed: ${g}`);
-  if (!removed.length) out.log('No fake responses on the selected tab');
+  if (!removed.length) out.log('No routes on the selected tab');
 }
 
 async function unroute(p, globs) {
@@ -246,8 +431,11 @@ const BODY_TIMEOUT = 15000;
 const RECENT_HIDDEN_TYPES = new Set(['image', 'font', 'stylesheet', 'media']);
 const recentLogs = new WeakMap();
 const consoleLogs = new WeakMap();
-const fakedRequests = new WeakSet();
+// request -> how a route changed it (faked or patched), shown after its status.
+const changedRequests = new WeakMap();
 const requestEntries = new WeakMap();
+// page -> when its page last fired its load event.
+const loadedAt = new WeakMap();
 // Tabs this REPL opened with tab new.
 const openedTabs = new WeakSet();
 
@@ -275,7 +463,9 @@ function ensureRecentLog(p) {
   recentLogs.set(p, log);
   consoleLogs.set(p, logs);
   p.on('request', req => {
-    const entry = { id: nextId++, t: Date.now(), method: req.method(), url: req.url(), type: req.resourceType(), status: 'pending', ms: null, response: null };
+    let navigation = false;
+    try { navigation = req.isNavigationRequest() && req.frame() === p.mainFrame(); } catch {}
+    const entry = { id: nextId++, t: Date.now(), method: req.method(), url: req.url(), type: req.resourceType(), status: 'pending', ms: null, response: null, navigation };
     requestEntries.set(req, entry);
     keep(log, entry);
   });
@@ -293,9 +483,10 @@ function ensureRecentLog(p) {
       res = await req.response();
       if (res) status = String(res.status());
     } catch {}
-    finish(req, fakedRequests.has(req) ? `${status} faked` : status, res);
+    finish(req, changedRequests.has(req) ? `${status} ${changedRequests.get(req)}` : status, res);
   });
   p.on('requestfailed', req => finish(req, `failed: ${req.failure()?.errorText || 'unknown'}`));
+  p.on('load', () => loadedAt.set(p, Date.now()));
   p.on('console', msg => keep(logs, { t: Date.now(), type: msg.type(), text: clipText(consoleText(msg)) }));
   // Uncaught exceptions never reach the console event.
   p.on('pageerror', error => keep(logs, { t: Date.now(), type: 'pageerror', text: clipText(error.stack || error.message) }));
@@ -675,7 +866,10 @@ function stopWatching(p, watch) {
 function activeModes(p) {
   const modes = [];
   if (watches.get(p)?.on) modes.push('watch');
-  if (networkCut.has(p)) modes.push('network:off');
+  const network = networkChanged.get(p);
+  if (network) modes.push(network.offline ? 'network:off' : 'network:slow');
+  const emulated = emulatedKinds(emulations.get(p));
+  if (emulated.length) modes.push(`emulate:${emulated.join(',')}`);
   const routes = pageRoutes.get(p)?.size;
   if (routes) modes.push(`routes:${routes}`);
   if (cap && cap.page === p) modes.push('capture');
@@ -693,6 +887,7 @@ function listModes() {
       ['capture on', 'record requests and console messages together'],
       ['route <url-glob> <status> <json-body>', 'fake a response'],
       ['network off', 'cut the tab\'s network'],
+      ['emulate mobile', 'show the tab as a phone would'],
     ]));
     return;
   }
@@ -717,7 +912,8 @@ async function allModesOff() {
       if (cap && cap.page === p) { endCapture(); done.push('capture off (capture shows it)'); }
       const globs = [...(pageRoutes.get(p)?.keys() || [])];
       if (globs.length) { await unroute(p, globs); done.push(`${globs.length} route${globs.length === 1 ? '' : 's'} removed`); }
-      if (networkCut.has(p)) { await setNetwork(p, true); done.push('network on'); }
+      if (networkChanged.has(p)) { await setNetwork(p, null); done.push('network on'); }
+      if (emulations.has(p)) { await setEmulation(p, {}); done.push('emulate off'); }
     } catch (error) {
       problem = error.message;
     }
@@ -728,6 +924,19 @@ async function allModesOff() {
   if (!any) out.log('No modes were on.');
 }
 
+// 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());
@@ -790,6 +999,35 @@ async function waitForRequest(pattern, timeout) {
   }
 }
 
+// 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
+// see the page being left, which has already loaded.
+async function waitForLoad(timeout) {
+  const p = state.page;
+  const since = state.previousCommandAt || 0;
+  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}`);
+    const loaded = navigation ? (loadedAt.get(p) || 0) >= navigation.t : await p.evaluate(() => document.readyState === 'complete').catch(() => false);
+    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));
+  }
+}
+
+// Gone once no match is visible, whether it was removed or hidden.
+async function waitGone(locator, what, timeout) {
+  try {
+    await locator.filter({ visible: true }).first().waitFor({ state: 'detached', timeout });
+  } catch (error) {
+    if (/Timeout \d+ms exceeded/.test(error.message)) throw new Error(`Still visible after ${timeout / 1000}s: ${what}`);
+    throw error;
+  }
+  out.log(`Gone: ${what}`);
+}
+
 const SNAPSHOT_HINT_LINES = 60;
 
 // Each matching line (any part of it: role, name, flags such as [disabled]),
@@ -1089,6 +1327,32 @@ const commands = {
     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);
+    if (!parsed || parsed.rest === undefined) throw new Error('Usage: upload <selector> <file>..., e.g. upload "input[type=file]" photo.png; quote a path with spaces');
+    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(', ')}`);
+  },
+
   async text(args, all) {
     const selector = soleSelector(args, 'text <selector>');
     printOutput(await onElement(selector, () => state.page.innerText(selector, { timeout: 5000 })), all);
@@ -1109,6 +1373,36 @@ const commands = {
     printOutput(result, all);
   },
 
+  // The page's own event listeners on an element, which only DevTools can
+  // list: the element is handed to a CDP session through the page, so any
+  // Playwright selector works, and the session asks for its listeners.
+  async listeners(args, all) {
+    const text = (args || '').trim();
+    const usage = 'listeners <selector> | listeners document | listeners window';
+    if (!text) throw new Error(`Usage: ${usage}`);
+    const which = text === 'document' || text === 'window' ? text : null;
+    const selector = which ? null : soleSelector(args, usage);
+    if (selector) await onElement(selector, () => state.page.locator(selector).first().evaluate(el => { window.__pwReplListenersOf = el; }, null, { timeout: 5000 }));
+    const cdp = await state.page.context().newCDPSession(state.page);
+    try {
+      // 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 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);
+        return `${l.type}${how ? ` (${how})` : ''}: ${handler} (line ${l.lineNumber + 1})`;
+      });
+      printOutput(lines.join('\n'), all);
+    } finally {
+      await cdp.send('Runtime.evaluate', { expression: 'delete window.__pwReplListenersOf' }).catch(() => {});
+      await cdp.send('Runtime.releaseObjectGroup', { objectGroup: 'pw-repl-listeners' }).catch(() => {});
+      await cdp.detach().catch(() => {});
+    }
+  },
+
   async count(args) {
     const selector = soleSelector(args, 'count <selector>');
     const els = await state.page.$$(selector);
@@ -1202,7 +1496,7 @@ 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 = await target.ariaSnapshot({ mode: 'ai', timeout: 5000 });
+    const raw = selector ? await onElement(selector, () => target.ariaSnapshot({ mode: 'ai', timeout: 5000 })) : await target.ariaSnapshot({ mode: 'ai', timeout: 5000 });
     const text = full ? raw : compactSnapshot(raw);
     if (needle !== null) {
       const hits = grepSnapshot(text, needle);
@@ -1218,28 +1512,82 @@ const commands = {
     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 (emulations.get(state.page)?.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 = emulations.get(state.page) || {};
+    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`);
+      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.
+    if (what === 'mobile' || what === 'locale') out.log('The page sees its user agent, touch and languages from its next load: reload to see all of it.');
+  },
+
   async wait(args) {
-    const usage = 'Usage: wait <selector> | wait text <text> | wait request <url-part|glob>, each with optional [seconds]';
+    const usage = 'Usage: wait <selector> | wait text <text> | wait request <url-part|glob> | wait load, with optional [seconds]; --gone for a selector or text';
     let tokens = (args || '').trim().split(/\s+/).filter(Boolean);
+    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());
     if (!tokens.length || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
     const timeout = seconds * 1000;
     const kind = tokens[0];
+    if (kind === 'load' && tokens.length === 1) {
+      if (gone) throw new Error(usage);
+      return waitForLoad(timeout);
+    }
     if ((kind === 'text' || kind === 'request') && tokens.length > 1) {
       const what = tokens.slice(1).join(' ').replace(/^(["'])(.*)\1$/, '$2').replace(/\\"/g, '"');
-      if (kind === 'text') {
-        await state.page.getByText(what).first().waitFor({ state: 'visible', timeout });
-        out.log(`Visible: ${what}`);
-        return;
+      if (kind === 'request') {
+        if (gone) throw new Error(usage);
+        return waitForRequest(what, timeout);
       }
-      return waitForRequest(what, timeout);
+      if (gone) return waitGone(state.page.getByText(what), what, timeout);
+      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout });
+      out.log(`Visible: ${what}`);
+      return;
     }
     const selector = toSelector(unquote(tokens.join(' ')));
+    if (gone) return waitGone(state.page.locator(selector), tokens.join(' '), timeout);
     await state.page.waitForSelector(selector, { state: 'attached', timeout });
     out.log(`Found: ${tokens.join(' ')}`);
   },
@@ -1253,22 +1601,28 @@ const commands = {
   // A stopped upstream does not reach the browser as a failure: the dev proxy
   // holds the request open instead of refusing it. Cutting the connection at
   // the browser is what a visitor's wifi or VPN dropping looks like to the page.
-  // The CDP session is kept alive because emulation resets when it detaches.
   async network(args) {
-    const arg = (args || '').trim().toLowerCase();
-    if (!arg) {
-      if (networkCut.has(state.page)) {
-        out.log('The selected tab\'s network is off (offline).');
-        out.log(hints([['network on', 'restore it']]));
-      } else {
-        out.log('The selected tab\'s network is on.');
-        out.log(hints([['network off', 'cut it, like dropped wifi']]));
-      }
+    const words = (args || '').trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const setting = networkChanged.get(state.page);
+    if (!words.length) {
+      out.log(`The selected tab's network is ${setting ? networkText(setting) : 'on'}.`);
+      if (setting) out.log(hints([['network on', 'restore it']]));
+      else out.log(hints([['network off', 'cut it, like dropped wifi'], ['network slow [<ms> [<kbps>]]', `slow it (default ${networkText(SLOW_DEFAULT).slice(6, -1)})`]]));
       return;
     }
-    if (arg !== 'on' && arg !== 'off') throw new Error('Usage: network [on|off]');
-    await setNetwork(state.page, arg === 'on');
-    out.log(`The selected tab's network is ${arg}`);
+    const [how, ...rest] = words;
+    if ((how === 'on' || how === 'off') && !rest.length) {
+      await setNetwork(state.page, how === 'on' ? null : { offline: true });
+      out.log(`The selected tab's network is ${how}`);
+      return;
+    }
+    const usage = `Usage: network [on | off | slow [<latency-ms> [<kbps>]]] (latency up to ${SLOW_LATENCY_MAX}ms)`;
+    if (how !== 'slow' || rest.length > 2 || !rest.every(w => /^\d+$/.test(w))) throw new Error(usage);
+    const [latency, kbps] = rest.map(Number);
+    if (latency > SLOW_LATENCY_MAX || kbps === 0) throw new Error(usage);
+    const slow = rest.length ? { latency, down: kbps || SLOW_DEFAULT.down, up: kbps || SLOW_DEFAULT.up } : SLOW_DEFAULT;
+    await setNetwork(state.page, slow);
+    out.log(`The selected tab's network is ${networkText(slow)}`);
   },
 
   // Fulfilled inside the browser, so the page's own code handles the fake
@@ -1278,35 +1632,28 @@ const commands = {
     if (!trimmed) return listRoutes();
     const off = /^off(?:\s+(\S+))?$/.exec(trimmed);
     if (off) return removeRoutes(off[1]);
-    const match = /^(\S+)\s+(\d{3})\s+([\s\S]+)$/.exec(trimmed);
-    if (!match) throw new Error('Usage: route <url-glob> <status> <json-body> | route off <url-glob>|--all');
-    const [, glob, statusText, body] = match;
-    const status = Number(statusText);
-    if (status < 200 || status > 599) throw new Error('Status must be from 200 to 599');
-    try { JSON.parse(body); } catch (error) { throw new Error(`Body is not valid JSON: ${error.message}`); }
+    const usage = 'Usage: route <url-glob> <status> <json-body> | route <url-glob> patch <json> | route <url-glob> delay <seconds> | route <url-glob> abort | route off <url-glob>|--all';
+    const match = /^(\S+)\s+(\S+)(?:\s+([\s\S]+))?$/.exec(trimmed);
+    if (!match) throw new Error(usage);
+    const [, glob, how, rest] = match;
+    const route = routeKind(how, rest, usage);
     const routes = routesFor(state.page);
     const previous = routes.get(glob);
     if (previous) await state.page.unroute(glob, previous.handler);
     const handler = async r => {
       const req = r.request();
-      fakedRequests.add(req);
+      const tag = () => { const id = requestEntries.get(req)?.id; return `${id ? `#${id} ` : ''}${req.method()} ${req.url()}`; };
       try {
-        await r.fulfill({ status, contentType: 'application/json', body });
-        // Recorded now: the browser reports the request finished only later.
-        const entry = requestEntries.get(req);
-        if (entry) { entry.status = `${status} faked`; entry.ms = Date.now() - entry.t; }
-        const id = entry?.id;
-        out.notice(`Faked: ${id ? `#${id} ` : ''}${req.method()} ${req.url()} -> ${status}`);
+        await route.handle(r, req, tag);
       } catch (error) {
-        // Aborted, never continued: a request meant to be faked must not reach the network.
+        // Aborted, never continued: a request meant to be changed must not reach the page as it was.
         await r.abort().catch(() => {});
-        const id = requestEntries.get(req)?.id;
-        out.notice(`Fake failed: ${id ? `#${id} ` : ''}${req.method()} ${req.url()} — ${error.message}; the request was aborted`);
+        out.notice(`Route failed: ${tag()} — ${error.message}; the request was aborted`);
       }
     };
     await state.page.route(glob, handler);
-    routes.set(glob, { status, body, handler });
-    out.log(`${previous ? 'Replaced' : 'Routed'}: ${glob} -> ${status}`);
+    routes.set(glob, { text: route.text, handler });
+    out.log(`${previous ? 'Replaced' : 'Routed'}: ${glob} -> ${route.text}`);
   },
 
   async requests(args) {
@@ -1340,7 +1687,7 @@ const commands = {
     const entry = (recentLogs.get(state.page) || []).find(e => e.id === id);
     if (!entry) throw new Error(`No request #${id} on the selected tab; requests lists them`);
     // A fake is marked answered before the browser hands over its response.
-    for (let waited = 0; !entry.response && /faked$/.test(entry.status) && waited < 2000; waited += 50) {
+    for (let waited = 0; !entry.response && /(?:faked|patched)$/.test(entry.status) && waited < 2000; waited += 50) {
       await new Promise(resolve => setTimeout(resolve, 50));
     }
     if (!entry.response) throw new Error(`#${id} has no response${entry.status === 'pending' ? ' yet' : ` (${entry.status})`}`);
@@ -1511,6 +1858,7 @@ const commands = {
 };
 
 onShutdown(discardCapture);
+onShutdown(resetEmulations);
 
 // Hooks every page needs from the moment the REPL sees it.
 function watchPage(p) {
@@ -1533,7 +1881,9 @@ function complete(line) {
   if (words.length === 2) {
     if (command === 'help') return match(['--all', ...Object.keys(HELP.TOPICS), ...Object.keys(HELP.COMMANDS).sort()]);
     if (command === 'tab') return match(['new', 'close']);
-    if (command === 'network') return match(['on', 'off']);
+    if (command === 'network') return match(['on', 'off', 'slow']);
+    if (command === 'emulate') return match([...EMULATE_KINDS, 'off']);
+    if (command === 'wait') return match(['text', 'request', 'load']);
     if (command === 'modes') return match(['off']);
     if (command === 'dialog') return match(['accept', 'dismiss']);
     if (command === 'watch') return match(['on', 'off', 'new', '--all']);
@@ -1542,6 +1892,7 @@ function complete(line) {
   }
   if (words.length >= 3 && command === 'watch' && words[1] === 'on') return match(['--changes', '--live'].filter(f => !words.slice(2, -1).includes(f)));
   if (words.length === 3 && command === 'capture' && words[1] === 'on') return match(['requests', 'console']);
+  if (words.length === 3 && command === 'emulate' && EMULATE_KINDS.includes(words[1])) return match(['off']);
   if (words.length === 3 && command === 'route' && words[1] === 'off') return match(['--all', ...(state.page ? routesFor(state.page).keys() : [])]);
   return [[], current];
 }