pw-repl 0.12.3 → 0.12.5

package/AGENTS.md

@@ -20,7 +20,8 @@ If you hit a limitation or write a workaround, consider adding the capability to
   drawn over the page, which the element and mouse commands glide first), `lib/toast.js` (a line of text
   over the page), `lib/overlay.js` (the element the cursor and toast are drawn in, one layer each), `lib/inspect.js` (reading the
   page, screenshots, eval, CDP, waits), `lib/watch.js`, `lib/requestlog.js` (requests, bodies, console),
-  `lib/routes.js`, `lib/network.js`, `lib/emulation.js` (and viewport), `lib/capture.js`, `lib/record.js`
+  `lib/routes.js`, `lib/network.js`, `lib/emulation.js` (and viewport), `lib/capture.js`, `lib/profile.js` (performance traces;
+  `lib/trace.js` reads and sums them up), `lib/record.js`
   (video, through ffmpeg, and the steps file saved with it), `lib/dialogs.js` and `lib/modes.js`. Beneath them, `lib/tabstate.js` is the one record kept per tab, `lib/cdp.js` the CDP
   session kept per tab, and `lib/util.js` small shared helpers. No facility requires `lib/modes.js` or
   `lib/commands.js`, and a unit test fails on a require cycle, which CommonJS would not report.

package/README.md

@@ -54,6 +54,8 @@ pw> console error                       # and see how the page copes
 - **Record:** what someone does in a tab (`watch`), a timeline of requests and console (`capture`), or a
   video of the tab (`record`), with a virtual pointer (`cursor`), captions (`toast`) and highlights
   (`highlight`).
+- **Profile:** what keeps a page's main thread busy (`profile`): long tasks and the function behind each,
+  forced style and layout, each click's or key's time to the next paint, and dropped frames.
 - **Share:** many clients on one REPL, each with its own tab; a command server on a Unix socket or a local
   port, with an HTTP+JSON protocol.
 
@@ -146,6 +148,7 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | see each step as I click              | `watch on --live`                                                                    |
 | replay what I clicked through         | `watch on`, click around, `watch save flow.txt`, then `pw-repl send --file flow.txt` |
 | record requests and console together  | `capture on`, then `capture off`                                                     |
+| find what makes the page slow         | `profile on`, then `profile off`; `profile reload` for a page load                   |
 | fake a backend response               | `route <glob> <status> <json>`, `route <glob> abort`                                 |
 | change or slow an API response        | `route <glob> patch <json>`, `route <glob> delay <secs>`                             |
 | cut or slow the whole network         | `network off`, `network slow`, then `network on`                                     |
@@ -159,11 +162,11 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 
 ### Modes
 
-Some commands turn on a mode that stays on until you turn it off: `watch`, `capture`, `route`, `network
-off` or `slow`, `emulate`, `viewport`, `record`, `highlight`, `cursor` and `toast`. 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. Each of these commands on its own shows its state and what you
-can run next.
+Some commands turn on a mode that stays on until you turn it off: `watch`, `capture`, `profile`, `route`,
+`network off` or `slow`, `emulate`, `viewport`, `record`, `highlight`, `cursor` and `toast`. 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. Each of these commands on its own shows its state and
+what you can run next.
 
 ## For agents and scripts
 

package/lib/commands.js

@@ -14,6 +14,7 @@ const { commands: networkCommands } = require('./network');
 const { commands: emulationCommands, EMULATE_KINDS } = require('./emulation');
 const { commands: captureCommands } = require('./capture');
 const { commands: recordCommands } = require('./record');
+const { commands: profileCommands } = require('./profile');
 const { commands: inspectCommands } = require('./inspect');
 const { commands: watchCommands, nextTabWanted, waitingForMe, watchNewTab } = require('./watch');
 const { commands: tabsCommands, isOpening } = require('./tabs');
@@ -33,6 +34,7 @@ const commands = {
   ...emulationCommands,
   ...captureCommands,
   ...recordCommands,
+  ...profileCommands,
   ...dialogsCommands,
   ...modesCommands,
 
@@ -117,6 +119,7 @@ function complete(line) {
     if (command === 'watch') return match(['on', 'off', 'new', '--all']);
     if (command === 'capture') return match(['on', 'off']);
     if (command === 'record') return match(['on', 'off']);
+    if (command === 'profile') return match(['on', 'off', 'save', 'reload']);
     if (command === 'cursor') return match(['on', 'off']);
     if (command === 'toast') return match(['off']);
     if (command === 'viewport') return match(['off']);
@@ -124,6 +127,7 @@ function complete(line) {
   }
   if (words.length >= 3 && command === 'watch' && words[1] === 'on') return match(['--changes', '--live', '--next-tab'].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 === 'profile' && words[1] === 'on') return match(['--cpu']);
   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

@@ -74,7 +74,7 @@ fill for selectors with spaces. mousemove and the other mouse commands act at a
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
-    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'highlight', 'viewport', 'emulate', 'wait', 'sleep'],
+    commands: ['snapshot', 'watch', 'profile', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'highlight', 'viewport', 'emulate', 'wait', 'sleep'],
   },
   video: {
     intro: `A video of what you do in a tab, for someone to watch. Record it from a file of commands sent with
@@ -235,7 +235,7 @@ A click at a point: mouseclick <x> <y>. A drag: mousedown, then mousemove to ano
 clicked with click, which waits for it. help mousemove shows how to find a point. The mouse stays at the point, for a mousewheel or mousedown after
 it. The cursor (help cursor) moves there first and shows a ring at the press.`,
   },
-  mousedown: { usage: 'mousedown [button]', summary: 'press a mouse button where the mouse is (left, right or middle)' },
+  mousedown: { usage: 'mousedown [button]', summary: 'press a mouse button at the mouse (left, right, middle)' },
   mouseup: { usage: 'mouseup [button]', summary: 'release a mouse button where the mouse is' },
   mousewheel: {
     usage: 'mousewheel <dx> <dy>',
@@ -252,7 +252,7 @@ scrolled or redrawn. While recording, it scrolls in eased steps over up to 1s (h
     summary: 'clear an input and fill it',
     args: [
       ['<selector>', 'the first word; quote it if it has spaces: fill "text=Your name" Ada.'],
-      ['<value>', 'the rest of the line; quotes around all of it are removed, so fill #name "" clears it.'],
+      ['<value>', 'the rest of the line; quotes around all of it are removed, so fill #name "" clears it. Over send, the shell\'s quotes do it: pw-repl send fill #name "" (\'""\' types two quote marks).'],
     ],
     options: [
       ['--submit', 'at the end: presses Enter in it afterwards.'],
@@ -261,8 +261,8 @@ scrolled or redrawn. While recording, it scrolls in eased steps over up to 1s (h
 once, even while recording: type shows it being typed.`,
   },
   type: {
-    usage: 'type [<selector>] <text> [--submit]',
-    summary: 'type key by key after what the field holds; text as for fill',
+    usage: 'type [--delay=<ms>] [<selector>] <text> [--submit]',
+    summary: 'type key by key after what the field holds',
     args: [
       ['[<selector>]', 'as for fill. Without it (one word, or one quoted), into what has focus: type "garden hose".'],
       ['<text>', 'the rest of the line, as fill\'s value.'],
@@ -281,10 +281,10 @@ Date and time inputs: they take keys part by part, in the order they show them (
 from the first part with a selector, or from the part a click landed on. type says what the input then
 holds. Their ISO form (2026-10-02) is refused, since typed it comes out mangled: fill sets it.`,
   },
-  press: { usage: 'press <key> | press <selector> <key>', summary: 'press a key (Enter, Escape, Control+A; any case), maybe on an element' },
+  press: { usage: 'press <key> | press <selector> <key>', summary: 'press a key: Enter, Escape, Control+A (any case)' },
   select: {
     usage: 'select <selector> <value>',
-    summary: 'choose an option in a select (the value is the rest of the line)',
+    summary: 'choose an option; the value is the rest of the line',
     args: [
       ['<value>', 'an option\'s value or its label.'],
     ],
@@ -314,6 +314,7 @@ all.`,
       ['<selector>', 'outlines the first match, with new refs: those from before stop working.'],
     ],
     options: [
+      ['--all', 'the whole outline, not capped.'],
       ['--full', 'Playwright\'s snapshot unchanged.'],
       ['--grep <text>', 'only the lines containing text (role, name or a flag such as [disabled], any case), each with the named elements around it.'],
       ['--regex <pattern>', '--grep by a regular expression: snapshot --regex "Total: \\d+".'],
@@ -332,7 +333,8 @@ value attribute so too. A field a Show password button made plain text, with no
 shows its value. Every other field shows what it holds (textbox "Name": Ada), and a select its chosen
 option: inputs lists the fields without what they hold.
 
-Output over 60 lines ends with a line count.`,
+Output over 60 lines ends with a line count. Past 12000 characters it is cut at the end of a line, saying
+where: --all shows all.`,
   },
   watch: {
     usage: 'watch on [options] | off | [n|new] | save <file>',
@@ -573,7 +575,8 @@ A (page) line marks each new page, loaded or routed to by a single-page app. It
 video.
 
 ffmpeg: $PW_FFMPEG, and only it when it is set (the REPL's, not send's); otherwise Playwright's own (npx
-playwright-core install ffmpeg, in $PLAYWRIGHT_BROWSERS_PATH or ~/.cache/ms-playwright), then one on the
+playwright-core install ffmpeg, in $PLAYWRIGHT_BROWSERS_PATH, or ~/.cache/ms-playwright on Linux and
+~/Library/Caches/ms-playwright on macOS), then one on the
 PATH. Playwright's writes only WebM; an MP4 needs a system ffmpeg with H.264. Without one that can write
 the format, record on fails at once, recording nothing. WebM plays in browsers, GitHub, GitLab and Slack;
 MP4 everywhere. About 15 MB a minute.`,
@@ -702,6 +705,59 @@ Kept from when the REPL connects; the last 200 per tab.
 
 A page brought back from the back/forward cache (back, forward) reports its earlier messages again, at
 the time it comes back, though nothing loaded again.`,
+  },
+  profile: {
+    usage: 'profile on [secs] | off | reload | save <file>',
+    summary: 'what slows the tab: long tasks, layouts, input, frames',
+    args: [
+      ['on', 'starts a performance trace of the selected tab, until profile off (at most 120 seconds).'],
+      ['[secs]', 'records that long (1 to 120), then prints. Other commands wait until it ends. Over 20, give send time too: pw-repl send -t 70 profile on 60.'],
+      ['off', 'stops it and prints the summary.'],
+      ['reload', 'reloads the tab and profiles its load, until its network is idle (at most 10s after load) and half a second more. For work that starts later (a timer): profile on, reload, sleep, profile off.'],
+      ['save <file>', 'writes the last profile\'s trace, the tab\'s events only, as Chrome trace JSON for DevTools\' Performance panel (Load profile) or ui.perfetto.dev. It refuses a file that exists.'],
+      ['(none)', 'says whether one is running, or shows the last one.'],
+    ],
+    optionsFor: 'profile on',
+    options: [
+      ['--cpu', 'samples JS more often, and adds the functions that ran longest themselves. The trace gets much bigger.'],
+    ],
+    detail: `For "the page feels slow": what the tab's main thread was busy with, and when. It is a Chrome
+performance trace, as DevTools' Performance panel records (Playwright's browser.startTracing), summed up.
+Use it around something you do (profile on, click e5, profile off), or while the user uses the page: steps
+they take in the browser are in it.
+
+The summary: main-thread busy time by kind (scripting, style/layout, paint, GC, other); the page's
+load marks, when it loaded; each long task (over 50ms), with what set it off, the script it ran, the
+function it spent most time in ("most in"), each as file:line function, and a big response (100 KB or more) that finished just before
+it; forced style and layout (work a script waited for, reading a size or a style), by where in the script; and the steps:
+each click or key press with its time to the next paint (input delay, handlers, presentation), and each
+burst of wheel or scroll events and each drag, with the main thread's busy time and the frames drawn and
+dropped. Times are from when it started. --all lists every long task and step, not the first ones.
+
+Size: a busy page fills Chrome's trace buffer in under a minute (one that restyles many elements as it
+draws, sooner), which stops the profile there, and the summary says so. Stopping a long one takes a
+while, as Chrome writes out its trace: give send time, pw-repl send -t 60 profile off. If send gives up
+first, the profile still ends, and profile shows it.
+
+One profile runs at a time, in a browser: Chrome traces one at a time, the whole browser's, so another
+REPL's profile, or DevTools' Performance panel recording, stops profile on. It belongs to the tab, ends
+if the tab closes (profile shows it), and modes lists it.`,
+    moreAbout: 'what is left out, inlined functions, frames in a background tab, and the mark it leaves in the page',
+    more: `The tab's own renderer only: a cross-site iframe running in a process of its own is left out, and
+so is anything another tab of the same site, sharing the tab's process, does at the same time.
+
+Frames: a tab pw-repl uses is kept drawing as if it were in front (help tab), so its frame counts are a
+tab in front's; one behind another tab draws far less, as the user would see it. The summary says so.
+
+A function the JS engine inlined into its caller counts as the caller, in "most in" and --cpu alike: a
+small hot function called in a loop can show as the loop's function.
+
+A wheel-zoom or drag the page handles in its own script (a map) shows as a step from its events; one the
+browser handles alone, with no listener, may show only as frames.
+
+profile on and off each run console.timeStamp in the page, which prints nothing, so the tab is found in
+the trace even when its page did nothing. The trace is kept in a temporary folder until the next
+profile, or until the REPL stops.`,
   },
   capture: {
     usage: 'capture on [requests|console] [secs] | off',

package/lib/inspect.js

@@ -422,7 +422,7 @@ const commands = {
       return;
     }
     const lines = text.split('\n').length;
-    printOutput(lines > SNAPSHOT_HINT_LINES ? `${text}\n[${lines} lines; snapshot --grep <text> or snapshot <eN> shows less]` : text, all);
+    printOutput(text, all, lines > SNAPSHOT_HINT_LINES ? `[${lines} lines; snapshot --grep <text> or snapshot <eN> shows less]` : '');
   },
 
   async wait(args) {

package/lib/launch.js

@@ -6,6 +6,7 @@ const { spawn } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { playwrightBrowsersDir } = require('./util');
 
 const START_TIMEOUT = 20000;
 // Stopping: a moment to connect and ask it to close, a few seconds to close, as long again after SIGTERM,
@@ -31,11 +32,14 @@ function findChrome() {
     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');
+  const dir = playwrightBrowsersDir();
   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']) {
+    for (const sub of ['chrome-linux64/chrome', 'chrome-linux-arm64/chrome', 'chrome-linux/chrome', 'chrome-win64/chrome.exe',
+      'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+      'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+      'chrome-mac/Chromium.app/Contents/MacOS/Chromium']) {
       const candidate = path.join(dir, name, sub);
       if (fs.existsSync(candidate)) return candidate;
     }

package/lib/modes.js

@@ -8,6 +8,7 @@ const { setNetwork } = require('./network');
 const { emulatedKinds, setEmulation, setViewport } = require('./emulation');
 const { recordingOf, finishRecording } = require('./record');
 const { currentCapture, endCapture } = require('./capture');
+const { currentProfile, finishProfile } = require('./profile');
 const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
 const { hideHighlights, setLabels } = require('./elements');
 const { cursorOf, cursorOff } = require('./cursor');
@@ -31,6 +32,7 @@ function activeModes(p) {
   if (cursorOf(p)) modes.push('cursor');
   if (toastOf(p)) modes.push('toast');
   if (currentCapture()?.page === p) modes.push('capture');
+  if (currentProfile()?.page === p) modes.push('profile');
   if (recordingOf(p)) modes.push('record');
   return modes;
 }
@@ -87,6 +89,8 @@ function modeOwners(p) {
   if (toast) owners.push([toast.owner ?? null, 'toast']);
   const capture = currentCapture();
   if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
+  const profile = currentProfile();
+  if (profile?.page === p) owners.push([profile.owner ?? null, 'profile']);
   const recording = recordingOf(p);
   if (recording) owners.push([recording.owner ?? null, 'record']);
   return owners;
@@ -116,6 +120,8 @@ async function allModesOff(mine = false) {
       if (watch?.on && ours(watch.owner)) { stopWatching(p, watch); done.push('watch off'); }
       const capture = currentCapture();
       if (capture?.page === p && ours(capture.owner)) { endCapture(); done.push('capture off (capture shows it)'); }
+      const profile = currentProfile();
+      if (profile?.page === p && ours(profile.owner)) { await finishProfile(); done.push('profile off (profile shows it)'); }
       const globs = [...(tabState(p).routes || [])].filter(([, route]) => ours(route.owner)).map(([glob]) => glob);
       if (globs.length) { await unroute(p, globs); done.push(`${globs.length} route${globs.length === 1 ? '' : 's'} removed`); }
       if ('network' in tabState(p) && ours(tabState(p).network.owner)) { await setNetwork(p, null); done.push('network on'); }

package/lib/output.js

@@ -65,16 +65,25 @@ function aside(text) {
   else console.log(text);
 }
 
-function printOutput(value, all = false) {
+// A footer is printed after the cut, so it is never cut off itself.
+function printOutput(value, all = false, footer = '') {
   let text;
   if (typeof value === 'string') text = value;
   else text = JSON.stringify(value, null, 2);
   if (text === undefined) text = 'undefined';
   if (!all && text.length > OUTPUT_LIMIT) {
-    log(`${text.slice(0, OUTPUT_LIMIT)}\n[truncated; add --all to the command to show all]`);
-  } else {
-    log(text);
+    // Cut at a line's end, unless the last one within the limit comes so early (a short line before a
+    // long minified one) that little would be shown.
+    const end = text.lastIndexOf('\n', OUTPUT_LIMIT);
+    if (end > OUTPUT_LIMIT / 2) {
+      const shown = text.slice(0, end);
+      const at = shown.split('\n').length;
+      text = `${shown}\n[truncated at line ${at} of ${text.split('\n').length}; add --all to the command to show all]`;
+    } else {
+      text = `${text.slice(0, OUTPUT_LIMIT)}\n[truncated; add --all to the command to show all]`;
+    }
   }
+  log(footer ? `${text}\n${footer}` : text);
 }
 
 module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, onSelectedTab, printOutput };

package/lib/profile.js

@@ -0,0 +1,310 @@
+// Profiling a tab: a Chrome performance trace of what its main thread did, summed up when it stops.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { state, onShutdown } = require('./state');
+const out = require('./output');
+const { NO_TAB, clock, hints } = require('./util');
+const { tabState } = require('./tabstate');
+const { targetIdOf } = require('./tabs');
+const { summarize, LONG_TASK } = require('./trace');
+
+const MAX_SECONDS = 120;
+const SHOWN = 10;
+// DevTools' Performance panel's categories, less the browser-wide ones the summary does not use.
+const CATEGORIES = ['devtools.timeline', 'disabled-by-default-devtools.timeline', 'disabled-by-default-devtools.timeline.frame',
+  'disabled-by-default-devtools.timeline.stack', 'toplevel', 'v8.execute', 'blink.user_timing', 'loading', 'latencyInfo',
+  // JS samples, which name the function a long task spent its time in; --cpu samples more often.
+  'disabled-by-default-v8.cpu_profiler'];
+const CPU_CATEGORIES = ['disabled-by-default-v8.cpu_profiler.hires'];
+
+let prof = null;
+// A profile still being read after it ended by itself (its tab closed, or it reached its limit).
+let finishing = null;
+let last = null;
+let dir = null;
+
+function currentProfile() {
+  return prof;
+}
+
+function workDir() {
+  if (!dir) dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-repl-profile-'));
+  return dir;
+}
+
+// A trace event naming the tab's frame, from its renderer, so an idle tab is still found in the trace.
+// console.timeStamp prints nothing in the console. A page held by a dialog does not answer: no wait.
+async function mark(page) {
+  if (page.isClosed()) return;
+  await Promise.race([page.evaluate(() => console.timeStamp('pw-repl profile')).catch(() => {}), new Promise(resolve => setTimeout(resolve, 1000))]);
+}
+
+function forget(profile) {
+  if (profile?.saveFile) fs.rmSync(profile.saveFile, { force: true });
+}
+
+async function startProfile(tokens, quiet = false) {
+  if (prof) throw new Error(`Already profiling ${prof.page.url()}; profile off stops it`);
+  const usage = `Usage: profile on [seconds] [--cpu] (seconds from 1 to ${MAX_SECONDS})`;
+  const cpu = tokens.includes('--cpu');
+  const rest = tokens.filter(t => t !== '--cpu');
+  if (rest.length > 1 || (rest.length && !/^\d+$/.test(rest[0]))) throw new Error(usage);
+  const seconds = rest.length ? Number(rest[0]) : null;
+  if (seconds !== null && (seconds < 1 || seconds > MAX_SECONDS)) throw new Error(usage);
+  if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
+  await finishing;
+  const page = state.page;
+  const frameId = await targetIdOf(page.context(), page);
+  if (!frameId) throw new Error('Could not tell which tab this is in the browser; profile needs a Chromium tab');
+  // The browser's own session, not the tab's: a tab's session goes when the tab closes, and its trace
+  // with it. Chrome ends the trace if the session goes, so a REPL that dies leaves none running.
+  const session = await state.browser.newBrowserCDPSession();
+  try {
+    await session.send('Tracing.start', {
+      transferMode: 'ReturnAsStream', streamFormat: 'json', streamCompression: 'none', bufferUsageReportingInterval: 500,
+      traceConfig: { includedCategories: cpu ? [...CATEGORIES, ...CPU_CATEGORIES] : CATEGORIES, excludedCategories: ['*'] },
+    });
+  } catch (error) {
+    await session.detach().catch(() => {});
+    if (/already/i.test(error.message)) throw new Error('The browser is already recording a trace, and records one at a time: DevTools\' Performance panel, or another REPL\'s profile. Stop that one first.');
+    throw error;
+  }
+  const profile = { page, session, frameId, cpu, owner: state.client, startedAt: Date.now(), url: page.url(), wake: null };
+  prof = profile;
+  await mark(page);
+  // A profile that stops by itself says why in its summary, and in a notice unless a timed profile on
+  // is waiting to print it.
+  const stop = (why, notice) => {
+    profile.stopped = why;
+    finishProfile().then(() => { if (!profile.wake) out.notice(`${notice}; profile shows its summary.`, page); }, () => {});
+  };
+  const onClose = () => {
+    if (prof === profile) stop('the tab closed.', 'The profiled tab closed, which ended the profile');
+  };
+  page.on('close', onClose);
+  // Chrome stops recording when its trace buffer fills, as a busy page does in under a minute; the
+  // profile stops with it, so it does not run on recording nothing.
+  const onUsage = ({ percentFull }) => {
+    if (prof !== profile || !(percentFull >= 0.99)) return;
+    const after = Math.round((Date.now() - profile.startedAt) / 1000);
+    stop(`Chrome's trace buffer filled after ${after}s. Profile a shorter stretch to have all of it.`, `Chrome's trace buffer filled, which stopped the profile after ${after}s`);
+  };
+  session.on('Tracing.bufferUsage', onUsage);
+  profile.unlisten = () => { page.off('close', onClose); session.off('Tracing.bufferUsage', onUsage); };
+  profile.cap = setTimeout(() => {
+    if (prof === profile) stop(`it reached ${MAX_SECONDS}s, the most a profile records.`, `The profile stopped at ${MAX_SECONDS}s, the most it records`);
+  }, MAX_SECONDS * 1000);
+  if (!seconds) {
+    if (quiet) return;
+    out.log(`Profiling the selected tab${cpu ? ' with a JS CPU profile' : ''}; profile off stops it and prints a summary.`);
+    return;
+  }
+  out.log(`Profiling the selected tab for ${seconds}s...`);
+  await new Promise(resolve => {
+    const timer = setTimeout(resolve, seconds * 1000);
+    profile.wake = () => { clearTimeout(timer); resolve(); };
+  });
+  // profile off may have ended it first, and printed it; anything else that ended it (its tab closed,
+  // the buffer filled) leaves it to this command to print.
+  if (profile.stoppedByOff) return;
+  await finishProfile();
+  await profile.finished;
+  printProfile(last);
+}
+
+// Ends the trace, reads it from the browser, and sums it up. Once, however many ask.
+function finishProfile() {
+  const profile = prof;
+  if (!profile) return Promise.resolve();
+  prof = null;
+  clearTimeout(profile.cap);
+  profile.unlisten();
+  profile.finished = (async () => {
+    await mark(profile.page);
+    const endedAt = Date.now();
+    const raw = path.join(workDir(), `raw-${process.pid}-${endedAt}.json`);
+    try {
+      const complete = new Promise(resolve => profile.session.once('Tracing.tracingComplete', resolve));
+      await profile.session.send('Tracing.end');
+      const { stream } = await complete;
+      const file = fs.openSync(raw, 'w', 0o600);
+      try {
+        for (;;) {
+          const chunk = await profile.session.send('IO.read', { handle: stream, size: 1 << 20 });
+          fs.writeSync(file, chunk.base64Encoded ? Buffer.from(chunk.data, 'base64') : chunk.data);
+          if (chunk.eof) break;
+        }
+      } finally {
+        fs.closeSync(file);
+        await profile.session.send('IO.close', { handle: stream }).catch(() => {});
+      }
+      await profile.session.detach().catch(() => {});
+      forget(last);
+      const saveFile = path.join(workDir(), `tab-${process.pid}-${endedAt}.json`);
+      const summary = await summarize(raw, { frameId: profile.frameId, url: profile.url, saveFile, cpu: profile.cpu });
+      last = { ...profile, endedAt, summary, saveFile, drawing: 'drawing' in tabState(profile.page) };
+    } catch (error) {
+      await profile.session.detach().catch(() => {});
+      last = { ...profile, endedAt, summary: null, error: error.message };
+    } finally {
+      fs.rmSync(raw, { force: true });
+      if (profile.wake) profile.wake();
+    }
+  })();
+  finishing = profile.finished;
+  return profile.finished;
+}
+
+function secs(us) {
+  return `${(us / 1e6).toFixed(2)}s`;
+}
+
+// A total in the unit of the items under it: ms under a second.
+function total(us) {
+  return us < 1e6 ? ms(us) : secs(us);
+}
+
+function ms(us) {
+  return `${Math.round(us / 1000)}ms`;
+}
+
+// The tab's request with this URL nearest to when the trace saw it, for its number in requests.
+function requestNumber(profile, request) {
+  const at = profile.startedAt + (request.sent - profile.summary.t0) / 1000;
+  const entries = (tabState(profile.page).log || []).filter(e => e.url === request.url);
+  const nearest = entries.sort((a, b) => Math.abs(a.t - at) - Math.abs(b.t - at))[0];
+  return nearest && Math.abs(nearest.t - at) < 2000 ? `#${nearest.id} ` : '';
+}
+
+function printProfile(profile, all = false) {
+  // So profile off does not show again what has been shown.
+  if (finishing && profile === last) finishing.shown = true;
+  if (profile.error) { out.log(`The profile from ${clock(profile.startedAt)} could not be read: ${profile.error}`); return; }
+  const s = profile.summary;
+  const lines = [];
+  if (!s) {
+    out.log(`Nothing from ${profile.url} was in the trace: its page did no work while it ran, or it closed first.`);
+    return;
+  }
+  const at = ts => `+${((ts - s.t0) / 1e6).toFixed(2)}s`;
+  lines.push(`Profiled ${profile.url} for ${secs(s.duration)}, from ${clock(profile.startedAt)}${profile.cpu ? ', with a JS CPU profile' : ''}`);
+  if (profile.stopped) lines.push(`Stopped early: ${profile.stopped}`);
+  const split = Object.entries(s.buckets).filter(([, us]) => us >= 5000).map(([b, us]) => `${b} ${secs(us)}`);
+  lines.push(`Main thread busy ${secs(s.busy)} (${s.duration ? Math.round((100 * s.busy) / s.duration) : 0}%)${split.length ? `: ${split.join(', ')}` : ''}`);
+  if (s.marks.length) lines.push(`Page: ${s.marks.map(([name, ts]) => `${name} ${at(ts)}`).join(', ')}`);
+  const longTotal = s.longTasks.reduce((sum, t) => sum + t.dur, 0);
+  lines.push(`Long tasks (over ${LONG_TASK / 1000}ms): ${s.longTasks.length ? `${s.longTasks.length}, ${total(longTotal)} in all` : 'none'}`);
+  const longest = all ? s.longTasks : [...s.longTasks].sort((a, b) => b.dur - a.dur).slice(0, SHOWN).sort((a, b) => a.ts - b.ts);
+  for (const t of longest) {
+    const after = t.after ? `  (after ${requestNumber(profile, t.after)}${t.after.method} ${t.after.url}, ${Math.round(t.after.size / 1024)}KB, finished ${at(t.after.finished)})` : '';
+    const hot = t.hot ? `; most in ${t.hot.where} (${ms(t.hot.us)})` : '';
+    lines.push(`  ${at(t.ts).padStart(8)}  ${ms(t.dur).padStart(6)}  ${[t.kind, t.trigger, t.script].filter(Boolean).join(', ')}${hot}${after}`);
+  }
+  if (longest.length < s.longTasks.length) lines.push(`  (the ${longest.length} longest; profile --all lists them all)`);
+  if (s.forced.length) {
+    const count = s.forced.reduce((sum, f) => sum + f.count, 0);
+    lines.push(`Forced style and layout (work a script waited for, reading a size or style): ${count}, ${ms(s.forced.reduce((sum, f) => sum + f.dur, 0))} in all`);
+    for (const f of all ? s.forced : s.forced.slice(0, SHOWN)) lines.push(`  ${`${f.count}x`.padStart(5)}  ${ms(f.dur).padStart(6)}  ${f.where}`);
+  }
+  if (s.steps.length) {
+    lines.push('Steps (input that reached the page, and what it did until 100ms after each step\'s last event):');
+    const steps = all ? s.steps : s.steps.slice(0, SHOWN * 2);
+    for (const step of steps) {
+      const span = step.latency != null
+        ? `${Math.round(step.latency)}ms to next paint (input delay ${Math.round(step.delay)}ms, handlers ${Math.round(step.handlers)}ms, presentation ${Math.round(step.presentation)}ms)`
+        : `${secs(step.end - step.start)}, ${step.events} event${step.events === 1 ? '' : 's'}`;
+      const frames = step.frames ? `, frames ${step.frames} drawn, ${step.dropped} dropped` : '';
+      lines.push(`  ${at(step.start).padStart(8)}  ${step.kind}  ${span}; busy ${ms(step.busy)}${step.longest ? `, longest task ${ms(step.longest)}` : ''}${frames}`);
+    }
+    if (steps.length < s.steps.length) lines.push(`  (the first ${steps.length} of ${s.steps.length}; profile --all lists them all)`);
+    if (profile.drawing && s.steps.some(step => step.frames)) {
+      lines.push('  Frames are counted as for a tab in front: pw-repl keeps every tab it uses drawing as if it were. Behind another tab, as the user would have it, Chrome draws far less.');
+    }
+  }
+  if (s.cpu) {
+    lines.push(s.cpu.length ? 'JS CPU profile, by own time:' : 'JS CPU profile: no JS ran');
+    for (const f of all ? s.cpu : s.cpu.slice(0, SHOWN)) lines.push(`  ${ms(f.us).padStart(7)}  ${f.where}`);
+  }
+  out.printOutput(lines.join('\n'), true);
+}
+
+const commands = {
+  async profile(args, all) {
+    const [sub, ...rest] = (args || '').trim().split(/\s+/).filter(Boolean);
+    if (sub === 'on') return startProfile(rest);
+    if (sub === 'off' && !rest.length) {
+      // One that ended by itself is printed once it has been read.
+      const ended = !prof && finishing && !finishing.shown;
+      if (!prof && !ended) { out.log('Not profiling.'); return; }
+      if (ended) out.log('The profile had already stopped:');
+      if (prof) prof.stoppedByOff = true;
+      await finishProfile();
+      await finishing;
+      printProfile(last, all);
+      out.log(hints([['profile save <file>', 'write the tab\'s trace, for DevTools\' Performance panel']]));
+      return;
+    }
+    await finishing;
+    if (sub === 'save') return saveProfile(rest.join(' '));
+    if (sub === 'reload' && !rest.length) return profileReload(all);
+    if (sub) throw new Error(`Usage: profile on [seconds] [--cpu] | off | save <file> | reload`);
+    if (prof) {
+      out.log(`Profiling ${prof.page.url()} since ${clock(prof.startedAt)}${prof.owner ? `, for ${prof.owner}` : ''}`);
+      out.log(hints([['profile off', 'stop and print a summary']]));
+      return;
+    }
+    if (last) {
+      out.log(`Not profiling. The last profile, from ${clock(last.startedAt)}:`);
+      printProfile(last, all);
+    } else {
+      out.log('Not profiling.');
+    }
+    out.log(hints([
+      ['profile on [seconds]', 'record what the selected tab\'s main thread does'],
+      ['profile reload', 'profile the selected tab\'s page as it loads'],
+    ]));
+  },
+};
+
+async function profileReload(all) {
+  if (prof) throw new Error(`Already profiling ${prof.page.url()}; profile off stops it`);
+  if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
+  const page = state.page;
+  await startProfile([], true);
+  let note = null;
+  try {
+    await page.reload({ waitUntil: 'load' });
+    await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => { note = 'Its network was still busy 10s after load; the profile stops there.'; });
+    // Its largest paint and the work after load land in the next frames.
+    await page.waitForTimeout(500);
+  } finally {
+    await finishProfile();
+  }
+  printProfile(last, all);
+  if (note) out.log(note);
+}
+
+function saveProfile(file) {
+  if (!file) throw new Error('Usage: profile save <file>, e.g. profile save load.json');
+  if (prof) throw new Error('Still profiling; profile off stops it first');
+  if (!last?.saveFile || !fs.existsSync(last.saveFile)) throw new Error('No profile to save: profile on records one first');
+  if (fs.existsSync(file)) throw new Error(`${file} exists already; name another file`);
+  if (!fs.existsSync(path.dirname(path.resolve(file)))) throw new Error(`No folder ${path.dirname(path.resolve(file))} to save ${path.basename(file)} in`);
+  fs.copyFileSync(last.saveFile, file, fs.constants.COPYFILE_EXCL);
+  const kb = Math.round(fs.statSync(file).size / 1024);
+  out.log(`Saved the profile of ${last.url} to ${file} (${kb} KB): the tab's events only. Chrome DevTools' Performance panel (Load profile) and ui.perfetto.dev open it.`);
+}
+
+// A profile must not outlive the REPL: Chrome traces one at a time, for the whole browser.
+onShutdown(async () => {
+  if (prof) {
+    const { session } = prof;
+    prof = null;
+    await session.send('Tracing.end').catch(() => {});
+    await session.detach().catch(() => {});
+  }
+  if (dir) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+module.exports = { commands, currentProfile, finishProfile };

package/lib/record.js

@@ -1,12 +1,11 @@
 // Recording a tab's page to a video, from Chrome's screencast of it through ffmpeg.
 const { spawn, execFileSync } = require('child_process');
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const { state, onShutdown } = require('./state');
 const out = require('./output');
 const { tabState } = require('./tabstate');
-const { clock, NO_TAB, STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
+const { clock, NO_TAB, STOPPED_RECORDING, ENDED_UNSEEN, playwrightBrowsersDir } = require('./util');
 const { shellWords, splitSelector } = require('./syntax');
 const { reapplyMetrics } = require('./emulation');
 
@@ -38,7 +37,7 @@ const FORMAT_NAMES = { webm: 'WebM (VP8)', mp4: 'MP4 (H.264)' };
 // Playwright's own (wherever PLAYWRIGHT_BROWSERS_PATH puts it), then one on the PATH.
 function ffmpegCandidates() {
   const found = [];
-  const dir = process.env.PLAYWRIGHT_BROWSERS_PATH || path.join(os.homedir(), '.cache', 'ms-playwright');
+  const dir = playwrightBrowsersDir();
   let names = [];
   try { names = fs.readdirSync(dir).filter(n => /^ffmpeg-\d+$/.test(n)).sort().reverse(); } catch {}
   for (const name of names) {

package/lib/runner.js

@@ -33,10 +33,10 @@ const READ_ONLY = new Set(['info', 'listeners', 'text', 'html', 'attrs', 'count'
   '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', 'record', 'dialog', 'help', 'quit', 'tab-select', 'close']);
+const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'profile', 'record', 'dialog', 'help', 'quit', 'tab-select', 'close']);
 
 // Commands that accept --all, right after the command or at the end, to lift the output limit.
-const INSPECTION = ['info', 'listeners', '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', 'profile', '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

@@ -114,7 +114,8 @@ function commandLine(words) {
       return words[n - 1] === '--filename' || !/^(?:\d+|-.*)$/.test(w) ? resolve(w) : w;
     });
   }
-  // watch save writes its file.
+  // watch save and profile save write their files.
+  if (words[0] === 'profile' && words[1] === 'save' && words.length > 2) resolved = ['profile', 'save', resolve(words.slice(2).join(' '))];
   if (words[0] === 'watch' && words[1] === 'save' && words.length > 2) resolved = ['watch', 'save', resolve(words.slice(2).join(' '))];
   if (words[0] === 'screenshot') {
     resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : w));
@@ -131,7 +132,7 @@ function commandLine(words) {
 
 // A file of commands, one per line, run in turn until one fails. A recording it started and did not
 // stop is still on: the next take would fail to start, so it says so.
-const PATHS = /^(?:upload|record|video-start|video-stop|screenshot|watch)$/;
+const PATHS = /^(?:upload|record|video-start|video-stop|screenshot|watch|profile)$/;
 // The values of the {{ PW_NAME }} variables in a command, from send's environment: { vars }, null with
 // none, or { error } for one that is not set or has a line break.
 function variablesFor(command) {

package/lib/tabs.js

@@ -259,4 +259,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, markStartTab, isOpening, openTab, listTabs };
+module.exports = { commands, markStartTab, isOpening, openTab, listTabs, targetIdOf };

package/lib/trace.js

@@ -0,0 +1,509 @@
+// Reading a Chrome performance trace for one tab: what its main thread was busy with, its long
+// tasks, forced layouts, frames and the input it handled. The trace is the whole browser's; the tab's
+// events are told apart by its renderer process, found from events that name its main frame.
+const fs = require('fs');
+const readline = require('readline');
+
+const LONG_TASK = 50000;
+const BIG_REQUEST = 100 * 1024;
+// Input events this close together are one step: a wheel-zoom or a scroll is many events.
+const STEP_GAP = 300000;
+// A step's frames and busy time include this long after its last input, for what it drew.
+const STEP_TAIL = 100000;
+
+const BUCKETS = ['scripting', 'style/layout', 'paint', 'GC', 'other'];
+
+// DevTools' categories, by event name; anything else counts as the task's own time, other.
+const SCRIPTING = new Set(['FunctionCall', 'EvaluateScript', 'v8.evaluateModule', 'v8.compile', 'v8.compileModule',
+  'V8.CompileCode', 'v8.produceCache', 'v8.run', 'TimerFire', 'EventDispatch', 'FireAnimationFrame', 'FireIdleCallback',
+  'RunMicrotasks', 'XHRReadyStateChange', 'XHRLoad', 'v8.callFunction', 'v8.parseOnBackground', 'CppGC.IncrementalSweep']);
+const LAYOUT = new Set(['UpdateLayoutTree', 'RecalculateStyles', 'Layout', 'HitTest', 'IntersectionObserverController::computeIntersections']);
+const PAINT = new Set(['Paint', 'PaintImage', 'PrePaint', 'Layerize', 'UpdateLayer', 'UpdateLayerTree', 'CompositeLayers',
+  'Commit', 'Decode Image', 'Draw LazyPixelRef', 'Decode LazyPixelRef', 'ImageDecodeTask']);
+const GC = new Set(['MinorGC', 'MajorGC', 'BlinkGC.AtomicPhase', 'V8.GCScavenger', 'V8.GCFinalizeMC', 'V8.GCIncrementalMarking',
+  'V8.GC_MC_BACKGROUND_EVACUATE_COPY', 'BlinkGC.ConcurrentMarking', 'CppGC.AtomicMark']);
+
+function bucketOf(name) {
+  if (SCRIPTING.has(name)) return 'scripting';
+  if (LAYOUT.has(name)) return 'style/layout';
+  if (PAINT.has(name)) return 'paint';
+  if (GC.has(name) || /^(?:V8|CppGC|BlinkGC)\.GC|GC$/.test(name)) return 'GC';
+  return null;
+}
+
+// What set a task off, from the first event in it that says.
+const TRIGGERS = { TimerFire: 'timer', FireAnimationFrame: 'animation frame', FireIdleCallback: 'idle callback',
+  ParseHTML: 'parsing HTML', XHRLoad: 'XHR load', XHRReadyStateChange: 'XHR', RunMicrotasks: 'promise callbacks' };
+
+const RUN_TASK = new Set(['RunTask', 'ThreadControllerImpl::RunTask']);
+
+// The main thread's events the summary times by name alone, read without parsing them: most of a busy
+// trace (a style recalculation and a paint per element changed).
+function timedOnly(name) {
+  return !DETAILED.has(name) && (RUN_TASK.has(name) || bucketOf(name) || TRIGGERS[name] || name === 'ParseHTML');
+}
+const DETAILED = new Set(['FunctionCall', 'EvaluateScript', 'EventDispatch', 'Layout', 'UpdateLayoutTree']);
+// The rest that collect reads.
+const PARSED = new Set([...DETAILED, 'EventTiming', 'PipelineReporter', 'ResourceSendRequest', 'ResourceFinish', 'MarkDOMContent',
+  'MarkLoad', 'navigationStart', 'firstContentfulPaint', 'largestContentfulPaint::Candidate', 'Profile', 'ProfileChunk']);
+
+// The trace's events, one at a time: Chrome writes each on a line of its own. A trace runs to hundreds
+// of megabytes, mostly other processes' events: wanted(line) passes over a line before it is parsed.
+async function eachEvent(file, fn, wanted = null) {
+  await eachLine(file, line => {
+    if (wanted && !wanted(line)) return;
+    let event;
+    try { event = JSON.parse(line); } catch { return; }
+    fn(event, line);
+  });
+}
+
+async function eachLine(file, fn) {
+  const lines = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity });
+  for await (let line of lines) {
+    if (!line.startsWith('{"') || line.startsWith('{"traceEvents"')) continue;
+    if (line.endsWith(',')) line = line.slice(0, -1);
+    // The last event shares its line with the end of the list, and the start of the trace's metadata.
+    else line = line.replace(/\](?:,"metadata":.*|\})$/, '');
+    fn(line);
+  }
+}
+
+function nameOf(line) {
+  const at = line.lastIndexOf('"name":"');
+  return at < 0 ? '' : line.slice(at + 8, line.indexOf('"', at + 8));
+}
+
+// A number field of an event, read from its line without parsing it. Chrome writes the keys in order,
+// args first, so the last one by that name is the event's own.
+function field(line, name) {
+  const at = line.lastIndexOf(`"${name}":`);
+  return at < 0 ? NaN : parseFloat(line.slice(at + name.length + 3));
+}
+
+function frameOf(e) {
+  return e.args?.data?.frame || e.args?.frame || null;
+}
+
+function shortUrl(url) {
+  if (!url) return '';
+  try {
+    const u = new URL(url);
+    if (u.protocol === 'data:') return 'data:…';
+    const file = u.pathname.split('/').filter(Boolean).pop();
+    return file || u.host;
+  } catch {
+    return url.slice(0, 60);
+  }
+}
+
+// url:line function, as DevTools names a function. Lines are 1-based in the trace's events and stacks,
+// 0-based in its JS samples' call frames.
+function where(frame, zeroBased = false) {
+  if (!frame) return '';
+  const line = frame.lineNumber != null && frame.lineNumber >= 0 ? `:${frame.lineNumber + (zeroBased ? 1 : 0)}` : '';
+  const fn = frame.functionName || '(anonymous)';
+  return `${shortUrl(frame.url)}${line} ${fn}`.trim();
+}
+
+// Reads the trace twice: once to find the tab's renderer processes and their threads, then to sum
+// up the tab's events, writing them (with what DevTools needs to open them) to saveFile.
+async function summarize(file, { frameId, url, saveFile, cpu = false }) {
+  const pids = new Set();
+  const threads = new Map();
+  let started = null;
+  let firstTs = Infinity;
+  let lastTs = 0;
+  const firstSeen = new Map();
+  await eachEvent(file, e => {
+    if (e.name === 'thread_name' && e.ph === 'M') threads.set(`${e.pid}:${e.tid}`, e.args?.name);
+    if (e.name === 'TracingStartedInBrowser') started = e;
+    if (frameOf(e) === frameId && e.pid) pids.add(e.pid);
+  }, line => {
+    const ts = field(line, 'ts');
+    if (ts && !line.includes('"ph":"M"')) {
+      const pid = field(line, 'pid');
+      if (!firstSeen.has(pid)) firstSeen.set(pid, ts);
+      firstTs = Math.min(firstTs, ts);
+      lastTs = Math.max(lastTs, ts + (field(line, 'dur') || 0));
+    }
+    return line.includes('"thread_name"') || line.includes('TracingStartedInBrowser') || line.includes(frameId);
+  });
+  const mainOf = new Map();
+  const compositorOf = new Map();
+  for (const [key, name] of threads) {
+    const [pid, tid] = key.split(':').map(Number);
+    if (!pids.has(pid)) continue;
+    if (name === 'CrRendererMain') mainOf.set(pid, tid);
+    if (name === 'Compositor') compositorOf.set(pid, tid);
+  }
+  // The browser process names the tab's frame too (its navigations): only renderers are the tab's.
+  for (const pid of pids) if (!mainOf.has(pid)) pids.delete(pid);
+  const t0 = started?.ts ?? firstTs;
+  const tracks = { main: new Events(), timings: new Map(), frames: [], requests: new Map(), marks: {}, profiles: new Map() };
+  // Written as it is read, in batches: a write stream would hold what the disk has not taken yet.
+  const save = saveFile ? { fd: fs.openSync(saveFile, 'w', 0o600), started: false, chunk: [], size: 0 } : null;
+  const flush = () => { fs.writeSync(save.fd, save.chunk.join('')); save.chunk = []; save.size = 0; };
+  const write = line => {
+    save.chunk.push(`${save.started ? ',\n' : '{"traceEvents":[\n'}${line}`);
+    save.started = true;
+    save.size += line.length;
+    if (save.size > 1 << 20) flush();
+  };
+  // DevTools finds the tab's renderer from these, which a trace of the whole browser leaves out.
+  if (save && started) {
+    const [first, ...later] = [...pids].map(pid => [pid, firstSeen.get(pid)]).sort((a, b) => a[1] - b[1]);
+    if (first) {
+      write(JSON.stringify({ ...started, args: { data: { frameTreeNodeId: 0, persistentIds: true, frames: [{ frame: frameId, url, name: '', processId: first[0] }] } } }));
+      for (const [pid, ts] of later) {
+        write(JSON.stringify({ ...started, name: 'FrameCommittedInBrowser', ts, args: { data: { frame: frameId, url, name: '', processId: pid } } }));
+      }
+    }
+  }
+  try {
+    await eachLine(file, line => {
+      const pid = field(line, 'pid');
+      if (!pids.has(pid)) return;
+      if (save) write(line);
+      const name = nameOf(line);
+      const main = mainOf.get(pid) === field(line, 'tid');
+      if (main && timedOnly(name)) {
+        if (line.includes('"ph":"X"')) tracks.main.push(name, field(line, 'ts'), field(line, 'dur') || 0, null);
+        return;
+      }
+      if (!PARSED.has(name)) return;
+      let e;
+      try { e = JSON.parse(line); } catch { return; }
+      collect(e, tracks, { frameId, main, compositor: compositorOf.get(pid) === e.tid });
+    });
+    if (save) {
+      if (!save.started) save.chunk.push('{"traceEvents":[');
+      save.chunk.push('\n]}\n');
+      flush();
+    }
+  } finally {
+    if (save) fs.closeSync(save.fd);
+  }
+  if (!pids.size) return null;
+  return analyse(tracks, t0, Math.max(lastTs, t0), { cpu });
+}
+
+// The main thread's events, kept compact: a busy page makes hundreds of thousands in a minute (a style
+// recalculation and a paint per element it changes). Their times and names in typed arrays; the few
+// details the summary names (a script, an event's type, a forced layout's stack) beside them.
+class Events {
+  constructor() {
+    this.n = 0;
+    this.ts = new Float64Array(1024);
+    this.dur = new Float64Array(1024);
+    this.code = new Uint8Array(1024);
+    this.names = [];
+    this.codes = new Map();
+    this.details = new Map();
+  }
+
+  push(name, ts, dur, detail) {
+    if (this.n === this.ts.length) {
+      for (const key of ['ts', 'dur', 'code']) {
+        const grown = new this[key].constructor(this.n * 2);
+        grown.set(this[key]);
+        this[key] = grown;
+      }
+    }
+    if (!this.codes.has(name)) { this.codes.set(name, this.names.length); this.names.push(name); }
+    this.ts[this.n] = ts;
+    this.dur[this.n] = dur;
+    this.code[this.n] = this.codes.get(name);
+    if (detail) this.details.set(this.n, detail);
+    this.n += 1;
+  }
+
+  name(i) {
+    return this.names[this.code[i]];
+  }
+}
+
+function collect(e, tracks, { frameId, main, compositor }) {
+  const data = e.args?.data;
+  if (main && e.ph === 'X' && (RUN_TASK.has(e.name) || bucketOf(e.name) || TRIGGERS[e.name] || e.name === 'ParseHTML')) {
+    let detail = null;
+    if (e.name === 'FunctionCall' || e.name === 'EvaluateScript') detail = { frame: { url: data?.url, lineNumber: data?.lineNumber, functionName: data?.functionName } };
+    if (e.name === 'EventDispatch') detail = { type: data?.type };
+    // A style recalculation or layout with the page's script on the stack: one the script waited for (pw-repl's
+    // own scripts have no URL).
+    if ((e.name === 'Layout' || e.name === 'UpdateLayoutTree') && e.args?.beginData?.stackTrace?.[0]?.url) detail = { stack: e.args.beginData.stackTrace[0] };
+    tracks.main.push(e.name, e.ts, e.dur || 0, detail);
+  }
+  if (e.name === 'EventTiming' && e.ph === 'b' && data?.interactionId && frameOf(e) === frameId) {
+    const list = tracks.timings.get(data.interactionId) || [];
+    list.push({ ts: e.ts, ...data });
+    tracks.timings.set(data.interactionId, list);
+  }
+  if (compositor && e.name === 'PipelineReporter' && e.ph === 'b') {
+    const state = e.args?.frame_reporter?.state;
+    if (state && state !== 'STATE_NO_UPDATE_DESIRED') tracks.frames.push({ ts: e.ts, dropped: state === 'STATE_DROPPED' });
+  }
+  if (e.name === 'ResourceSendRequest' && data?.requestId) tracks.requests.set(data.requestId, { url: data.url, method: data.requestMethod, sent: e.ts });
+  if (e.name === 'ResourceFinish' && data?.requestId) {
+    const request = tracks.requests.get(data.requestId);
+    // One from the cache has no encoded length.
+    if (request) Object.assign(request, { finished: e.ts, size: Math.max(data.encodedDataLength || 0, data.decodedBodyLength || 0), failed: data.didFail });
+  }
+  const isMain = data?.isOutermostMainFrame ?? data?.isMainFrame;
+  if (e.name === 'MarkDOMContent' && isMain && frameOf(e) === frameId) tracks.marks.DOMContentLoaded ??= e.ts;
+  if (e.name === 'MarkLoad' && isMain && frameOf(e) === frameId) tracks.marks.load ??= e.ts;
+  if (e.name === 'navigationStart' && frameOf(e) === frameId) tracks.marks.navigation ??= e.ts;
+  if (e.name === 'firstContentfulPaint' && frameOf(e) === frameId) tracks.marks['first contentful paint'] ??= e.ts;
+  if (e.name === 'largestContentfulPaint::Candidate' && frameOf(e) === frameId) tracks.marks['largest contentful paint'] = e.ts;
+  // The JS sampling profile of a thread: its call tree and samples, in chunks after a Profile event
+  // on the thread it samples.
+  if ((e.name === 'Profile' || e.name === 'ProfileChunk') && e.id) {
+    const profile = tracks.profiles.get(`${e.pid}:${e.id}`) || { nodes: new Map(), samples: [], deltas: [] };
+    if (e.name === 'Profile') Object.assign(profile, { main, startTime: data?.startTime });
+    const cpu = data?.cpuProfile;
+    for (const node of cpu?.nodes || []) profile.nodes.set(node.id, { ...node.callFrame, parent: node.parent });
+    for (const id of cpu?.samples || []) profile.samples.push(id);
+    for (const delta of data?.timeDeltas || []) profile.deltas.push(delta);
+    tracks.profiles.set(`${e.pid}:${e.id}`, profile);
+  }
+}
+
+// The main thread's events nested as they ran: the order they started in, each one's own time (less
+// its children's), and its top-level task. A task's events follow it in that order, up to its end.
+function nest(events) {
+  const { n, ts, dur } = events;
+  const order = new Uint32Array(n);
+  for (let i = 0; i < n; i++) order[i] = i;
+  order.sort((a, b) => ts[a] - ts[b] || dur[b] - dur[a]);
+  const self = Float64Array.from(dur.subarray(0, n));
+  const taskOf = new Int32Array(n).fill(-1);
+  const tasks = [];
+  const stack = [];
+  for (let p = 0; p < n; p++) {
+    const i = order[p];
+    while (stack.length && ts[stack[stack.length - 1]] + dur[stack[stack.length - 1]] <= ts[i]) stack.pop();
+    const parent = stack[stack.length - 1];
+    if (parent !== undefined) { self[parent] -= Math.min(dur[i], ts[parent] + dur[parent] - ts[i]); taskOf[i] = taskOf[parent]; }
+    else if (RUN_TASK.has(events.name(i))) { taskOf[i] = i; tasks.push({ i, p, ts: ts[i], dur: dur[i] }); }
+    stack.push(i);
+  }
+  for (const task of tasks) {
+    let p = task.p + 1;
+    while (p < n && ts[order[p]] < task.ts + task.dur) p++;
+    task.end = p;
+  }
+  return { order, self, taskOf, tasks };
+}
+
+// The main thread's JS samples in time order: when each was taken, how long it stands for, and the
+// page's function it was in (an index into keys), -1 for none.
+function mainSamples(profiles) {
+  const keys = [];
+  const keyIndex = new Map();
+  const taken = [];
+  for (const { main, startTime, nodes, samples: ids, deltas } of profiles.values()) {
+    if (!main || startTime == null) continue;
+    const scriptOf = new Map();
+    let t = startTime;
+    for (let i = 0; i < ids.length; i++) {
+      t += deltas[i] ?? 0;
+      if (!scriptOf.has(ids[i])) {
+        const frame = scriptFrame(nodes, nodes.get(ids[i]));
+        const key = frame ? where(frame, true) : null;
+        if (key !== null && !keyIndex.has(key)) { keyIndex.set(key, keys.length); keys.push(key); }
+        scriptOf.set(ids[i], key === null ? -1 : keyIndex.get(key));
+      }
+      const frame = nodes.get(ids[i]);
+      taken.push(t, scriptOf.get(ids[i]), cpuKey(frame, scriptFrame(nodes, frame), keyIndex, keys));
+    }
+  }
+  const count = taken.length / 3;
+  const order = new Uint32Array(count);
+  for (let i = 0; i < count; i++) order[i] = i;
+  order.sort((a, b) => taken[a * 3] - taken[b * 3]);
+  const samples = { t: new Float64Array(count), us: new Float64Array(count), script: new Int32Array(count), own: new Int32Array(count), keys };
+  for (let k = 0; k < count; k++) {
+    samples.t[k] = taken[order[k] * 3];
+    samples.script[k] = taken[order[k] * 3 + 1];
+    samples.own[k] = taken[order[k] * 3 + 2];
+  }
+  // Samples can come out of order (a negative delta); each stands for the time until the next one,
+  // but no more than a few intervals, so one before a pause does not take the pause.
+  for (let k = 0; k < count; k++) samples.us[k] = k + 1 < count ? Math.min(samples.t[k + 1] - samples.t[k], 2000) : 0;
+  return samples;
+}
+
+// The function a sample itself was in, for --cpu's list: a built-in with the page's function that
+// called it; -1 for idle, and for code not the page's (pw-repl's own, run in the page, has no URL).
+function cpuKey(frame, script, keyIndex, keys) {
+  if (!frame || /^\((?:idle|program|root)\)$/.test(frame.functionName)) return -1;
+  let key;
+  if (frame.url) key = where(frame, true);
+  else if (frame.functionName === '(garbage collector)') key = frame.functionName;
+  else if (script) key = `${frame.functionName || '(anonymous)'} (built-in, from ${where(script, true)})`;
+  else return -1;
+  if (!keyIndex.has(key)) { keyIndex.set(key, keys.length); keys.push(key); }
+  return keyIndex.get(key);
+}
+
+// The page's own function a sample was in: a built-in (performance.now, JSON.parse) counts as the
+// function that called it.
+function scriptFrame(nodes, frame) {
+  for (let f = frame, depth = 0; f && depth < 200; f = nodes.get(f.parent), depth++) if (f.url) return f;
+  return null;
+}
+
+// The page's function that ran longest itself between two times, from the samples.
+function hottest(samples, from, to) {
+  const self = new Map();
+  for (let k = lowerBound(samples.t, from); k < samples.t.length && samples.t[k] < to; k++) {
+    if (samples.script[k] < 0) continue;
+    self.set(samples.script[k], (self.get(samples.script[k]) || 0) + samples.us[k]);
+  }
+  const [top] = [...self].sort((a, b) => b[1] - a[1]);
+  return top ? { where: samples.keys[top[0]], us: top[1] } : null;
+}
+
+function lowerBound(times, t) {
+  let lo = 0;
+  let hi = times.length;
+  while (lo < hi) { const mid = (lo + hi) >> 1; if (times[mid] < t) lo = mid + 1; else hi = mid; }
+  return lo;
+}
+
+function analyse(tracks, t0, tEnd, { cpu }) {
+  const events = tracks.main;
+  const nested = nest(events);
+  const samples = mainSamples(tracks.profiles);
+  const buckets = Object.fromEntries(BUCKETS.map(b => [b, 0]));
+  for (let i = 0; i < events.n; i++) {
+    if (nested.taskOf[i] < 0) continue;
+    buckets[bucketOf(events.name(i)) || 'other'] += Math.max(0, nested.self[i]);
+  }
+  const busy = nested.tasks.reduce((sum, t) => sum + t.dur, 0);
+  const big = [...tracks.requests.values()].filter(r => r.finished && !r.failed && r.size >= BIG_REQUEST).sort((a, b) => a.finished - b.finished);
+  const longTasks = nested.tasks.filter(t => t.dur >= LONG_TASK).map(t => ({ ...describeTask(t, events, nested, big), hot: hottest(samples, t.ts, t.ts + t.dur) }));
+  const forced = new Map();
+  for (const [i, detail] of events.details) {
+    if (!detail.stack) continue;
+    const kind = events.name(i) === 'Layout' ? 'layout' : 'style';
+    const key = `${where(detail.stack)} (${kind})`;
+    const entry = forced.get(key) || { where: key, count: 0, dur: 0 };
+    entry.count += 1;
+    entry.dur += events.dur[i];
+    forced.set(key, entry);
+  }
+  return {
+    t0, duration: tEnd - t0, busy, buckets,
+    marks: Object.entries(tracks.marks).sort((a, b) => a[1] - b[1]),
+    longTasks,
+    forced: [...forced.values()].sort((a, b) => b.dur - a.dur),
+    steps: steps(tracks, events, nested),
+    cpu: cpu ? cpuTop(samples) : null,
+    frames: tracks.frames.length,
+  };
+}
+
+function describeTask(task, events, { order, self }, big) {
+  const own = {};
+  let trigger = null;
+  let script = null;
+  for (let p = task.p; p < task.end; p++) {
+    const i = order[p];
+    const name = events.name(i);
+    const b = bucketOf(name) || 'other';
+    own[b] = (own[b] || 0) + Math.max(0, self[i]);
+    // One task can dispatch several events (pointerdown, mousedown, click): the one that took longest.
+    if ((name === 'EventDispatch' || TRIGGERS[name] || name === 'EvaluateScript') && (!trigger || events.dur[i] > events.dur[trigger])) trigger = i;
+    if (events.details.get(i)?.frame?.url && (script === null || events.dur[i] > events.dur[script])) script = i;
+  }
+  const kind = Object.entries(own).sort((a, b) => b[1] - a[1])[0][0];
+  const triggerName = trigger === null ? null : events.name(trigger);
+  const triggerText = triggerName === null ? null : triggerName === 'EventDispatch' ? `${events.details.get(trigger).type} event` : triggerName === 'EvaluateScript' ? 'script' : TRIGGERS[triggerName];
+  const after = big.filter(r => r.finished <= task.ts && task.ts - r.finished < 1000000).pop() || null;
+  return { ts: task.ts, dur: task.dur, kind, trigger: triggerText, script: script === null ? null : where(events.details.get(script).frame), after };
+}
+
+// Each step of the user's: an interaction (click, key), a burst of wheel or scroll events, or a drag
+// (pointer down, moves, up), with what the page did in it. Interactions inside a drag are its own.
+function steps(tracks, events, { taskOf, tasks }) {
+  const found = [];
+  const dispatches = [...events.details].filter(([, d]) => d.type).map(([i, d]) => ({ ts: events.ts[i], dur: events.dur[i], type: d.type, task: taskOf[i] })).sort((a, b) => a.ts - b.ts);
+  // A step starts with the task its first event ran in.
+  const began = e => (e.task >= 0 ? events.ts[e.task] : e.ts);
+  let burst = null;
+  for (const e of dispatches.filter(d => /^(?:wheel|mousewheel|scroll)$/.test(d.type))) {
+    if (burst && e.ts - burst.end <= STEP_GAP) { burst.end = e.ts + e.dur; burst.events += 1; continue; }
+    burst = { kind: 'wheel/scroll', start: began(e), end: e.ts + e.dur, events: 1 };
+    found.push(burst);
+  }
+  let down = null;
+  let moves = 0;
+  for (const e of dispatches) {
+    if (/^(?:pointerdown|mousedown|touchstart)$/.test(e.type)) { if (!down) { down = e; moves = 0; } }
+    else if (down && /^(?:pointermove|mousemove|touchmove)$/.test(e.type)) moves += 1;
+    else if (down && /^(?:pointerup|mouseup|touchend|pointercancel|touchcancel)$/.test(e.type)) {
+      if (moves >= 3) found.push({ kind: 'drag', start: began(down), end: e.ts + e.dur, events: moves });
+      down = null;
+    }
+  }
+  // An interaction's latency is its slowest event's, to the paint after it, as DevTools has it; a key's
+  // keydown and keyup share an interaction but not a frame. It is split over the events shown in that
+  // frame (pointerup and click): input delay to the first handler, handlers to the last one's end,
+  // presentation from then to the paint.
+  const drags = found.filter(s => s.kind === 'drag');
+  for (const list of tracks.timings.values()) {
+    const ts = Math.min(...list.map(t => t.ts));
+    const end = Math.max(...list.map(t => t.ts + t.duration * 1000));
+    if (drags.some(s => ts <= s.end && end >= s.start)) continue;
+    const slowest = list.reduce((a, b) => (b.duration > a.duration ? b : a));
+    const painted = slowest.timeStamp + slowest.duration;
+    const frame = list.filter(t => Math.abs(t.timeStamp + t.duration - painted) < 8);
+    const startAt = Math.min(...frame.map(t => t.timeStamp));
+    const processingStart = Math.min(...frame.map(t => t.processingStart));
+    const processingEnd = Math.max(...frame.map(t => t.processingEnd));
+    const latency = slowest.duration;
+    const type = list.some(t => /^key/.test(t.type)) ? 'key press' : list.some(t => /click|pointer|mouse/.test(t.type)) ? 'click' : list[0].type;
+    found.push({
+      kind: type, start: ts, end, latency,
+      delay: processingStart - startAt, handlers: processingEnd - processingStart,
+      presentation: Math.max(0, latency - (processingEnd - startAt)),
+    });
+  }
+  found.sort((a, b) => a.start - b.start);
+  const taskStarts = tasks.map(t => t.ts);
+  const frames = tracks.frames.sort((a, b) => a.ts - b.ts);
+  const frameTimes = frames.map(f => f.ts);
+  for (const [i, step] of found.entries()) {
+    // Up to the next step, which what follows is counted in.
+    const end = Math.max(step.end, Math.min(step.end + STEP_TAIL, found[i + 1]?.start ?? Infinity));
+    step.busy = 0;
+    step.longest = 0;
+    // Tasks in start order; one that began before the step and runs into it counts its part.
+    for (let k = Math.max(0, lowerBound(taskStarts, step.start) - 1); k < tasks.length && tasks[k].ts < end; k++) {
+      const t = tasks[k];
+      if (t.ts + t.dur <= step.start) continue;
+      step.busy += Math.min(t.ts + t.dur, end) - Math.max(t.ts, step.start);
+      if (t.ts >= step.start) step.longest = Math.max(step.longest, t.dur);
+    }
+    step.frames = 0;
+    step.dropped = 0;
+    for (let k = lowerBound(frameTimes, step.start); k < frames.length && frames[k].ts < end; k++) {
+      step.frames += 1;
+      if (frames[k].dropped) step.dropped += 1;
+    }
+  }
+  return found;
+}
+
+// The functions that ran longest themselves, from the sampling profile's samples.
+function cpuTop(samples) {
+  const self = new Map();
+  for (let k = 0; k < samples.t.length; k++) {
+    if (samples.own[k] < 0) continue;
+    self.set(samples.own[k], (self.get(samples.own[k]) || 0) + samples.us[k]);
+  }
+  return [...self].map(([key, us]) => ({ where: samples.keys[key], us })).sort((a, b) => b.us - a.us);
+}
+
+module.exports = { summarize, eachEvent, LONG_TASK };

package/lib/util.js

@@ -1,5 +1,8 @@
 // Small helpers the commands share: output hints, clipping, times, patterns and number arguments.
 
+const os = require('os');
+const path = require('path');
+
 const COMMAND_TIMEOUT = 15000;
 
 const MAX_EVENT_TEXT = 4000;
@@ -51,4 +54,16 @@ function clock(t) {
 const STOPPED_RECORDING = 'The REPL stopped, which ended a recording';
 const ENDED_UNSEEN = 'A recording ended before the REPL stopped, unseen since';
 
-module.exports = { STOPPED_RECORDING, ENDED_UNSEEN, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock };
+// Where Playwright installs its browsers and ffmpeg, worked out as playwright-core does it: a cache of
+// each platform's own (~/Library/Caches on macOS), unless PLAYWRIGHT_BROWSERS_PATH says otherwise.
+function playwrightBrowsersDir() {
+  const given = process.env.PLAYWRIGHT_BROWSERS_PATH;
+  if (given === '0') return path.join(path.dirname(require.resolve('playwright-core/package.json')), '.local-browsers');
+  if (given) return path.resolve(process.env.INIT_CWD || process.cwd(), given);
+  const cache = process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Caches')
+    : process.platform === 'win32' ? process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')
+      : process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(cache, 'ms-playwright');
+}
+
+module.exports = { STOPPED_RECORDING, ENDED_UNSEEN, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock, playwrightBrowsersDir };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-repl",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "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 the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), 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, recording what the user does, and recording a video of a tab, with a pointer and on-screen captions. 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.
+description: Inspect and drive a Chromium browser, possibly one the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), 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, recording what the user does, profiling what makes a page slow (long tasks, forced layouts, input delay, dropped frames), and recording a video of a tab, with a pointer and on-screen captions. 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.
 allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 ---
 
@@ -181,6 +181,11 @@ When watching someone:
 - A watch belongs to the tab: when another client watches it too, read it with `watch <n>`, since
   `watch new`'s place is shared and each one's would hide steps from the other.
 
+When a page is slow or feels laggy, `requests` shows a slow response; for what the page itself is busy
+with, `profile on` and `profile off` around what you do, or while the user uses it, sum up a performance
+trace of the tab: long tasks and the function behind each, forced layouts, each click's time to the next
+paint, and frames dropped while scrolling or dragging. `profile reload` profiles a load. `help profile`.
+
 Exit status: `0` ok, `1` the command failed, `2` completion not confirmed (outcome unknown: do not
 blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --help` has the options.
 
@@ -249,7 +254,8 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - `PW_FFMPEG` — the ffmpeg `record` uses, and no other, read by the REPL, not by `send` (default:
   Playwright's own, then one on the `PATH`).
 - Playwright's own Chromium and ffmpeg are found where Playwright installs them:
-  `PLAYWRIGHT_BROWSERS_PATH`, or `~/.cache/ms-playwright`.
+  `PLAYWRIGHT_BROWSERS_PATH`, or `~/.cache/ms-playwright` on Linux and `~/Library/Caches/ms-playwright`
+  on macOS.
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
 - `PW_SCREENSHOT_DIR` — where the REPL saves screenshots (a folder that exists), read when it starts,
   not by `send`. Without it, a REPL on a socket of its own saves them next to its socket, and any other