@vosjs/cli 0.37.0 → 0.39.0

package/dist/{chunk-DD6OXVFJ.js → chunk-RECQEBXN.js}

@@ -2,8 +2,10 @@
 import {
   BrowserUnavailableError,
   directoryKind,
-  launchBrowser
-} from "./chunk-NHKHTIDR.js";
+  launchBrowser,
+  noteGivenFlag,
+  trackFlags
+} from "./chunk-FACYY7VV.js";
 
 // src/plugin/run.ts
 import { mkdir as mkdir10, readFile as readFile15, rm as rm5 } from "fs/promises";
@@ -52,7 +54,9 @@ function parseArgs(argv, booleanFlags, multiFlags = /* @__PURE__ */ new Set()) {
     }
     positionals.push(arg);
   }
-  return { positionals, flags, multi };
+  for (const name of Object.keys(flags)) noteGivenFlag(name);
+  for (const name of Object.keys(multi)) noteGivenFlag(name);
+  return { positionals, flags: trackFlags(flags), multi: trackFlags(multi) };
 }
 function numFlag(flags, name, fallback) {
   const v = flags[name];
@@ -943,6 +947,17 @@ function lintDoc(docIn) {
   }
   const TRANSITIONS = ["none", "fade", "rise"];
   const PRESETS = ["title", "caption", "label"];
+  let footageEnd = null;
+  if (recording && Array.isArray(doc.segments)) {
+    try {
+      footageEnd = ratedSegments(doc).reduce(
+        (a, s) => a + (s.out - s.in) / (s.rate ?? 1),
+        0
+      );
+    } catch {
+      footageEnd = null;
+    }
+  }
   for (let i = 0; i < (overlays?.length ?? 0); i++) {
     const o = overlays[i];
     const name = `overlays[${i}]`;
@@ -960,6 +975,14 @@ function lintDoc(docIn) {
     if (!isNum(o.duration) || o.duration <= 0) {
       problems.push(`${name}.duration must be > 0 (seconds)`);
     }
+    if (footageEnd !== null && footageEnd > 0 && isNum(o.start) && isNum(o.duration)) {
+      const over = o.start + o.duration - footageEnd;
+      if (over > 0.05) {
+        warnings.push(
+          o.start >= footageEnd ? `${name} starts at ${o.start.toFixed(2)}s, after the footage ends (${footageEnd.toFixed(2)}s): it plays on bare backdrop and lengthens the output by ${over.toFixed(2)}s. A trim moves the footage, never an OUTPUT-anchored layer: re-place it (vos callout with the same --id), or put a freeze under it` : `${name} ends ${over.toFixed(2)}s after the footage (${footageEnd.toFixed(2)}s): the output extends over bare backdrop. Shorten it, or put a freeze under it`
+        );
+      }
+    }
     checkPin(o, name, docIn, recording, problems, warnings);
     if (o.kind === "text") {
       if (typeof o.text !== "string")
@@ -1635,7 +1658,7 @@ function framingWarnings(docIn, doc, zoom, overlays, warnings) {
       if (pinned) {
         if (pinned.clamped > 4) {
           warnings.push(
-            `overlays[${i}] is pinned ${pinned.side} of its referent but the frame has no room there \u2014 it sits ${Math.round(pinned.clamped)} design px off; a smaller box, another side, or a lower zoom level keeps it beside what it names`
+            `overlays[${i}] is pinned ${pinned.side} of its referent but the frame has no room there \u2014 it sits ${Math.round(pinned.clamped)} design px off; a smaller box, another side, or a lower zoom level keeps it beside what it names. A pin resolves THROUGH the camera, so author the zoom first: a callout composed before it is measured against a frame the viewer never sees`
           );
         }
         return;
@@ -1798,7 +1821,7 @@ import { pipeline } from "stream/promises";
 
 // src/plugin/take.ts
 import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
-import { existsSync } from "fs";
+import { existsSync, readdirSync, statSync } from "fs";
 import { basename, join } from "path";
 var RECORDING_NAME = "recording.webm";
 function takeMediaFiles(dir, stem) {
@@ -1829,6 +1852,20 @@ async function ensureTakeDir(dir) {
   await mkdir(p.framesDir, { recursive: true });
   return p;
 }
+async function dropScreencastFrames(p) {
+  if (!existsSync(p.recording) || statSync(p.recording).size === 0) return 0;
+  if (!existsSync(p.framesDir)) return 0;
+  let freed = 0;
+  for (const name of readdirSync(p.framesDir)) {
+    try {
+      freed += statSync(join(p.framesDir, name)).size;
+    } catch {
+    }
+  }
+  await rm(p.framesDir, { recursive: true, force: true });
+  await rm(p.framesIndex, { force: true });
+  return freed;
+}
 async function prepareReRecord(dir) {
   const p = takePaths(dir);
   const kept = [];
@@ -2154,7 +2191,7 @@ import {
 
 // src/plugin/server.ts
 import { createServer } from "http";
-import { existsSync as existsSync3, readFileSync, statSync } from "fs";
+import { existsSync as existsSync3, readFileSync, statSync as statSync2 } from "fs";
 import { writeFile as writeFile3 } from "fs/promises";
 import { extname, join as join3 } from "path";
 var MIME = {
@@ -2203,8 +2240,8 @@ function startTakeServer(rootDir, pages) {
       return;
     }
     const file = join3(rootDir, decodeURIComponent(url.pathname));
-    if (existsSync3(file) && statSync(file).isFile()) {
-      const size = statSync(file).size;
+    if (existsSync3(file) && statSync2(file).isFile()) {
+      const size = statSync2(file).size;
       const buf = readFileSync(file);
       const type = sniffMediaType(buf.subarray(0, MEDIA_HEAD_BYTES)) ?? MIME[extname(file)] ?? "application/octet-stream";
       const range = req.headers.range;
@@ -5659,6 +5696,19 @@ function winRate(verdicts) {
   };
 }
 
+// src/plugin/fontName.ts
+import { findFontFamily as findFontFamily2 } from "@vosjs/shared";
+function catalogFamily(family) {
+  const name = family.trim();
+  if (findFontFamily2(name)) return name;
+  const base = name.replace(/\s+Variable$/i, "");
+  if (base !== name) {
+    const hit = findFontFamily2(base);
+    if (hit) return hit.family;
+  }
+  return family;
+}
+
 // src/plugin/callout.ts
 import { existsSync as existsSync10 } from "fs";
 import { readFile as readFile9 } from "fs/promises";
@@ -5668,6 +5718,7 @@ import {
   CALLOUT_DEFAULT_BODY_PX,
   CALLOUT_SHAPES,
   calloutClip,
+  calloutLook,
   calloutGroundOf,
   cameraModel as cameraModel2,
   deltaE,
@@ -5686,10 +5737,11 @@ var CALLOUT_DELTA_E_PROBLEM = 8;
 var CALLOUT_DELTA_E_WARNING = 16;
 function registerFrom(roles, flags) {
   const ground = flags.ground ?? roles?.bgA;
-  const accent = flags.accent ?? roles?.accent;
+  const accent = flags.accent ?? roles?.callout ?? roles?.accent;
   if (!ground || !accent) return null;
   if (!hexToRgb(ground) || !hexToRgb(accent)) return null;
-  const face = flags.face ?? roles?.fontBody;
+  const named = flags.face ?? roles?.fontBody;
+  const face = named ? catalogFamily(named) : named;
   return {
     ground,
     accent,
@@ -5755,16 +5807,28 @@ function composeCallout(doc, register, ask) {
   let n = 2;
   while (taken.has(id) && !ask.id)
     id = `${ask.shape}-${ask.step ?? Math.round(window2.start * 10)}-${n++}`;
+  const seen = appScaleAt(doc, window2.start + 0.35);
+  const scale = ask.bodyPxGiven ? 1 : seen;
+  const look = calloutLook(register, scale);
   const clip = calloutClip(ask.shape, register, ask.words, {
     id,
     start: window2.start,
     duration: window2.duration,
-    scale: appScaleAt(doc, window2.start + 0.35),
+    scale,
     pin,
     // The fallback place, in the margin: the lower third.
     at: { x: 0.5, y: 0.82 }
   });
-  return { clip, window: window2 };
+  return {
+    clip,
+    window: window2,
+    sizes: {
+      scale: +seen.toFixed(3),
+      kickerPx: look.kickerPx,
+      titlePx: look.titlePx,
+      bodyPx: look.bodyPx
+    }
+  };
 }
 function isCalloutShape(s) {
   return CALLOUT_SHAPES.includes(s);
@@ -6565,7 +6629,8 @@ function paceLine(r) {
 }
 
 // src/plugin/recorder.ts
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var DRY_PAUSE_MS = 120;
 function jpegDims(buf) {
   let i = 2;
   while (i < buf.length - 9) {
@@ -6580,12 +6645,15 @@ function jpegDims(buf) {
   return null;
 }
 async function recordTake(browser, url, actions, paths, log, opts = {}) {
-  const maxSeconds = opts.maxDurationSeconds ?? Infinity;
+  const dry = opts.dryRun === true;
+  const sleep = dry ? (ms) => realSleep(Math.min(ms, DRY_PAUSE_MS)) : realSleep;
+  const maxSeconds = dry ? Infinity : opts.maxDurationSeconds ?? Infinity;
   const vw = actions.viewport?.width ?? 1280;
   const vh = actions.viewport?.height ?? 720;
   const context = await browser.newContext({
     viewport: { width: vw, height: vh },
-    deviceScaleFactor: 1
+    deviceScaleFactor: 1,
+    ...opts.storageState ? { storageState: opts.storageState } : {}
   });
   const page = await context.newPage();
   page.on("console", (m) => {
@@ -6602,22 +6670,24 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const frames = [];
   let frameIdx = 0;
   let t0 = 0;
-  cdp.on("Page.screencastFrame", (ev) => {
-    const tsMs = ev.metadata.timestamp ? ev.metadata.timestamp * 1e3 : Date.now();
-    const file = `frame-${String(frameIdx++).padStart(5, "0")}.jpg`;
-    writeFileSync2(join13(paths.framesDir, file), Buffer.from(ev.data, "base64"));
-    frames.push({ file, tMs: Math.max(0, Math.round(tsMs - t0)) });
-    cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {
+  if (!dry)
+    cdp.on("Page.screencastFrame", (ev) => {
+      const tsMs = ev.metadata.timestamp ? ev.metadata.timestamp * 1e3 : Date.now();
+      const file = `frame-${String(frameIdx++).padStart(5, "0")}.jpg`;
+      writeFileSync2(join13(paths.framesDir, file), Buffer.from(ev.data, "base64"));
+      frames.push({ file, tMs: Math.max(0, Math.round(tsMs - t0)) });
+      cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {
+      });
     });
-  });
   t0 = Date.now();
-  await cdp.send("Page.startScreencast", {
-    format: "jpeg",
-    quality: 90,
-    maxWidth: vw,
-    maxHeight: vh,
-    everyNthFrame: 1
-  });
+  if (!dry)
+    await cdp.send("Page.startScreencast", {
+      format: "jpeg",
+      quality: 90,
+      maxWidth: vw,
+      maxHeight: vh,
+      everyNthFrame: 1
+    });
   const events = [];
   const cur = { x: 48, y: 48 };
   const now = () => Date.now() - t0;
@@ -6629,7 +6699,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     const dist = Math.hypot(tx - cur.x, ty - cur.y);
     const from = { ...cur };
     await clockMotion(
-      pointerTravelMs(dist),
+      dry ? 0 : pointerTravelMs(dist),
       async (u) => {
         cur.x = from.x + (tx - from.x) * u;
         cur.y = from.y + (ty - from.y) * u;
@@ -6904,12 +6974,14 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       `   WARNING: ${freezePct}% of the take is visually frozen (${freezes.length} freezes, longest ${Math.max(...freezes.map((f) => f.ms))}ms) \u2014 keep motion in frame or trim these spans in doc.json`
     );
   }
-  await writeJson(paths.cursor, events);
-  await writeJson(paths.meta, meta, true);
-  await writeJson(paths.framesIndex, frames);
-  await writeJson(paths.actions, { ...actions, url }, true);
   const pace = paceReport(paces);
-  log(`   ${paceLine(pace)}`);
+  if (!dry) {
+    await writeJson(paths.cursor, events);
+    await writeJson(paths.meta, meta, true);
+    await writeJson(paths.framesIndex, frames);
+    await writeJson(paths.actions, { ...actions, url }, true);
+    log(`   ${paceLine(pace)}`);
+  }
   return {
     events,
     frames,
@@ -7890,6 +7962,15 @@ function printChanges(r, changes, protectedIds) {
     r.event({ event: "protected", nodes: protectedIds });
   }
 }
+function takePushRefusal(ask) {
+  if (ask.programOnly.length) {
+    const list = ask.programOnly.map((f) => `--${f}`).join(", ");
+    return `${list} ${ask.programOnly.length > 1 ? "belong" : "belongs"} to a PROGRAM push (a config.json); a take push reads --vos, --title, --label, --note, --folder, --override and --yes`;
+  }
+  if (ask.vos !== void 0 && ask.trackedVosId !== null && ask.trackedVosId !== ask.vos)
+    return `this take tracks vos ${ask.trackedVosId} (its vos.json), not ${ask.vos}. Drop --vos to push there, or remove vos.json to adopt ${ask.vos} instead`;
+  return null;
+}
 async function pushTake(dir, flags, r) {
   const take = await loadTake(dir);
   if (!take.doc) {
@@ -7906,7 +7987,22 @@ async function pushTake(dir, flags, r) {
     );
   }
   const ctx = apiContext(flags);
-  const state = readSyncState(dir);
+  const tracked = readSyncState(dir);
+  const firstPush = tracked === null;
+  let state = tracked;
+  if (!state && flags.vos) {
+    const meta = await api(ctx, `/vos/${flags.vos}`);
+    const head = meta.json.vos?.currentVersionId;
+    if (meta.status !== 200 || !head) {
+      throw new Error(
+        `--vos ${flags.vos}: cannot adopt it (${meta.status}${meta.json.error ? `: ${String(meta.json.error)}` : ""}) \u2014 it must be a vos this credential can read, with a version to build on`
+      );
+    }
+    r.log(
+      `adopting vos ${flags.vos}: this take becomes the next version after its head (${head})`
+    );
+    state = { vosId: flags.vos, versionId: head };
+  }
   let folderId;
   if (flags.folder) {
     if (state) {
@@ -7919,7 +8015,7 @@ async function pushTake(dir, flags, r) {
       flags.folder
     ).id;
   }
-  if (!state && !flags.yes) {
+  if (firstPush && !flags.yes) {
     if (!process.stdin.isTTY) {
       throw new Error(
         "first push of this take uploads its recording \u2014 pass --yes to consent headlessly"
@@ -8256,12 +8352,12 @@ async function browserLogin(origin, r, opts) {
   r.log(`Sign in at ${verifyUrl}`);
   if (opts.openBrowser) void launchDefaultBrowser(verifyUrl);
   r.log("Waiting for approval\u2026 (Ctrl-C to cancel)");
-  const sleep2 = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
+  const sleep = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
   let intervalMs = baseIntervalMs;
   let failures = 0;
   let capNoted = false;
   while (Date.now() < expiresAt) {
-    await sleep2(intervalMs);
+    await sleep(intervalMs);
     let res;
     try {
       res = await apiJson(origin, "/api/cli/login/poll", {
@@ -9311,10 +9407,12 @@ function composeBrand(input) {
   const bgC = mixHex(bgA, accent, 0.14);
   p.bgC = `bgA tinted 14% toward the accent (a highlight ground)`;
   p.ink = w.h1 ? `the h1's colour` : `the body's colour`;
-  const fontDisplay = design?.fonts[0] ?? (w.h1 ? firstFamily(w.h1.fontFamily) : firstFamily(w.body.fontFamily));
+  const fontDisplay = catalogFamily(
+    design?.fonts[0] ?? (w.h1 ? firstFamily(w.h1.fontFamily) : firstFamily(w.body.fontFamily))
+  );
   p.fontDisplay = design?.fonts[0] ? `named in design.md` : w.h1 ? `the h1's computed face` : `the body's computed face (no h1)`;
   const designBody = design?.fonts.slice(1).find((f) => !/\bmono\b/i.test(f));
-  const fontBody = designBody ?? firstFamily(w.body.fontFamily);
+  const fontBody = catalogFamily(designBody ?? firstFamily(w.body.fontFamily));
   p.fontBody = designBody ? `named in design.md` : `the body's computed face`;
   const isIcon = (u) => /favicon|apple-touch|icon/i.test(u);
   const onDark = (u) => /on-dark|white/i.test(u);
@@ -10016,14 +10114,16 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "composed",
   "check",
   "motion",
-  "leader"
+  "leader",
+  "keep-frames",
+  "dry-run"
 ]);
-var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override"]);
+var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg"]);
 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] [--max-duration <s>] [--background <slug|url|none>] [render flags] [--json]
-  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--max-duration <s>] [--background <slug|url|none>] [--json]
+  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--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] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--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]
@@ -10031,7 +10131,7 @@ Take pipeline
   vos digest <take> [--out dir] [--full 960] [--crop 640] [--no-frames] [--transcript <file.json>] [--style <doc.json|vosId>] [--json]
   vos brand <url> [--out BRAND.md] [--json]
   vos open <take> [--studio <url>] [--print]
-  vos callout <take> <note|tag|code> --step <id> [--title "\u2026"] [--body "\u2026"] [--kicker "\u2026"] [--code "\u2026"|--code-file f] [--seconds 3] [--side auto|right|left|below|above] [--mark ring|underline|none] [--leader] [--color #hex] [--brand BRAND.md] [--ground #hex] [--accent #hex] [--font "\u2026"] [--body-px 14] [--id x] [--print] [--json]
+  vos callout <take> <note|tag|code> --step <id> [--title "\u2026"] [--body "\u2026"] [--kicker "\u2026"] [--code "\u2026"|--code-file f] [--seconds 3] [--side auto|right|left|below|above] [--mark ring|underline|none] [--leader] [--color #hex (the mark and leader; the kicker is --accent)] [--brand BRAND.md] [--ground #hex] [--accent #hex] [--font "\u2026"] [--body-px <n> (the body size on the delivered frame)] [--id x] [--print] [--json]
   vos validate <actions.json|take|kit.json> [--picture] [--json]
   vos judge <kit.json> --against <MANIFEST.json> [--out dir] [--json]
   vos actions from-agent-browser <steps.jsonl> [--out actions.json] [--url <url>] [--viewport WxH] [--json]
@@ -10051,7 +10151,10 @@ Platform (vos.so) \u2014 fetch, edit, push, pull, repeat
             a take DIRECTORY (doc.json) pushes recording + doc; a config.json
             pushes the program. No --vos: create a PRIVATE vos; with --vos:
             add a version against the tracked base \u2014 a stale push 409s WITH
-            the platform's typed changelog. --claimable (programs only, NO
+            the platform's typed changelog. A TAKE pushes to the vos in its
+            vos.json; --vos on a take with none ADOPTS that vos (the take
+            becomes its next version, built on its head), and --vos that
+            disagrees with vos.json is refused before anything uploads. --claimable (programs only, NO
             credential): creates a 72h claim link instead \u2014 hand it to the
             user and nowhere else; unclaimed work is deleted after 72h.
             --override consents to touching
@@ -10298,6 +10401,18 @@ function strictReason(rec) {
   if (rec.capped) parts.push("stopped at --max-duration");
   return parts.join(" + ");
 }
+function takeBrowserArgs(multi) {
+  const given = multi["browser-arg"];
+  return (given ?? []).filter(Boolean);
+}
+function takeStorageState(flags) {
+  const raw = strFlag(flags, "storage-state");
+  if (!raw) return void 0;
+  const path = resolve9(raw);
+  if (!existsSync15(path))
+    throw new UsageError(`--storage-state: no such file: ${path}`);
+  return path;
+}
 async function takeBackdrop(flags, r) {
   const { backdrop, note } = await openingBackdrop(
     strFlag(flags, "background"),
@@ -10309,8 +10424,20 @@ async function takeBackdrop(flags, r) {
   if (note) r.log(`note: ${note}`);
   return backdrop;
 }
+async function releaseFrames(paths, flags, log) {
+  if (flags["keep-frames"] === true) return;
+  const freed = await dropScreencastFrames(paths);
+  if (freed >= 1e6)
+    log(
+      `released ${Math.round(freed / 1e6)} MB of screencast frames (the recording holds them now; --keep-frames keeps them)`
+    );
+}
 async function cmdRecord(argv) {
-  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS5);
+  const { positionals, flags, multi } = parseArgs(
+    argv,
+    BOOLEAN_FLAGS5,
+    MULTI_FLAGS2
+  );
   const actionsPath = strFlag(flags, "actions") ?? positionals[0];
   if (!actionsPath)
     throw new UsageError(
@@ -10324,6 +10451,49 @@ async function cmdRecord(argv) {
   const outDir = resolve9(strFlag(flags, "out") ?? "take");
   const backdrop = await takeBackdrop(flags, r);
   const maxDurationSeconds = await maxDuration(flags, r);
+  const storageState = takeStorageState(flags);
+  const browserArgs = takeBrowserArgs(multi);
+  if (flags["dry-run"] === true) {
+    void flags.strict;
+    void flags["keep-frames"];
+    const browser2 = await launchBrowser(browserArgs);
+    try {
+      r.log("rehearsing (nothing is captured or written)\u2026");
+      r.event({ event: "phase", phase: "rehearse" });
+      const started = Date.now();
+      const rec = await recordTake(
+        browser2,
+        url,
+        actions,
+        takePaths(outDir),
+        r.log,
+        { storageState, dryRun: true }
+      );
+      const steps = rec.meta.steps ?? [];
+      const lines = steps.map((s) => {
+        const rect = s.rect ? `  rect ${s.rect.x},${s.rect.y} ${s.rect.w}\xD7${s.rect.h}` : "";
+        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;
+      r.done(
+        {
+          dryRun: true,
+          ok: !failed2,
+          seconds: +((Date.now() - started) / 1e3).toFixed(1),
+          steps,
+          skipped: rec.skipped,
+          navTimeout: rec.navTimeout
+        },
+        `${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`}`
+      );
+      return failed2 ? EXIT_USAGE : EXIT_OK;
+    } finally {
+      await browser2.close();
+    }
+  }
   if (existsSync15(join18(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
@@ -10332,12 +10502,13 @@ async function cmdRecord(argv) {
   }
   await mkdir10(outDir, { recursive: true });
   const paths = await ensureTakeDir(outDir);
-  const browser = await launchBrowser();
+  const browser = await launchBrowser(browserArgs);
   try {
     r.log("recording\u2026");
     r.event({ event: "phase", phase: "record" });
     const rec = await recordTake(browser, url, actions, paths, r.log, {
-      maxDurationSeconds
+      maxDurationSeconds,
+      storageState
     });
     r.event({ event: "phase", phase: "encode" });
     r.log("encoding\u2026");
@@ -10346,6 +10517,7 @@ async function cmdRecord(argv) {
       outDir,
       (p) => r.event({ event: "progress", phase: "encode", fraction: p })
     );
+    await releaseFrames(paths, flags, r.log);
     r.event({ event: "phase", phase: "plan" });
     const plan = await planTake(outDir, { backdrop });
     const clicks = rec.events.filter((e) => e.type === "down").length;
@@ -10408,6 +10580,8 @@ async function cmdCreate2(argv) {
   }
   const backdrop = await takeBackdrop(flags, r);
   const maxDurationSeconds = await maxDuration(flags, r);
+  const storageState = takeStorageState(flags);
+  const browserArgs = takeBrowserArgs(multi);
   if (existsSync15(join18(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
@@ -10416,12 +10590,13 @@ async function cmdCreate2(argv) {
   }
   await mkdir10(outDir, { recursive: true });
   const paths = await ensureTakeDir(outDir);
-  const browser = await launchBrowser();
+  const browser = await launchBrowser(browserArgs);
   try {
     r.log("recording\u2026");
     r.event({ event: "phase", phase: "record" });
     const rec = await recordTake(browser, url, actions, paths, r.log, {
-      maxDurationSeconds
+      maxDurationSeconds,
+      storageState
     });
     r.event({ event: "phase", phase: "encode" });
     r.log("encoding\u2026");
@@ -10430,6 +10605,7 @@ async function cmdCreate2(argv) {
       outDir,
       (p) => r.event({ event: "progress", phase: "encode", fraction: p })
     );
+    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)) {
@@ -11129,7 +11305,7 @@ async function cmdCallout(argv) {
   const shape = positionals[1];
   if (!dir || !shape || !isCalloutShape(shape))
     throw new UsageError(
-      'vos callout <take> <note|tag|code> --step <id> [--title "\u2026"] [--body "\u2026"] [--kicker "\u2026"] [--code "\u2026"|--code-file f] [--seconds 3] [--side \u2026] [--mark ring|underline|none] [--leader] [--color #hex] [--brand BRAND.md] [--ground #hex --accent #hex] [--font "\u2026"] [--body-px 14] [--id x] [--print] [--json]'
+      'vos callout <take> <note|tag|code> --step <id> [--title "\u2026"] [--body "\u2026"] [--kicker "\u2026"] [--code "\u2026"|--code-file f] [--seconds 3] [--side \u2026] [--mark ring|underline|none] [--leader] [--color #hex (the mark and leader; the kicker is --accent)] [--brand BRAND.md] [--ground #hex --accent #hex] [--font "\u2026"] [--body-px <n> (the body size on the delivered frame)] [--id x] [--print] [--json]'
     );
   const r = createReporter(flags.json === true);
   const take = await loadTake(dir);
@@ -11180,15 +11356,16 @@ async function cmdCallout(argv) {
       side,
       mark,
       leader: flags.leader === true,
-      color: strFlag(flags, "color")
+      color: strFlag(flags, "color"),
+      bodyPxGiven: bodyPx !== void 0
     });
   } catch (e) {
     throw new UsageError(e instanceof Error ? e.message : String(e));
   }
-  const { clip, window: window2 } = composed;
+  const { clip, window: window2, sizes } = composed;
   if (flags.print === true) {
     r.done(
-      { clip, window: window2, register, brand: brand?.file ?? null },
+      { clip, window: window2, sizes, register, brand: brand?.file ?? null },
       JSON.stringify(clip, null, 2)
     );
     return EXIT_OK;
@@ -11210,11 +11387,12 @@ async function cmdCallout(argv) {
     {
       clip,
       window: window2,
+      sizes,
       register,
       brand: brand?.file ?? null,
       warnings: lint.warnings
     },
-    `${shape} "${clip.id}" at ${window2.start.toFixed(2)}s for ${window2.duration.toFixed(2)}s${clip.pin ? `, pinned to ${clip.pin.step !== void 0 ? `step ${String(clip.pin.step)}` : `the press at ${String(clip.pin.press)}s`}` : ""}, ground ${register.ground} \u2192 card in the product's hue, written to ${take.paths.doc}${lint.warnings.length ? `
+    `${shape} "${clip.id}" at ${window2.start.toFixed(2)}s for ${window2.duration.toFixed(2)}s${clip.pin ? `, pinned to ${clip.pin.step !== void 0 ? `step ${String(clip.pin.step)}` : `the press at ${String(clip.pin.press)}s`}` : ""}, ground ${register.ground} \u2192 card in the product's hue, type ${sizes.kickerPx} / ${sizes.titlePx} / ${sizes.bodyPx} px (kicker / title / body; ${bodyPx !== void 0 ? `--body-px ${bodyPx} as delivered` : `the app's body as seen, footage scale ${sizes.scale}; --body-px <n> sets the delivered size`}), written to ${take.paths.doc}${lint.warnings.length ? `
   warnings:
   ${lint.warnings.join("\n  ")}` : ""}`
   );
@@ -11377,8 +11555,16 @@ async function cmdPush3(argv) {
   const dir = positionals[0];
   if (!dir)
     throw new UsageError(
-      "vos push <take> [--title|--label|--note|--folder|--override|--yes|--key|--api]"
+      "vos push <take> [--vos|--title|--label|--note|--folder|--override|--yes|--key|--api]"
     );
+  const refusal = takePushRefusal({
+    vos: strFlag(flags, "vos"),
+    trackedVosId: readSyncState(resolve9(dir))?.vosId ?? null,
+    programOnly: ["slug", "desc", "tags", "base", "remix-of"].filter(
+      (name) => hasFlag(flags, name)
+    )
+  });
+  if (refusal) throw new UsageError(refusal);
   const r = createReporter(flags.json === true);
   const overrides = multi.override;
   const result = await pushTake(
@@ -11388,6 +11574,7 @@ async function cmdPush3(argv) {
       api: strFlag(flags, "api"),
       origin: strFlag(flags, "origin"),
       yes: flags.yes === true,
+      vos: strFlag(flags, "vos"),
       title: strFlag(flags, "title"),
       label: strFlag(flags, "label"),
       note: strFlag(flags, "note"),
@@ -11548,6 +11735,9 @@ export {
   parseAgentBrowserLog,
   splitCommand,
   convertAgentBrowser,
+  MULTI_FLAGS2 as MULTI_FLAGS,
+  HELP,
+  takeBrowserArgs,
   run
 };
-//# sourceMappingURL=chunk-DD6OXVFJ.js.map
+//# sourceMappingURL=chunk-RECQEBXN.js.map