pw-repl 0.3.0 → 0.3.2

package/AGENTS.md

@@ -11,18 +11,45 @@ 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
   used, and leave its Custom rules section empty.
 
+## Waves
+
+Work goes in waves, and each one ends with a release that is ready to push.
+
+1. Build what was asked, with tests, and try it in a running REPL.
+2. Try it on a fresh agent that has not seen the code or the change (a guinea pig), on something real: a
+   small local page whose planted bugs need the change to find.
+   - Brief it with goals only: what to find out or do in the browser, never the commands.
+   - First it reads back its plan, learned from `pw-repl skill` and help alone: the commands, where it
+     found them, and what is unclear. It runs nothing yet.
+   - A wrong or unsure plan means the docs or the brief were unclear: find out which, fix that, then
+     ask again.
+   - Then it carries the plan out, in a browser and on a socket of its own, and reports as it goes:
+     above all, where the tool did something other than what the docs led it to expect.
+3. Triage what it reports. Fix what matters, and what is small and useful; don't put off something
+   useful for later. Leave trivia alone, and say why.
+4. Repeat 2 and 3, with a fresh agent each time, until a pass comes back clean: no real bugs, and
+   nothing unclear in the docs or the brief that changed the plan. A pass after fixes tries the fixes,
+   and something not tried yet.
+5. Only then cut the release (Releasing, steps 1-3), and say it is ready. The maintainer pushes and
+   publishes it, and the next wave starts from what they find. A release cut too early and not pushed
+   yet is undone (its commit and tag) and cut again after the fixes.
+
 ## Releasing
 
 Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`,

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);
@@ -151,12 +154,12 @@ async function viewportText() {
 
 // A page restored from the back/forward cache never fires its load events
 // again, so back and forward wait only for the navigation, then briefly for
-// the page, rather than time out on a page that is already there.
+// the document to be parsed, which a restored one already is.
 async function historyStep(go, direction) {
   const before = state.page.url();
   const response = await go();
   if (response === null && state.page.url() === before) throw new Error(`No page to go ${direction} to`);
-  await state.page.waitForLoadState('domcontentloaded', { timeout: 3000 }).catch(() => {});
+  await state.page.waitForFunction(() => document.readyState !== 'loading', null, { timeout: 3000 }).catch(() => {});
 }
 
 const SCREENSHOT_DELAY_MAX = 60;
@@ -166,25 +169,135 @@ 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);
+}
+
+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 = emulations.get(p) || {};
+  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) 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 +447,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 +476,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 +499,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 +879,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 +900,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 +925,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 +937,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 +1012,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]),
@@ -890,7 +1055,11 @@ function grepSnapshot(text, needle) {
     const indent = line.length - line.trimStart().length;
     while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
     if (line.toLowerCase().includes(lower)) {
-      const path = stack.filter(a => !/^generic(?: \[|$)/.test(a.label)).map(a => a.label.replace(/ \[ref=[^\]]+\]/g, ''));
+      const around = stack.filter(a => !/^generic(?: \[|$)/.test(a.label));
+      // A hit with no ref of its own (text) keeps the ref of what holds it, so
+      // snapshot <ref> can show what sits beside it: the value next to a label.
+      const own = /\[ref=/.test(line);
+      const path = around.map((a, i) => (!own && i === around.length - 1 ? a.label : a.label.replace(/ \[ref=[^\]]+\]/g, '')));
       hits.push([...path, label(line)].join(' › '));
     }
     stack.push({ indent, label: label(line) });
@@ -1175,6 +1344,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);
@@ -1295,7 +1490,19 @@ const commands = {
     // Chrome does not draw a tab that is not in front, and tabs open in the
     // background, so the tab is brought to the front for the shot.
     await state.page.bringToFront();
-    const image = await state.page.screenshot({ fullPage: full });
+    let image;
+    try {
+      image = await state.page.screenshot({ fullPage: full });
+    } finally {
+      // Playwright's screenshot resets the screen size and pixel ratio it
+      // finds; an emulated phone's are set again.
+      const device = emulations.get(state.page)?.device;
+      if (device) {
+        const session = await keptSession(state.page);
+        await session.send('Emulation.clearDeviceMetricsOverride');
+        await deviceMetrics(session, device);
+      }
+    }
     try {
       fs.writeFileSync(filepath, image, { flag: 'wx', mode: 0o600 });
     } catch (error) {
@@ -1334,29 +1541,85 @@ 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;
+    // Said plainly, not as Playwright's call log.
+    const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };
     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 }).catch(plainly(`No visible text matches ${what} within ${seconds}s`));
+      out.log(`Visible: ${what}`);
+      return;
     }
     const selector = toSelector(unquote(tokens.join(' ')));
-    await state.page.waitForSelector(selector, { state: 'attached', timeout });
+    if (gone) return waitGone(state.page.locator(selector), tokens.join(' '), timeout);
+    await state.page.waitForSelector(selector, { state: 'attached', timeout }).catch(plainly(`No element matches ${tokens.join(' ')} within ${seconds}s`));
     out.log(`Found: ${tokens.join(' ')}`);
   },
 
@@ -1369,22 +1632,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 +1889,7 @@ const commands = {
 };
 
 onShutdown(discardCapture);
+onShutdown(resetEmulations);
 
 // Hooks every page needs from the moment the REPL sees it.
 function watchPage(p) {
@@ -1642,7 +1912,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 +1923,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,18 +41,18 @@ 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.',
     commands: ['requests', 'body', 'console', 'capture', 'route', 'network'],
   },
   devtools: {
-    intro: 'Cookie and storage listings omit values. eval, html, screenshots and URLs can still show sensitive data.',
+    intro: 'Cookie and storage listings omit values. eval, cdp, html, screenshots and URLs can still show\nsensitive data (cdp Network.getCookies shows cookie values).',
     commands: ['eval', 'cdp', 'cookies', 'storage'],
   },
   session: {
@@ -80,8 +84,12 @@ const COMMANDS = {
     summary: 'navigate the selected tab',
     detail: 'Without a scheme, http:// is assumed for localhost, 127.x and [::1], and https:// otherwise, as in\nthe address bar. tab new <url> reads its URL the same way.',
   },
-  back: { usage: 'back', summary: 'go back one history entry' },
-  forward: { usage: 'forward', summary: 'go forward one history entry' },
+  back: {
+    usage: 'back',
+    summary: 'go back one history entry',
+    detail: 'The browser may bring the page back from its back/forward cache, as it was: nothing loads or runs\nagain, so a loading message or a request the page makes on load does not come back. reload loads it\nafresh.',
+  },
+  forward: { usage: 'forward', summary: 'go forward one history entry', detail: 'Like back, it may bring the page back from the back/forward cache without loading it again.' },
   reload: { usage: 'reload', summary: 'reload the selected tab' },
   info: { usage: 'info', summary: 'selected tab URL, title and viewport' },
   click: { usage: 'click <selector>', summary: 'click the first match' },
@@ -97,10 +105,15 @@ 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',
-    detail: 'Playwright\'s accessibility snapshot, with unnamed layout wrappers (generic) and cursor hints left\nout; --full shows it unchanged.\n\n--grep <text> prints only the lines containing text (role, name or flag such as [disabled], any\ncase), each with the named elements around it. A hit with no named element around it prints without\na path.\n\nsnapshot e3 outlines one element. A ref (e3, or f1e3 in newer Playwright) works as a selector in any\ncommand: click e3. Refs can change when the page changes (e102 may become f4e98), so take a new\nsnapshot after it does.\n\nOutput over 60 lines ends with a line count.',
+    detail: 'Playwright\'s accessibility snapshot, with unnamed layout wrappers (generic) and cursor hints left\nout; --full shows it unchanged.\n\n--grep <text> prints only the lines containing text (role, name or flag such as [disabled], any\ncase), each with the named elements around it. A hit with no named element around it prints without\na path. A hit on text (a label) keeps the ref of the element holding it, so snapshot <that ref>\nshows what sits beside it, such as the value next to the label.\n\nsnapshot e3 outlines one element. A ref (e3, or f1e3 in newer Playwright) works as a selector in any\ncommand: click e3. Refs can change when the page changes (e102 may become f4e98), so take a new\nsnapshot after it does.\n\nOutput over 60 lines ends with a line count.',
   },
   watch: {
     usage: 'watch on [--changes] [--live] | off | [n|new]',
@@ -122,13 +135,18 @@ const COMMANDS = {
   screenshot: {
     usage: 'screenshot [--full] [--delay|-d <seconds>] [name]',
     summary: 'save a PNG of the viewport (or --full page)',
-    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.',
+    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. The image is at CSS pixel size,\none image pixel per CSS pixel, also while emulate mobile is on.\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; a name that is not\n                         exact lists the devices it matches (emulate mobile galaxy)\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\nturning mobile or locale on or off. 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. A page\nthat changes its own URL without loading (an app\'s own routing) is not a load: wait for something on\nthe new view instead.\n\nwait text matches any part of an element\'s text, in any case.\n\n--gone waits instead until nothing matching is visible (removed or hidden): wait .spinner --gone.\nIt is done at once if nothing matches yet, so wait for it to appear first if it may not have.\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: {
@@ -144,7 +162,7 @@ const COMMANDS = {
   console: {
     usage: 'console [--all] [n] [filter]',
     summary: 'the last n console messages and page errors',
-    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: time, [type],\ntext. Types are console levels (log, warning, error, ...) and pageerror for uncaught exceptions.\n\nfilter matches the type or the text, e.g. console error.',
+    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: time, [type],\ntext. Types are console levels (log, warning, error, ...) and pageerror for uncaught exceptions.\n\nfilter matches the type or the text, e.g. console error.\n\nA page brought back from the back/forward cache (back, forward) reports its earlier messages again,\nat the time it comes back, though nothing loaded again.',
   },
   capture: {
     usage: 'capture on [requests|console] [secs] | off',
@@ -157,9 +175,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 makes each request take at least <ms> (Chrome\'s latency is a minimum, not added to a\nslow server\'s own time) and limits its speed: by default as DevTools\' Slow 4G (563ms, 1440 kbps\ndown, 675 up); network slow <ms> [<kbps>] sets them, kbps both ways (left out, it stays Slow\n4G\'s). To slow one API, use route <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 +194,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/send.js

@@ -117,7 +117,8 @@ async function where(options) {
   // use, so a REPL that will not start can be told apart from one that is not running.
   const cdp = info?.browser || process.env.PW_CDP_URL || 'http://localhost:9222';
   const version = await fetch(`${cdp}/json/version`, { signal: AbortSignal.timeout(2000) }).then(r => r.json()).catch(() => null);
-  const whose = info?.launched ? ', launched by this REPL' : '';
+  // With no REPL running, it is only where one would connect, not a browser of a REPL that stopped.
+  const whose = info?.launched ? ', launched by this REPL' : info ? '' : '; run and serve connect here without --launch';
   console.log(version ? `browser: ${cdp} answers (${version.Browser}${whose})` : `browser: nothing answers at ${cdp}; pw-repl run says how to start one`);
   if (way.kind === 'server') {
     const name = client.describe(way.endpoint);

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.2",
   "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.
 
@@ -59,9 +59,10 @@ pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
 ```
 
 Always send commands with `pw-repl send`; don't type into the pane yourself. The words after `send`
-are the command. For `fill`, `type`, `select` and `press`, a word quoted in your shell stays one word
-(`pw-repl send fill "text=Your name" Ada`); other commands get the words as they are
-(`pw-repl send eval "document.title + ' x'"`). It works however the REPL was started:
+are the command. For `fill`, `type`, `select`, `press` and `upload`, a word quoted in your shell stays
+one word (`pw-repl send fill "text=Your name" Ada`); other commands get the words as they are, joined by
+spaces (`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the whole
+line, spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL was started:
 
 - `run` (in tmux): `send` types the command into the tmux pane and reads the result back off the screen.
   It types only when the pane's last line is a bare prompt, so nothing lands in a shell or in the middle
@@ -114,8 +115,9 @@ help is the command reference; this file does not repeat it.
   one works too (`--headless=new`); nobody answers its dialogs but `dialog`.
 - `PW_CHROME` — the Chromium `--launch` starts (default: Playwright's own, then one on the `PATH`).
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
-- `PW_SCREENSHOT_DIR` — where screenshots go (default `/tmp`). They are all named `screenshot-*.png`,
-  so `rm /tmp/screenshot-*.png` cleans up.
+- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots (default `/tmp`), read when it starts, not by
+  `send`. `screenshot` prints each file's path; other REPLs may save theirs there too. Remove only your
+  own, and keep those too if they are needed, e.g. as evidence or as something to hand over.
 - `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `send`
   looks for when neither is given (default `/tmp/playwright-repl.sock`).