pw-repl 0.12.7 → 0.13.0

package/lib/runner.js

@@ -29,14 +29,16 @@ const DIALOG = /^dialog(?:-accept|-dismiss)?(?:\s|$)/;
 // 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', 'listeners', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs',
+const READ_ONLY = new Set(['info', 'clipboard', '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', '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', 'profile', 'body', 'console', 'snapshot', 'watch'];
+const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'clipboard', 'cookies', 'storage', 'capture', 'profile', 'body', 'console', 'snapshot', 'watch'];
+
+const SUBCOMMANDS = ['run', 'serve', 'attach', 'stop', 'send', 'where', 'skill'];
 
 let queue = Promise.resolve();
 // The server command running now, so a quit at the prompt can answer it.
@@ -63,12 +65,13 @@ function busy() {
   return running > 0;
 }
 
-// A queued command runs as its client; quit and dialog, which skip the queue,
-// run as whoever is running, so they never switch the client under a command.
-async function execute(text, client, direct = false) {
+// A queued command runs as its client; quit and dialog, which skip the queue, run as the client of
+// the queued command running now, so a dialog that holds a client's click answers in that client's tab.
+// run is the command's record (asClient).
+async function execute(text, client, direct = false, run = {}) {
   running += 1;
   try {
-    return direct ? await executeCommand(text) : await asClient(client, () => executeCommand(text));
+    return direct ? await executeCommand(text) : await asClient(client, () => executeCommand(text), run);
   } finally {
     running -= 1;
   }
@@ -100,6 +103,11 @@ async function executeCommand(text) {
   state.currentCommandAt = Date.now();
   const run = Object.hasOwn(commands, cmd) ? commands[cmd] : translated && Object.hasOwn(cliCommands, cmd) ? cliCommands[cmd] : null;
   if (!run) {
+    // An agent fresh from the skill tries send where; those are the command line's, not the REPL's.
+    if (SUBCOMMANDS.includes(cmd)) {
+      out.error(`Error: ${cmd} is a pw-repl subcommand, run at the shell: pw-repl ${cmd}${args ? ' ...' : ''}`);
+      return { status: 'error', cmd };
+    }
     out.log(`Unknown command: ${cmd}. Type 'help' for commands.`);
     return { status: 'error', cmd };
   }
@@ -117,6 +125,10 @@ async function executeCommand(text) {
     stepEnded(step, true);
     // Playwright colours its call log; the codes are noise anywhere but a terminal.
     e.message = String(e.message || '').replace(/\x1b\[[0-9;]*m/g, '');
+    // A page's own error (eval's SyntaxError, a cdp method not found) without Playwright's method name
+    // or the stack of its injected script, which point at Playwright, not at the line that was sent.
+    e.message = e.message.split('\n').filter(line => !/^\s+at /.test(line)).join('\n')
+      .replace(/^(?:page|frame|elementHandle|jsHandle|cdpSession)\.(?:evaluate|evaluateHandle|send): /, '');
     out.error(`Error: ${e.message}`);
     const uncertain = !READ_ONLY.has(cmd) && isUncertain(e);
     if (uncertain) out.error('Outcome unknown: it timed out after it began acting on the page. Check the page before trying again.');
@@ -189,7 +201,9 @@ function enqueue(line) {
 // client names the sender: its commands show as [server:<client>] and use its own selected tab.
 // vars: values for the {{ PW_NAME }} variables in text (from send), filled in to run it; text is shown
 // as written, so a password in one is not in the command as the pane, the log and the prompt's history show it.
-function submit(text, client = null, vars = null) {
+// signal aborts when the sender gives up (send -t): a command still queued is dropped, and one
+// running is no longer waited for, so the queue moves on; whatever it set going may still run.
+function submit(text, client = null, vars = null, signal = null) {
   let run = text;
   if (vars) {
     try { run = expandVariables(text, vars); } catch (error) { return Promise.resolve({ status: 'error', output: `Error: ${error.message}` }); }
@@ -202,6 +216,10 @@ function submit(text, client = null, vars = null) {
   return new Promise(resolve => {
     queue = queue.then(async () => {
       if (state.stopping) return resolve({ status: 'error', output: 'The REPL is shutting down.' });
+      if (signal?.aborted) {
+        console.log(`[server${client ? `:${client}` : ''}] ${text}: dropped, its sender gave up before it ran`);
+        return resolve({ status: 'error', output: 'Dropped: the sender gave up before it ran.' });
+      }
       // Printed above whatever the user at the prompt is typing, which is
       // redrawn afterwards rather than broken up.
       if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
@@ -218,9 +236,21 @@ function submit(text, client = null, vars = null) {
         let result;
         const flight = { text, resolve, answered: false };
         inFlight = flight;
-        const output = await out.collect(async () => { result = await execute(run, client); });
+        const record = { cancelled: false };
+        let giveUp;
+        const gaveUp = new Promise(r => { giveUp = r; });
+        const onAbort = () => {
+          record.cancelled = true;
+          out.take();
+          const cmd = text.split(' ')[0];
+          console.log(`[server${client ? `:${client}` : ''}] ${text}: cancelled, its sender gave up${READ_ONLY.has(cmd) ? '' : '; it may still be acting on the page'}`);
+          giveUp(null);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        const output = await Promise.race([out.collect(async () => { result = await execute(run, client, false, record); }), gaveUp]);
+        signal?.removeEventListener('abort', onAbort);
         if (inFlight === flight) inFlight = null;
-        if (!flight.answered) resolve({ status: result.status, output, uncertain: result.uncertain });
+        if (!flight.answered) resolve(output === null ? { status: 'error', output: 'Cancelled: the sender gave up.' } : { status: result.status, output, uncertain: result.uncertain });
       }
       if (!state.stopping) prompt(true);
     }).catch(e => { out.error(`Error: ${e.message}`); resolve({ status: 'error', output: e.message }); });

package/lib/send.js

@@ -88,6 +88,20 @@ async function viaTmux(session, command, timeoutMs) {
   return 2;
 }
 
+// A word in double quotes, as the REPL reads them (unescapeDouble): every other character goes as it is.
+function doubleQuote(word) {
+  return `"${word.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
+}
+
+// Where eval's --file is, after its --timeout if it has one; -1 when it has none.
+function evalFileAt(words) {
+  if (words[0] !== 'eval') return -1;
+  let at = 1;
+  if (/^--timeout=/.test(words[at] || '')) at += 1;
+  else if (words[at] === '--timeout') at += 2;
+  return /^--file(?:=|$)/.test(words[at] || '') ? at : -1;
+}
+
 // A command's words as send was given them, made into the line the REPL reads: quoted again where the
 // shell had kept a word whole, and with the files it reads or writes made absolute from the sender's
 // folder, since the REPL's may be another.
@@ -99,8 +113,8 @@ function commandLine(words) {
   const { SELECTOR_FIRST } = require('./syntax');
   // So does playwright-cli's storage key (localstorage-set "my key" v).
   // And record's file, which may have spaces in it, and wait's text, whose last word would otherwise be
-  // taken as the seconds when it is a number (wait text 'Showing 1').
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || words[0] === 'wait' || /^video-(?:start|stop)$/.test(words[0]));
+  // taken as the time when it is a number (wait text 'Showing 1').
+  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || words[0] === 'drag' || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || words[0] === 'wait' || /^video-(?:start|stop)$/.test(words[0]));
   // An empty word (fill #name "") is the empty value.
   // upload's files are read by the REPL, whose folder may not be this one.
   // So are the files upload reads and screenshot --filename writes.
@@ -117,15 +131,22 @@ function commandLine(words) {
   // 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(' '))];
+  // So does the file eval --file reads.
+  const at = evalFileAt(words);
+  if (at > 0) {
+    // As one word, --file=<path>, which is quoted below when the path has spaces.
+    const [file, rest] = words[at] === '--file' ? [words[at + 1], words.slice(at + 2)] : [words[at].slice(7), words.slice(at + 1)];
+    if (file) resolved = [...words.slice(0, at), `--file=${resolve(file)}`, ...rest];
+  }
   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));
   }
-  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
+  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? doubleQuote(w) : w)) : resolved;
   // An option's value the shell kept whole stays whole too: --device='iPhone 15'.
   // Single quotes escape nothing, so a backslash (a regexp's \d) reaches it as typed.
   for (const [n, w] of quoted.entries()) {
     const option = /^(--[A-Za-z][\w-]*=)([\s\S]*\s[\s\S]*)$/.exec(w);
-    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? JSON.stringify(option[2]) : `'${option[2]}'`}`;
+    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? doubleQuote(option[2]) : `'${option[2]}'`}`;
   }
   return quoted.join(' ').trim();
 }
@@ -155,7 +176,8 @@ async function sendFile(options) {
     console.log(`> ${line}`);
     // Read as the prompt reads it; a file it reads or writes is the sender's, as on send's command line.
     const words = shellWords(line);
-    const command = PATHS.test(words[0]) ? commandLine(words) : line;
+    // eval's own line keeps its quotes; only eval --file names a file.
+    const command = PATHS.test(words[0]) || evalFileAt(words) > 0 ? commandLine(words) : line;
     const found = options.noVars ? null : variablesFor(command);
     if (found?.error) { console.error(`pw-repl: stopped at line ${i + 1} of ${options.file} (${line}): ${found.error}`); return 1; }
     const status = await send({ ...options, file: null, command, vars: found?.vars || null });
@@ -182,7 +204,7 @@ async function send(options) {
     if (found?.error) return fail(found.error);
     options = { ...options, vars: found?.vars || null };
   }
-  const timeoutMs = options.timeout * 1000;
+  const timeoutMs = options.timeout;
   const way = route(options);
   const name = options.client || process.env.PW_CLIENT || null;
   if (name && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(name)) return fail('a client name is 1-40 letters, digits, dots, dashes and underscores');

package/lib/server.js

@@ -56,7 +56,10 @@ function handle(req, res) {
     }
     // Bound before the browser is reached, so where and send find it while it starts.
     if (!state.serving) return send(res, 503, { status: 'error', starting: true, output: `The REPL is starting (${state.startingStep}); retry shortly` });
-    const result = await runner.submit(command.trim(), client || null, vars || null);
+    // The sender gave up (send -t) once its connection closes before the answer is written.
+    const gone = new AbortController();
+    res.once('close', () => { if (!res.writableEnded) gone.abort(); });
+    const result = await runner.submit(command.trim(), client || null, vars || null, gone.signal);
     if (!result.uncertain) return send(res, 200, { status: result.status, output: result.output });
     // unconfirmed: the command may or may not have done what it was sent to do.
     send(res, 200, { status: result.status, output: result.output, unconfirmed: true });

package/lib/start.js

@@ -5,6 +5,7 @@ const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./st
 const out = require('./output');
 const { watchPage, complete } = require('./commands');
 const { listTabs, openTab, markStartTab } = require('./tabs');
+const { tabState } = require('./tabstate');
 const runner = require('./runner');
 
 // A browser --launch starts has its own address instead.
@@ -88,10 +89,14 @@ async function start(options) {
 
   if (START_URL) {
     state.startingStep = 'opening the start URL';
-    state.page = await openTab();
+    // A Chromium the REPL launched has only its first blank tab, which nobody else is using: the start
+    // URL goes there, rather than into a second tab behind a blank one.
+    const first = state.launched && pages.length === 1 && pages[0].url() === 'about:blank' ? pages[0] : null;
+    if (first) Object.assign(tabState(first), { opened: true, owner: state.client });
+    state.page = first || await openTab();
     markStartTab(state.page);
     await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
-    out.log(`Opened ${state.page.url()} in a new tab`);
+    out.log(`Opened ${state.page.url()}${first ? '' : ' in a new tab'}`);
   }
 
   out.log('');

package/lib/state.js

@@ -1,14 +1,12 @@
 // Session state shared by the entry point, the runner, and the commands, plus
 // the shutdown that ends the session.
+const { AsyncLocalStorage } = require('async_hooks');
 const out = require('./output');
 
 const SHUTDOWN_TIMEOUT = 5000;
 
 const state = {
   browser: null,
-  // The client whose command runs now: null for the prompt and senders without
-  // a name, who share one selected tab, as before clients had names.
-  client: null,
   rl: null,
   promptBase: 'pw> ',
   // The browser the REPL is connected to, and whether --launch started it.
@@ -36,18 +34,31 @@ function clientRecord(name = state.client) {
   return clients.get(name);
 }
 
+// The command running in this async context: its client, and whether its sender gave up on it.
+// Code outside any command (a browser event, quit and dialog, which skip the queue) goes by the
+// queued command running now.
+const running = new AsyncLocalStorage();
+let queued = null;
+
+// The client whose command runs now: null for the prompt and senders without a name, who share one
+// selected tab, as before clients had names. Each command keeps its own for its whole life, so one
+// its sender gave up on, still running, never acts as the command after it.
+Object.defineProperty(state, 'client', { enumerable: true, get: () => (running.getStore() ?? queued)?.client ?? null });
+
+out.onCancelled(() => running.getStore()?.cancelled === true);
+
 for (const key of Object.keys(PER_CLIENT)) {
   Object.defineProperty(state, key, { enumerable: true, get: () => clientRecord()[key], set: value => { clientRecord()[key] = value; } });
 }
 
-// Runs fn as the named client. Commands run one at a time, so this is safe.
-async function asClient(name, fn) {
-  const previous = state.client;
-  state.client = name || null;
-  try { return await fn(); } finally { state.client = previous; }
+// Runs fn as the named client. run is the command's record, whose cancelled the runner sets.
+async function asClient(name, fn, run = {}) {
+  queued = Object.assign(run, { client: name || null });
+  try { return await running.run(run, fn); } finally { if (queued === run) queued = null; }
 }
 
 const cleanups = [];
+const endings = [];
 const exitWaits = [];
 let shutdownPromise = null;
 
@@ -65,6 +76,11 @@ function onShutdown(fn) {
   cleanups.push(fn);
 }
 
+// Run once every cleanup has finished, before the browser is closed.
+function onShutdownEnd(fn) {
+  endings.push(fn);
+}
+
 // Things to finish before the process exits, e.g. answers still being sent.
 function onBeforeExit(fn) {
   exitWaits.push(fn);
@@ -80,6 +96,7 @@ async function shutdown() {
   shutdownPromise = (async () => {
     // Some undo what the REPL changed in the browser, so they finish first.
     await withTimeout(Promise.all(cleanups.map(async fn => fn())), 'Cleanup').catch(() => {});
+    for (const fn of endings) try { await fn(); } 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}`); }
@@ -88,4 +105,4 @@ async function shutdown() {
   return shutdownPromise;
 }
 
-module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown, SHUTDOWN_TIMEOUT };
+module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onShutdownEnd, onBeforeExit, beforeExit, shutdown, SHUTDOWN_TIMEOUT };

package/lib/syntax.js

@@ -11,25 +11,31 @@ function toSelector(word) {
   return REF.test(word) ? `aria-ref=${word}` : word;
 }
 
-// Quotes around the whole of a value are removed; \" inside double quotes is a quote.
+// Inside double quotes, \n, \t and \r are a newline, tab and carriage return, so a value send quotes
+// keeps them on one line; any other \X is X (\" a quote, \\ a backslash).
+function unescapeDouble(text) {
+  return text.replace(/\\(.)/g, (_, c) => (c === 'n' ? '\n' : c === 't' ? '\t' : c === 'r' ? '\r' : c));
+}
+
+// Quotes around the whole of a value are removed.
 function unquote(text) {
   const match = /^"((?:[^"\\]|\\.)*)"$|^'([^']*)'$/.exec(text);
   if (!match) return text;
-  return match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2];
+  return match[1] !== undefined ? unescapeDouble(match[1]) : match[2];
 }
 
 // The words of a line as a shell reads them: quoted parts may hold spaces, and lose their quotes
 // (--filename="my dir/a.webm" is one word, --filename=my dir/a.webm).
 function shellWords(text) {
   return [...(text || '').matchAll(/(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']+|["'])+/g)]
-    .map(m => m[0].replace(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g, (_, double, single) => (double !== undefined ? double.replace(/\\(.)/g, '$1') : single)));
+    .map(m => m[0].replace(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g, (_, double, single) => (double !== undefined ? unescapeDouble(double) : single)));
 }
 
 // The first word of args, or a quoted selector with spaces in it, and the rest of the line.
 function splitSelector(args) {
   const match = /^(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+))(?:\s+([\s\S]*))?$/.exec((args || '').trim());
   if (!match) return null;
-  const word = match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2] !== undefined ? match[2] : match[3];
+  const word = match[1] !== undefined ? unescapeDouble(match[1]) : match[2] !== undefined ? match[2] : match[3];
   return { word, selector: toSelector(word), rest: match[4] };
 }
 
@@ -83,4 +89,4 @@ function expandVariables(line, values) {
   });
 }
 
-module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };
+module.exports = { SELECTOR_FIRST, REF, toSelector, unescapeDouble, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };

package/lib/toast.js

@@ -7,6 +7,7 @@ const { unquote } = require('./syntax');
 const { takeOptions } = require('./cli-names');
 const { inOverlay, keepAcrossPages, forget } = require('./overlay');
 const { recordingOf, beforeRecordingEnds } = require('./record');
+const { parseDuration } = require('./util');
 
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -81,12 +82,6 @@ async function toastOff(p, fade = true) {
 beforeRecordingEnds(p => (p && !p.isClosed() ? waitToRead(p) : null));
 
 // 3s, 1.5s, 800ms, or a number of milliseconds.
-function parseDuration(value) {
-  const match = /^(\d+(?:\.\d+)?)(ms|s)?$/.exec(value || '');
-  if (!match) return null;
-  return Math.round(Number(match[1]) * (match[2] === 's' ? 1000 : 1));
-}
-
 onShutdown(async () => {
   if (!state.browser || state.connectionLost) return;
   const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => !p.isClosed());

package/lib/util.js

@@ -20,6 +20,28 @@ function hints(pairs) {
   return `\n${pairs.map(([command, what]) => `  ${command.padEnd(width)}  ${what}`).join('\n')}`;
 }
 
+// A time: milliseconds, as Playwright and JavaScript count it, or seconds with an s (1500, 1.5s, 1500ms).
+const TIME = /^(\d+(?:\.\d+)?)(ms|s)?$/;
+
+function parseDuration(value) {
+  const match = TIME.exec(value || '');
+  if (!match) return null;
+  return Math.round(Number(match[1]) * (match[2] === 's' ? 1000 : 1));
+}
+
+// How a time reads back: 1.5s, or 250ms under a second.
+function durationText(ms) {
+  return ms >= 1000 ? `${Number((ms / 1000).toFixed(3))}s` : `${ms}ms`;
+}
+
+// A time that is a second or more, where a smaller one is most likely seconds written as before.
+function longDuration(value, what) {
+  const ms = parseDuration(value);
+  if (ms === null) throw new Error(`${what} is a time, in milliseconds or with s for seconds: 30000 or 30s (got ${value})`);
+  if (ms < 1000) throw new Error(`${what} is in milliseconds, 1000 or more: ${value} is ${durationText(ms)}; ${value}s for seconds`);
+  return ms;
+}
+
 function clipText(text) {
   return text.length > MAX_EVENT_TEXT ? `${text.slice(0, MAX_EVENT_TEXT)}…` : text;
 }
@@ -56,6 +78,8 @@ function clock(t) {
 // by itself unseen: stop prints those lines.
 const STOPPED_RECORDING = 'The REPL stopped, which ended a recording';
 const ENDED_UNSEEN = 'A recording ended before the REPL stopped, unseen since';
+// Each line stop prints of the files a client left.
+const FILES_LEFT = 'Files left';
 
 // 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.
@@ -69,4 +93,4 @@ function playwrightBrowsersDir() {
   return path.join(cache, 'ms-playwright');
 }
 
-module.exports = { BUSY_PAGE, STOPPED_RECORDING, ENDED_UNSEEN, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock, playwrightBrowsersDir };
+module.exports = { TIME, parseDuration, durationText, longDuration, BUSY_PAGE, STOPPED_RECORDING, ENDED_UNSEEN, FILES_LEFT, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock, playwrightBrowsersDir };

package/lib/watch.js

@@ -4,6 +4,7 @@ const out = require('./output');
 const { printOutput } = out;
 const fs = require('fs');
 const path = require('path');
+const { noteWritten } = require('./written');
 const { clipText, clock, hints, NO_TAB } = require('./util');
 const { tabState } = require('./tabstate');
 const { keptSession, keepDrawing } = require('./cdp');
@@ -22,8 +23,8 @@ const PW_SETTINGS = ['PW_CDP_URL', 'PW_CHROME', 'PW_CLIENT', 'PW_ENDPOINT', 'PW_
   'PW_SOCKET', 'PW_START_URL', 'PW_TEST_CHROME', 'PW_TMUX_SESSION'];
 const PAGE_ACTIONS = new Set(['click', 'check', 'uncheck', 'select', 'fill', 'type', 'press', 'submit']);
 const WATCH_BINDING = '__pwReplWatch';
-// Seconds a saved step waits for its element after the app's own routing (watch save).
-const ROUTE_WAIT = 30;
+// How long a saved step waits for its element after the app's own routing (watch save).
+const ROUTE_WAIT = '30s';
 
 // Runs in the page. Describes elements the way snapshot does: role and name.
 const WATCH_SCRIPT = `(() => {
@@ -811,6 +812,7 @@ const commands = {
       if (variables.length) header.push(`# It needs ${variables.join(', ')} set in the environment: what was typed into ${where}, not saved here`);
       // It holds what was typed, so it is the user's own to read.
       fs.writeFileSync(file, `${[...header, ...lines].join('\n')}\n`, { mode: 0o600, flag: 'wx' });
+      noteWritten(file, 'watch file');
       out.log(`Saved ${watch.events.length} step${watch.events.length === 1 ? '' : 's'} to ${file}${skipped ? `; ${skipped} could not be written as commands, and are comments there saying why` : ''}.`);
       if (variables.length) out.log(`What was typed into ${where} is a variable there, filled in from the environment: ${variables.map(name => `{{ ${name} }}`).join(', ')}.`);
       out.log(`${variables.map(name => `${name}=... `).join('')}pw-repl send --file ${file} runs them.`);

package/lib/written.js

@@ -0,0 +1,67 @@
+// The files the REPL wrote this session, and for whom, so close and stop can say which are still
+// there to clean up. Kept in memory only, and nothing is removed.
+const fs = require('fs');
+const path = require('path');
+const { state, onShutdownEnd } = require('./state');
+const out = require('./output');
+const { FILES_LEFT } = require('./util');
+
+const written = new Map();
+
+// kind: what it is, as the summary counts it (screenshot, video, steps file, profile, watch file).
+function noteWritten(file, kind, client = state.client) {
+  written.set(path.resolve(file), { kind, client: client ?? null });
+}
+
+// A file renamed (record off <file>) is still the same one.
+function noteMoved(from, to) {
+  const entry = written.get(path.resolve(from));
+  if (!entry) return;
+  written.delete(path.resolve(from));
+  written.set(path.resolve(to), entry);
+}
+
+function remaining(client) {
+  const files = [];
+  for (const [file, entry] of written) {
+    if (entry.client !== (client ?? null)) continue;
+    try { files.push({ file, kind: entry.kind, size: fs.statSync(file).size }); } catch {}
+  }
+  return files;
+}
+
+function sizeText(bytes) {
+  if (bytes < 1024 * 1024) return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+  return `${Number((bytes / 1024 / 1024).toFixed(1))} MB`;
+}
+
+// For close: the client's own files, in full.
+function ownFilesText(client) {
+  const files = remaining(client);
+  if (!files.length) return null;
+  return [`Files you wrote that are still there; remove what is no longer needed:`, ...files.map(f => `  ${f.file} (${sizeText(f.size)})`)].join('\n');
+}
+
+const plural = (n, kind) => `${n} ${kind}${n === 1 ? '' : 's'}`;
+
+// For stop: one line for each client that left files, each with what and where.
+function summaryLines() {
+  const clients = [...new Set([...written.values()].map(e => e.client))];
+  const lines = [];
+  for (const client of clients) {
+    const files = remaining(client);
+    if (!files.length) continue;
+    const kinds = new Map();
+    for (const f of files) kinds.set(f.kind, (kinds.get(f.kind) || 0) + 1);
+    const folders = [...new Set(files.map(f => `${path.dirname(f.file)}/`))];
+    const bytes = files.reduce((sum, f) => sum + f.size, 0);
+    const who = client ? `by ${client}` : 'without a client name';
+    lines.push(`${FILES_LEFT} ${who}: ${plural(files.length, 'file')}, ${sizeText(bytes)} (${[...kinds].map(([k, n]) => plural(n, k)).join(', ')}) in ${folders.join(' and ')}`);
+  }
+  return lines;
+}
+
+// After every recording has been saved, so its file is whole.
+onShutdownEnd(() => { for (const line of summaryLines()) out.log(line); });
+
+module.exports = { noteWritten, noteMoved, ownFilesText, summaryLines };

package/package.json

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