@vosjs/cli 0.41.0 → 0.42.0

package/README.md

@@ -90,7 +90,20 @@ vos plan take --reuse                                   # re-time that cut onto
 
 **The wall check.** Once the first navigation settles, and before a frame is captured, `record`, `create` and `--dry-run` ask whether the recorder landed where it was sent. A take that met a sign-in instead is refused with exit 4 and a sentence (`asked for /dashboard, landed on /login: no session for app.acme.com`): the asked URL answered 401 or 403, the recorder was sent to an identity provider or a sign-in path, or the page is a sign-in form (one password field, or a one-time-code field) rendered in place. A redirect somewhere else with no sign-in in sight, which is what a site that shows strangers a public page looks like, is refused under `--strict` and in a rehearsal, and said as a warning otherwise. The check runs before a re-record clears anything, so a session that expired since the last take never costs the footage it failed to replace. The way past a wall is a session: `--storage-state <file>`, minted from the test auth the project already has wherever that exists. `--allow-wall` records the page anyway (a video OF a sign-in page is a legitimate take), and the take's `meta.wall` and its digest then say so.
 
-**Rehearse before you record.** `vos record … --dry-run` runs every step against the real page, in order, because a later selector usually exists only after an earlier click. Nothing is captured and nothing is written: the pointer lands instead of travelling, every pause is cut to a beat, and the take directory beside it keeps its footage, its cut and its script exactly as they were (a real re-record moves `doc.json` aside; a rehearsal does not). Selector lookups keep their whole timeout, so a miss here is a miss in the take. It prints each step with the rect it resolved, in capture px, which are the rects a pin or `vos callout --step` reads, and exits 2 on any miss or a first load that never settled. Add `--dry-run` to the exact command you were about to run; `--storage-state` and `--browser-arg=` apply to it too.
+**What the frame shows.** Getting past a login puts the account's own data in the picture, and asking for a demo account does not hold that line: a person asked to sign in signs in as themselves. So the recorder looks. After the page opens and after every step it reads the text visible in the viewport and reports the KIND of thing it saw and where, never the string: an email address (one on `example.com` or a `.test`, `.example`, `.invalid` or `.localhost` domain is demo data and is not reported), something shaped like an API key or a JWT, a card number that passes the Luhn check, a masked card's visible tail. They land in `meta.exposures[]` (`step`, `kind`, `selector`, `rect`, `seen`), in the `record` and `create` done events, at the end of a rehearsal (before anything is recorded), as warnings in `vos validate <take>`, and in the digest's `take.exposures`. They warn; they do not fail a take, because a product may legitimately show addresses. The `selector` reaches that element and no other, so it can be pasted into a mask.
+
+**`mask`** in `actions.json` hides a selector BEFORE the first frame is captured and keeps it hidden across navigations and re-renders, so the real value is never in a frame, never in the recording, never pushed:
+
+```json
+"mask": [
+  { "selector": "nav > span", "as": "text", "text": "jane@acme.test" },
+  { "selector": ".card-number" }
+]
+```
+
+`as: "blur"` (the default) blurs the element; `as: "text"` swaps its words, which reads as a product where a blur reads as a redaction. Use `text` for IDENTIFIERS (an email, a name, an account id), never for product copy or numbers: the video stays true to the product. A form control is always blurred, since writing into an input would change what the app submits. A mask whose selector reached no element hid nothing, so it fails `--strict` and a rehearsal (exit 2) and is named; `meta.masks[]` records each mask's `hits`.
+
+**Rehearse before you record.** `vos record … --dry-run` runs every step against the real page, in order, because a later selector usually exists only after an earlier click. Nothing is captured and nothing is written: the pointer lands instead of travelling, every pause is cut to a beat, and the take directory beside it keeps its footage, its cut and its script exactly as they were (a real re-record moves `doc.json` aside; a rehearsal does not). Selector lookups keep their whole timeout, so a miss here is a miss in the take. It prints each step with the rect it resolved, in capture px, which are the rects a pin or `vos callout --step` reads, and exits 2 on any miss or a first load that never settled. Add `--dry-run` to the exact command you were about to run; `--storage-state` and `--browser-arg=` apply to it too, and the `Next:` line it prints carries them, so the command it hands you records what it rehearsed.
 
 **Digest first.** `vos digest <take>` is how an agent sees a recording without reading the video. It writes `digest/digest.json`: one moment per thing the cursor track says mattered (click clusters, typing sessions, scroll runs, dwells, idle gaps, head, tail, and frame-diff scene changes), each with source and output extents, a normalized `focus` and `rect` you can copy into a zoom span, per-second `activity`, and the planners' `proposed` span ids; plus one footage frame and a crop around the target per moment, and `sheet.png`, the contact sheet. Read the JSON, then the sheet, then a crop only where you must decide. `vos validate` then warns when a zoom does not contain what was clicked under it, and `vos frames --at-moments` renders the composed output at every moment so a still and its footage crop share an id.
 
@@ -256,6 +269,7 @@ vos push /tmp/take --label "$TAG launch" --yes --json       # VOS_API_KEY as a r
 ## For scripts and agents
 
 - **Output.** Logs on stderr, results on stdout. `--json` turns every verb into NDJSON events ending with `{"event":"done",…}`.
+- **`vos <verb> --help`** prints that verb's usage lines and exits 0 (it used to be a usage error).
 - **Exit codes.** 0 ok, 1 error, 2 usage (including `--strict` failures), 3 no browser found, 4 the recorder met a wall (a sign-in, or under `--strict` a redirect away from the asked page) and nothing was recorded or cleared. `--json` carries the verdict as a `wall` event (`kind`, `level`, `asked`, `landed`, `refused`).
 - **`--strict`** on `record` and `create` (agents: always): a skipped selector, a page that never reaches network idle, or a take that hit `--max-duration` exits 2 and lists `skipped[]` (and `capped`) in the done event. The default is lenient (exit 0, `skipped[]` still reported) for exploratory runs.
 - **`--max-duration <s>`** on `record` and `create` defaults to the hosted recording cap, read live from `GET /api/limits` (2 s, fail-open to 30 min when the origin is unreachable): the capture stops there and the done event says so. Cut the flow rather than raising the cap; the platform refuses a longer take.

package/dist/{chunk-BD4FXBUO.js → chunk-7RMULTDM.js}

@@ -129,6 +129,24 @@ function validateActions(value) {
       }
     }
   }
+  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;
@@ -6687,7 +6705,7 @@ function redirectedAway(asked, landed) {
   if (l.endsWith(a)) return false;
   return true;
 }
-var LADDER = 'Walk the session ladder (mint a session from the test auth the project already has, or pass --storage-state): https://vos.so/llms-full.txt, "Sessions". A take OF this page is --allow-wall.';
+var LADDER = 'This is a missing or expired session, not a script bug. Ways past, cheapest first: mint a session from the test auth the project already has; script the sign-in off camera and save the storage state; or have a person sign in once (npx playwright open --channel chrome --save-storage=<file> <url>). Then pass --storage-state <file>. The ladder: https://vos.so/llms-full.txt, "Sessions". A take OF this page is --allow-wall.';
 function wallVerdict(a) {
   const asked = parse(a.askedUrl);
   const landed = parse(a.landedUrl);
@@ -6758,6 +6776,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;
@@ -6785,7 +6996,14 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     deviceScaleFactor: 1,
     ...opts.storageState ? { storageState: opts.storageState } : {}
   });
+  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()}`);
   });
@@ -6815,6 +7033,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 +7293,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 +7324,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 +7362,8 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     skipped,
     navTimeout,
     wall,
+    exposures: exposureLog.exposures(),
+    masks: exposureLog.masks(masks),
     freezes,
     freezePct,
     capped
@@ -10575,8 +10799,23 @@ 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 takeBrowserArgs(multi) {
   const given = multi["browser-arg"];
   return (given ?? []).filter(Boolean);
@@ -10674,7 +10913,13 @@ 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}`),
+        ...flags["allow-wall"] === true ? ["--allow-wall"] : []
+      ].join(" ");
+      const nextOut = strFlag(flags, "out") ?? "take";
       r.done(
         {
           dryRun: true,
@@ -10682,11 +10927,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 ${outDir} --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 {
@@ -10728,7 +10975,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(
@@ -10747,11 +10994,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 {
@@ -10822,7 +11071,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,
@@ -10866,10 +11115,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 {
@@ -11434,12 +11685,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.`
     );
@@ -11703,6 +11956,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);
@@ -11842,6 +12107,23 @@ async function cmdPull2(argv) {
   );
   return EXIT_OK;
 }
+function verbHelp(verb) {
+  const lines = HELP.split("\n");
+  const out = [];
+  let taking = false;
+  for (const line of lines) {
+    if (/^ {2}vos /.test(line)) taking = line.startsWith(`  vos ${verb} `);
+    else if (taking && !/^ {3,}\S/.test(line)) taking = false;
+    if (taking) out.push(line);
+  }
+  if (out.length === 0) return `vos ${verb}: no such verb here. Run: vos help
+`;
+  return `${out.join("\n")}
+
+The whole reference, with every flag explained: https://vos.so/llms-full.txt
+Exit codes: 0 ok, 1 error, 2 usage or --strict failure, 3 no browser, 4 the recorder met a sign-in instead of the page.
+`;
+}
 async function run(argv) {
   const [cmd, ...rest] = argv;
   try {
@@ -11849,6 +12131,10 @@ async function run(argv) {
       process.stdout.write(HELP);
       return cmd ? EXIT_OK : EXIT_USAGE;
     }
+    if (rest.includes("--help") || rest.includes("-h")) {
+      process.stdout.write(verbHelp(cmd));
+      return EXIT_OK;
+    }
     switch (cmd) {
       case "create":
         return await cmdCreate2(rest);
@@ -11959,6 +12245,7 @@ export {
   MULTI_FLAGS2 as MULTI_FLAGS,
   HELP,
   takeBrowserArgs,
+  verbHelp,
   run
 };
-//# sourceMappingURL=chunk-BD4FXBUO.js.map
+//# sourceMappingURL=chunk-7RMULTDM.js.map