pw-repl 0.2.2 → 0.3.1

package/lib/help.js

@@ -10,17 +10,22 @@ 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
   see each step as I click          watch on --live
   requests and console together     capture on, then capture off
-  break the backend on purpose      route <glob> <status> <json>, network 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
@@ -36,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', '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.',
@@ -96,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',
@@ -109,6 +119,11 @@ const COMMANDS = {
   text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
   html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match' },
   attrs: { usage: 'attrs [--all] <selector>', summary: 'attributes of the first match' },
+  listeners: {
+    usage: 'listeners <selector>|document|window',
+    summary: 'the page\'s event listeners on an element',
+    detail: 'One line each: the event, how it was added (capture, once, passive), the start of the handler and\nits line in its script. Listeners added on a parent (e.g. document, for delegation) are not the\nelement\'s own: check listeners document too.',
+  },
   count: { usage: 'count <selector>', summary: 'number of matches' },
   visible: { usage: 'visible <selector>', summary: 'whether the first match is visible' },
   links: { usage: 'links [--all]', summary: 'links on the page (text and href)' },
@@ -119,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: {
@@ -146,14 +166,14 @@ const COMMANDS = {
     detail: 'capture on records both until capture off, which prints them; requests or console records only one.\nWith secs (1-3600 seconds) it records that long, then prints. Other commands wait until a timed\ncapture ends, so it suits recording what someone does in the browser; around your own commands, use\ncapture on and capture off.\n\nOne capture runs at a time, on the tab selected when it started. Unlike requests and console it\nkeeps more than the last 200 and lists both together.\n\ncapture on its own says whether one is running, or shows the last one.',
   },
   route: {
-    usage: 'route <glob> <status> <json> | off <glob>|--all',
-    summary: 'answer the selected tab\'s matching requests with fake JSON',
-    detail: 'The fake is fulfilled inside the browser, so the page handles it as a real response and the request\nnever reaches the network; it still answers while the network is off. Each one prints "Faked: #<n>\n<METHOD> <url> -> <status>" in the REPL window (and in the answer to a command running then), with\n#<n> as in requests. If fulfilling fails it prints "Fake failed" and aborts the request, so it never\nreaches the network.\n\nStatus: 200-599. wait request <glob> after the page loads prints the request with its status, so a\nfake shows as <status> faked.\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/health_check 503 {"detail":{"code":"service_unavailable"}}',
+    usage: 'route <glob> <how> | off <glob>|--all',
+    summary: 'fake, patch, delay or fail the selected tab\'s matching requests',
+    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>',
@@ -170,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/launch.js

@@ -0,0 +1,115 @@
+// pw-repl run|serve --launch: a Chromium of the REPL's own, started for it and
+// stopped with it, in a profile that is removed afterwards. It is the quick
+// start; a browser set up any other way is reached with PW_CDP_URL instead.
+const { spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const START_TIMEOUT = 20000;
+const STOP_TIMEOUT = 5000;
+const INSTALL = 'npx playwright-core install chromium';
+const ON_PATH = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome', 'microsoft-edge'];
+const MAC_APPS = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+];
+
+// PW_CHROME, then Playwright's own Chromium (wherever PLAYWRIGHT_BROWSERS_PATH
+// puts it), then any other revision of it, then a Chromium on the PATH.
+function findChrome() {
+  if (process.env.PW_CHROME) return process.env.PW_CHROME;
+  try {
+    const bundled = require('playwright-core').chromium.executablePath();
+    if (fs.existsSync(bundled)) return bundled;
+  } catch {}
+  // Any Chromium works over CDP, so a revision other than this Playwright's is fine.
+  const dir = process.env.PLAYWRIGHT_BROWSERS_PATH || path.join(os.homedir(), '.cache', 'ms-playwright');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter(n => /^chromium-\d+$/.test(n)).sort().reverse(); } catch {}
+  for (const name of names) {
+    for (const sub of ['chrome-linux64/chrome', 'chrome-linux/chrome', 'chrome-mac/Chromium.app/Contents/MacOS/Chromium']) {
+      const candidate = path.join(dir, name, sub);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  for (const folder of (process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    for (const name of ON_PATH) {
+      const candidate = path.join(folder, name);
+      try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch {}
+    }
+  }
+  return MAC_APPS.find(app => fs.existsSync(app)) || null;
+}
+
+// Containers often give /dev/shm too little room, and Chromium's tabs then crash.
+function smallShm() {
+  try { const shm = fs.statfsSync('/dev/shm'); return shm.blocks * shm.bsize < 1024 ** 3; } catch { return false; }
+}
+
+// Starts it and waits for the port it picked, which it writes into its profile.
+function start(exe, args, profile) {
+  return new Promise(resolve => {
+    // Its own process group, so stopping it also stops the helper processes it starts.
+    const proc = spawn(exe, args, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+    let stderr = '';
+    let settled = false;
+    const done = result => { if (!settled) { settled = true; clearInterval(poll); clearTimeout(timer); resolve(result); } };
+    proc.stderr.on('data', d => { if (stderr.length < 20000) stderr += d; });
+    proc.on('error', error => done({ error: error.message, stderr }));
+    proc.on('exit', code => done({ error: `it exited with code ${code}`, stderr }));
+    const portFile = path.join(profile, 'DevToolsActivePort');
+    const poll = setInterval(() => {
+      try { const port = fs.readFileSync(portFile, 'utf8').split('\n')[0].trim(); if (port) done({ proc, port }); } catch {}
+    }, 100);
+    const timer = setTimeout(() => { proc.kill('SIGKILL'); done({ error: `no debugging port within ${START_TIMEOUT / 1000}s`, stderr }); }, START_TIMEOUT);
+  });
+}
+
+function quoted(args) {
+  return args.map(a => (/[\s"'$]/.test(a) ? JSON.stringify(a) : a)).join(' ');
+}
+
+async function launch({ headed = false, extraArgs = [] }) {
+  const exe = findChrome();
+  if (!exe) {
+    throw new Error(`No Chromium found to launch. Install Playwright's with:\n  ${INSTALL}\nor set PW_CHROME to one, or start one yourself with --remote-debugging-port and set PW_CDP_URL.`);
+  }
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-repl-chrome-'));
+  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', `--user-data-dir=${profile}`,
+    '--no-first-run', '--no-default-browser-check', ...(smallShm() ? ['--disable-dev-shm-usage'] : [])];
+  // Flags given after -- come after these, so they can override them.
+  let args = [...ours, ...extraArgs, 'about:blank'];
+  let result = await start(exe, args, profile);
+  let note = null;
+  // Tried with the sandbox first; a container often cannot give Chromium one.
+  if (result.error && /sandbox/i.test(result.stderr)) {
+    args = [...ours, '--no-sandbox', ...extraArgs, 'about:blank'];
+    result = await start(exe, args, profile);
+    note = 'Chromium could not use its sandbox here, so it runs with --no-sandbox.';
+  }
+  const command = quoted([exe, ...args]);
+  if (result.error) {
+    fs.rmSync(profile, { recursive: true, force: true });
+    const last = result.stderr.trim().split('\n').slice(-5).join('\n');
+    throw new Error(`Chromium did not start (${result.error}):\n  ${command}${last ? `\n${last}` : ''}`);
+  }
+  const { proc, port } = result;
+  const signal = name => { try { process.kill(-proc.pid, name); } catch {} };
+  const stop = async () => {
+    if (proc.exitCode === null && proc.signalCode === null) {
+      signal('SIGTERM');
+      await new Promise(resolve => { const t = setTimeout(() => { signal('SIGKILL'); resolve(); }, STOP_TIMEOUT); proc.once('exit', () => { clearTimeout(t); resolve(); }); });
+    }
+    // Its helper processes can still be writing to the profile for a moment.
+    for (let tries = 0; tries < 30; tries++) {
+      try { fs.rmSync(profile, { recursive: true, force: true }); return; } catch { await new Promise(resolve => setTimeout(resolve, 100)); }
+    }
+  };
+  // If the REPL goes without shutting down, the browser still goes with it.
+  process.on('exit', () => signal('SIGKILL'));
+  return { url: `http://127.0.0.1:${port}`, command, note, headed, stop };
+}
+
+module.exports = { findChrome, launch, INSTALL };

package/lib/runner.js

@@ -8,14 +8,14 @@ const { commands, dialogCommand, activeModes } = require('./commands');
 // A timeout here cannot have changed anything, so it is an ordinary error. Any
 // other command that times out may or may not have done what it was sent to
 // do; that is reported, and the REPL carries on.
-const READ_ONLY = new Set(['info', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs',
+const READ_ONLY = new Set(['info', 'listeners', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs',
   'snapshot', 'screenshot', 'wait', 'sleep', 'requests', 'body', 'console', 'cookies', 'storage', 'capture', 'help']);
 
 // Commands that work with no tab selected.
 const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'dialog', 'help', 'quit']);
 
 // Commands that accept a leading --all to lift the output limit.
-const INSPECTION = ['info', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
+const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
 
 let queue = Promise.resolve();
 // The server command running now, so a quit at the prompt can answer it.

package/lib/send.js

@@ -112,13 +112,16 @@ async function send(options) {
 // Reports the route a command would take, checking it the way a command would.
 async function where(options) {
   const way = route(options);
-  // Whether the browser answers, so a REPL that will not start can be told apart from one that is not running.
-  const cdp = process.env.PW_CDP_URL || 'http://localhost:9222';
+  const info = way.kind === 'server' ? await client.healthInfo(way.endpoint, 5000) : null;
+  // The browser a running REPL uses (one it launched has its own address); otherwise the one it would
+  // 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);
-  console.log(version ? `browser: ${cdp} answers (${version.Browser})` : `browser: nothing answers at ${cdp}; pw-repl run says how to start one`);
+  const whose = info?.launched ? ', launched by this REPL' : '';
+  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);
-    if (await client.health(way.endpoint, 5000)) {
+    if (info) {
       const background = require('./background').describeBackground(way.endpoint);
       console.log(`server: ${name} (the REPL was started with pw-repl serve${background ? ' --background' : ''})`);
       if (background) console.log(background);

package/lib/server.js

@@ -5,7 +5,7 @@ const net = require('net');
 const fs = require('fs');
 const out = require('./output');
 const runner = require('./runner');
-const { onShutdown, onBeforeExit } = require('./state');
+const { state, onShutdown, onBeforeExit } = require('./state');
 const { parseEndpoint, describe } = require('./client');
 
 const MAX_BODY = 1024 * 1024;
@@ -29,7 +29,7 @@ function handle(req, res) {
   // cross-origin POST, and cannot send a JSON content type without a
   // preflight this server never answers.
   if (req.headers.origin) return send(res, 403, { status: 'error', output: 'Requests from web pages are refused' });
-  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: 'ok' });
+  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: 'ok', browser: state.cdpUrl, launched: state.launched });
   if (req.method !== 'POST' || req.url !== '/run') return send(res, 404, { status: 'error', output: 'Use POST /run or GET /health' });
   if (!/^application\/json\b/.test(req.headers['content-type'] || '')) return send(res, 415, { status: 'error', output: 'Content-Type must be application/json' });
   let body = '';

package/lib/start.js

@@ -1,12 +1,13 @@
 // Connects to the browser and runs the prompt (and the server with serve).
 const { chromium } = require('playwright-core');
 const readline = require('readline');
-const { state, withTimeout, shutdown, beforeExit } = require('./state');
+const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./state');
 const out = require('./output');
 const { listTabs, openTab, watchPage, complete } = require('./commands');
 const runner = require('./runner');
 
-const CDP_URL = process.env.PW_CDP_URL || 'http://localhost:9222';
+// A browser --launch starts has its own address instead.
+let CDP_URL = process.env.PW_CDP_URL || 'http://localhost:9222';
 const CONNECT_TIMEOUT = 15000;
 
 // What to do about a browser that cannot be reached, rather than the bare socket error.
@@ -21,11 +22,23 @@ pw-repl needs a Chromium-based browser (Chrome, Chromium, Edge, ...) started wit
   chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
   chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-headless
 It needs a --user-data-dir of its own: Chrome does not open the port on its default profile.
-curl ${CDP_URL}/json/version checks that it answers; PW_CDP_URL points at a browser elsewhere.`;
+curl ${CDP_URL}/json/version checks that it answers; PW_CDP_URL points at a browser elsewhere.
+Or let pw-repl start a private one for this REPL: pw-repl run --launch (or serve --launch).`;
 }
 
 async function start(options) {
   const START_URL = options.startUrl || process.env.PW_START_URL || null;
+  if (options.launch) {
+    const launched = await require('./launch').launch({ headed: options.headed, extraArgs: options.chromeArgs });
+    onBeforeExit(launched.stop);
+    CDP_URL = launched.url;
+    out.log(`Launched a ${launched.headed ? 'visible' : 'headless'} Chromium of this REPL's own; it stops with the REPL:`);
+    out.log(`  ${launched.command}`);
+    if (launched.note) out.log(launched.note);
+    out.log(`Another REPL reaches it with PW_CDP_URL=${CDP_URL}`);
+  }
+  state.cdpUrl = CDP_URL;
+  state.launched = !!options.launch;
   out.log(`Connecting to ${CDP_URL}...`);
   try { state.browser = await chromium.connectOverCDP(CDP_URL, { timeout: CONNECT_TIMEOUT }); }
   catch (error) { throw new Error(connectHelp(error)); }
@@ -40,7 +53,7 @@ async function start(options) {
     state.stopping = true;
     process.exitCode = 1;
     out.error('Chromium connection lost; queued commands will not run.');
-    void shutdown().then(() => process.exit(1));
+    void shutdown().then(beforeExit).then(() => process.exit(1));
   });
   out.log('Connected to Chromium via CDP');
 
@@ -119,7 +132,7 @@ async function start(options) {
     endPromptLine();
     out.error('Input ended; disconnecting.');
     runner.drained().then(() => shutdown(), () => shutdown())
-      .then(() => process.exit(process.exitCode || 0));
+      .then(beforeExit).then(() => process.exit(process.exitCode || 0));
   });
   rl.on('SIGINT', stop);
 }
@@ -140,4 +153,4 @@ function stop() {
 // SIGHUP too: closing the terminal must still remove the server's socket.
 for (const signal of ['SIGTERM', 'SIGHUP']) process.on(signal, stop);
 
-module.exports = { start: options => start(options).catch(e => { out.error(e.message); shutdown().finally(() => process.exit(1)); }) };
+module.exports = { start: options => start(options).catch(e => { out.error(e.message); shutdown().then(beforeExit).finally(() => process.exit(1)); }) };

package/lib/state.js

@@ -11,6 +11,9 @@ const state = {
   tabListing: [],
   rl: null,
   promptBase: 'pw> ',
+  // The browser the REPL is connected to, and whether --launch started it.
+  cdpUrl: null,
+  launched: false,
   stopping: false,
   connectionLost: false,
   shutdownFailed: false,
@@ -49,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.2.2",
+  "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
@@ -27,6 +27,9 @@ one; each takes an optional start URL, which opens in a new tab.
   and takes commands; `pw-repl stop` stops it.
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
   `pw[serve]>`.
+- Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
+  own instead of connecting to one: headless unless `--headed`, in a temporary profile, stopped with the
+  REPL. It prints the command it ran; flags after `--` are passed to that Chromium.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
   the tmux session `playwright-repl`:
 
@@ -44,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.
 
@@ -107,8 +110,9 @@ help is the command reference; this file does not repeat it.
 
 ## Environment
 
-- Chromium must be running with `--remote-debugging-port=9222`. A headless one works too
-  (`--headless=new`); nobody answers its dialogs but `dialog`.
+- Chromium must be running with `--remote-debugging-port=9222`, unless `--launch` starts one. A headless
+  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.