pw-repl 0.12.7 → 0.13.0

package/lib/inspect.js

@@ -6,15 +6,16 @@ const out = require('./output');
 const { printOutput } = out;
 const { devices } = require('playwright-core');
 const { toSelector, REF, unquote } = require('./syntax');
-const { regexOf, COMMAND_TIMEOUT, BUSY_PAGE } = require('./util');
+const { regexOf, COMMAND_TIMEOUT, BUSY_PAGE, TIME, parseDuration, durationText } = require('./util');
 const { tabState } = require('./tabstate');
-const { keptSession } = require('./cdp');
+const { noteWritten } = require('./written');
+const { keptSession, keepDrawing } = require('./cdp');
 const { CDP_REFUSED } = require('./dialogs');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
 const { deviceMetrics, viewportMetrics, reapplyMetrics } = require('./emulation');
 
-const SCREENSHOT_DELAY_MAX = 60;
+const SCREENSHOT_DELAY_MAX = 60000;
 // What inputs lists: native form controls, and elements that are one by their ARIA role.
 const INPUTS = ['input', 'select', 'textarea', ...['checkbox', 'radio', 'switch', 'combobox', 'listbox', 'textbox', 'searchbox', 'slider', 'spinbutton'].map(role => `[role=${role}]`)].join(', ');
 
@@ -111,15 +112,14 @@ function compactSnapshot(text) {
   return lines.join('\n');
 }
 
-const WAIT_DEFAULT = 10;
-const WAIT_MAX = 120;
+const WAIT_DEFAULT = 10000;
 
 // Gone once no match is visible, whether it was removed or hidden.
 async function waitGone(locator, what, timeout) {
   try {
     await locator.filter({ visible: true }).first().waitFor({ state: 'detached', timeout });
   } catch (error) {
-    if (/Timeout \d+ms exceeded/.test(error.message)) throw new Error(`Still visible after ${timeout / 1000}s: ${what}`);
+    if (/Timeout \d+ms exceeded/.test(error.message)) throw new Error(`Still visible after ${durationText(timeout)}: ${what}`);
     throw error;
   }
   out.log(`Gone: ${what}`);
@@ -127,9 +127,9 @@ async function waitGone(locator, what, timeout) {
 
 const SNAPSHOT_HINT_LINES = 60;
 
-function evaluated(promise) {
-  return withTimeout(promise, 'Page evaluation', COMMAND_TIMEOUT).catch(error => {
-    if (error.message === 'Page evaluation timed out') error.message += ` after ${COMMAND_TIMEOUT / 1000}s; ${BUSY_PAGE}`;
+function evaluated(promise, timeout = COMMAND_TIMEOUT) {
+  return withTimeout(promise, 'Page evaluation', timeout).catch(error => {
+    if (error.message === 'Page evaluation timed out') error.message += ` after ${durationText(timeout)}: eval --timeout=<time> waits longer (and send -t with it), but ${BUSY_PAGE}`;
     throw error;
   });
 }
@@ -316,7 +316,7 @@ const commands = {
   },
 
   async screenshot(args) {
-    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <seconds>] [name | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens.';
+    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <time>] [name | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens.';
     // The file first: a path may be quoted, with spaces in it.
     let file = null;
     const rest = (args || '').replace(/(?:^|\s)--filename(?:=|\s+)("(?:[^"\\]|\\.)*"|'[^']*'|\S+)/, (_, value) => { file = unquote(value); return ' '; });
@@ -334,9 +334,9 @@ const commands = {
       if (token === '--delay' || token === '-d') {
         const value = tokens[++i];
         // Capped low on purpose: a timed shot is human-in-the-loop, and a typo
-        // like `-d 300` would otherwise park the serialized command queue.
-        if (!value || !/^\d+$/.test(value) || Number(value) > SCREENSHOT_DELAY_MAX) throw new Error(`Usage: screenshot --delay <seconds> (maximum ${SCREENSHOT_DELAY_MAX})`);
-        delay = Number(value);
+        // like `-d 300s` would otherwise park the serialized command queue.
+        delay = parseDuration(value);
+        if (delay === null || delay > SCREENSHOT_DELAY_MAX) throw new Error(`Usage: screenshot --delay <time> (ms, or 5s; at most ${durationText(SCREENSHOT_DELAY_MAX)})`);
         continue;
       }
       names.push(token);
@@ -345,9 +345,11 @@ const commands = {
     const name = names[0] || null;
     // Counted down out loud so a watcher can time a hover or menu state, and so
     // the wait is distinguishable from a hung command in a tmux capture.
-    for (let remaining = delay; remaining > 0; remaining--) {
-      out.log(`${remaining}...`);
-      await state.page.waitForTimeout(1000);
+    for (let left = delay; left > 0;) {
+      out.log(`${Math.ceil(left / 1000)}...`);
+      const step = left % 1000 || 1000;
+      await state.page.waitForTimeout(step);
+      left -= step;
     }
     // Named after the countdown so a default filename timestamps the capture.
     // A file given is relative to the REPL's folder; pw-repl send makes it the sender's.
@@ -388,6 +390,7 @@ const commands = {
       if (error.code === 'EEXIST') throw new Error(`Screenshot already exists: ${filepath}`);
       throw error;
     }
+    noteWritten(filepath, 'screenshot');
     out.log(`Saved: ${filepath}`);
   },
 
@@ -433,22 +436,22 @@ const commands = {
   },
 
   async wait(args) {
-    const usage = 'Usage: wait <selector> | wait text <text> | wait request <url-part|glob> | wait load, with optional [seconds]; --gone for a selector or text';
+    const usage = 'Usage: wait <selector> | wait text <text> | wait request <url-part|glob> | wait load, with an optional [time] (ms, or 30s); --gone for a selector or text';
     let tokens = (args || '').trim().split(/\s+/).filter(Boolean);
     const gone = tokens.includes('--gone');
     tokens = tokens.filter(t => t !== '--gone');
-    let seconds = WAIT_DEFAULT;
-    // A number last is the seconds, unless it is all there is to wait for: wait text 990.
+    // A time last is how long, unless it is all there is to wait for: wait text 990.
     const onlyWhat = (tokens[0] === 'text' || tokens[0] === 'request') && tokens.length === 2;
-    const tookSeconds = tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1]);
-    if (tookSeconds) seconds = Number(tokens.pop());
-    if (!tokens.length) throw new Error(`${usage} (1-${WAIT_MAX})`);
-    if (seconds < 1 || seconds > WAIT_MAX) {
-      // Most likely text that ends in a number, not seconds at all.
-      const text = tokens[0] === 'text' && !/^["']/.test(tokens[1]) ? `; for text that ends in a number, quote it: wait text "${tokens.slice(1).join(' ')} ${seconds}"` : '';
-      throw new Error(`wait takes 1-${WAIT_MAX} seconds (got ${seconds})${text}`);
+    const tookTime = tokens.length > 1 && !onlyWhat && TIME.test(tokens[tokens.length - 1]);
+    const given = tookTime ? tokens.pop() : null;
+    const timeout = given ? parseDuration(given) : WAIT_DEFAULT;
+    if (!tokens.length) throw new Error(usage);
+    if (!timeout) {
+      // Most likely text that ends in a number, not a time at all.
+      const text = tokens[0] === 'text' && !/^["']/.test(tokens[1]) ? `; for text that ends in a number, quote it: wait text "${tokens.slice(1).join(' ')} ${given}"` : '';
+      throw new Error(`wait takes a time over 0 (got ${given})${text}`);
     }
-    const timeout = seconds * 1000;
+    const within = durationText(timeout);
     // Said plainly, not as Playwright's call log.
     const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };
     const kind = tokens[0];
@@ -464,37 +467,64 @@ const commands = {
       }
       if (gone) return waitGone(state.page.getByText(what), what, timeout);
       // Text that ends in a number gives it up as the seconds, unless quoted: said when it times out.
-      const quote = tookSeconds && !/^["']/.test(tokens[1]) ? ` (${seconds} was taken as the seconds: wait text "${what} ${seconds}" waits for that text)` : '';
-      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${seconds}s${quote}`));
+      const quote = tookTime && !/^["']/.test(tokens[1]) ? ` (${given} was taken as the time: wait text "${what} ${given}" waits for that text)` : '';
+      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${within}${quote}`));
       out.log(`Visible: ${what}`);
       return;
     }
     const selector = toSelector(unquote(tokens.join(' ')));
     if (gone) return waitGone(state.page.locator(selector), tokens.join(' '), timeout);
-    await state.page.waitForSelector(selector, { state: 'visible', timeout }).catch(plainly(`No visible element matches ${tokens.join(' ')} within ${seconds}s`));
+    await state.page.waitForSelector(selector, { state: 'visible', timeout }).catch(plainly(`No visible element matches ${tokens.join(' ')} within ${within}`));
     out.log(`Visible: ${tokens.join(' ')}`);
   },
 
   async sleep(args) {
-    if (!args || !/^\d+$/.test(args) || Number(args) > 3600000) throw new Error('Usage: sleep <ms> (maximum 3600000)');
-    await state.page.waitForTimeout(Number(args));
+    const ms = parseDuration(args);
+    if (ms === null) throw new Error('Usage: sleep <time> (ms, or 3s)');
+    await state.page.waitForTimeout(ms);
     // sleep 3 is easily meant as seconds.
-    out.log(Number(args) < 100 ? `Slept ${args}ms (sleep takes milliseconds: sleep ${args}000 is ${args}s)` : `Slept ${args}ms`);
+    out.log(/^\d+$/.test(args) && ms < 100 ? `Slept ${args}ms (sleep takes milliseconds: sleep ${args}s for ${args}s)` : `Slept ${durationText(ms)}`);
   },
 
   async eval(args, all) {
     if (!args) throw new Error('Usage: eval <js-expression>');
-    // eval <function> <ref> calls the function with that element, as playwright-cli's eval does.
-    const onRef = /^([\s\S]+?)\s+((?:f\d+)?e\d+)$/.exec(args.trim());
-    if (onRef && isFunctionText(unquote(onRef[1]))) {
-      const selector = toSelector(onRef[2]);
+    // eval --timeout=<time> [--file=...] <JavaScript>: how long the page has to answer.
+    let timeout = COMMAND_TIMEOUT;
+    const timed = /^--timeout(?:=|\s+)(\S+)(?:\s+([\s\S]*))?$/.exec(args.trim());
+    if (/^--timeout(?:[=\s]|$)/.test(args.trim())) {
+      timeout = parseDuration(timed?.[1]);
+      if (!timeout) throw new Error('Usage: eval --timeout=<time> <JavaScript>, a time in ms or with s: eval --timeout=60s ...');
+      args = timed[2] || '';
+      if (!args.trim()) throw new Error('Usage: eval --timeout=<time> <JavaScript>');
+    }
+    let ref = null;
+    // eval --file=<path> [<ref or selector>]: the file's text is what the line would be, over as many lines as
+    // it likes. The rest of the line can only be the element, so any selector goes there, not only a ref.
+    const fromFile = /^--file(?:=|\s+)("(?:[^"\\]|\\.)*"|'[^']*'|\S+)(?:\s+([\s\S]*))?$/.exec(args.trim());
+    if (/^--file(?:[=\s]|$)/.test(args.trim())) {
+      if (!fromFile) throw new Error('Usage: eval --file=<path> [<ref or selector>]: the JavaScript is in the file');
+      const file = path.resolve(unquote(fromFile[1]));
+      const target = fromFile[2]?.trim() || null;
+      try { args = fs.readFileSync(file, 'utf8').trim(); } catch (error) {
+        // eval --file=my dir/x.js reads "my" as the file and "dir/x.js" as the element.
+        throw new Error(`eval --file: cannot read ${file} (${error.code || error.message})${target ? '; quote a path with spaces' : ''}`);
+      }
+      if (!args) throw new Error(`eval --file: ${file} is empty`);
+      ref = target && unquote(target);
+    } else {
+      // eval <function> <ref> calls the function with that element, as playwright-cli's eval does.
+      const onRef = /^([\s\S]+?)\s+((?:f\d+)?e\d+)$/.exec(args.trim());
+      if (onRef && isFunctionText(unquote(onRef[1]))) [args, ref] = [unquote(onRef[1]), onRef[2]];
+    }
+    if (ref) {
+      const selector = toSelector(ref);
       const el = await onElement(selector, () => state.page.locator(selector).first().elementHandle({ timeout: 5000 }));
       try {
         // Made from its text by the debugger, as eval is, so a page's CSP cannot
         // refuse it, and in the element's own frame, which may be an iframe.
-        const fn = await evaluated((await el.ownerFrame()).evaluateHandle(unquote(onRef[1])));
+        const fn = await evaluated((await el.ownerFrame()).evaluateHandle(args), timeout);
         try {
-          printOutput(await el.evaluate((e, f) => f(e), fn), all);
+          printOutput(await evaluated(el.evaluate((e, f) => f(e), fn), timeout), all);
         } finally {
           await fn.dispose().catch(() => {});
         }
@@ -514,13 +544,13 @@ const commands = {
     const call = `const value = (${args}\n); return typeof value === 'function' ? value() : value;`;
     if (awaits && !single && compiles(AsyncFunction, args)) {
       const session = await keptSession(state.page);
-      const { result, exceptionDetails } = await evaluated(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }));
+      const { result, exceptionDetails } = await evaluated(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }), timeout);
       if (exceptionDetails) throw new Error(exceptionDetails.exception?.description || exceptionDetails.text);
       printOutput(result.value !== undefined ? result.value : result.description ?? 'undefined', all);
       return;
     }
     const expression = single ? `(${awaits ? 'async ' : ''}() => { ${call} })()` : args;
-    const value = await evaluated(state.page.evaluate(expression));
+    const value = await evaluated(state.page.evaluate(expression), timeout);
     // An empty string is shown as one, not as no output at all.
     printOutput(value === '' ? '""' : value, all);
     // Quotes around the whole of it, as a shell's quoting sent on, make it a string, not code to run:
@@ -530,6 +560,38 @@ const commands = {
     }
   },
 
+  // Read through the selected tab, granted clipboard-read for that moment only. A browser with a
+  // window reads the system's clipboard, the user's, so only with --shared-clipboard.
+  async clipboard(args, all) {
+    const words = (args || '').trim().split(/\s+/).filter(Boolean);
+    if (words.some(w => w !== '--shared-clipboard')) throw new Error('Usage: clipboard [--shared-clipboard]');
+    const browser = await state.browser.newBrowserCDPSession();
+    try {
+      // Headless says so in its user agent (its product name says Chrome either way).
+      const { userAgent } = await browser.send('Browser.getVersion');
+      if (!/\bHeadlessChrome\//.test(userAgent) && !words.length) {
+        throw new Error('This browser has a window, so its clipboard is the computer\'s: whatever its user last copied, a password too. clipboard --shared-clipboard reads it anyway; ask them first. A headless browser (--launch, without --headed) has a clipboard of its own.');
+      }
+      const p = state.page;
+      const origin = await evaluated(p.evaluate(() => (isSecureContext && location.origin !== 'null' ? location.origin : null)));
+      if (!origin) throw new Error(`The selected tab (${p.url()}) is not a secure page, and only one can read the clipboard: https, or http on localhost`);
+      const permission = { name: 'clipboard-read' };
+      const before = await p.evaluate(() => navigator.permissions.query({ name: 'clipboard-read' }).then(s => s.state));
+      // readText also needs the page focused: a tab the REPL uses is told it is (help tab).
+      await keepDrawing(p);
+      await browser.send('Browser.setPermission', { permission, setting: 'granted', origin });
+      try {
+        const granted = await p.evaluate(() => navigator.permissions.query({ name: 'clipboard-read' }).then(s => s.state));
+        if (granted !== 'granted') throw new Error('The browser did not let the selected tab read the clipboard: a tab in a private window, or in a browser context of its own, does not take the grant');
+        printOutput(await evaluated(p.evaluate(() => navigator.clipboard.readText())), all);
+      } finally {
+        await browser.send('Browser.setPermission', { permission, setting: before, origin }).catch(() => {});
+      }
+    } finally {
+      await browser.detach().catch(() => {});
+    }
+  },
+
   async cdp(args, all) {
     const match = /^(\S+)\s+([\s\S]+)$/.exec(args || '');
     if (!match) throw new Error('Usage: cdp <method> <JSON object>');

package/lib/launch.js

@@ -139,7 +139,9 @@ async function launch({ headed = false, extraArgs = [] }) {
   const onExit = () => { if (group) killGroup(group); try { removeProfile(); } catch {} };
   process.on('exit', onExit);
   const onSpawn = proc => { group = proc.pid; };
-  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', ...(given ? [] : [`--user-data-dir=${profile}`]),
+  // A laptop's window, rather than Chromium's headless 800x600 or so, unless the flags after -- size it.
+  const sized = extraArgs.some(a => a.startsWith('--window-size=')) ? [] : ['--window-size=1280,800'];
+  const ours = [...(headed ? [] : ['--headless=new']), ...sized, '--remote-debugging-port=0', ...(given ? [] : [`--user-data-dir=${profile}`]),
     '--no-first-run', '--no-default-browser-check', ...(smallShm() ? ['--disable-dev-shm-usage'] : [])];
   // A profile already used has tabs to restore; a blank tab of its own each time would pile up there.
   // Local State is written at its root on the first run, whichever --profile-directory is used.

package/lib/output.js

@@ -4,14 +4,21 @@ const OUTPUT_LIMIT = 12000;
 
 let sink = null;
 
+// A cancelled command still running prints to the pane only, never into the next command's answer.
+let cancelled = () => false;
+
+function onCancelled(fn) {
+  cancelled = fn;
+}
+
 function log(text) {
   console.log(text);
-  if (sink) sink.push(String(text));
+  if (sink && !cancelled()) sink.push(String(text));
 }
 
 function error(text) {
   console.error(text);
-  if (sink) sink.push(String(text));
+  if (sink && !cancelled()) sink.push(String(text));
 }
 
 // Commands run one at a time, so a single sink is enough. Lines printed by
@@ -86,4 +93,4 @@ function printOutput(value, all = false, footer = '') {
   log(footer ? `${text}\n${footer}` : text);
 }
 
-module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, onSelectedTab, printOutput };
+module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, onSelectedTab, onCancelled, printOutput };

package/lib/profile.js

@@ -3,13 +3,15 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { state, onShutdown } = require('./state');
+const { noteWritten } = require('./written');
 const out = require('./output');
-const { NO_TAB, clock, hints } = require('./util');
+const { NO_TAB, clock, hints, TIME, longDuration, durationText } = require('./util');
 const { tabState } = require('./tabstate');
 const { targetIdOf } = require('./tabs');
 const { summarize, LONG_TASK } = require('./trace');
 
-const MAX_SECONDS = 120;
+// Without a time, a profile left on stops by itself after this long.
+const UNTIMED_MAX = 120000;
 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',
@@ -52,12 +54,11 @@ function forget(profile) {
 
 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 usage = 'Usage: profile on [time] [--cpu] (ms, or 30s)';
   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 (rest.length > 1 || (rest.length && !TIME.test(rest[0]))) throw new Error(usage);
+  const ms = rest.length ? longDuration(rest[0], 'profile on\'s time') : null;
   if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
   await finishing;
   const page = state.page;
@@ -98,17 +99,17 @@ async function startProfile(tokens, quiet = false) {
   };
   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 (!ms) {
+    profile.cap = setTimeout(() => {
+      if (prof === profile) stop(`it reached ${durationText(UNTIMED_MAX)}, the most a profile records without a time (profile on <time> for longer).`, `The profile stopped at ${durationText(UNTIMED_MAX)}, the most it records without a time`);
+    }, UNTIMED_MAX);
     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...`);
+  out.log(`Profiling the selected tab for ${durationText(ms)}...`);
   await new Promise(resolve => {
-    const timer = setTimeout(resolve, seconds * 1000);
+    const timer = setTimeout(resolve, ms);
     profile.wake = () => { clearTimeout(timer); resolve(); };
   });
   // profile off may have ended it first, and printed it; anything else that ended it (its tab closed,
@@ -257,7 +258,7 @@ const commands = {
     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 (sub) throw new Error(`Usage: profile on [time] [--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']]));
@@ -270,7 +271,7 @@ const commands = {
       out.log('Not profiling.');
     }
     out.log(hints([
-      ['profile on [seconds]', 'record what the selected tab\'s main thread does'],
+      ['profile on [time]', 'record what the selected tab\'s main thread does'],
       ['profile reload', 'profile the selected tab\'s page as it loads'],
     ]));
   },
@@ -301,6 +302,7 @@ function saveProfile(file) {
   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);
+  noteWritten(file, 'profile');
   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.`);
 }

package/lib/record.js

@@ -5,12 +5,14 @@ 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, playwrightBrowsersDir } = require('./util');
+const { clock, NO_TAB, STOPPED_RECORDING, ENDED_UNSEEN, playwrightBrowsersDir, TIME, longDuration, durationText } = require('./util');
 const { shellWords, splitSelector } = require('./syntax');
 const { reapplyMetrics } = require('./emulation');
+const { noteWritten, noteMoved } = require('./written');
 
 const FPS = 25;
-const MAX_SECONDS = 3600;
+// Without a time, a recording left on stops by itself after this long.
+const UNTIMED_MAX = 3600000;
 // While recording: a moment after each action for its result to be seen, and still page at both ends,
 // so a video neither starts nor stops on an action (record on --pause, --lead, --tail).
 const PACING = { pause: 750, lead: 1000, tail: 1000 };
@@ -121,7 +123,7 @@ function sizeText(bytes) {
 }
 
 // Each client's last recording that ended, and how, for record to report: one that ends on
-// its own (its seconds, its tab closing) says so only in the pane.
+// its own (its time, its tab closing) says so only in the pane.
 const lastEnded = new Map();
 // Each client's recordings still being saved, which record waits for before it reports.
 const saving = new Map();
@@ -141,7 +143,7 @@ function recordingPages() {
   return state.browser.contexts().flatMap(c => c.pages()).filter(p => recordingOf(p));
 }
 
-async function startRecording(p, file, seconds, format, keepSteps, pacing) {
+async function startRecording(p, file, ms, format, keepSteps, pacing) {
   const exe = findFfmpeg(format);
   // As screenshot does: a tab that has not been in front since it was emulated as a phone can
   // be drawn at the window's size.
@@ -252,8 +254,8 @@ async function startRecording(p, file, seconds, format, keepSteps, pacing) {
   // drawn yet (a tab still opening) starts it when it does.
   await Promise.race([gotFirstFrame, new Promise(resolve => setTimeout(resolve, FIRST_FRAME_TIMEOUT))]);
   rec.limit = setTimeout(() => {
-    finishRecording(rec, `It reached its ${seconds}s and stopped`).then(text => out.notice(text, p));
-  }, seconds * 1000);
+    finishRecording(rec, `It reached its ${durationText(ms)} and stopped`).then(text => out.notice(text, p));
+  }, ms);
   rec.onClose = () => finishRecording(rec, TAB_CLOSED).then(text => out.notice(text, p));
   p.once('close', rec.onClose);
   // A new page, loaded or routed to by a single-page app, is a step of its own, for whoever edits the
@@ -391,7 +393,7 @@ function videoTime(rec) {
 // What a step is, for its line: the command and what it acts on, never what it types or chooses, the
 // code it runs or the URL it goes to, which can hold a password or a token. A steps file goes where the
 // video goes, and the video shows a password as dots.
-const WHOLE = new Set(['click', 'dblclick', 'hover', 'check', 'uncheck', 'mousemove', 'mouseclick', 'mousedown', 'mouseup', 'mousewheel']);
+const WHOLE = new Set(['click', 'dblclick', 'hover', 'drag', 'check', 'uncheck', 'mousemove', 'mouseclick', 'mousedblclick', 'mousedown', 'mouseup', 'mousewheel']);
 const TARGET_FIRST = new Set(['fill', 'type', 'select', 'press', 'upload']);
 function stepLabel(cmd, args) {
   if (WHOLE.has(cmd)) {
@@ -501,6 +503,7 @@ function writeSteps(rec, seconds) {
   } catch (error) {
     return { file, error: error.code === 'EEXIST' ? `${file} already exists` : error.message };
   }
+  noteWritten(file, 'steps file', rec.owner);
   rec.stepsFile = file;
   return { file, count: rec.steps.length };
 }
@@ -565,7 +568,7 @@ function fileWords(words, usage) {
     // playwright-cli's video-start --size: here the video is the page's size.
     else if (/^--size(?:=|$)/.test(word)) throw new Error(`record takes no --size: the video is the page's size; set it first with viewport <width>x<height>`);
     else if (word.startsWith('-')) throw new Error(`record takes no ${word}. ${usage}`);
-    else if (/^\d+$/.test(word)) rest.push(word);
+    else if (TIME.test(word)) rest.push(word);
     else files.push(word);
   }
   if (files.length > 1) throw new Error(`record takes one file, and ${files.map(f => `"${f}"`).join(' and ')} are two: quote a file name with spaces in it. ${usage}`);
@@ -592,13 +595,14 @@ function moveRecording(from, to) {
     fs.chmodSync(to, 0o600);
     fs.unlinkSync(from);
   }
+  noteMoved(from, to);
 }
 
 const commands = {
   async record(args) {
     // A file may be quoted, with spaces in it.
     const words = shellWords(args);
-    const usage = `Usage: record [on [file.webm|file.mp4] [seconds] [--steps] [--pause=<ms>] [--lead=<ms>] [--tail=<ms>] | off [file]] (seconds from 1 to ${MAX_SECONDS})`;
+    const usage = `Usage: record [on [file.webm|file.mp4] [time] [--steps] [--pause=<ms>] [--lead=<ms>] [--tail=<ms>] | off [file]] (a time in ms, or 30s)`;
     if (!words.length) {
       await Promise.allSettled([...(saving.get(state.client ?? null) || [])]);
       out.log(statusText(state.page));
@@ -636,7 +640,7 @@ const commands = {
       const other = (rec.owner ?? null) !== (state.client ?? null);
       const clientName = c => c ?? 'the unnamed client';
       // What must be seen before the end (a toast's read time), then the tail: still page after the last
-      // action. Only record off has them; the seconds limit is a hard stop.
+      // action. Only record off has them; the time limit is a hard stop.
       if (!rec.finishing) for (const wait of beforeEnding) await wait(state.page);
       if (!rec.finishing) await sleep(rec.pacing.tail);
       const text = await finishRecording(rec, other ? `${clientName(state.client)}'s record off ended ${clientName(rec.owner)}'s recording` : null);
@@ -662,8 +666,7 @@ const commands = {
       return;
     }
     if (numbers.length > 1) throw new Error(usage);
-    const seconds = numbers.length ? Number(numbers[0]) : MAX_SECONDS;
-    if (seconds < 1 || seconds > MAX_SECONDS) throw new Error(usage);
+    const ms = numbers.length ? longDuration(numbers[0], 'record on\'s time') : UNTIMED_MAX;
     const file = named || nextRecordingPath();
     const current = recordingOf(state.page);
     if (current) throw new Error(`The selected tab is already being recorded to ${current.file}; record off stops it`);
@@ -673,13 +676,14 @@ const commands = {
     // ffmpeg writes over it and keeps the mode. It never replaces a file.
     try {
       fs.closeSync(fs.openSync(file, 'wx', 0o600));
+      noteWritten(file, 'video');
     } catch (error) {
       if (error.code === 'EEXIST') throw new Error(`Recording already exists: ${file}`);
       throw error;
     }
     let rec;
     try {
-      rec = await startRecording(state.page, file, seconds, format, steps, { ...PACING, ...pacing });
+      rec = await startRecording(state.page, file, ms, format, steps, { ...PACING, ...pacing });
     } catch (error) {
       fs.rmSync(file, { force: true });
       throw error;
@@ -697,7 +701,7 @@ const commands = {
     const until = Date.now() + 2000;
     while (rec.firstFrameAt === null && !rec.finishing && Date.now() < until) await sleep(20);
     if (rec.firstFrameAt !== null && !rec.finishing) await sleep(Math.max(0, rec.pacing.lead - (Date.now() - rec.firstFrameAt)));
-    const limit = numbers.length ? `for ${seconds}s` : `until record off (at most ${MAX_SECONDS / 60} minutes)`;
+    const limit = numbers.length ? `for ${durationText(ms)}` : `until record off (at most ${UNTIMED_MAX / 60000} minutes)`;
     out.log(`Recording the selected tab to ${file} ${limit}${steps ? ', with its steps' : ''}${pacingText(rec.pacing)}; record off stops it and saves the file.`);
   },
 };

package/lib/routes.js

@@ -2,7 +2,7 @@
 const { state } = require('./state');
 const out = require('./output');
 const { unquote, splitSelector } = require('./syntax');
-const { hints } = require('./util');
+const { hints, parseDuration, durationText } = require('./util');
 const { tabState } = require('./tabstate');
 const { markChanged, requestEntries } = require('./requestlog');
 
@@ -14,7 +14,6 @@ function routesFor(p) {
   return tabState(p).routes;
 }
 
-const ROUTE_DELAY_MAX = 120;
 
 // A JSON Merge Patch (RFC 7386): objects merge, null removes a key, anything else replaces.
 function mergePatch(target, patch) {
@@ -77,14 +76,14 @@ function routeKind(how, rest, usage) {
     };
   }
   if (how === 'delay') {
-    const seconds = Number(rest);
-    if (!/^\d+(?:\.\d+)?$/.test(rest || '') || seconds <= 0 || seconds > ROUTE_DELAY_MAX) throw new Error(`Usage: route <url-glob> delay <seconds> (up to ${ROUTE_DELAY_MAX})`);
+    const ms = parseDuration(rest);
+    if (!ms) throw new Error('Usage: route <url-glob> delay <time> (ms, or 3s)');
     return {
-      text: `delay ${seconds}s`,
+      text: `delay ${durationText(ms)}`,
       async handle(r, req, tag, notice) {
-        await new Promise(resolve => setTimeout(resolve, seconds * 1000));
+        await new Promise(resolve => setTimeout(resolve, ms));
         await r.continue();
-        notice(`Delayed ${seconds}s: ${tag()}`);
+        notice(`Delayed ${durationText(ms)}: ${tag()}`);
       },
     };
   }
@@ -106,7 +105,7 @@ function listRoutes() {
     ['route <url-glob> <status> [json-body]', 'answer it with this status and JSON'],
     ['route <url-glob> <status> --content-type=<type> <body>', 'or with a body of another type'],
     ['route <url-glob> patch <json>', 'let it through, then change its JSON'],
-    ['route <url-glob> delay <seconds>', 'hold it, then let it through'],
+    ['route <url-glob> delay <time>', 'hold it, then let it through'],
     ['route <url-glob> abort', 'fail it as if the connection broke'],
   ];
   if (!routes.size) {
@@ -147,7 +146,7 @@ const commands = {
     // A glob may be quoted, as it is in a shell.
     const off = /^off(?:\s+(\S+))?$/.exec(trimmed);
     if (off) return removeRoutes(off[1] && unquote(off[1]));
-    const usage = 'Usage: route <url-glob> <status> [json-body] | route <url-glob> patch <json> | route <url-glob> delay <seconds> | route <url-glob> abort | route off <url-glob>|--all';
+    const usage = 'Usage: route <url-glob> <status> [json-body] | route <url-glob> patch <json> | route <url-glob> delay <time> | route <url-glob> abort | route off <url-glob>|--all';
     const parsed = splitSelector(trimmed);
     const match = /^(\S+)(?:\s+([\s\S]+))?$/.exec(parsed?.rest || '');
     if (!match) throw new Error(usage);