pw-repl 0.10.0 → 0.11.0

package/lib/watch.js

@@ -2,19 +2,24 @@
 const { state, clientRecord } = require('./state');
 const out = require('./output');
 const { printOutput } = out;
+const fs = require('fs');
+const path = require('path');
 const { clipText, clock, hints, NO_TAB } = require('./util');
 const { tabState } = require('./tabstate');
 const { keptSession, keepDrawing } = require('./cdp');
 const { RECENT_HIDDEN_TYPES, keepBodiesDurable, keep, WATCH_HIDDEN_TYPES, RECENT_DEFAULT } = require('./requestlog');
 const { compactSnapshot } = require('./inspect');
 
-// Opt-in record of what the person at the browser does, so an agent can see
+// Opt-in record of what the user at the browser does, so an agent can see
 // the steps and the requests each one caused. Values typed into fields are
 // never recorded, and password fields not at all.
 const WATCH_MAX = 200;
 const WATCH_REQUESTS_SHOWN = 5;
 
 const TYPING_BACKDATE_MAX = 60000;
+const WATCH_FLAGS = new Set(['--changes', '--live', '--no-values']);
+const PW_SETTINGS = ['PW_CDP_URL', 'PW_CHROME', 'PW_CLIENT', 'PW_ENDPOINT', 'PW_FFMPEG', 'PW_REPL_PID_FILE', 'PW_SCREENSHOT_DIR',
+  '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';
 
@@ -37,7 +42,7 @@ const WATCH_SCRIPT = `(() => {
     if (/^h[1-6]$/.test(tag)) return 'heading';
     return tag;
   };
-  // Text inside these may be what the person typed, so it is never used as a name.
+  // Text inside these may be what the user typed, so it is never used as a name.
   const typedInto = el => el.matches('input,select,textarea,form') || el.isContentEditable || !!el.closest('[contenteditable]:not([contenteditable=false])');
   const isPassword = el => el.matches('input[type=password]') || (el.control && el.control.matches('input[type=password]'));
   // An element holding an editable area would be named partly by what was typed there.
@@ -57,15 +62,104 @@ const WATCH_SCRIPT = `(() => {
       || el.getAttribute('placeholder') || el.getAttribute('title') || (typedInto(el) || hasEditable(el) ? '' : el.innerText));
   };
   const describe = el => { const name = nameOf(el); return roleOf(el) + (name ? ' ' + JSON.stringify(name) : ''); };
+  // A field that was a password field while watched stays one when a "show password" button makes it
+  // text; and some take secrets under another type. Their values never leave the page.
+  const secrets = new WeakSet();
+  const SECRET_AUTOCOMPLETE = /\\b(?:current-password|new-password|one-time-code|cc-number|cc-csc)\\b/;
+  const notePasswords = () => { for (const el of document.querySelectorAll('input[type=password]')) secrets.add(el); };
+  notePasswords();
+  document.addEventListener('focusin', notePasswords, true);
+  const isSecret = el => !!el && (secrets.has(el) || (el.matches && el.matches('input[type=password]')) || SECRET_AUTOCOMPLETE.test((el.getAttribute && el.getAttribute('autocomplete')) || ''));
+  const valueOf = el => (el.isContentEditable ? el.innerText : el.value);
+  // A selector that finds this element and no other, as Playwright reads it, for watch save. Playwright's
+  // CSS goes into open shadow roots, so matches are counted in them too; inside one, the element's own
+  // selector there follows its host's, which a descendant combinator crosses into.
+  const shadowRoots = scope => {
+    const found = [scope];
+    for (let i = 0; i < found.length; i++) for (const el of found[i].querySelectorAll('*')) if (el.shadowRoot) found.push(el.shadowRoot);
+    return found;
+  };
+  const textOf = el => (el.textContent || '').replace(/\\s+/g, ' ').trim();
+  const cssString = text => '"' + text.replace(/\\\\/g, '\\\\\\\\').replace(/"/g, '\\\\"') + '"';
+  const selectorIn = (el, scope) => {
+    const roots = shadowRoots(scope);
+    const count = sel => { let n = 0; for (const r of roots) n += r.querySelectorAll(sel).length; return n; };
+    const tag = el.localName;
+    if (el.id && count('#' + CSS.escape(el.id)) === 1) return '#' + CSS.escape(el.id);
+    const testid = el.getAttribute('data-testid');
+    if (testid && count('[data-testid=' + cssString(testid) + ']') === 1) return '[data-testid=' + cssString(testid) + ']';
+    const name = el.getAttribute('name');
+    if (name && /^(?:input|select|textarea)$/.test(tag) && count(tag + '[name=' + cssString(name) + ']') === 1) return tag + '[name=' + cssString(name) + ']';
+    const text = textOf(el);
+    if (text && text.length <= 60 && !el.querySelector('input,select,textarea')) {
+      let same = 0;
+      for (const r of roots) for (const other of r.querySelectorAll(tag)) if (textOf(other) === text) same++;
+      if (same === 1) return tag + ':text-is(' + cssString(text) + ')';
+    }
+    // Its place: the path down from the nearest ancestor with an id of its own, or from the top.
+    const steps = [];
+    for (let at = el; at && at.parentNode; at = at.parentNode) {
+      if (at !== el && at.id && count('#' + CSS.escape(at.id)) === 1) { steps.unshift('#' + CSS.escape(at.id)); break; }
+      if (at.localName === 'body') { steps.unshift('body'); break; }
+      const same = [...at.parentNode.children].filter(c => c.localName === at.localName);
+      steps.unshift(same.length > 1 ? at.localName + ':nth-of-type(' + (same.indexOf(at) + 1) + ')' : at.localName);
+      if (!(at.parentNode instanceof Element)) break;
+    }
+    return steps.join(' > ');
+  };
+  const partsOf = el => {
+    const root = el.getRootNode();
+    if (root === document) return [selectorIn(el, document)];
+    if (!(root instanceof ShadowRoot) || root.mode !== 'open') return null;
+    const host = partsOf(root.host);
+    return host && [...host, selectorIn(el, root)];
+  };
+  // Each part matched in the element's own tree, the one before it by an ancestor, its host's included,
+  // as Playwright reads a descendant combinator. A path inside a shadow root is anchored to nothing
+  // there, so it could match deeper in the host: the whole selector is counted before it is used.
+  const composedParent = el => el.parentElement || (el.parentNode instanceof ShadowRoot ? el.parentNode.host : null);
+  const TEXT_IS = /^([a-z][\\w-]*):text-is\\("((?:[^"\\\\]|\\\\.)*)"\\)$/;
+  const matchesPart = (el, part) => {
+    const text = part.match(TEXT_IS);
+    return text ? el.localName === text[1] && textOf(el) === text[2].replace(/\\\\(.)/g, '$1') : el.matches(part);
+  };
+  const matchesParts = (el, parts) => {
+    if (!matchesPart(el, parts[parts.length - 1])) return false;
+    if (parts.length === 1) return true;
+    const rest = parts.slice(0, -1);
+    for (let at = composedParent(el); at; at = composedParent(at)) if (matchesParts(at, rest)) return true;
+    return false;
+  };
+  const selectorOf = el => {
+    if (window !== window.top) return null;
+    const parts = partsOf(el);
+    if (!parts) return null;
+    let n = 0;
+    for (const r of shadowRoots(document)) for (const other of r.querySelectorAll('*')) if (matchesParts(other, parts) && ++n > 1) return null;
+    return n === 1 ? parts.join(' ') : null;
+  };
   // el null: the page itself, e.g. Escape with nothing focused.
   const send = (action, el, extra, since) => {
     // Typing still waiting for its pause is recorded first, so the steps stay in order.
     if (action !== 'type') for (const field of [...pending.keys()]) flushTyping(field);
-    if (typeof window.__pwReplWatch === 'function') window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', extra: extra || '', since: since || 0 }));
+    if (typeof window.__pwReplWatch !== 'function') return;
+    let selector = null;
+    try { selector = el ? selectorOf(el) : null; } catch {}
+    const typed = (action === 'type' || action === 'fill') && el;
+    const secret = typed && isSecret(el);
+    const option = action === 'select' ? el.value : null;
+    window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', extra: extra || '', since: since || 0, selector, secret, value: typed && !secret ? valueOf(el) : null, option }));
   };
+  // The element itself, not its component's host, when it is inside an open shadow root.
+  const targetOf = e => (e.composedPath && e.composedPath()[0]) || e.target;
+  // Enter in a form's field submits it with a click on its submit button, which is the Enter's doing:
+  // recorded too, it would submit the form again when the steps run again.
+  let enteredForm = null;
   document.addEventListener('click', e => {
-    const el = e.target.closest ? (e.target.closest(INTERACTIVE) || e.target) : e.target;
+    const t = targetOf(e);
+    const el = t.closest ? (t.closest(INTERACTIVE) || t) : t;
     if (!el.matches || el.matches('input[type=checkbox],input[type=radio],select') || isPassword(el)) return;
+    if (e.detail === 0 && enteredForm && el.form === enteredForm) return;
     send('click', el);
   }, true);
   // Typing is recorded once it pauses, not on change, so a typeahead's requests
@@ -87,25 +181,30 @@ const WATCH_SCRIPT = `(() => {
   const editable = el => el.isContentEditable ? (el.closest('[contenteditable]:not([contenteditable=false])') || el) : null;
   const textEntry = el => el.matches('textarea,input:not([type=checkbox],[type=radio],[type=button],[type=submit],[type=reset],[type=image],[type=file],[type=range],[type=color])');
   document.addEventListener('input', e => {
-    const el = editable(e.target) || e.target;
-    if (!el.matches || isPassword(el) || !(textEntry(el) || el.isContentEditable)) return;
+    const el = editable(targetOf(e)) || targetOf(e);
+    if (!el.matches || !(textEntry(el) || el.isContentEditable)) return;
+    // Typing here ends typing anywhere else, recorded first: one that ended with no change event (the
+    // value it had before) would otherwise wait out its pause, and come after the fields typed since.
+    for (const field of [...pending.keys()]) if (field !== el) flushTyping(field);
     const start = pending.has(el) ? pending.get(el).start : Date.now();
     clearTimeout(pending.get(el)?.timer);
     pending.set(el, { start, timer: setTimeout(() => flushTyping(el), TYPING_PAUSE) });
   }, true);
   document.addEventListener('keydown', e => {
     if (e.key !== 'Enter' && e.key !== 'Escape') return;
-    if (!e.target.matches) return;
-    const el = editable(e.target) || e.target.closest(INTERACTIVE);
-    if (el && isPassword(el)) return;
+    const t = targetOf(e);
+    if (!t.matches) return;
+    const el = editable(t) || t.closest(INTERACTIVE);
     // Enter on a button or link is recorded as the click it causes.
     if (e.key === 'Enter' && !(el && (textEntry(el) || el.isContentEditable))) return;
     if (el) flushTyping(el);
     send('press', el, e.key);
+    // The click comes in the same task as the key, if at all.
+    if (e.key === 'Enter' && el && el.form) { enteredForm = el.form; setTimeout(() => { enteredForm = null; }); }
   }, true);
   document.addEventListener('change', e => {
-    const el = e.target;
-    if (!el.matches || isPassword(el)) return;
+    const el = targetOf(e);
+    if (!el.matches) return;
     if (el.matches('input[type=checkbox],input[type=radio]')) return send(el.checked ? 'check' : 'uncheck', el);
     if (el.matches('select')) return send('select', el, JSON.stringify(clip(el.selectedOptions[0]?.text)));
     if (pending.has(el)) { flushTyping(el); typed.delete(el); return; }
@@ -117,7 +216,7 @@ const WATCH_SCRIPT = `(() => {
 
 // What changed on screen between two snapshots, in a few lines. Refs, links'
 // URLs and focus are dropped, and so are the values of text fields, which may
-// be what the person typed. A new or removed element is shown once, with the
+// be what the user typed. A new or removed element is shown once, with the
 // first few named things inside it, not line by line.
 const CHANGES_SHOWN = 5;
 const CHANGE_WIDTH = 100;
@@ -202,7 +301,7 @@ function summarizeChanges(beforeText, afterText) {
 const SETTLE_QUIET = 800;
 const SETTLE_MAX = 3000;
 
-// Text in an editable area (contenteditable) may be what the person typed,
+// Text in an editable area (contenteditable) may be what the user typed,
 // and the snapshot shows it as ordinary text, so it is blanked out: a line's
 // text or name is dropped when it is part of an editable area's text.
 async function snapshotText(p) {
@@ -257,7 +356,7 @@ function printLive(p, watch) {
   out.aside(lines.map((line, i) => `${i ? ' '.repeat(prefix.length) : prefix}${line}`).join('\n'));
 }
 
-async function startWatching(p, changes = false, live = false) {
+async function startWatching(p, changes = false, live = false, values = true) {
   await keepBodiesDurable(p);
   let watch = tabState(p).watch;
   if (!watch) {
@@ -265,11 +364,14 @@ async function startWatching(p, changes = false, live = false) {
     const created = { on: false, startedAt: 0, changes: false, live: false, liveStep: null, snapshot: null, settleTimer: null, events: [], nextSeq: 1, shownSeq: 0, shownRequestId: 0 };
     // since backdates a step (typing is reported once it pauses), but never to
     // before the previous step, so the page cannot reorder the record.
-    const record = (action, target, extra, since = 0) => {
+    // more: what watch save needs, the element's selector and a typed value (kept whole), or a navigation's URL.
+    const record = (action, target, extra, since = 0, more = {}) => {
       if (!created.on) return;
       const previous = created.events[created.events.length - 1];
       const t = Math.max(Date.now() - Math.min(Math.max(Number(since) || 0, 0), TYPING_BACKDATE_MAX), previous ? previous.t : 0);
-      const step = { seq: created.nextSeq++, t, action, target: clipText(target), extra: clipText(extra) };
+      const step = { seq: created.nextSeq++, t, action, target: clipText(target), extra: clipText(extra), selector: more.selector || null, secret: !!more.secret, url: more.url };
+      if (typeof more.option === 'string') step.option = more.option;
+      if (typeof more.value === 'string' && created.values) step.value = more.value;
       keep(created.events, step);
       // A step that has not settled yet is printed now: this one ends it.
       printLive(p, created);
@@ -288,7 +390,10 @@ async function startWatching(p, changes = false, live = false) {
         if (name !== WATCH_BINDING || !binding.record) return;
         let event;
         try { event = JSON.parse(payload); } catch { return; }
-        if (event && PAGE_ACTIONS.has(event.action)) binding.record(event.action, String(event.target || ''), String(event.extra || ''), event.since);
+        if (event && PAGE_ACTIONS.has(event.action)) {
+          binding.record(event.action, String(event.target || ''), String(event.extra || ''), event.since,
+            { selector: typeof event.selector === 'string' ? event.selector : null, secret: !!event.secret, value: event.value, option: event.option });
+        }
       });
       // Calls are reported only to a session with Runtime on.
       await session.send('Runtime.enable');
@@ -297,7 +402,7 @@ async function startWatching(p, changes = false, live = false) {
     }
     tabState(p).watchBinding.record = record;
     await p.addInitScript(WATCH_SCRIPT);
-    p.on('framenavigated', frame => { if (frame === p.mainFrame()) record('navigate', frame.url(), ''); });
+    p.on('framenavigated', frame => { if (frame === p.mainFrame()) record('navigate', frame.url(), '', 0, { url: frame.url() }); });
     // Only now: a failed first attempt must leave nothing half set up to retry against.
     tabState(p).watch = created;
     watch = created;
@@ -311,6 +416,8 @@ async function startWatching(p, changes = false, live = false) {
   await p.evaluate(WATCH_SCRIPT);
   watch.changes = changes;
   watch.live = live;
+  watch.values = values;
+  if (!watch.on) watch.startUrl = p.url();
   if (!live) watch.liveStep = null;
   // The first step's changes are measured from how the page looks now. A page
   // too busy to snapshot is not a reason to fail: the step after one that
@@ -358,7 +465,7 @@ function watchNewTab(p) {
   const want = nextTab;
   tabState(p).watchStarting = true;
   keepBodiesDurable(p);
-  startWatching(p, want.changes, want.live).then(() => {
+  startWatching(p, want.changes, want.live, want.values).then(() => {
     delete tabState(p).watchStarting;
     tabState(p).watch.owner = want.client;
     const onNavigate = frame => {
@@ -378,7 +485,7 @@ function watchNewTab(p) {
       // A page that loaded before the watch was ready: its step is added, at its request's time.
       if (first < 0) {
         const request = (tabState(p).log || []).filter(e => e.navigation && e.url === url).pop();
-        watch.events.unshift({ seq: watch.nextSeq++, t: request ? request.t : Date.now(), action: 'navigate', target: clipText(url), extra: '' });
+        watch.events.unshift({ seq: watch.nextSeq++, t: request ? request.t : Date.now(), action: 'navigate', target: clipText(url), extra: '', url });
       }
       // Selected for the client that asked, whoever's command runs now.
       const record = clientRecord(want.client);
@@ -412,7 +519,8 @@ function requestsByStep(watch, p = state.page) {
 }
 
 function stepLines(e, caused, note = '', withChanges = true) {
-  const lines = [`${clock(e.t)} ${e.action} ${e.target}${e.extra ? ` ${e.extra}` : ''}${note}`];
+  const typed = e.secret ? ' (a password: not recorded)' : typeof e.value === 'string' ? ` ${JSON.stringify(clipText(e.value))}` : '';
+  const lines = [`${clock(e.t)} ${e.action} ${e.target}${typed}${e.extra ? ` ${e.extra}` : ''}${note}`];
   const indent = ' '.repeat(clock(e.t).length + 1);
   for (const r of caused.slice(0, WATCH_REQUESTS_SHOWN)) lines.push(`${indent}#${r.id} ${r.method} ${r.status} ${r.url}`);
   if (caused.length > WATCH_REQUESTS_SHOWN) lines.push(`${indent}… ${caused.length - WATCH_REQUESTS_SHOWN} more (requests)`);
@@ -436,12 +544,66 @@ function showWatch(watch, all) {
     if (steps > shown.length) lines.push(`(last ${shown.length} of ${steps})`);
   }
   const more = ['watch <n>', `the last n steps (up to ${WATCH_MAX})`];
-  if (watch?.on) lines.push(hints([more, ['watch new', 'only the steps not shown by watch new yet'], ['watch off', 'stop recording']]));
-  else if (steps) lines.push(hints([more, ['watch on [--changes] [--live]', 'record again']]));
+  const save = ['watch save <file>', 'save them as commands, for send --file to run again'];
+  if (watch?.on) lines.push(hints([more, ['watch new', 'only the steps not shown by watch new yet'], ...(steps ? [save] : []), ['watch off', 'stop recording']]));
+  else if (steps) lines.push(hints([more, save, ['watch on [--changes] [--live]', 'record again']]));
   else lines.push(hints([['watch on', 'record clicks, typing, form changes and navigations'], ['watch on --changes', 'also record what each step changes on the page'], ['watch on --live', 'also print each step here as it happens']]));
   printOutput(lines.join('\n'), all);
 }
 
+// watch save: the steps as commands for send --file to run again, a step that cannot be one (a value
+// with a line break, an element in a frame) as a comment saying so. What was typed into a password field,
+// or with --no-values, is a {{ PW_NAME }} variable, named after the field, that send --file fills in. A
+// selector is quoted as lib/syntax.js reads one: single quotes, which escape nothing, unless it holds
+// one. A value is always double-quoted, so an empty one, or one that starts with -, stays the value.
+function savedCommands(watch, p) {
+  const sel = text => (text.includes("'") ? `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` : `'${text}'`);
+  const value = text => `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const documents = (tabState(p).log || []).filter(r => r.navigation);
+  const events = watch.events.slice();
+  const first = events[0]?.action === 'navigate' ? events.shift().url : watch.startUrl;
+  const lines = [`goto ${first}`];
+  let skipped = 0;
+  const variables = new Map();
+  // PW_, so a field named User or pwd is not filled with the shell's USER or PWD; and never pw-repl's own.
+  const variableFor = e => {
+    if (variables.has(e.selector)) return variables.get(e.selector);
+    const label = /"([^"]+)"$/.exec(e.target)?.[1] || /(?:#|name=")([\w-]+)/.exec(e.selector)?.[1] || 'TEXT';
+    const base = `PW_${label.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'TEXT'}`;
+    const taken = new Set([...variables.values(), ...PW_SETTINGS]);
+    let name = base;
+    for (let n = 2; taken.has(name); n++) name = `${base}_${n}`;
+    variables.set(e.selector, name);
+    return name;
+  };
+  const comment = (e, why) => { skipped += 1; lines[lines.length - 1] += `: ${why}`; };
+  for (const [i, e] of events.entries()) {
+    const previous = events[i - 1];
+    if (e.action === 'navigate') {
+      // The page an action led to: waited for if it loaded a document, not if the app only changed its URL.
+      if (previous && previous.action !== 'navigate') {
+        const loaded = documents.some(r => r.url === e.url && r.t >= previous.t && r.t <= e.t + 1000);
+        lines.push(loaded ? `wait load` : `# the app went to ${e.url} without loading a page`);
+      } else {
+        lines.push(`goto ${e.url}`);
+      }
+      continue;
+    }
+    if (e.action === 'submit') continue;
+    lines.push(`# ${e.action} ${e.target}${e.extra ? ` ${e.extra}` : ''}`);
+    if (!e.selector && !(e.action === 'press' && e.target === 'page')) { comment(e, 'no selector finds it alone: it is in a frame or a closed shadow root, or its place matches others too'); continue; }
+    if (e.action === 'click' || e.action === 'check' || e.action === 'uncheck') lines.push(`${e.action} ${sel(e.selector)}`);
+    else if (e.action === 'select' && typeof e.option !== 'string') comment(e, 'the option was not recorded');
+    else if (e.action === 'select' && /[\r\n]/.test(e.option)) comment(e, 'the option\'s value has a line break, which a line of a file cannot hold');
+    else if (e.action === 'select') lines.push(`select ${sel(e.selector)} ${value(e.option)}`);
+    else if (e.action === 'press') lines.push(e.target === 'page' ? `press ${e.extra}` : `press ${sel(e.selector)} ${e.extra}`);
+    else if (e.secret || typeof e.value !== 'string') lines.push(`fill ${sel(e.selector)} "{{ ${variableFor(e)} }}"`);
+    else if (/[\r\n]/.test(e.value)) comment(e, 'what was typed has a line break, which a line of a file cannot hold: type it with type, line by line, pressing Enter');
+    else lines.push(`fill ${sel(e.selector)} ${value(e.value)}`);
+  }
+  return { lines, skipped, variables: [...new Set(variables.values())] };
+}
+
 function stopWatching(p, watch) {
   clearTimeout(watch.settleTimer);
   printLive(p, watch);
@@ -459,10 +621,10 @@ const commands = {
     if (sub === 'on' && next !== -1) {
       const part = flags[next + 1] && !flags[next + 1].startsWith('--') ? flags[next + 1] : null;
       const rest = flags.filter((f, i) => i !== next && !(part && i === next + 1));
-      if (!rest.every(f => f === '--changes' || f === '--live')) throw new Error('Usage: watch on [--changes] [--live] --next-tab [url-part]');
+      if (!rest.every(f => WATCH_FLAGS.has(f))) throw new Error('Usage: watch on [--changes] [--live] [--no-values] --next-tab [url-part]');
       // One wait at a time: a second client's would silently take the first's place.
       if (nextTab && nextTab.client !== state.client) throw new Error(`${waitingText()} already, for ${waiter()}: one at a time. modes shows it; that client's watch off, or modes off, stops it`);
-      nextTab = { part, changes: rest.includes('--changes'), live: rest.includes('--live'), client: state.client };
+      nextTab = { part, changes: rest.includes('--changes'), live: rest.includes('--live'), values: !rest.includes('--no-values'), client: state.client };
       out.log(`${waitingText()}: it is watched from its first page, and selected. watch off stops waiting.`);
       return;
     }
@@ -470,13 +632,15 @@ const commands = {
       out.log(`${waitingText()} (watch on --next-tab); it is selected once it opens, and watch then shows its steps.`);
       return;
     }
-    if (sub === 'on' && flags.every(f => f === '--changes' || f === '--live')) {
+    if (sub === 'on' && flags.every(f => WATCH_FLAGS.has(f))) {
       if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
       const changes = flags.includes('--changes');
       const live = flags.includes('--live');
-      await startWatching(state.page, changes, live);
+      const values = !flags.includes('--no-values');
+      await startWatching(state.page, changes, live, values);
       tabState(state.page).watch.owner = state.client;
-      out.log(`Watching the selected tab: clicks, typing, form changes, submits and navigations${changes ? ', and what each changed on screen' : ''} (typed values are not recorded)`);
+      out.log(`Watching the selected tab: clicks, typing, form changes, submits and navigations${changes ? ', and what each changed on screen' : ''}`);
+      out.log(values ? 'What is typed is recorded, except in password fields; --no-values leaves it out.' : 'What is typed is not recorded (--no-values).');
       out.log(live ? 'Each step prints here once it settles; watch shows them again.' : 'watch shows what it has recorded; watch on --live also prints each step here as it happens.');
       return;
     }
@@ -491,7 +655,24 @@ const commands = {
       return;
     }
     if (!arg) return showWatch(watch, all);
-    const usage = `Usage: watch on [--changes] [--live] | watch off | watch [n] | watch new (n from 1 to ${WATCH_MAX})`;
+    if (sub === 'save') {
+      const file = arg.slice(4).trim();
+      if (!file) throw new Error('Usage: watch save <file>, e.g. watch save flow.txt; pw-repl send --file flow.txt runs it');
+      if (!watch || !watch.events.length) throw new Error('Nothing to save: watch on records the steps first');
+      if (fs.existsSync(file)) throw new Error(`${file} exists already; name another file`);
+      const { lines, skipped, variables } = savedCommands(watch, state.page);
+      const run = `${variables.map(name => `${name}=... `).join('')}pw-repl send --file ${path.basename(file)}`;
+      const header = [`# pw-repl watch, saved ${new Date().toISOString()} from ${state.page.url()}`, `# ${run} runs it; a line starting with # is not run`];
+      const where = watch.values ? 'password fields' : 'fields (watch on --no-values)';
+      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' });
+      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.`);
+      return;
+    }
+    const usage = `Usage: watch on [--changes] [--live] [--no-values] | watch off | watch [n] | watch new | watch save <file> (n from 1 to ${WATCH_MAX})`;
     const onlyNew = arg === 'new';
     if (arg && !onlyNew && !/^\d+$/.test(arg)) throw new Error(usage);
     const count = onlyNew ? RECENT_DEFAULT : Number(arg);

package/package.json

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

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, 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 person does, and recording a video of a tab. 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 (playwright-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.
 allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 ---
 
@@ -9,15 +9,17 @@ allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 <!-- pw-repl skill stamp -->
 
 pw-repl (playwright-repl) is a REPL that drives a running Chromium over CDP. The browser may be a
-shared session: a person can have their own tabs open in it and be using it while you work.
+shared session: the user can have their own tabs open in it and be using it while you work.
 
 `pw-repl` below is the command the `pw-repl` npm package installs. Without a global install, use
 `npx pw-repl@latest` in its place, in that same form for every command, so each one runs the same
 version; from a clone, `<clone>/bin/pw-repl.js`.
 
-`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. When
-that is not the skill named at the top of this file, tell the user once, in these words and in passing,
-with whatever else you are telling them, and carry on with the task:
+`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. Compare
+its hash (`e5f6a7b8`) with the one at the top of this file. The same hash is the same skill, whatever
+the versions say, since a release that leaves the skill as it was keeps its hash: say nothing. When the
+hashes differ, tell the user once, in these words and in passing, with whatever else you are telling
+them, and carry on with the task:
 
 - if this file's pw-repl version is newer than that one, pw-repl is behind: "🔄 pw-repl is older than
   this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
@@ -50,12 +52,12 @@ run one; each takes an optional start URL, which opens in a new tab.
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
   `pw[serve]>`. It stops at that prompt (`quit`, or Ctrl-C); `pw-repl stop` is for a background one.
 - Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
-  own instead of connecting to one: headless unless `--headed`, in a temporary profile, on a free port of
-  its own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns once
-  it has exited. It prints the command it ran; flags after `--` are passed to that Chromium, and a
-  `--user-data-dir=<dir>` among them is used instead of the temporary profile, and kept. Started again in
-  a kept profile, Chromium picks up where it left off, as it would for a person, headless too: its tabs
-  come back, and session cookies with them, so a login stays. They start loading before the REPL is
+  own instead of connecting to one: headless unless `--headed`, in a temporary profile, on a free port
+  of its own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns
+  once it has exited. It prints the command it ran; flags after `--` are passed to that Chromium, and a
+  `--user-data-dir=<dir>` among them is used instead of the temporary profile, and kept. Started again
+  in a kept profile, Chromium picks up where it left off, as it would for the user, headless too: its
+  tabs come back, and session cookies with them, so a login stays. They start loading before the REPL is
   attached, so `requests` and `console` have only what came after, often nothing: `reload` for a full
   record.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
@@ -74,14 +76,15 @@ pw-repl send -e /tmp/mine.sock tab new http://localhost:3000
 pw-repl stop -e /tmp/mine.sock
 ```
 
-A socket file left by a REPL that died is replaced when the next one starts there. The log of a background REPL is next to its socket
-(`/tmp/mine.log`), appended to run after run, with a line where each starts and stops (past 5 MB, a
-start moves it to `/tmp/mine.log.1`); `tail -f` on it follows along without a terminal to attach from.
-`serve <port>` listens on TCP 127.0.0.1 instead of a socket, with no access control.
+A socket file left by a REPL that died is replaced when the next one starts there. The log of a
+background REPL is next to its socket (`/tmp/mine.log`), appended to run after run, with a line where
+each starts and stops (past 5 MB, a start moves it to `/tmp/mine.log.1`); `tail -f` on it follows along
+without a terminal to attach from. `serve <port>` listens on TCP 127.0.0.1 instead of a socket, with no
+access control.
 
 ### One REPL, many clients
 
-One REPL serves everyone using its browser: the person at its prompt and any number of agents. When
+One REPL serves everyone using its browser: the user at its prompt and any number of agents. When
 `pw-repl where` finds one running for the browser you need, use it rather than start another, as a
 client of your own: `PW_CLIENT=<name>` (or `send -c <name>`), with a name that says who you are.
 
@@ -107,9 +110,10 @@ pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
 Always send commands with `pw-repl send`; don't type into the pane yourself, except `quit` at the prompt
 of a REPL of your own, which `send` refuses. The words after `send` are the command. For `fill`, `type`,
 `select`, `press` and `upload`, a word quoted in your shell stays one word
-(`pw-repl send fill "text=Your name" Ada`); other commands get the words as they are, joined by spaces
-(`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the whole line,
-spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL was started:
+(`pw-repl send fill "text=Your name" Ada`); other commands get the words as they are, joined by
+spaces (`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the
+whole line, spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL was
+started:
 
 - `run` (in tmux): `send` types the command into the tmux pane and reads the result back off the screen.
   It types only when the pane's last line is a bare prompt, so nothing lands in a shell or in the middle
@@ -123,8 +127,14 @@ spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL
 REPL), or why neither is reachable, without running anything.
 
 `send --file take.txt` runs a file of commands, one per line, as typed at the prompt (no shell quoting;
-files relative to your folder, as on `send`'s command line; `#` comments), and stops at the first that fails, saying which line.
-It is the way to record a video without gaps (`help record`), and to keep a repro to run again.
+files relative to your folder, as on `send`'s command line; `#` comments), and stops at the first that
+fails, saying which line. It is the way to record a video without gaps (`help record`), and to keep a
+repro to run again. A `{{ PW_NAME }}` in a line is the variable PW_NAME from `send`'s environment, best
+in double quotes (`fill '#password' "{{ PW_PASSWORD }}"`): the REPL fills it in as it runs the line, and
+its pane and log show the line as written, so a secret stays out of both the file and the log. Only
+`PW_` names are variables; any other `{{ ... }}` (a page's template text) is sent as written. One that
+is not set stops the file; `--no-vars` sends it as written. A single `send` takes them too: to type a
+password, `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}"` keeps it out of the log.
 
 `send` takes one command; chain several in your shell. Use `&&` when a step only makes sense if the one
 before it worked: it stops at any exit status but 0, a failure and an outcome not confirmed included.
@@ -146,11 +156,15 @@ Every command you run and its output show in the REPL's pane, or in `attach` and
 background REPL (server commands as `[server]` lines), so whoever looks there sees what you do. The pane
 shows REPL commands only, not what was clicked in the browser (unless `watch on --live` is on); for
 that, look at the browser itself: `tab` and `info` for where things are, `requests` for the requests the
-clicks made (`body <#>` for what one returned), `console` for console messages and page errors. `watch
-on` records each step someone takes in a tab, with the requests it caused (`watch on --changes` adds
-what each step changed on the page); `watch` reads it back, and `watch new` only what it has not shown
-yet. For a tab they have not opened yet, `watch on --next-tab [url-part]` waits for it and watches it
-from its first page.
+clicks made (`body <#>` for what one returned), `console` for console messages and page errors.
+`watch on` records each step someone takes in a tab, with the requests it caused (`watch on --changes`
+adds what each step changed on the page); `watch` reads it back, and `watch new` only what it has not
+shown yet. For a tab they have not opened yet, `watch on --next-tab [url-part]` waits for it and
+watches it from its first page. `watch save <file>` writes the steps as commands that `send --file`
+runs again, a repro to keep. What is typed is recorded, except in password fields; `watch on
+--no-values` leaves it out. The file has a `{{ PW_PASSWORD }}` variable where a password was typed,
+which `send --file` fills in from its environment (`PW_PASSWORD=... pw-repl send --file login.txt`), so
+the file can be shared without it.
 
 When watching someone:
 
@@ -185,7 +199,7 @@ task (`cart-bug`), since two agents with one name are one client:
 pw-repl send -c <name> open http://localhost:3000   # a tab of your own in the shared browser
 pw-repl send -c <name> snapshot                     # no snapshot after each command; ask for one
 pw-repl send -c <name> click e5
-pw-repl send -c <name> close                        # your modes off; tab close <url-part> closes your tab
+pw-repl send -c <name> close                        # your modes off; tab close <url-part> closes yours
 ```
 
 - There is no browser of your own to open or close: `open` opens a tab in the one the REPL uses, and
@@ -199,27 +213,27 @@ pw-repl send -c <name> close                        # your modes off; tab close
 ## Sharing the browser
 
 - The browser may have tabs that are not yours, and someone may be using it. Whether to read or act in
-  one of those tabs, or to open your own (`tab new <url>`), depends on the task; when that is not
-  clear, ask.
+  one of those tabs, or to open your own (`tab new <url>`), depends on the task; when that is not clear,
+  ask. `tab` marks `(in front)` the tab the user sees: "this page" is usually that one. A tab you have
+  selected is never marked (help tab says why).
 - No tab is selected when the REPL starts. A start URL's tab, marked `(the start URL)` in `tab`, is
   selected at its prompt and for `send` without a client name; a named client (`-c`) selects it with
   `tab <index>`. Closing a tab the REPL opened goes back to the tab before it, if the REPL opened that
-  one too; otherwise no tab is selected.
-  Tab numbers change when tabs open or close; `tab <url-part>` and `tab close <url-part>` pick a tab by
-  its URL and refuse if it is ambiguous.
-- You can answer any dialog yourself, one you opened included: `dialog` shows it, and `dialog accept`
-  or `dialog dismiss` answers it. Nothing answers one on its own, and while one is open its page and
-  the commands that read it wait. One answered in the browser is gone from `dialog` too.
+  one too; otherwise no tab is selected. Tab numbers change when tabs open or close; `tab <url-part>`
+  and `tab close <url-part>` pick a tab by its URL and refuse if it is ambiguous.
+- You can answer any dialog yourself, one you opened included: `dialog` shows it, and `dialog accept` or
+  `dialog dismiss` answers it. Nothing answers one on its own, and while one is open its page and the
+  commands that read it wait. One answered in the browser is gone from `dialog` too.
 - Modes and tabs stay on or open until they are turned off or closed, whoever started them. `modes`
   lists what is on in every tab (the prompt shows the selected tab's, e.g. `(watch routes:1) pw>`);
   `modes off` turns off every mode in every tab.
 - Someone may be attached to the REPL's tmux session; killing the session ends it for them too.
-- To point something out, to the person or in a screenshot, `highlight <ref|selector>` draws a box over it
+- To point something out, to the user or in a screenshot, `highlight <ref|selector>` draws a box over it
   without changing the page (`--style=<css>` restyles it; `highlight off` hides them), without
   Playwright's locator label unless `highlight --labels on`.
 - For a video, `help video` says how: a take written as a file and sent with `send --file`, `record on`
-  around it, `cursor on` for a pointer, and the pacing recording adds for the viewer; a screen recorder on
-  the user's machine records what they see.
+  around it, `cursor on` for a pointer, `toast` to say what is happening, and the pacing recording adds
+  for the viewer; a screen recorder on the user's machine records what they see.
 
 ## Environment
 
@@ -228,13 +242,13 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - `PW_CHROME` — the Chromium `--launch` starts (default: Playwright's own, then one on the `PATH`).
 - `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's own Chromium and ffmpeg are found where Playwright installs them:
+  `PLAYWRIGHT_BROWSERS_PATH`, or `~/.cache/ms-playwright`.
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
-- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots, 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 in `/tmp`. `screenshot`
-  prints each file's path; other REPLs may save theirs in the same place. Remove only your
-  own, and keep those too if they are needed, e.g. as evidence or as something to hand over.
+- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots, 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 in `/tmp`. `screenshot`
+  prints each file's path; other REPLs may save theirs in the same place. Remove only your own, and keep
+  those too if they are needed, e.g. as evidence or as something to hand over.
 - `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `serve`
   serves on and `send` looks for when neither is given (default `/tmp/playwright-repl.sock`).