@vosjs/cli 0.41.1 → 0.43.0

package/dist/{chunk-4QVEV3HX.js → chunk-6PJPGBKH.js}

@@ -101,8 +101,137 @@ function createReporter(json) {
   };
 }
 
+// src/plugin/setup.ts
+var VERBS = /* @__PURE__ */ new Set(["wait", "click", "type", "press", "goto"]);
+function validateSetup(value) {
+  const errors = [];
+  if (!Array.isArray(value)) return ["setup must be an array of steps"];
+  value.forEach((raw, i) => {
+    const at2 = `setup[${i}]`;
+    if (typeof raw !== "object" || raw === null) {
+      errors.push(`${at2}: must be an object`);
+      return;
+    }
+    const s = raw;
+    if (typeof s.do !== "string" || !VERBS.has(s.do)) {
+      errors.push(`${at2}: "do" must be one of ${[...VERBS].join(", ")}`);
+      return;
+    }
+    if ((s.do === "click" || s.do === "type") && typeof s.selector !== "string")
+      errors.push(`${at2}: ${s.do} needs a selector`);
+    if (s.do === "wait" && typeof s.ms !== "number")
+      errors.push(`${at2}: wait needs ms`);
+    if (s.do === "press" && typeof s.key !== "string")
+      errors.push(`${at2}: press needs a key`);
+    if (s.do === "goto" && typeof s.url !== "string")
+      errors.push(`${at2}: goto needs a url`);
+    if (s.do === "type") {
+      const t = s.text;
+      const isEnv = typeof t === "object" && t !== null && typeof t.env === "string" && Object.keys(t).length === 1;
+      if (typeof t !== "string" && !isEnv)
+        errors.push(
+          `${at2}: type needs text, a string or { "env": "NAME" } read at run time`
+        );
+      if (typeof t === "string" && /passw|secret|token/i.test(String(s.selector)) && t.length > 0)
+        errors.push(
+          `${at2}: a literal value typed into ${String(s.selector)} would live in actions.json, which is committed and pushed. Use { "env": "NAME" }`
+        );
+    }
+  });
+  return errors;
+}
+function resolveSetupText(t, env = process.env) {
+  if (typeof t === "string") return { value: t, secret: false };
+  const v = env[t.env];
+  if (v === void 0 || v === "")
+    throw new SetupEnvError(
+      `setup: the environment variable ${t.env} is not set, and a type step reads it. Export it in the shell that runs vos record; it is never written to a file`
+    );
+  return { value: v, secret: true };
+}
+async function runSetup(page, steps, opts) {
+  const lines = [];
+  for (const [i, step] of steps.entries()) {
+    const settle = "ms" in step && typeof step.ms === "number" ? step.ms : 150;
+    try {
+      switch (step.do) {
+        case "wait":
+          await opts.sleep(step.ms);
+          lines.push(`setup #${i} wait ${step.ms}ms`);
+          break;
+        case "goto":
+          await page.goto(step.url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
+          });
+          lines.push(`setup #${i} goto ${step.url}`);
+          break;
+        case "press":
+          await page.keyboard.press(step.key);
+          await opts.sleep(settle);
+          lines.push(`setup #${i} press ${step.key}`);
+          break;
+        case "click": {
+          const loc = page.locator(step.selector).first();
+          await loc.waitFor({ state: "visible", timeout: 8e3 });
+          await loc.click();
+          await opts.sleep(settle);
+          lines.push(`setup #${i} click ${step.selector}`);
+          break;
+        }
+        case "type": {
+          const loc = page.locator(step.selector).first();
+          await loc.waitFor({ state: "visible", timeout: 8e3 });
+          const { value, secret } = resolveSetupText(step.text, opts.env);
+          await loc.fill(value);
+          await opts.sleep(settle);
+          lines.push(
+            `setup #${i} type ${secret ? `\${${step.text.env}}` : `${value.length} chars`} into ${step.selector}`
+          );
+          break;
+        }
+      }
+    } catch (e) {
+      if (e instanceof SetupEnvError) throw e;
+      return {
+        ran: i,
+        lines,
+        failed: {
+          step: i,
+          do: step.do,
+          ..."selector" in step ? { selector: step.selector } : {}
+        }
+      };
+    }
+  }
+  return { ran: steps.length, lines };
+}
+var SetupEnvError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SetupEnvError";
+  }
+};
+var SetupError = class extends Error {
+  constructor(failed2) {
+    super(
+      `setup #${failed2.step} ${failed2.do}${failed2.selector ? ` ${failed2.selector}` : ""}: the selector never appeared, so the take would begin at a half-finished setup. Nothing was recorded. Fix the setup step (rehearse with --dry-run), then record.`
+    );
+    this.failed = failed2;
+    this.name = "SetupError";
+  }
+  failed;
+};
+function parseHeaders(given) {
+  const out = {};
+  for (const h of given ?? []) {
+    const i = h.indexOf("=");
+    if (i <= 0) throw new Error(`--header wants name=value, got "${h}"`);
+    out[h.slice(0, i).trim()] = h.slice(i + 1);
+  }
+  return out;
+}
+
 // src/plugin/actions.ts
-var VERBS = /* @__PURE__ */ new Set([
+var VERBS2 = /* @__PURE__ */ new Set([
   "wait",
   "hover",
   "click",
@@ -129,6 +258,25 @@ function validateActions(value) {
       }
     }
   }
+  if (obj.setup !== void 0) errors.push(...validateSetup(obj.setup));
+  if (obj.mask !== void 0) {
+    if (!Array.isArray(obj.mask)) {
+      errors.push("mask must be an array of { selector, as?, text? }");
+    } else {
+      obj.mask.forEach((raw, i) => {
+        const at2 = `mask[${i}]`;
+        const m = raw ?? {};
+        if (typeof m.selector !== "string" || !m.selector.trim())
+          errors.push(`${at2}: needs a selector`);
+        if (m.as !== void 0 && m.as !== "blur" && m.as !== "text")
+          errors.push(`${at2}: as must be "blur" or "text"`);
+        if (m.as === "text" && (typeof m.text !== "string" || !m.text))
+          errors.push(`${at2}: as "text" needs the text to show instead`);
+        if (m.as !== "text" && m.text !== void 0)
+          errors.push(`${at2}: text is only read with as "text"`);
+      });
+    }
+  }
   if (!Array.isArray(obj.steps) || obj.steps.length === 0) {
     errors.push("steps must be a non-empty array");
     return errors;
@@ -141,8 +289,8 @@ function validateActions(value) {
       return;
     }
     const s = raw;
-    if (typeof s.do !== "string" || !VERBS.has(s.do)) {
-      errors.push(`${at2}: "do" must be one of ${[...VERBS].join(", ")}`);
+    if (typeof s.do !== "string" || !VERBS2.has(s.do)) {
+      errors.push(`${at2}: "do" must be one of ${[...VERBS2].join(", ")}`);
       return;
     }
     if (s.id !== void 0) {
@@ -6758,6 +6906,199 @@ var WALL_PROBE = `(() => {
   }
 })()`;
 
+// src/plugin/exposure.ts
+var EXPOSURE_MATCHERS_SRC = `(() => {
+  const EMAIL = /[A-Za-z0-9._%+-]+@((?:[A-Za-z0-9-]+\\.)+[A-Za-z]{2,})/g
+  const SAFE_HOST = /(^|\\.)example\\.(com|org|net)$|\\.(test|example|invalid|localhost)$/i
+  const KEY = new RegExp([
+    '\\\\b[srp]k_(?:live|test)_[A-Za-z0-9]{8,}',
+    '\\\\bgh[pousr]_[A-Za-z0-9]{20,}',
+    '\\\\bgithub_pat_[A-Za-z0-9_]{20,}',
+    '\\\\bxox[abprs]-[A-Za-z0-9-]{10,}',
+    '\\\\bAKIA[0-9A-Z]{16}\\\\b',
+    '\\\\bAIza[0-9A-Za-z_-]{30,}',
+    '\\\\bvos_(?:sk|rg|ho)_[A-Za-z0-9]{8,}',
+    '\\\\beyJ[A-Za-z0-9_-]{8,}\\\\.eyJ[A-Za-z0-9_-]{8,}\\\\.[A-Za-z0-9_-]{8,}',
+  ].join('|'))
+  const CARD = /(?:^|[^0-9])((?:[0-9][ -]?){12,18}[0-9])(?![0-9])/g
+  const TAIL = /[\\u2022\\u00b7*xX]{2,}[ -]?[0-9]{4}(?![0-9])/
+  const luhn = (digits) => {
+    let sum = 0, alt = false
+    for (let i = digits.length - 1; i >= 0; i--) {
+      let d = digits.charCodeAt(i) - 48
+      if (alt) { d *= 2; if (d > 9) d -= 9 }
+      sum += d; alt = !alt
+    }
+    return sum % 10 === 0
+  }
+  const kindsIn = (text) => {
+    const kinds = []
+    if (!text || text.length < 6) return kinds
+    EMAIL.lastIndex = 0
+    for (let m; (m = EMAIL.exec(text)); ) {
+      if (!SAFE_HOST.test(m[1])) { kinds.push('email'); break }
+    }
+    if (KEY.test(text)) kinds.push('key')
+    CARD.lastIndex = 0
+    for (let m; (m = CARD.exec(text)); ) {
+      const digits = m[1].replace(/[ -]/g, '')
+      if (digits.length >= 13 && digits.length <= 19 && !/^0+$/.test(digits) && luhn(digits)) { kinds.push('card'); break }
+    }
+    if (TAIL.test(text)) kinds.push('card-tail')
+    return kinds
+  }
+  return { kindsIn }
+})()`;
+var EXPOSURE_PROBE = `(() => {
+  const { kindsIn } = ${EXPOSURE_MATCHERS_SRC}
+  const vw = innerWidth, vh = innerHeight
+  // A selector that reaches THIS element and no other, so it can be pasted
+  // into "mask" as it is: climb until the path is unique, and say which
+  // sibling wherever a tag-and-class alone would match several.
+  const segment = (el) => {
+    const tid = el.getAttribute('data-testid')
+    if (tid) return el.tagName.toLowerCase() + '[data-testid="' + tid + '"]'
+    if (el.id && /^[A-Za-z_][\\w-]*$/.test(el.id)) return el.tagName.toLowerCase() + '#' + el.id
+    const cls = [...el.classList].filter((c) => /^[A-Za-z_-][\\w-]*$/.test(c)).slice(0, 2)
+    let seg = el.tagName.toLowerCase() + (cls.length ? '.' + cls.join('.') : '')
+    const p = el.parentElement
+    if (p && [...p.children].filter((c) => c.matches(seg)).length > 1)
+      seg += ':nth-child(' + ([...p.children].indexOf(el) + 1) + ')'
+    return seg
+  }
+  const name = (el) => {
+    const parts = []
+    for (let cur = el; cur && cur !== document.body && cur !== document.documentElement; cur = cur.parentElement) {
+      parts.unshift(segment(cur))
+      let n = 2
+      try { n = document.querySelectorAll(parts.join(' > ')).length } catch {}
+      // a bare tag is unique HERE and nowhere else: give it its parent too
+      const bare = parts.length === 1 && !/[#.\\[]/.test(parts[0])
+      if ((n === 1 && !bare) || parts.length >= 5) break
+    }
+    return parts.join(' > ')
+  }
+  const seen = (el) => {
+    if (el.closest('[data-vos-masked]')) return null
+    const r = el.getBoundingClientRect()
+    if (r.width < 2 || r.height < 2) return null
+    if (r.bottom <= 0 || r.right <= 0 || r.top >= vh || r.left >= vw) return null
+    const s = getComputedStyle(el)
+    if (s.visibility === 'hidden' || s.display === 'none' || +s.opacity === 0) return null
+    return r
+  }
+  const out = [], keys = new Set()
+  const add = (el, text) => {
+    const kinds = kindsIn(text)
+    if (!kinds.length) return
+    const r = seen(el)
+    if (!r) return
+    const selector = name(el)
+    for (const kind of kinds) {
+      const k = kind + '|' + selector
+      if (keys.has(k) || out.length >= 40) continue
+      keys.add(k)
+      out.push({ kind, selector, rect: { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) } })
+    }
+  }
+  const walker = document.createTreeWalker(document.body || document.documentElement, NodeFilter.SHOW_TEXT)
+  for (let n; (n = walker.nextNode()); ) {
+    const el = n.parentElement
+    if (!el || /^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE)$/.test(el.tagName)) continue
+    add(el, n.nodeValue)
+  }
+  for (const el of document.querySelectorAll('input, textarea')) {
+    if (/^(password|hidden|file|checkbox|radio)$/.test(el.type)) continue
+    add(el, el.value)
+  }
+  const hits = {}
+  for (const [sel, n] of Object.entries(window.__vosMaskHits || {})) hits[sel] = n
+  return { exposures: out, maskHits: hits }
+})()`;
+function maskInitScript(masks) {
+  const rules = masks.map((m) => ({
+    selector: m.selector,
+    as: m.as === "text" ? "text" : "blur",
+    text: m.text ?? ""
+  }));
+  return `(() => {
+  const RULES = ${JSON.stringify(rules)}
+  const hits = (window.__vosMaskHits = window.__vosMaskHits || {})
+  for (const r of RULES) hits[r.selector] = hits[r.selector] || 0
+  const css = RULES.map((r) => r.selector + '[data-vos-masked="blur"]{filter:blur(7px) !important;user-select:none !important}').join('\\n')
+  const paint = () => {
+    const root = document.head || document.documentElement
+    if (!root || document.getElementById('__vos-mask-style')) return
+    const style = document.createElement('style')
+    style.id = '__vos-mask-style'
+    style.textContent = css
+    root.appendChild(style)
+  }
+  const apply = () => {
+    paint()
+    for (const r of RULES) {
+      let found
+      try { found = document.querySelectorAll(r.selector) } catch { continue }
+      if (found.length > hits[r.selector]) hits[r.selector] = found.length
+      for (const el of found) {
+        const form = /^(INPUT|TEXTAREA|SELECT)$/.test(el.tagName)
+        const mode = r.as === 'text' && !form ? 'text' : 'blur'
+        if (el.getAttribute('data-vos-masked') !== mode) el.setAttribute('data-vos-masked', mode)
+        if (mode !== 'text') continue
+        const texts = []
+        const w = document.createTreeWalker(el, NodeFilter.SHOW_TEXT)
+        for (let n; (n = w.nextNode()); ) texts.push(n)
+        if (!texts.length) { if (el.textContent !== r.text) el.textContent = r.text; continue }
+        texts.forEach((n, i) => { const want = i === 0 ? r.text : ''; if (n.nodeValue !== want) n.nodeValue = want })
+      }
+    }
+  }
+  new MutationObserver(apply).observe(document, { childList: true, subtree: true, characterData: true })
+  document.addEventListener('DOMContentLoaded', apply)
+  apply()
+})()`;
+}
+var ExposureLog = class {
+  byKey = /* @__PURE__ */ new Map();
+  maskHits = /* @__PURE__ */ new Map();
+  constructor(masks = []) {
+    for (const m of masks) this.maskHits.set(m.selector, 0);
+  }
+  add(step, scan) {
+    if (!scan) return;
+    for (const e of scan.exposures ?? []) {
+      const key = `${e.kind}|${e.selector}`;
+      const had = this.byKey.get(key);
+      if (had) had.seen += 1;
+      else this.byKey.set(key, { step, ...e, seen: 1 });
+    }
+    for (const [sel, n] of Object.entries(scan.maskHits ?? {})) {
+      if (n > (this.maskHits.get(sel) ?? 0)) this.maskHits.set(sel, n);
+    }
+  }
+  exposures() {
+    return [...this.byKey.values()];
+  }
+  masks(rules) {
+    return rules.map((m) => ({
+      selector: m.selector,
+      as: m.as === "text" ? "text" : "blur",
+      hits: this.maskHits.get(m.selector) ?? 0
+    }));
+  }
+};
+var KIND_WORDS = {
+  email: "an email address",
+  key: "something shaped like an API key or token",
+  card: "a card number",
+  "card-tail": "a card's last digits"
+};
+function exposureLine(e) {
+  const when = e.step < 0 ? "as the page opened" : `at step #${e.step}`;
+  return `${KIND_WORDS[e.kind]} in ${e.selector} (${when}, ${e.rect.x},${e.rect.y} ${e.rect.w}\xD7${e.rect.h})`;
+}
+var EXPOSURE_ADVICE = 'The recording shows these. Record from a demo account, or hide them before the camera rolls with "mask" in actions.json: { "selector": "\u2026", "as": "text", "text": "demo@acme.test" } swaps the words, "as": "blur" blurs. Then re-record.';
+
 // src/plugin/recorder.ts
 var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var DRY_PAUSE_MS = 120;
@@ -6783,20 +7124,42 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const context = await browser.newContext({
     viewport: { width: vw, height: vh },
     deviceScaleFactor: 1,
-    ...opts.storageState ? { storageState: opts.storageState } : {}
+    ...opts.storageState ? { storageState: opts.storageState } : {},
+    ...opts.headers && Object.keys(opts.headers).length ? { extraHTTPHeaders: opts.headers } : {}
   });
+  const masks = actions.mask ?? [];
+  if (masks.length) await context.addInitScript(maskInitScript(masks));
+  const exposureLog = new ExposureLog(masks);
   const page = await context.newPage();
+  const scanExposures = async (step) => {
+    const scan = await page.evaluate(EXPOSURE_PROBE).catch(() => null);
+    exposureLog.add(step, scan);
+  };
   page.on("console", (m) => {
     if (m.type() === "error") log(`   [page error] ${m.text()}`);
   });
   log(`goto ${url}`);
   let navTimeout = false;
-  const response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
+  let response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
     navTimeout = true;
     log("   (networkidle timeout \u2014 continuing)");
     return null;
   });
   await sleep(800);
+  const setup = actions.setup ?? [];
+  if (setup.length) {
+    log(`setup: ${setup.length} step(s), off camera`);
+    const result = await runSetup(page, setup, { sleep: realSleep });
+    for (const line of result.lines) log(`   ${line}`);
+    if (result.failed) {
+      await context.close().catch(() => {
+      });
+      throw new SetupError(result.failed);
+    }
+    log(`goto ${url} (after setup)`);
+    response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => null);
+    await sleep(800);
+  }
   let wall = null;
   if (opts.onArrival) {
     const seen = await page.evaluate(WALL_PROBE).catch(() => null);
@@ -6815,6 +7178,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       throw e;
     }
   }
+  await scanExposures(-1);
   const cdp = await context.newCDPSession(page);
   const frames = [];
   let frameIdx = 0;
@@ -7074,6 +7438,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       gestureMs,
       wallMs: now() - stepStart
     });
+    await scanExposures(stepIdx);
   }
   if (!capped) await sleep(TRAILING_HOLD_MS);
   if (capped || capReached(now(), maxSeconds)) {
@@ -7104,7 +7469,9 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     platform: process.platform === "darwin" ? "mac" : process.platform === "win32" ? "windows" : "linux",
     producer: "cli",
     steps: stepSpans,
-    ...wall ? { wall: { kind: wall.kind, asked: wall.asked, landed: wall.landed } } : {}
+    ...wall ? { wall: { kind: wall.kind, asked: wall.asked, landed: wall.landed } } : {},
+    ...exposureLog.exposures().length ? { exposures: exposureLog.exposures() } : {},
+    ...masks.length ? { masks: exposureLog.masks(masks) } : {}
   };
   const freezes = [];
   for (let i = 1; i < frames.length; i++) {
@@ -7140,6 +7507,8 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     skipped,
     navTimeout,
     wall,
+    exposures: exposureLog.exposures(),
+    masks: exposureLog.masks(masks),
     freezes,
     freezePct,
     capped
@@ -10294,12 +10663,12 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "dry-run",
   "allow-wall"
 ]);
-var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg"]);
+var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg", "header"]);
 var HELP = `vos \u2014 record a browser flow, plan effects, render a product video; sync with vos.so
 
 Take pipeline
-  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
-  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
+  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--header name=value]... [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
+  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--header name=value]... [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
   vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--with <doc.json|vosId>[@end|@start|@step:<id>|@<s>]]... [--background <slug|url|none>] [--motion] [--headline "\u2026"] [--kicker "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md] [--music <slug|mood|none>] [--entrance tilt-in|pull-out|rise|fade|slide|none] [--transitions slide|fade|scale|none] [--end-card on|none|<doc.json|vosId>] [--captions none] [--clicks none] [--still <t>] [--release v2.1] [--json]
   vos render <take> [out.webm] [--width] [--height] [--fps] [--format webm|mp4] [--parallel N] [--range a..b] [--draft] [--frame <kind>] [--background <url|slug>] [--set <path=value>]... [--json]
   vos frames <take> [--times 0,25%,50%,75%,100%] [--frame <t>] [--at-zooms] [--at-moments] [--at-still] [--size WxH] [--out dir] [--background <url|slug>] [--set <path=value>]... [--json]
@@ -10575,8 +10944,30 @@ function strictReason(rec) {
   const parts = [`${rec.skipped.length} skipped step(s)`];
   if (rec.navTimeout) parts.push("networkidle timeout");
   if (rec.capped) parts.push("stopped at --max-duration");
+  const missed = maskMisses(rec);
+  if (missed.length)
+    parts.push(
+      `${missed.length} mask(s) that hid nothing (${missed.join(", ")}): whatever they were for may be showing`
+    );
   return parts.join(" + ");
 }
+function maskMisses(rec) {
+  return (rec.masks ?? []).filter((m) => m.hits === 0).map((m) => m.selector);
+}
+function exposureNote(rec) {
+  if (!rec.exposures.length) return "";
+  return `
+  EXPOSED in the frame (${rec.exposures.length}):
+${rec.exposures.map((e) => `    - ${exposureLine(e)}`).join("\n")}
+  ${EXPOSURE_ADVICE}`;
+}
+function takeHeaders(multi) {
+  try {
+    return parseHeaders(multi.header);
+  } catch (e) {
+    throw new UsageError(e instanceof Error ? e.message : String(e));
+  }
+}
 function takeBrowserArgs(multi) {
   const given = multi["browser-arg"];
   return (given ?? []).filter(Boolean);
@@ -10647,6 +11038,7 @@ async function cmdRecord(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  const headers = takeHeaders(multi);
   if (flags["dry-run"] === true) {
     void flags.strict;
     void flags["keep-frames"];
@@ -10663,6 +11055,7 @@ async function cmdRecord(argv) {
         r.log,
         {
           storageState,
+          headers,
           dryRun: true,
           // A rehearsal is always strict, and it touches no directory.
           onArrival: wallGate(flags, r, { strict: true })
@@ -10674,10 +11067,11 @@ async function cmdRecord(argv) {
         const what = s.selector ? ` ${s.selector}` : "";
         return `  ${s.skipped ? "\u2717" : "\u2713"} #${s.step}${s.id ? ` (${s.id})` : ""} ${s.do}${what}${s.skipped ? "  NOT FOUND" : rect}${s.navigated ? "  \u2192 navigated" : ""}`;
       });
-      const failed2 = rec.skipped.length > 0 || rec.navTimeout;
+      const failed2 = rec.skipped.length > 0 || rec.navTimeout || maskMisses(rec).length > 0;
       const carried = [
         ...strFlag(flags, "storage-state") ? [`--storage-state ${strFlag(flags, "storage-state")}`] : [],
         ...browserArgs.map((a) => `--browser-arg=${a}`),
+        ...Object.entries(headers).map(([k, v]) => `--header ${k}=${v}`),
         ...flags["allow-wall"] === true ? ["--allow-wall"] : []
       ].join(" ");
       const nextOut = strFlag(flags, "out") ?? "take";
@@ -10688,11 +11082,13 @@ async function cmdRecord(argv) {
           seconds: +((Date.now() - started) / 1e3).toFixed(1),
           steps,
           skipped: rec.skipped,
-          navTimeout: rec.navTimeout
+          navTimeout: rec.navTimeout,
+          exposures: rec.exposures,
+          masks: rec.masks
         },
         `${failed2 ? "REHEARSAL FAILED" : "Rehearsal passed"}: ${steps.length - rec.skipped.length}/${steps.length} steps resolved in ${((Date.now() - started) / 1e3).toFixed(1)}s${rec.navTimeout ? " (the first load never reached networkidle)" : ""}
 ${lines.join("\n")}
-  ${failed2 ? "Fix the script, rehearse again, then record." : `Rects are capture px (the step rects a pin or a callout reads). Next: vos record --actions ${actionsPath} --out ${nextOut}${carried ? ` ${carried}` : ""} --strict`}`
+  ${maskMisses(rec).length ? `MASK hid nothing: ${maskMisses(rec).join(", ")} (the selector reached no element). ` : ""}${failed2 ? "Fix the script, rehearse again, then record." : `Rects are capture px (the step rects a pin or a callout reads). Next: vos record --actions ${actionsPath} --out ${nextOut}${carried ? ` ${carried}` : ""} --strict`}${exposureNote(rec)}`
       );
       return failed2 ? EXIT_USAGE : EXIT_OK;
     } finally {
@@ -10717,6 +11113,7 @@ ${lines.join("\n")}
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
       storageState,
+      headers,
       onArrival: wallGate(flags, r, {
         strict: flags.strict === true,
         prepare
@@ -10734,7 +11131,7 @@ ${lines.join("\n")}
     const plan = await planTake(outDir, { backdrop });
     const clicks = rec.events.filter((e) => e.type === "down").length;
     const strict = flags.strict === true;
-    const strictFail = strict && (rec.skipped.length > 0 || rec.navTimeout || rec.capped);
+    const strictFail = strict && (rec.skipped.length > 0 || rec.navTimeout || rec.capped || maskMisses(rec).length > 0);
     const skippedNote = rec.skipped.length ? `
   SKIPPED ${rec.skipped.length} step(s): ${rec.skipped.map((s) => `#${s.step} ${s.do} ${s.selector}`).join(", ")}` : "";
     r.done(
@@ -10753,11 +11150,13 @@ ${lines.join("\n")}
         capped: rec.capped,
         pace: rec.pace,
         ...rec.wall ? { wall: rec.wall } : {},
+        exposures: rec.exposures,
+        ...rec.masks.length ? { masks: rec.masks } : {},
         ...strictFail ? { strictFailed: true } : {}
       },
-      strictFail ? `STRICT: take recorded but incomplete \u2014 ${strictReason(rec)}; fix the flow and re-record.${skippedNote}` : `Take ready: ${outDir}
+      strictFail ? `STRICT: take recorded but incomplete \u2014 ${strictReason(rec)}; fix the flow and re-record.${skippedNote}${exposureNote(rec)}` : `Take ready: ${outDir}
   ${(rec.meta.durationMs / 1e3).toFixed(1)}s \xB7 ${rec.frames.length} frames \xB7 ${rec.events.length} cursor events \xB7 ${clicks} clicks \xB7 ${plan.doc.zoom.length} zoom spans planned \xB7 ${rec.freezePct}% frozen${rec.freezePct >= 25 ? " \u26A0 keep motion in frame or trim" : ""}${skippedNote}
-  Next: edit ${join18(outDir, "doc.json")} (optional), then: vos render ${outDir}`
+  Next: edit ${join18(outDir, "doc.json")} (optional), then: vos render ${outDir}${exposureNote(rec)}`
     );
     return strictFail ? EXIT_USAGE : EXIT_OK;
   } finally {
@@ -10795,6 +11194,7 @@ async function cmdCreate2(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  const headers = takeHeaders(multi);
   const paths = takePaths(outDir);
   const prepare = async () => {
     if (existsSync15(join18(outDir, "meta.json"))) {
@@ -10813,6 +11213,7 @@ async function cmdCreate2(argv) {
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
       storageState,
+      headers,
       onArrival: wallGate(flags, r, {
         strict: flags.strict === true,
         prepare
@@ -10828,7 +11229,7 @@ async function cmdCreate2(argv) {
     await releaseFrames(paths, flags, r.log);
     r.event({ event: "phase", phase: "plan" });
     await planTake(outDir, { backdrop });
-    if (flags.strict === true && (rec.skipped.length > 0 || rec.navTimeout || rec.capped)) {
+    if (flags.strict === true && (rec.skipped.length > 0 || rec.navTimeout || rec.capped || maskMisses(rec).length > 0)) {
       r.done(
         {
           take: outDir,
@@ -10872,10 +11273,12 @@ async function cmdCreate2(argv) {
         navTimeout: rec.navTimeout,
         freezes: rec.freezes,
         freezePct: rec.freezePct,
+        exposures: rec.exposures,
+        ...rec.masks.length ? { masks: rec.masks } : {},
         ...flags.draft === true ? { draft: true } : {}
       },
       `Created ${result.out} (${(result.bytes / 1024).toFixed(0)} KB, ${result.width}x${result.height}@${result.fps}, ${result.duration.toFixed(1)}s, ${result.zoomSpans} zoom spans, ${result.clicks} click effects${result.audio ? ", audio" : ""}${flags.draft === true ? ", DRAFT" : ""})
-  take: ${outDir} \u2014 inspect with: vos frames ${outDir} --at-zooms; edit doc.json and re-render with: vos render ${outDir}`
+  take: ${outDir} \u2014 inspect with: vos frames ${outDir} --at-zooms; edit doc.json and re-render with: vos render ${outDir}${exposureNote(rec)}`
     );
     return EXIT_OK;
   } finally {
@@ -11440,12 +11843,14 @@ async function cmdDigest(argv) {
         outputDuration: d.take.outputDuration,
         hasCursor: d.take.hasCursor,
         ...d.take.wall ? { wall: d.take.wall } : {},
+        ...d.take.exposures.length ? { exposures: d.take.exposures } : {},
         tokensEstimate: d.images.tokensEstimate,
         bytes: result.bytes
       },
       `Wrote ${result.file} \u2014 ${d.moments.length} moments (${Object.entries(
         kinds
-      ).map(([k, n]) => `${n} ${k}`).join(", ")}), ${d.images.full} frames + ${d.images.crop} crops` + (d.images.sheet ? `, sheet.png` : "") + ` \u2014 ~${d.images.tokensEstimate} image tokens to read them all` + (d.take.hasCursor ? "" : "\n  no cursor track: moments are head/tail/scenes only \u2014 pace by activity, zoom only where the ask names a place") + (d.take.wall ? `
+      ).map(([k, n]) => `${n} ${k}`).join(", ")}), ${d.images.full} frames + ${d.images.crop} crops` + (d.images.sheet ? `, sheet.png` : "") + ` \u2014 ~${d.images.tokensEstimate} image tokens to read them all` + (d.take.hasCursor ? "" : "\n  no cursor track: moments are head/tail/scenes only \u2014 pace by activity, zoom only where the ask names a place") + (d.take.exposures.length ? `
+  EXPOSED in the footage: ${d.take.exposures.map((e) => `${e.kind} in ${e.selector}`).join("; ")} \u2014 look at those frames before this take goes anywhere` : "") + (d.take.wall ? `
   WALL: asked for ${d.take.wall.asked}, recorded ${d.take.wall.landed} \u2014 this footage may be the wrong page; re-record with a session before cutting it` : "") + `
   Read digest.json, then the sheet, then a crop only where you must decide.`
     );
@@ -11709,6 +12114,18 @@ async function cmdValidate(argv) {
     );
     if (mismatch) warnings.push(mismatch);
   }
+  for (const e of take.meta.exposures ?? [])
+    warnings.push(`the recording shows ${exposureLine(e)}`);
+  if (take.meta.exposures?.length) warnings.push(EXPOSURE_ADVICE);
+  for (const m of take.meta.masks ?? [])
+    if (m.hits === 0)
+      warnings.push(
+        `mask "${m.selector}" reached no element, so it hid nothing: whatever it was for may be showing`
+      );
+  if (take.meta.wall)
+    warnings.push(
+      `recorded past a wall: asked for ${take.meta.wall.asked}, landed on ${take.meta.wall.landed}. This footage may be the wrong page`
+    );
   if (!take.doc) problems.push("missing doc.json (run plan)");
   if (take.doc) {
     const lint = lintDoc(take.doc);
@@ -11937,6 +12354,11 @@ async function run(argv) {
   } catch (e) {
     if (e instanceof UsageError) {
       process.stderr.write(`usage error: ${e.message}
+`);
+      return EXIT_USAGE;
+    }
+    if (e instanceof SetupError || e instanceof SetupEnvError) {
+      process.stderr.write(`${e.message}
 `);
       return EXIT_USAGE;
     }
@@ -11989,4 +12411,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-4QVEV3HX.js.map
+//# sourceMappingURL=chunk-6PJPGBKH.js.map