pw-repl 0.3.0 → 0.3.1

package/AGENTS.md

@@ -11,13 +11,17 @@ If you hit a limitation or write a workaround, consider adding the capability to
 - A command is a function in the `commands` object in `lib/commands.js`, plus an entry in `lib/help.js`
   under one topic.
 - `bin/pw-repl.js` is the command line; `lib/start.js` connects and runs the prompt; `lib/runner.js`
-  runs commands one at a time; `lib/server.js` is the opt-in server; `lib/send.js` and `lib/client.js`
-  are `send` and `where`; `lib/output.js` routes all output so the server can return it.
+  runs commands one at a time (`quit` and `dialog` skip its queue); `lib/server.js` is the command
+  server; `lib/send.js` and `lib/client.js` are `send` and `where`; `lib/background.js` is
+  `serve --background`, `attach` and `stop`; `lib/launch.js` is `--launch`; `lib/syntax.js` is how a
+  command line's words are read, shared with `send`; `lib/state.js` holds the session state;
+  `lib/output.js` routes all output so the server can return it.
 - Comment the *why* when it isn't obvious from the code.
-- `npm test` runs the suite (about 40s): a private headless Chromium, a local test site, and the real
-  REPL with its server. Nothing is mocked, and the shared browser is never touched. It finds Chromium
-  through `PW_TEST_CHROME` or Playwright's installed browsers, and skips the browser tests if there is
-  none. Add a test with each new command or behaviour.
+- `npm test` runs the suite (about a minute): a private headless Chromium, a local test site
+  (`test/harness.js`), and the real REPL with its server. Nothing is mocked, and the shared browser is
+  never touched. It finds Chromium through `PW_TEST_CHROME`, or where `--launch` looks (Playwright's
+  browsers, then the `PATH`), and skips the browser tests if there is none. Add a test with each new
+  command or behaviour.
 - For anything the tests can't reach, exercise the change in a running REPL. Use your own tmux session
   and a new tab, not the user's.
 - `skill/SKILL.md` is how agents learn to use the REPL: keep it in step with a change to how it is

package/README.md

@@ -71,6 +71,9 @@ Commands act on the selected tab (`tab` lists the tabs, with `*` on the selected
 | see where I am                       | `tab`, `info`                                                                         |
 | see what is on the page              | `snapshot`, `screenshot`                                                              |
 | do something on it                   | `click`, `fill`, `press`                                                              |
+| wait for a page or element           | `wait load`, `wait <selector>`, `wait <selector> --gone`                              |
+| choose a file in a file input        | `upload <selector> <file>`                                                            |
+| see it as a phone, or in dark mode   | `emulate mobile`, `emulate dark` (also `emulate locale`, `emulate timezone`)          |
 | see what the page requested          | `requests`, then `body <#>` for what one got back                                     |
 | see console messages and errors      | `console`                                                                             |
 | show an agent what I do              | `watch on`, click around in the browser, then `watch`                                 |
@@ -78,19 +81,20 @@ Commands act on the selected tab (`tab` lists the tabs, with `*` on the selected
 | record requests and console together | `capture on`, then `capture off`                                                      |
 | break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `route <glob> abort`, `network off` |
 | change or slow an API response       | `route <glob> patch <json>`, `route <glob> delay <secs>`                              |
+| slow the whole network               | `network slow`                                                                        |
 | clean up                             | `modes off`                                                                           |
 
 Everything else is in `help <topic>`; `help <command>` has usage and caveats.
 
 ### Modes
 
-`watch`, `capture`, `route` and `network off` stay on until you turn them off: `watch on|off`,
-`capture on|off`, `route ...|route off`, `network off|on`. While any are on in the selected tab, the prompt
-shows them: `(watch network:off routes:2) pw>`. `modes` lists them for every tab, and `modes off` turns them
-all off.
+`watch`, `capture`, `route`, `network off` or `slow`, and `emulate` stay on until you turn them off:
+`watch on|off`, `capture on|off`, `route ...|route off`, `network off|slow|on`, `emulate ...|emulate off`.
+While any are on in the selected tab, the prompt shows them: `(watch network:off routes:2) pw>`. `modes`
+lists them for every tab, and `modes off` turns them all off.
 
-`tab`, `watch`, `capture`, `route`, `network` and `modes` on their own show their state and what you can
-run next.
+`tab`, `watch`, `capture`, `route`, `network`, `emulate` and `modes` on their own show their state and what
+you can run next.
 
 ## Options
 
@@ -156,6 +160,6 @@ The same text is in `skill/SKILL.md`. Working on the REPL itself: see `AGENTS.md
 npm test
 ```
 
-Runs against a private headless Chromium it starts itself (via `PW_TEST_CHROME`, or Playwright's installed
-browsers: `npx playwright-core install chromium`) and a local test site; the browser tests are skipped when no
-Chromium is found.
+Runs against a private headless Chromium it starts itself (`PW_TEST_CHROME`, or the one `--launch` would
+use: Playwright's, e.g. from `npx playwright-core install chromium`, then one on the `PATH`) and a local
+test site; the browser tests are skipped when no Chromium is found.

package/bin/pw-repl.js

@@ -79,7 +79,9 @@ function parseSendArgs(args, allowCommand) {
   const { SELECTOR_FIRST } = require('../lib/syntax');
   const requote = words.length > 1 && SELECTOR_FIRST.has(words[0]);
   // An empty word (fill #name "") is the empty value.
-  const quoted = requote ? words.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : words;
+  // upload's files are read by the REPL, whose folder may not be this one.
+  const resolved = words[0] === 'upload' ? words.map((w, n) => (n > 1 ? require('path').resolve(w) : w)) : words;
+  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
   options.command = quoted.join(' ').trim();
   return options;
 }

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
@@ -334,6 +434,8 @@ const consoleLogs = new WeakMap();
 // 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();
 
@@ -361,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);
   });
@@ -382,6 +486,7 @@ function ensureRecentLog(p) {
     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) }));
@@ -761,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');
@@ -779,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;
   }
@@ -803,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;
     }
@@ -814,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());
@@ -876,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]),
@@ -1175,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);
@@ -1334,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(' ')}`);
   },
@@ -1369,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;
+    }
+    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;
     }
-    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 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
@@ -1620,6 +1858,7 @@ const commands = {
 };
 
 onShutdown(discardCapture);
+onShutdown(resetEmulations);
 
 // Hooks every page needs from the moment the REPL sees it.
 function watchPage(p) {
@@ -1642,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']);
@@ -1651,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];
 }

package/lib/help.js

@@ -10,6 +10,9 @@ Common tasks:
   where am I?                       tab, info
   what is on the page?              snapshot, screenshot
   do something on it                click, fill, press
+  wait for a page or element        wait load, wait <selector>, wait <selector> --gone
+  choose a file in a file input     upload <selector> <file>
+  see it as a phone, or dark        emulate mobile, emulate dark
   what did the page request?        requests, then body <#> for what one got back
   console messages and errors       console
   show an agent what I do           watch on, click around, then watch
@@ -17,11 +20,12 @@ Common tasks:
   requests and console together     capture on, then capture off
   break the backend on purpose      route <glob> <status> <json>, route <glob> abort, network off
   change or slow an API response    route <glob> patch <json>, route <glob> delay <secs>
+  slow the whole network            network slow
   clean up                          modes off
 
-Modes (watch, capture, route, network off) stay on until turned off; the prompt shows the selected tab's:
-(watch routes:1) pw>. tab, watch, capture, route, network and modes on their own show their state and
-what you can run next.
+Modes (watch, capture, route, network off or slow, emulate) stay on until turned off; the prompt shows
+the selected tab's: (watch routes:1) pw>. tab, watch, capture, route, network, emulate and modes on
+their own show their state and what you can run next.
 
 Topics (help <topic>):
   tabs      open, select, close, navigate        network   requests, bodies, console, fakes, network off
@@ -37,11 +41,11 @@ const TOPICS = {
   },
   interact: {
     intro: 'Selectors are Playwright selectors (CSS, text=..., role=...) or snapshot refs such as e5.\nCommands use the first match; see help fill for selectors with spaces.',
-    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck'],
+    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload'],
   },
   inspect: {
     intro: 'Output is capped; put --all right after the command for everything (e.g. text --all body).',
-    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'wait', 'sleep'],
+    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'emulate', 'wait', 'sleep'],
   },
   network: {
     intro: 'requests and console record all the time; a capture records only while it runs.',
@@ -97,6 +101,11 @@ const COMMANDS = {
   select: { usage: 'select <selector> <value>', summary: 'choose an option in a select (the value is the rest of the line)' },
   check: { usage: 'check <selector>', summary: 'check a checkbox' },
   uncheck: { usage: 'uncheck <selector>', summary: 'uncheck a checkbox' },
+  upload: {
+    usage: 'upload <selector> <file>...',
+    summary: 'choose files in a file input, as the file picker would',
+    detail: 'The selector is a file input (even a hidden one), its label, or a button that opens the file\npicker. The page then does what it does with a chosen file; often that is the upload itself.\n\nThe REPL reads the files and hands the page their contents, so they need not be where the browser\nruns; up to 50MB in all. Relative paths are from the folder pw-repl send runs in, or the REPL\'s own\nfor a command typed at its prompt. Quote a path with spaces.',
+  },
   snapshot: {
     usage: 'snapshot [--full] [--grep <text> | <eN> | selector]',
     summary: 'outline by role and name, with [ref=eN] labels',
@@ -125,10 +134,15 @@ const COMMANDS = {
     detail: 'Saved as screenshot-<name or timestamp>.png in $PW_SCREENSHOT_DIR (default /tmp). It brings the tab to\nthe front of its window first: Chrome draws only the tab in front.\n\n--delay counts down out loud first (maximum 60s), so someone can hold a hover or open a menu.',
   },
   viewport: { usage: 'viewport [WxH]', summary: 'show or set the viewport size' },
+  emulate: {
+    usage: 'emulate [<what> [off] | off]',
+    summary: 'emulate a phone, dark mode, a locale or a timezone',
+    detail: 'emulate mobile [device]  a phone\'s screen, touch and user agent: a Pixel 7, or a device named as in\n                         Playwright\'s list, e.g. emulate mobile iPhone 13\nemulate dark | light     the color scheme the page\'s CSS and matchMedia see\nemulate locale <tag>     the language (Accept-Language, navigator.language) and date and number\n                         formats, e.g. fr-FR\nemulate timezone <zone>  an IANA timezone, e.g. Asia/Tokyo\nemulate <what> off       stop one (dark or light off stops the color scheme); emulate off stops all\n\nPer tab, until turned off or the REPL exits. emulate on its own shows what is on.\n\nThe page sees the user agent, touch and navigator.languages from its next load: reload after\nemulate mobile or emulate locale. While mobile is on, viewport refuses: the device sets the size.',
+  },
   wait: {
-    usage: 'wait [text|request] <what> [secs]',
-    summary: 'wait for an element, text, or a response (default 10s)',
-    detail: 'wait <selector> waits for a matching element; wait text <text> for text to be visible; wait request\n<url-part|glob> for a matching response, counting one that finished since the previous command began\n(so click, then wait request, does not miss it).\n\nUp to 120s. A wait that times out is an error; the REPL carries on.',
+    usage: 'wait [text|request] <what> [--gone] [secs]',
+    summary: 'wait for an element, text, a response or a load (10s)',
+    detail: 'wait <selector> waits for a matching element; wait text <text> for text to be visible; wait request\n<url-part|glob> for a matching response, counting one that finished since the previous command began\n(so click, then wait request, does not miss it).\n\nwait load waits for the page to finish loading (its load event). A navigation that began since the\nprevious command began counts, so click a link, then wait load, waits for the new page.\n\n--gone waits instead until nothing matching is visible (removed or hidden): wait .spinner --gone.\n\nUp to 120s. A wait that times out is an error; the REPL carries on.',
   },
   sleep: { usage: 'sleep <ms>', summary: 'wait a fixed time (maximum 3600000)' },
   requests: {
@@ -157,9 +171,9 @@ const COMMANDS = {
     detail: 'route <glob> <status> <json>  answer with this status (200-599) and JSON; it never reaches the network,\n                              so it still answers while the network is off\nroute <glob> patch <json>     let it through, then change its JSON response: a JSON Merge Patch, where\n                              objects merge, null removes a key and anything else replaces\nroute <glob> delay <secs>     hold it for up to 120 seconds, then let it through\nroute <glob> abort            fail it as if the connection broke\n\nEach matching request prints a line (Faked:, Patched:, Delayed:, Aborted:) in the REPL window, and in\nthe answer to a command running then, with its number as in requests; requests shows a fake as\n<status> faked and a patch as <status> patched. If a route fails it prints "Route failed" and aborts\nthe request.\n\nRoutes belong to the tab and last until route off <glob> (or route off --all) or the REPL exits.\nRouting the same glob again replaces it. route on its own lists the selected tab\'s routes.\n\nExample: route **/api/cart patch {"total": 0}',
   },
   network: {
-    usage: 'network [on|off]',
-    summary: 'cut or restore the tab\'s network, like dropped wifi',
-    detail: 'Stopping a service is not the same: a dev proxy in front of it usually holds the request open, so\nthe page spins instead of failing.\n\nPer tab; lasts until network on or the REPL exits. Routes still answer while it is off.',
+    usage: 'network [on|off|slow [<ms> [<kbps>]]]',
+    summary: 'cut, slow or restore the tab\'s network',
+    detail: 'network off cuts it, like dropped wifi. Stopping a service is not the same: a dev proxy in front of\nit usually holds the request open, so the page spins instead of failing.\n\nnetwork slow adds latency to each request and limits its speed: by default as DevTools\' Slow 4G\n(563ms, 1440 kbps down, 675 up); network slow <ms> [<kbps>] sets them. To slow one API, use route\n<glob> delay <secs>.\n\nPer tab; lasts until network on or the REPL exits. Routes still answer while it is off or slow.',
   },
   eval: {
     usage: 'eval [--all] <JavaScript>',
@@ -176,7 +190,7 @@ const COMMANDS = {
   modes: {
     usage: 'modes [off]',
     summary: 'the modes on in every tab; modes off turns them all off',
-    detail: 'The modes are watch, network off, route and capture. Each is turned on and off with its own command:\nwatch on|off, network off|on, route <glob> ... | route off <glob>|--all, capture on|off.\n\nmodes off turns off every one in every tab; a capture it stops is kept for capture to show.',
+    detail: 'The modes are watch, network off or slow, route, capture and emulate. Each is turned on and off with\nits own command: watch on|off, network off|slow|on, route <glob> ... | route off <glob>|--all,\ncapture on|off, emulate ... | emulate off.\n\nmodes off turns off every one in every tab; a capture it stops is kept for capture to show.',
   },
   dialog: {
     usage: 'dialog [accept [text] | dismiss]',

package/lib/state.js

@@ -52,7 +52,8 @@ async function shutdown() {
   if (shutdownPromise) return shutdownPromise;
   state.stopping = true;
   shutdownPromise = (async () => {
-    cleanups.forEach(fn => fn());
+    // Some undo what the REPL changed in the browser, so they finish first.
+    await withTimeout(Promise.all(cleanups.map(async fn => fn())), 'Cleanup').catch(() => {});
     if (state.browser) {
       try { await withTimeout(state.browser.close(), 'Chromium shutdown'); }
       catch (error) { state.shutdownFailed = true; process.exitCode = 1; out.error(`Could not confirm Chromium shutdown: ${error.message}`); }

package/lib/syntax.js

@@ -2,7 +2,7 @@
 
 // Commands whose first word is a selector, quoted if it has spaces, and whose
 // value is the rest of the line. Other commands take the rest of the line as it is.
-const SELECTOR_FIRST = new Set(['fill', 'type', 'select', 'press']);
+const SELECTOR_FIRST = new Set(['fill', 'type', 'select', 'press', 'upload']);
 
 // A snapshot ref (e5, or f1e5 in newer Playwright) stands for aria-ref=e5.
 const REF = /^(?:f\d+)?e\d+$/;

package/package.json

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

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, requests and their bodies, console messages, fake responses, cutting the network, and recording what the person does. Use when asked to look at, debug or test something in a browser that runs with remote debugging.
+description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, requests and their bodies, console messages, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, and recording what the person does. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
 ---
 
 # pw-repl
@@ -47,7 +47,7 @@ listens on TCP 127.0.0.1 instead of a socket, with no access control.
 Several REPLs can run at once, each on its own socket, e.g. one per agent. Each has its own selected tab,
 command queue and modes, so they do not wait on or select for each other. They share the browser,
 though: each sees every tab, `modes` lists only its own REPL's modes, and two REPLs acting on the same
-tab can undo each other's routes or network setting.
+tab can undo each other's routes, network or emulation settings.
 
 A REPL in a terminal stops at its prompt (`quit`, or Ctrl-C); `send quit` is refused.