@vosjs/cli 0.31.1 → 0.33.0

package/dist/{chunk-APVJ4MDJ.js → chunk-6O55OD6D.js}

@@ -6,9 +6,9 @@ import {
 } from "./chunk-NHKHTIDR.js";
 
 // src/plugin/run.ts
-import { mkdir as mkdir9, readFile as readFile14, rm as rm4 } from "fs/promises";
-import { existsSync as existsSync14 } from "fs";
-import { join as join17, resolve as resolve9 } from "path";
+import { mkdir as mkdir9, readFile as readFile15, rm as rm4 } from "fs/promises";
+import { existsSync as existsSync15 } from "fs";
+import { join as join18, resolve as resolve9 } from "path";
 import {
   END_CARD_FROM as END_CARD_FROM2,
   docOutputDuration as docOutputDuration3,
@@ -210,9 +210,16 @@ import {
   ZOOM_LEVEL_MIN,
   ZOOM_SPAN_MIN,
   docCardLayout,
+  docZoomTrack,
+  findStep,
   outputEnd,
+  pinBox,
+  pinCandidates,
+  pinRectOnScreen,
+  pinReferent,
   ratedSegments,
   recommendedExportResolution,
+  resolvePins,
   spanOutputExtent,
   zoomCoversRect,
   cameraModel
@@ -944,6 +951,7 @@ function lintDoc(docIn) {
     if (!isNum(o.duration) || o.duration <= 0) {
       problems.push(`${name}.duration must be > 0 (seconds)`);
     }
+    checkPin(o, name, docIn, recording, problems, warnings);
     if (o.kind === "text") {
       if (typeof o.text !== "string")
         problems.push(`${name}.text must be a string`);
@@ -1455,6 +1463,106 @@ function clicksWithRects(source) {
   }
   return out;
 }
+var PIN_SIDES = ["auto", "right", "left", "below", "above"];
+var PIN_MARKS = ["none", "ring", "underline"];
+function checkPin(o, name, docIn, recording, problems, warnings) {
+  if (o.pin === void 0) return;
+  if (!isObj(o.pin)) {
+    problems.push(
+      `${name}.pin must be { step | press | rect, side?, gap?, mark?, leader?, color? }`
+    );
+    return;
+  }
+  const p = o.pin;
+  const named = ["step", "press", "rect"].filter((k) => p[k] !== void 0);
+  if (named.length !== 1) {
+    problems.push(
+      `${name}.pin names its referent by exactly one of step (a recorder step id or index), press (a source second) or rect (video fractions)${named.length ? ` \u2014 got ${named.join(" and ")}` : ""}`
+    );
+    return;
+  }
+  if (p.step !== void 0 && typeof p.step !== "string" && !(isNum(p.step) && Number.isInteger(p.step) && p.step >= 0)) {
+    problems.push(
+      `${name}.pin.step must be a step id (string) or index (integer \u2265 0)`
+    );
+  }
+  if (p.press !== void 0 && !isNum(p.press))
+    problems.push(`${name}.pin.press must be a source second (number)`);
+  if (p.rect !== void 0) {
+    const r = isObj(p.rect) ? p.rect : null;
+    if (!r || !isNum(r.x) || !isNum(r.y) || !isNum(r.w) || !isNum(r.h)) {
+      problems.push(`${name}.pin.rect must be { x, y, w, h }`);
+    } else if (Math.abs(r.x) > 2 || Math.abs(r.y) > 2 || r.w > 2 || r.h > 2) {
+      problems.push(
+        `${name}.pin.rect looks like PIXELS (${String(r.x)}, ${String(r.y)}, ${String(r.w)}\xD7${String(r.h)}) \u2014 it is FRACTIONS of the video frame [0..1] (the zoom cx/cy convention)`
+      );
+    } else if (r.w <= 0 || r.h <= 0) {
+      problems.push(`${name}.pin.rect must have w > 0 and h > 0`);
+    }
+  }
+  if (p.side !== void 0 && !PIN_SIDES.includes(p.side))
+    problems.push(`${name}.pin.side must be one of ${PIN_SIDES.join(" | ")}`);
+  if (p.gap !== void 0 && (!isNum(p.gap) || p.gap < 0))
+    problems.push(`${name}.pin.gap must be design px \u2265 0`);
+  if (p.mark !== void 0 && !PIN_MARKS.includes(p.mark))
+    problems.push(`${name}.pin.mark must be one of ${PIN_MARKS.join(" | ")}`);
+  if (p.leader !== void 0 && typeof p.leader !== "boolean")
+    problems.push(`${name}.pin.leader must be true or false`);
+  if (p.color !== void 0 && typeof p.color !== "string")
+    problems.push(`${name}.pin.color must be a CSS colour string`);
+  if (problems.some((m) => m.startsWith(`${name}.pin`))) return;
+  if (!recording) {
+    problems.push(
+      `${name}.pin names something on a recording's page; a program has no referents \u2014 place the layer with transform`
+    );
+    return;
+  }
+  const doc = docIn;
+  const steps = doc.source.meta.steps ?? [];
+  if (p.step !== void 0) {
+    const step = findStep(steps, p.step);
+    if (!step) {
+      const known = steps.filter((s) => s.selector).map((s) => s.id !== void 0 ? s.id : String(s.step));
+      problems.push(
+        `${name}.pin.step "${String(p.step)}" is not a step of this take${known.length ? ` \u2014 steps with an element: ${known.join(", ")}` : " \u2014 the take has no step timeline (a human recording); pin by press or rect"}`
+      );
+      return;
+    }
+    if (step.skipped) {
+      problems.push(
+        `${name}.pin.step "${String(p.step)}" was skipped at record time (its selector never became visible), so it has no element to point at`
+      );
+      return;
+    }
+  }
+  let ref;
+  try {
+    ref = pinReferent(doc, p);
+  } catch {
+    ref = null;
+  }
+  if (!ref) {
+    problems.push(
+      p.step !== void 0 ? `${name}.pin.step "${String(p.step)}" has no element rect and no press inside its window (a wait, scroll or move step touches nothing) \u2014 pin a hover, click, type or drag step, or a press` : p.press !== void 0 ? `${name}.pin.press ${String(p.press)}s has no press with an element rect within half a second \u2014 the presses are the cursor track's down events` : `${name}.pin.rect could not be read`
+    );
+    return;
+  }
+  if (ref.at !== null && isNum(o.start) && isNum(o.duration)) {
+    const rated = ratedSegments(doc);
+    for (const s of steps) {
+      if (s.tStart <= ref.at) continue;
+      if (s.do !== "scroll" && !s.navigated) continue;
+      const out = spanOutputExtent(rated, s.tStart, s.tEnd);
+      if (!out) continue;
+      if (out.start < o.start + o.duration && out.end > o.start) {
+        warnings.push(
+          `${name} is pinned to something measured at ${ref.at.toFixed(1)}s, but ${s.do === "scroll" ? "a scroll" : "a navigation"} at ${s.tStart.toFixed(1)}s (output ${out.start.toFixed(1)}s) falls inside the layer's window \u2014 the referent may have moved; end the layer before it`
+        );
+        break;
+      }
+    }
+  }
+}
 function framingWarnings(docIn, doc, zoom, overlays, warnings) {
   try {
     const source = isObj(doc.source) ? doc.source : {};
@@ -1496,24 +1604,65 @@ function framingWarnings(docIn, doc, zoom, overlays, warnings) {
       }
     }
     const rated = ratedSegments(docIn);
-    const toFrame = (nx, ny) => ({
-      x: (layout.dx + nx * layout.dw) / layout.W,
-      y: (layout.dy + ny * layout.dh) / layout.H
-    });
+    const camera = cameraModel(docIn.frame);
+    const zoomTrack = docZoomTrack(docIn);
+    const pins = resolvePins(docIn, layout, camera, zoomTrack);
     overlays.forEach((o, i) => {
-      if (!isObj(o) || o.kind !== void 0 && o.kind !== "text") return;
+      if (!isObj(o) || !isNum(o.start) || !isNum(o.duration)) return;
       const tf = isObj(o.transform) ? o.transform : null;
-      if (!tf || !isNum(tf.x) || !isNum(tf.y) || !isNum(o.start) || !isNum(o.duration))
+      if (!tf || !isNum(tf.x) || !isNum(tf.y)) return;
+      const pinned = pins.get(String(o.id));
+      if (!pinned && o.pin === void 0 && (o.kind === "html" || o.kind === "image" || o.kind === "video")) {
+        const cands = pinCandidates(docIn, {
+          start: o.start,
+          duration: o.duration
+        });
+        if (cands.length) {
+          warnings.push(
+            `overlays[${i}] is not pinned, and ${cands.length === 1 ? "a step with an element sits" : "steps with an element sit"} inside its window: ${cands.map((c) => `${String(c.step)} (${c.do}${c.selector ? ` ${c.selector}` : ""})`).join(", ")} \u2014 a callout about one of them says so: pin: { step: "${String(cands[0].step)}" }`
+          );
+        }
+      }
+      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`
+          );
+        }
         return;
+      }
+      let box;
+      try {
+        box = pinBox(o, layout);
+      } catch {
+        return;
+      }
       for (const c of clicks) {
         const out = spanOutputExtent(rated, c.t, c.t + 1e-3);
         if (!out || out.start < o.start || out.start > o.start + o.duration)
           continue;
-        const a = toFrame(c.rect.x / w, c.rect.y / h);
-        const b = toFrame((c.rect.x + c.rect.w) / w, (c.rect.y + c.rect.h) / h);
-        if (tf.x >= a.x && tf.x <= b.x && tf.y >= a.y && tf.y <= b.y) {
+        const target = pinRectOnScreen(
+          {
+            x: c.rect.x / w,
+            y: c.rect.y / h,
+            w: c.rect.w / w,
+            h: c.rect.h / h
+          },
+          out.start,
+          layout,
+          camera,
+          zoomTrack
+        );
+        const L = {
+          x: tf.x * layout.W - box.w / 2,
+          y: tf.y * layout.H - box.h / 2,
+          w: box.w,
+          h: box.h
+        };
+        const overlaps2 = L.x < target.x + target.w && L.x + L.w > target.x && L.y < target.y + target.h && L.y + L.h > target.y;
+        if (overlaps2) {
           warnings.push(
-            `overlays[${i}] sits over the thing being clicked at ${c.t.toFixed(1)}s (output ${out.start.toFixed(1)}s) \u2014 move it off the target`
+            `overlays[${i}] sits over the thing being clicked at ${c.t.toFixed(1)}s (output ${out.start.toFixed(1)}s) \u2014 pin it to that step (pin: { step }) so it sits beside the target and follows it, or move it off`
           );
           break;
         }
@@ -5157,10 +5306,208 @@ function winRate(verdicts) {
   return { wins, ties, judged, rate: judged ? (wins + ties / 2) / judged : null };
 }
 
+// src/plugin/callout.ts
+import { existsSync as existsSync9 } from "fs";
+import { readFile as readFile9 } from "fs/promises";
+import { join as join10 } from "path";
+import { lerpArray, sample } from "@vosjs/timeline";
+import {
+  CALLOUT_DEFAULT_BODY_PX,
+  CALLOUT_SHAPES,
+  calloutClip,
+  calloutGroundOf,
+  cameraModel as cameraModel2,
+  deltaE,
+  docCardLayout as docCardLayout2,
+  docZoomTrack as docZoomTrack2,
+  hexToRgb,
+  parseCssColour,
+  pinBox as pinBox2,
+  ratedSegments as ratedSegments5,
+  resolvePins as resolvePins2,
+  spanOutputExtent as spanOutputExtent5
+} from "@vosjs/studio-core";
+var CALLOUT_DEFAULT_SECONDS = 3;
+var CALLOUT_LEAD_SECONDS = 0.2;
+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;
+  if (!ground || !accent) return null;
+  if (!hexToRgb(ground) || !hexToRgb(accent)) return null;
+  const face = flags.face ?? roles?.fontBody;
+  return {
+    ground,
+    accent,
+    ...face && !/^ui-sans-serif$|^system-ui$/.test(face) ? { face } : {},
+    ...flags.mono ? { mono: flags.mono } : {},
+    body: flags.body ?? CALLOUT_DEFAULT_BODY_PX
+  };
+}
+function appScaleAt(doc, t) {
+  const layout = docCardLayout2(doc);
+  const meta = doc.source.meta;
+  const base = layout.dw / Math.max(1, meta.width);
+  const track = docZoomTrack2(doc);
+  if (!track || !track.keyframes.length) return base;
+  const z = sample(track, t, lerpArray);
+  return base * Math.max(1, z[0]);
+}
+function windowForStep(doc, step, seconds = CALLOUT_DEFAULT_SECONDS) {
+  const steps = doc.source.meta.steps ?? [];
+  const s = steps.find((x) => x.id !== void 0 && x.id === step) ?? steps.find((x) => String(x.step) === String(step));
+  if (!s || s.skipped) return null;
+  const rated = ratedSegments5(doc);
+  const ext = spanOutputExtent5(rated, s.tStart, s.tEnd);
+  if (!ext) return null;
+  const at2 = s.do === "click" || s.do === "drag" ? ext.start : ext.end;
+  const start = +(at2 + CALLOUT_LEAD_SECONDS).toFixed(3);
+  let end = start + seconds;
+  for (const n of steps) {
+    if (n.tStart <= s.tStart) continue;
+    if (n.do !== "scroll" && !n.navigated) continue;
+    const ne = spanOutputExtent5(rated, n.tStart, n.tEnd);
+    if (ne && ne.start > start && ne.start < end) end = ne.start - 0.05;
+  }
+  return { start, duration: +Math.max(0.5, end - start).toFixed(3) };
+}
+function composeCallout(doc, register, ask) {
+  let window2 = null;
+  if (ask.step !== void 0) {
+    window2 = windowForStep(doc, ask.step, ask.seconds);
+    if (!window2)
+      throw new Error(
+        `step "${String(ask.step)}" is not in the take's step timeline, was skipped, or falls outside the cut`
+      );
+  } else if (ask.at !== void 0) {
+    window2 = {
+      start: ask.at,
+      duration: ask.seconds ?? CALLOUT_DEFAULT_SECONDS
+    };
+  } else {
+    throw new Error(
+      "name the step the callout is about (--step <id>), or --at <output seconds>"
+    );
+  }
+  const pin = ask.step !== void 0 ? { step: ask.step } : ask.press !== void 0 ? { press: ask.press } : void 0;
+  if (pin) {
+    if (ask.side && ask.side !== "auto") pin.side = ask.side;
+    if (ask.mark && ask.mark !== "none") pin.mark = ask.mark;
+    if (ask.leader) pin.leader = true;
+    if (ask.color) pin.color = ask.color;
+  }
+  const taken = new Set((doc.overlays ?? []).map((o) => o.id));
+  let id = ask.id ?? `${ask.shape}-${ask.step ?? Math.round(window2.start * 10)}`;
+  let n = 2;
+  while (taken.has(id) && !ask.id)
+    id = `${ask.shape}-${ask.step ?? Math.round(window2.start * 10)}-${n++}`;
+  const clip = calloutClip(ask.shape, register, ask.words, {
+    id,
+    start: window2.start,
+    duration: window2.duration,
+    scale: appScaleAt(doc, window2.start + 0.35),
+    pin,
+    // The fallback place, in the margin: the lower third.
+    at: { x: 0.5, y: 0.82 }
+  });
+  return { clip, window: window2 };
+}
+function isCalloutShape(s) {
+  return CALLOUT_SHAPES.includes(s);
+}
+async function groundFindings(doc, frameAt) {
+  const out = [];
+  const overlays = doc.overlays ?? [];
+  const layout = docCardLayout2(doc);
+  const camera = cameraModel2(doc.frame);
+  const track = docZoomTrack2(doc);
+  const pins = resolvePins2(doc, layout, camera, track);
+  for (let i = 0; i < overlays.length; i++) {
+    const o = overlays[i];
+    if (o.kind !== "html") continue;
+    const card = calloutGroundOf(o.css ?? "");
+    if (!card) {
+      out.push({
+        index: i,
+        id: o.id,
+        level: "note",
+        deltaE: null,
+        card: null,
+        footage: null,
+        message: `overlays[${i}] declares no readable background on its root rule \u2014 the ground check cannot read it`
+      });
+      continue;
+    }
+    const t = o.start + Math.min(0.35, o.duration / 2);
+    const img = await frameAt(t);
+    if (!img) {
+      out.push({
+        index: i,
+        id: o.id,
+        level: "note",
+        deltaE: null,
+        card,
+        footage: null,
+        message: `overlays[${i}]: the frame at ${t.toFixed(2)}s could not be read`
+      });
+      continue;
+    }
+    const box = pinBox2(o, layout);
+    const pinned = pins.get(o.id);
+    let cx = o.transform.x * layout.W;
+    let cy = o.transform.y * layout.H;
+    if (pinned) {
+      const v = sample(pinned.track, t - o.start, lerpArray);
+      cx = v[0] * layout.W;
+      cy = v[1] * layout.H;
+    }
+    const sx = img.w / layout.W;
+    const sy = img.h / layout.H;
+    const rect = {
+      x: (cx - box.w / 2) * sx,
+      y: (cy - box.h / 2) * sy,
+      w: box.w * sx,
+      h: box.h * sy
+    };
+    const footage = medianColour(img, rect);
+    const cardRgb = parseCssColour(card);
+    if (!cardRgb) continue;
+    const d = deltaE(cardRgb, footage);
+    const fh = `#${footage.map((c) => c.toString(16).padStart(2, "0")).join("")}`;
+    const level = d < CALLOUT_DELTA_E_PROBLEM ? "problem" : d < CALLOUT_DELTA_E_WARNING ? "warning" : "note";
+    out.push({
+      index: i,
+      id: o.id,
+      level,
+      deltaE: +d.toFixed(1),
+      card,
+      footage: fh,
+      message: level === "note" ? `overlays[${i}] ground ${card} over footage ${fh}: \u0394E ${d.toFixed(1)}, reads as lifted` : `overlays[${i}] ground ${card} is within \u0394E ${d.toFixed(1)} of the footage it covers (${fh}) at ${t.toFixed(2)}s \u2014 it reads as one more panel of the app; invert its value (vos callout does) or move it to the margin`
+    });
+  }
+  return out;
+}
+async function footageFrames(browser, dir, doc, times, framesTake2) {
+  const out = /* @__PURE__ */ new Map();
+  if (!times.length) return out;
+  const bare = { ...doc, overlays: [] };
+  const outDir = join10(dir, ".ground-check");
+  const res = await framesTake2(browser, dir, { times, outDir, doc: bare });
+  for (const f of res.frames) {
+    if (!existsSync9(f.file)) continue;
+    out.set(
+      +f.time.toFixed(3),
+      decodePng(new Uint8Array(await readFile9(f.file)))
+    );
+  }
+  return out;
+}
+
 // src/plugin/kitPicture.ts
 import { execFile } from "child_process";
 import { promisify } from "util";
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 var execFileP = promisify(execFile);
 var SUBJECT_BAND = { min: 0.6, max: 0.92 };
 var BLANK_INK = 0.12;
@@ -5188,7 +5535,7 @@ function apcaContrast(text, bg) {
   return sapc > -0.1 ? 0 : -(sapc + 0.027) * 100;
 }
 var pct = (v) => `${Math.round(v * 100)}%`;
-var hexToRgb = (h) => {
+var hexToRgb2 = (h) => {
   const m = /^#([0-9a-f]{6})$/i.exec(h.trim());
   if (!m) return null;
   const n = parseInt(m[1], 16);
@@ -5337,7 +5684,7 @@ function textFindings(a, img) {
         });
       }
     }
-    const rgb = t.color ? hexToRgb(t.color) : null;
+    const rgb = t.color ? hexToRgb2(t.color) : null;
     if (rgb) {
       const ground = medianColour(img, box);
       const lc = apcaContrast(rgb, ground);
@@ -5436,7 +5783,7 @@ async function pictureChecks(assets) {
   let ffmpeg = null;
   for (const a of assets) {
     if (/\.png$/i.test(a.file)) {
-      const img = decodePng(new Uint8Array(await readFile9(a.file)));
+      const img = decodePng(new Uint8Array(await readFile10(a.file)));
       if (!img) {
         findings.push({
           code: "unreadable",
@@ -5529,9 +5876,9 @@ function formatFinding(f) {
 }
 
 // src/plugin/validateKit.ts
-import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile10, stat as stat2 } from "fs/promises";
-import { dirname as dirname2, isAbsolute as isAbsolute4, join as join10 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { readFile as readFile11, stat as stat2 } from "fs/promises";
+import { dirname as dirname2, isAbsolute as isAbsolute4, join as join11 } from "path";
 import { DESTINATIONS as DESTINATIONS3 } from "@vosjs/studio-core";
 var PNG_SIG2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 function pngDimensions(bytes) {
@@ -5550,7 +5897,7 @@ async function probeVideo(path) {
   const MB = await import("mediabunny");
   const input = new MB.Input({
     formats: MB.ALL_FORMATS,
-    source: new MB.BufferSource(new Uint8Array(await readFile10(path)))
+    source: new MB.BufferSource(new Uint8Array(await readFile11(path)))
   });
   try {
     const track = await input.getPrimaryVideoTrack();
@@ -5571,7 +5918,7 @@ async function validateKit(kitPath, opts = {}) {
   const measured = [];
   let kit;
   try {
-    kit = JSON.parse(await readFile10(kitPath, "utf8"));
+    kit = JSON.parse(await readFile11(kitPath, "utf8"));
   } catch (e) {
     return {
       valid: false,
@@ -5590,8 +5937,8 @@ async function validateKit(kitPath, opts = {}) {
   }
   const base = dirname2(kitPath);
   const resolvePath = (p) => {
-    if (isAbsolute4(p) && existsSync9(p)) return p;
-    const beside = join10(base, p.split("/").pop() ?? p);
+    if (isAbsolute4(p) && existsSync10(p)) return p;
+    const beside = join11(base, p.split("/").pop() ?? p);
     return beside;
   };
   const perDestination = /* @__PURE__ */ new Map();
@@ -5617,7 +5964,7 @@ async function validateKit(kitPath, opts = {}) {
     let h = null;
     let seconds = null;
     if (/\.(png|jpe?g|webp)$/i.test(file)) {
-      const head = Buffer.from(await readFile10(file));
+      const head = Buffer.from(await readFile11(file));
       const kind = sniffImage(head);
       if (file.toLowerCase().endsWith(".png") && kind !== "png")
         problems.push(
@@ -5727,7 +6074,7 @@ async function validateKit(kitPath, opts = {}) {
 
 // src/plugin/recorder.ts
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 
 // src/plugin/recordingCap.ts
 var HOSTED_RECORDING_CAP_SECONDS = 30 * 60;
@@ -5815,7 +6162,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   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(join11(paths.framesDir, file), Buffer.from(ev.data, "base64"));
+    writeFileSync2(join12(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(() => {
     });
@@ -5894,6 +6241,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     const stepStart = now();
     const skippedBefore = skipped.length;
     const urlBefore = page.url();
+    let stepRect = null;
     switch (step.do) {
       case "wait":
         await sleep(clampWait(step.ms, now(), maxSeconds));
@@ -5903,6 +6251,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
         break;
       case "hover": {
         const rect = await boxOf(step.selector);
+        stepRect = rect;
         if (rect) {
           await moveTo(rect.x + rect.w / 2, rect.y + rect.h / 2);
           log(`hover ${step.selector}`);
@@ -5913,6 +6262,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       }
       case "click": {
         const rect = await boxOf(step.selector);
+        stepRect = rect;
         if (rect) {
           await clickAt(rect);
           log(`click ${step.selector}`);
@@ -5923,6 +6273,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       }
       case "type": {
         const rect = await boxOf(step.selector);
+        stepRect = rect;
         if (rect) {
           if (step.focus !== false) await clickAt(rect);
           const delay = step.delayMs ?? 40;
@@ -5964,6 +6315,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
         let rect;
         if (step.selector) {
           const box = await boxOf(step.selector);
+          stepRect = box;
           if (box) {
             rect = box;
             start = { x: box.x + box.w / 2, y: box.y + box.h / 2 };
@@ -6026,7 +6378,15 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       tStart: +(stepStart / 1e3).toFixed(3),
       tEnd: +(now() / 1e3).toFixed(3),
       ...skipped.length > skippedBefore ? { skipped: true } : {},
-      ...page.url() !== urlBefore ? { navigated: true } : {}
+      ...page.url() !== urlBefore ? { navigated: true } : {},
+      ...stepRect ? {
+        rect: {
+          x: +stepRect.x.toFixed(1),
+          y: +stepRect.y.toFixed(1),
+          w: +stepRect.w.toFixed(1),
+          h: +stepRect.h.toFixed(1)
+        }
+      } : {}
     });
   }
   if (!capped) await sleep(600);
@@ -6040,7 +6400,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   await sleep(200);
   const pageTitle = await page.title().catch(() => "");
   await context.close();
-  const firstFrame = frames[0] ? jpegDims(readFileSync3(join11(paths.framesDir, frames[0].file))) : null;
+  const firstFrame = frames[0] ? jpegDims(readFileSync3(join12(paths.framesDir, frames[0].file))) : null;
   const meta = {
     dpr: 1,
     zoom: 1,
@@ -6148,9 +6508,9 @@ async function encodeRecording(browser, takeDir, onProgress) {
 }
 
 // src/plugin/plan.ts
-import { existsSync as existsSync10 } from "fs";
-import { readFile as readFile11 } from "fs/promises";
-import { join as join12 } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { readFile as readFile12 } from "fs/promises";
+import { join as join13 } from "path";
 import {
   DEFAULT_FRAME_STYLE,
   STYLE_FIELDS,
@@ -6372,10 +6732,10 @@ function retimeCut(prev, newSteps, newDurationMs) {
 // src/plugin/plan.ts
 var overlaps = (a, b) => a.in < b.out && b.in < a.out;
 async function readDigestActivity(dir) {
-  const file = join12(dir, "digest", "digest.json");
-  if (!existsSync10(file)) return null;
+  const file = join13(dir, "digest", "digest.json");
+  if (!existsSync11(file)) return null;
   try {
-    const d = JSON.parse(await readFile11(file, "utf8"));
+    const d = JSON.parse(await readFile12(file, "utf8"));
     return Array.isArray(d.activity) && d.activity.every((v) => typeof v === "number") ? d.activity : null;
   } catch {
     return null;
@@ -6585,17 +6945,17 @@ async function planTake(dir, opts = {}) {
 
 // src/plugin/sync.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync12 } from "fs";
-import { readFile as readFile12 } from "fs/promises";
+import { existsSync as existsSync13 } from "fs";
+import { readFile as readFile13 } from "fs/promises";
 import { createInterface } from "readline/promises";
-import { basename, join as join15 } from "path";
+import { basename, join as join16 } from "path";
 import { lowerToComposition as lowerToComposition3, migrateHostedDoc as migrateHostedDoc3 } from "@vosjs/studio-core";
 
 // src/plugin/media.ts
 import { isKeyedOverlay } from "@vosjs/studio-core";
-import { createWriteStream, existsSync as existsSync11 } from "fs";
+import { createWriteStream, existsSync as existsSync12 } from "fs";
 import { writeFile as writeFile9 } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 var MIC_NAME = "mic.webm";
@@ -6719,8 +7079,8 @@ async function pullMedia(ctx, dir, doc, log) {
     const url = doc.source[key];
     const assetId = assetIdOf(url);
     if (!assetId) continue;
-    const target = join13(dir, file);
-    if (existsSync11(target)) {
+    const target = join14(dir, file);
+    if (existsSync12(target)) {
       result.kept.push(file);
     } else {
       const abs = /^https?:/.test(url) ? url : `${ctx.origin}${url}`;
@@ -6745,8 +7105,8 @@ async function pullMedia(ctx, dir, doc, log) {
   for (const ref of docMediaRefs(doc, (k) => assetIdOf(k) !== null)) {
     const assetId = assetIdOf(ref.key);
     const abs = /^https?:/.test(ref.key) ? ref.key : `${ctx.origin}${ref.key}`;
-    const existing = existsSync11(join13(dir, "media")) ? (await import("fs/promises").then(
-      (fs) => fs.readdir(join13(dir, "media"))
+    const existing = existsSync12(join14(dir, "media")) ? (await import("fs/promises").then(
+      (fs) => fs.readdir(join14(dir, "media"))
     )).find((f) => f.startsWith(`${assetId}.`)) : void 0;
     let file;
     if (existing) {
@@ -6763,9 +7123,9 @@ async function pullMedia(ctx, dir, doc, log) {
       }
       const ext = extensionFor(res.headers.get("content-type") ?? "");
       file = `media/${assetId}${ext}`;
-      const target = join13(dir, file);
+      const target = join14(dir, file);
       await import("fs/promises").then(
-        (fs) => fs.mkdir(join13(dir, "media"), { recursive: true })
+        (fs) => fs.mkdir(join14(dir, "media"), { recursive: true })
       );
       await pipeline(
         Readable.fromWeb(res.body),
@@ -6779,17 +7139,17 @@ async function pullMedia(ctx, dir, doc, log) {
     }
     ref.set(file);
   }
-  const metaPath = join13(dir, "meta.json");
-  if (!existsSync11(metaPath)) await writeJson(metaPath, doc.source.meta, true);
-  const cursorPath = join13(dir, "cursor.json");
-  if (!existsSync11(cursorPath)) await writeJson(cursorPath, doc.source.cursor);
-  await writeFile9(join13(dir, "doc.json"), JSON.stringify(doc, null, 2));
+  const metaPath = join14(dir, "meta.json");
+  if (!existsSync12(metaPath)) await writeJson(metaPath, doc.source.meta, true);
+  const cursorPath = join14(dir, "cursor.json");
+  if (!existsSync12(cursorPath)) await writeJson(cursorPath, doc.source.cursor);
+  await writeFile9(join14(dir, "doc.json"), JSON.stringify(doc, null, 2));
   return result;
 }
 
 // src/plugin/folder.ts
 import { mkdir as mkdir7, writeFile as writeFile10 } from "fs/promises";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 import { recipeHints } from "@vosjs/shared/frontmatter";
 import { migrateHostedDoc as migrateHostedDoc2 } from "@vosjs/studio-core";
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "help", "media"]);
@@ -6965,18 +7325,18 @@ async function cmdPull(argv) {
     throw new Error(apiError(`pull folder ${folder.slug}`, res));
   const payload = res.body;
   const out = strFlag(flags, "out") ?? folder.slug;
-  await mkdir7(join14(out, "recipes"), { recursive: true });
+  await mkdir7(join15(out, "recipes"), { recursive: true });
   const lines = [];
   const recipes = [];
   for (const rec of payload.recipes) {
-    const path = join14(out, "recipes", safeName(rec.filename));
+    const path = join15(out, "recipes", safeName(rec.filename));
     await writeFile10(path, rec.body ?? "");
     recipes.push({ path, line: recipeLine(rec.filename, rec.body ?? "") });
   }
   for (const rec of payload.inheritedRecipes) {
     const from = safeName(rec.folderSlug ?? "inherited");
-    await mkdir7(join14(out, "recipes", "_inherited", from), { recursive: true });
-    const path = join14(
+    await mkdir7(join15(out, "recipes", "_inherited", from), { recursive: true });
+    const path = join15(
       out,
       "recipes",
       "_inherited",
@@ -6991,7 +7351,7 @@ async function cmdPull(argv) {
   }
   const members = [];
   for (const v of payload.voses) {
-    const dir = join14(out, "members", safeName(v.slug || v.title || v.id));
+    const dir = join15(out, "members", safeName(v.slug || v.title || v.id));
     await mkdir7(dir, { recursive: true });
     const cfg = await apiJson(origin, `/api/vos/${v.id}/config`, { key });
     if (cfg.status !== 200) {
@@ -6999,7 +7359,7 @@ async function cmdPull(argv) {
       continue;
     }
     await writeFile10(
-      join14(dir, "config.json"),
+      join15(dir, "config.json"),
       JSON.stringify(cfg.body.config, null, 2)
     );
     let take = false;
@@ -7011,7 +7371,7 @@ async function cmdPull(argv) {
       );
       if (doc.status === 200) {
         await writeFile10(
-          join14(dir, "doc.json"),
+          join15(dir, "doc.json"),
           JSON.stringify(doc.body, null, 2)
         );
         take = true;
@@ -7128,7 +7488,7 @@ async function pushTake(dir, flags, r) {
     throw new Error(`doc.json fails lint:
   ${lint.problems.join("\n  ")}`);
   }
-  if (!existsSync12(take.paths.recording)) {
+  if (!existsSync13(take.paths.recording)) {
     throw new Error("no recording.webm in this take");
   }
   const ctx = apiContext(flags);
@@ -7160,7 +7520,7 @@ async function pushTake(dir, flags, r) {
       throw new Error("push cancelled");
     }
   }
-  const bytes = await readFile12(take.paths.recording);
+  const bytes = await readFile13(take.paths.recording);
   const hash = createHash("sha256").update(bytes).digest("hex");
   r.log(`uploading recording (${Math.round(bytes.length / 1024)} kB)\u2026`);
   const upload = await api(ctx, "/assets/recording", {
@@ -7199,12 +7559,12 @@ async function pushTake(dir, flags, r) {
     delete docForPush.source.micKey;
   }
   for (const ref of docMediaRefs(docForPush)) {
-    const file = join15(dir, takeRelativeFile(ref.key));
-    if (!existsSync12(file)) {
+    const file = join16(dir, takeRelativeFile(ref.key));
+    if (!existsSync13(file)) {
       r.log(`  ${ref.where}: ${ref.key} is not in the take \u2014 left as is`);
       continue;
     }
-    const media = await readFile12(file);
+    const media = await readFile13(file);
     const mediaHash = createHash("sha256").update(media).digest("hex");
     const type = mediaContentType(file);
     const put = await api(ctx, "/assets/recording", {
@@ -7340,9 +7700,9 @@ async function pullTake(dir, flags, r) {
       };
     }
     let media2;
-    if (flags.media && existsSync12(join15(dir, "doc.json"))) {
+    if (flags.media && existsSync13(join16(dir, "doc.json"))) {
       const local = JSON.parse(
-        await readFile12(join15(dir, "doc.json"), "utf8")
+        await readFile13(join16(dir, "doc.json"), "utf8")
       );
       media2 = await pullMedia(ctx, dir, local, r.log);
     }
@@ -7402,10 +7762,10 @@ async function pullTake(dir, flags, r) {
   }
   const hostedDoc = migrateHostedDoc3(docRes.json);
   const doc = hostedDoc;
-  if (existsSync12(join15(dir, RECORDING_NAME))) {
+  if (existsSync13(join16(dir, RECORDING_NAME))) {
     doc.source.videoKey = RECORDING_NAME;
   }
-  await writeJson(join15(dir, "doc.json"), doc, true);
+  await writeJson(join16(dir, "doc.json"), doc, true);
   const media = flags.media ? await pullMedia(ctx, dir, doc, r.log) : void 0;
   const versions = await api(ctx, `/vos/${vosId}/versions`);
   const headRow = (versions.json.versions ?? []).find((v) => v.id === head);
@@ -7424,10 +7784,10 @@ async function pullTake(dir, flags, r) {
 }
 
 // src/plugin/program.ts
-import { existsSync as existsSync13 } from "fs";
-import { mkdir as mkdir8, readFile as readFile13, writeFile as writeFile11 } from "fs/promises";
+import { existsSync as existsSync14 } from "fs";
+import { mkdir as mkdir8, readFile as readFile14, writeFile as writeFile11 } from "fs/promises";
 import { createInterface as createInterface2 } from "readline/promises";
-import { basename as basename2, dirname as dirname3, join as join16 } from "path";
+import { basename as basename2, dirname as dirname3, join as join17 } from "path";
 import {
   CURRENT_CONFIG_VERSION,
   migrateConfig,
@@ -7597,8 +7957,8 @@ function preflightConfig(parsed) {
 }
 function resolveConfigPath(target) {
   if (target.endsWith(".json")) return target;
-  const inDir = join16(target, "config.json");
-  if (existsSync13(inDir)) return inDir;
+  const inDir = join17(target, "config.json");
+  if (existsSync14(inDir)) return inDir;
   throw new UsageError(
     `${target} has no config.json (and is not a take \u2014 no doc.json)`
   );
@@ -7626,7 +7986,7 @@ async function cmdFetch(argv) {
   const out = strFlag(flags, "out") ?? slug;
   await mkdir8(out, { recursive: true });
   await writeFile11(
-    join16(out, "config.json"),
+    join17(out, "config.json"),
     JSON.stringify(cfg.body.config, null, 2)
   );
   const title = typeof vosMeta.title === "string" ? vosMeta.title : "";
@@ -7651,12 +8011,12 @@ async function cmdFetch(argv) {
       const hosted = migrateHostedDoc4(doc.body);
       const { config: own } = await writeProgramDoc(out, hosted);
       if (own) {
-        await writeFile11(join16(out, "config.json"), JSON.stringify(own, null, 2));
+        await writeFile11(join17(out, "config.json"), JSON.stringify(own, null, 2));
       }
     } else if (doc.status === 200) {
       take = true;
       const hosted = migrateHostedDoc4(doc.body);
-      await writeFile11(join16(out, "doc.json"), JSON.stringify(hosted, null, 2));
+      await writeFile11(join17(out, "doc.json"), JSON.stringify(hosted, null, 2));
       if (flags.media === true) {
         const media = await pullMedia({ origin, key }, out, hosted, r.log);
         mediaLine = media.downloaded.length ? ` + ${media.downloaded.map((m) => m.file).join(", ")}` : "";
@@ -7769,7 +8129,7 @@ async function cmdPushProgram(argv) {
     api: strFlag(flags, "api")
   });
   const dir = dirname3(source);
-  const parsed = JSON.parse(await readFile13(source, "utf8"));
+  const parsed = JSON.parse(await readFile14(source, "utf8"));
   const pre = preflightConfig(parsed);
   if (!pre.ok || !pre.config) {
     for (const issue of pre.issues) r.log(`error ${issue}`);
@@ -8010,10 +8370,10 @@ async function cmdPullProgram(argv) {
   const cfg = await apiJson(origin, `/api/vos/${vosId}/config`, { key });
   if (cfg.status !== 200)
     throw new Error(apiError(`fetch head config for ${vosId}`, cfg));
-  const configPath = join16(dir, "config.json");
+  const configPath = join17(dir, "config.json");
   let backedUp = false;
-  if (existsSync13(configPath)) {
-    await writeFile11(join16(dir, "config.backup.json"), await readFile13(configPath));
+  if (existsSync14(configPath)) {
+    await writeFile11(join17(dir, "config.backup.json"), await readFile14(configPath));
     backedUp = true;
   }
   let headConfig = cfg.body.config;
@@ -8046,7 +8406,7 @@ async function cmdPullProgram(argv) {
       protected: protectedIds,
       changes,
       out: configPath,
-      backup: backedUp ? join16(dir, "config.backup.json") : null
+      backup: backedUp ? join17(dir, "config.backup.json") : null
     },
     `Pulled ${changes.length} version${changes.length === 1 ? "" : "s"} \u2192 ${configPath}` + (backedUp ? ` (previous copy: config.backup.json)` : "") + `
 Re-apply your edit on the new head, then: vos push ${configPath} --vos ${vosId}`
@@ -8108,9 +8468,9 @@ function storedProgramConfig(config, programDoc) {
   return lowerProgramDoc(doc).config;
 }
 async function readProgramDoc(dir, config) {
-  const docPath = join16(dir, "doc.json");
-  if (!existsSync13(docPath)) return null;
-  const parsed = JSON.parse(await readFile13(docPath, "utf8"));
+  const docPath = join17(dir, "doc.json");
+  if (!existsSync14(docPath)) return null;
+  const parsed = JSON.parse(await readFile14(docPath, "utf8"));
   if (typeof parsed !== "object" || parsed === null || "source" in parsed)
     return null;
   const raw = parsed;
@@ -8121,7 +8481,7 @@ async function writeProgramDoc(dir, hosted) {
   const program = hosted.program && typeof hosted.program === "object" ? hosted.program : {};
   const { config, ...rest } = program;
   const onDisk = { ...hosted, program: rest };
-  await writeFile11(join16(dir, "doc.json"), JSON.stringify(onDisk, null, 2));
+  await writeFile11(join17(dir, "doc.json"), JSON.stringify(onDisk, null, 2));
   return {
     config: config && typeof config === "object" ? config : null
   };
@@ -9177,8 +9537,8 @@ async function cmdActions(argv) {
     if (!m) throw new UsageError("--viewport expects WxH, e.g. 1280x720");
     viewport = { width: Number(m[1]), height: Number(m[2]) };
   }
-  const { readFile: readFile15 } = await import("fs/promises");
-  const text = await readFile15(resolve8(input), "utf8");
+  const { readFile: readFile16 } = await import("fs/promises");
+  const text = await readFile16(resolve8(input), "utf8");
   const { records, problems } = parseAgentBrowserLog(text);
   for (const p of problems) r.log(`  ${p}`);
   const result = convertAgentBrowser(records, {
@@ -9232,7 +9592,8 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "yes",
   "composed",
   "check",
-  "motion"
+  "motion",
+  "leader"
 ]);
 var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override"]);
 var HELP = `vos \u2014 record a browser flow, plan effects, render a product video; sync with vos.so
@@ -9247,6 +9608,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 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]
@@ -9480,7 +9842,7 @@ lint-gated, so a bad override fails like a bad doc.json):
                        first ready loop (the house backdrop the studio opens on), or a flat ground offline
 `;
 async function loadActions(file) {
-  const raw = JSON.parse(await readFile14(file, "utf8"));
+  const raw = JSON.parse(await readFile15(file, "utf8"));
   const errors = validateActions(raw);
   if (errors.length)
     throw new UsageError(`invalid actions file:
@@ -9539,7 +9901,7 @@ async function cmdRecord(argv) {
   const outDir = resolve9(strFlag(flags, "out") ?? "take");
   const backdrop = await takeBackdrop(flags, r);
   const maxDurationSeconds = await maxDuration(flags, r);
-  if (existsSync14(join17(outDir, "meta.json"))) {
+  if (existsSync15(join18(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
       `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
@@ -9586,7 +9948,7 @@ async function cmdRecord(argv) {
       },
       strictFail ? `STRICT: take recorded but incomplete \u2014 ${strictReason(rec)}; fix the flow and re-record.${skippedNote}` : `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 ${join17(outDir, "doc.json")} (optional), then: vos render ${outDir}`
+  Next: edit ${join18(outDir, "doc.json")} (optional), then: vos render ${outDir}`
     );
     return strictFail ? EXIT_USAGE : EXIT_OK;
   } finally {
@@ -9615,14 +9977,14 @@ async function cmdCreate2(argv) {
   if (fmtRaw !== "webm" && fmtRaw !== "mp4")
     throw new UsageError("--format must be webm or mp4");
   const format = fmtRaw;
-  const out = positionals[0] ?? join17(outDir, `out.${format}`);
+  const out = positionals[0] ?? join18(outDir, `out.${format}`);
   const parallel = numFlag(flags, "parallel", 1);
   if (!Number.isInteger(parallel) || parallel < 1 || parallel > 16) {
     throw new UsageError("--parallel expects an integer between 1 and 16");
   }
   const backdrop = await takeBackdrop(flags, r);
   const maxDurationSeconds = await maxDuration(flags, r);
-  if (existsSync14(join17(outDir, "meta.json"))) {
+  if (existsSync15(join18(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
       `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
@@ -9713,24 +10075,24 @@ async function cmdPlan(argv) {
     );
   const r = createReporter(flags.json === true);
   if (flags.fresh === true) {
-    await rm4(join17(dir, "doc.json"), { force: true });
+    await rm4(join18(dir, "doc.json"), { force: true });
     r.log("note: --fresh discarded the existing doc.json");
   }
   let reuse;
   if (flags.reuse === true) {
-    const from = resolve9(strFlag(flags, "from") ?? join17(dir, PREV_DOC_NAME));
-    if (!existsSync14(from)) {
+    const from = resolve9(strFlag(flags, "from") ?? join18(dir, PREV_DOC_NAME));
+    if (!existsSync15(from)) {
       throw new UsageError(
         `--reuse: ${from} does not exist \u2014 a re-record into this take writes doc.prev.json, or pass --from <doc.json>`
       );
     }
     reuse = {
       from,
-      doc: JSON.parse(await readFile14(from, "utf8"))
+      doc: JSON.parse(await readFile15(from, "utf8"))
     };
   }
   const style = await resolveStyleRef(flags);
-  const hasDoc = existsSync14(join17(dir, "doc.json"));
+  const hasDoc = existsSync15(join18(dir, "doc.json"));
   const backdrop = hasDoc ? null : await takeBackdrop(flags, r);
   const release = await releaseInputs(dir, flags, r, multi.with ?? []);
   const motionWanted = !hasDoc || flags.motion === true || flags.fresh === true;
@@ -9788,7 +10150,7 @@ async function cmdPlan(argv) {
       ...s.motion ? { motion: s.motion } : {},
       ...s.reuse ? { reuse: s.reuse } : {}
     },
-    `${s.reuse ? "Reused" : s.fresh ? "Planned" : "Refreshed"} ${join17(dir, "doc.json")}: ${s.zoomAuto} auto + ${s.zoomManual} manual zoom spans${s.cursorKept ? "" : " (cursor track dropped)"}${layoutLines}${motionLines}${reuseLines}`
+    `${s.reuse ? "Reused" : s.fresh ? "Planned" : "Refreshed"} ${join18(dir, "doc.json")}: ${s.zoomAuto} auto + ${s.zoomManual} manual zoom spans${s.cursorKept ? "" : " (cursor track dropped)"}${layoutLines}${motionLines}${reuseLines}`
   );
   return EXIT_OK;
 }
@@ -9914,7 +10276,7 @@ async function cmdRender(argv) {
   if (fmtRaw !== "webm" && fmtRaw !== "mp4")
     throw new UsageError("--format must be webm or mp4");
   const format = fmtRaw;
-  const out = positionals[1] ?? join17(dir, `out.${format}`);
+  const out = positionals[1] ?? join18(dir, `out.${format}`);
   const parallel = numFlag(flags, "parallel", 1);
   if (!Number.isInteger(parallel) || parallel < 1 || parallel > 16) {
     throw new UsageError("--parallel expects an integer between 1 and 16");
@@ -10161,15 +10523,15 @@ async function resolveStyleRef(flags) {
 }
 async function resolveDocRef(ref, flags, what) {
   const styleRef = ref;
-  const file = existsSync14(styleRef) ? resolve9(
+  const file = existsSync15(styleRef) ? resolve9(
     styleRef,
-    existsSync14(join17(styleRef, "doc.json")) ? "doc.json" : ""
+    existsSync15(join18(styleRef, "doc.json")) ? "doc.json" : ""
   ) : null;
-  if (file && existsSync14(file)) {
+  if (file && existsSync15(file)) {
     return {
       from: file,
       doc: migrateHostedDoc5(
-        JSON.parse(await readFile14(file, "utf8"))
+        JSON.parse(await readFile15(file, "utf8"))
       )
     };
   }
@@ -10221,7 +10583,7 @@ async function cmdDigest(argv) {
   const take = await loadTake(dir);
   if (!take.doc) throw new UsageError(`${dir} has no doc.json \u2014 run plan first`);
   const transcriptPath = strFlag(flags, "transcript");
-  const transcript = transcriptPath ? parseTranscript(JSON.parse(await readFile14(transcriptPath, "utf8"))) : null;
+  const transcript = transcriptPath ? parseTranscript(JSON.parse(await readFile15(transcriptPath, "utf8"))) : null;
   const style = await resolveStyleRef(flags);
   const noFrames = flags["no-frames"] === true;
   let browser = null;
@@ -10252,7 +10614,7 @@ async function cmdDigest(argv) {
         kinds,
         frames: d.images.full,
         crops: d.images.crop,
-        sheet: d.images.sheet ? join17(result.outDir, d.images.sheet) : null,
+        sheet: d.images.sheet ? join18(result.outDir, d.images.sheet) : null,
         scenes: kinds.scene ?? 0,
         sourceDuration: d.take.sourceDuration,
         outputDuration: d.take.outputDuration,
@@ -10276,7 +10638,7 @@ async function cmdOpen(argv) {
   if (!dir) throw new UsageError("vos open <take> [--studio <url>]");
   const r = createReporter(flags.json === true);
   const take = await loadTake(dir);
-  if (!existsSync14(take.paths.recording)) {
+  if (!existsSync15(take.paths.recording)) {
     throw new UsageError(`${dir} has no recording.webm \u2014 re-run record`);
   }
   const studio = (strFlag(flags, "studio") ?? "http://localhost:6060").replace(
@@ -10317,12 +10679,12 @@ async function cmdJudge(argv) {
       "vos judge <kit.json> --against <MANIFEST.json> [--out dir] [--json]\n(the manifest names the reference set: id, file, role, layout, facts, rule per asset)"
     );
   const r = createReporter(flags.json === true);
-  const kitFile = target.endsWith("kit.json") ? target : join17(target, "kit.json");
-  if (!existsSync14(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
-  if (!existsSync14(against))
+  const kitFile = target.endsWith("kit.json") ? target : join18(target, "kit.json");
+  if (!existsSync15(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
+  if (!existsSync15(against))
     throw new UsageError(`${against}: no reference manifest`);
   const result = await judgeKit(kitFile, against, strFlag(flags, "out"));
-  const verdicts = JSON.parse(await readFile14(result.verdictFile, "utf8")).verdicts;
+  const verdicts = JSON.parse(await readFile15(result.verdictFile, "utf8")).verdicts;
   const rate = winRate(verdicts);
   const lines = result.sheets.map(
     (s) => `${s.asset} vs ${s.reference}: ${s.sheetA}, ${s.sheetB}, ${s.rubric}`
@@ -10337,12 +10699,109 @@ Win rate so far: ${rate.wins} win(s), ${rate.ties} tie(s) of ${rate.judged} judg
   );
   return EXIT_OK;
 }
+async function cmdCallout(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS5);
+  const dir = positionals[0];
+  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]'
+    );
+  const r = createReporter(flags.json === true);
+  const take = await loadTake(dir);
+  if (!take.doc) throw new UsageError(`${dir} has no doc.json \u2014 run plan first`);
+  const brand = await readBrandBesideTake(dir, strFlag(flags, "brand"));
+  const bodyPx = strFlag(flags, "body-px");
+  const register = registerFrom(brand?.roles ?? null, {
+    ground: strFlag(flags, "ground"),
+    accent: strFlag(flags, "accent"),
+    face: strFlag(flags, "font"),
+    mono: strFlag(flags, "mono"),
+    body: bodyPx !== void 0 ? Number(bodyPx) : void 0
+  });
+  if (!register)
+    throw new UsageError(
+      `no register: put a BRAND.md beside the take (vos brand <url> --out BRAND.md; its bgA and accent are the ground and the accent), or pass --ground #hex --accent #hex`
+    );
+  const codeFile = strFlag(flags, "code-file");
+  const code = codeFile ? await readFile15(codeFile, "utf8") : strFlag(flags, "code");
+  const words = {
+    kicker: strFlag(flags, "kicker"),
+    title: strFlag(flags, "title"),
+    body: strFlag(flags, "body"),
+    code: code?.replace(/\\n/g, "\n")
+  };
+  if (shape === "code" && !words.code)
+    throw new UsageError(
+      'a code callout needs --code "\u2026" or --code-file <file>'
+    );
+  if (shape === "note" && !words.title)
+    throw new UsageError('a note needs --title "\u2026"');
+  if (shape === "tag" && !words.kicker && !words.title)
+    throw new UsageError('a tag needs --kicker "\u2026"');
+  const stepRaw = strFlag(flags, "step");
+  const atRaw = strFlag(flags, "at");
+  const secondsRaw = strFlag(flags, "seconds");
+  const side = strFlag(flags, "side");
+  const mark = strFlag(flags, "mark");
+  let composed;
+  try {
+    composed = composeCallout(take.doc, register, {
+      shape,
+      words,
+      id: strFlag(flags, "id"),
+      step: stepRaw !== void 0 ? /^\d+$/.test(stepRaw) ? Number(stepRaw) : stepRaw : void 0,
+      at: atRaw !== void 0 ? Number(atRaw) : void 0,
+      seconds: secondsRaw !== void 0 ? Number(secondsRaw) : void 0,
+      side,
+      mark,
+      leader: flags.leader === true,
+      color: strFlag(flags, "color")
+    });
+  } catch (e) {
+    throw new UsageError(e instanceof Error ? e.message : String(e));
+  }
+  const { clip, window: window2 } = composed;
+  if (flags.print === true) {
+    r.done(
+      { clip, window: window2, register, brand: brand?.file ?? null },
+      JSON.stringify(clip, null, 2)
+    );
+    return EXIT_OK;
+  }
+  const doc = take.doc;
+  const overlays = (doc.overlays ?? []).filter((o) => o.id !== clip.id);
+  const next = { ...doc, overlays: [...overlays, clip] };
+  const lint = lintDoc(next);
+  if (lint.problems.length) {
+    r.done(
+      { valid: false, problems: lint.problems, warnings: lint.warnings, clip },
+      `the callout would not validate:
+  ${lint.problems.join("\n  ")}`
+    );
+    return EXIT_ERROR;
+  }
+  await writeJson(take.paths.doc, next, true);
+  r.done(
+    {
+      clip,
+      window: window2,
+      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 ? `
+  warnings:
+  ${lint.warnings.join("\n  ")}` : ""}`
+  );
+  return EXIT_OK;
+}
 async function cmdValidate(argv) {
   const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS5);
   const target = positionals[0];
   if (!target) throw new UsageError("vos validate <actions.json|take>");
   const r = createReporter(flags.json === true);
-  const kitTarget = target.endsWith("kit.json") ? target : existsSync14(join17(target, "kit.json")) && !isTakeDir(target) ? join17(target, "kit.json") : null;
+  const kitTarget = target.endsWith("kit.json") ? target : existsSync15(join18(target, "kit.json")) && !isTakeDir(target) ? join18(target, "kit.json") : null;
   if (kitTarget) {
     const picture = flags.picture === true;
     const verdict = await validateKit(kitTarget, { picture });
@@ -10374,9 +10833,9 @@ async function cmdValidate(argv) {
     r.done({ valid: true, target }, `${target}: valid actions file`);
     return EXIT_OK;
   }
-  if (!isTakeDir(target) && existsSync14(join17(target, "config.json"))) {
+  if (!isTakeDir(target) && existsSync15(join18(target, "config.json"))) {
     const parsed = JSON.parse(
-      await readFile14(join17(target, "config.json"), "utf8")
+      await readFile15(join18(target, "config.json"), "utf8")
     );
     const pre = preflightConfig(parsed);
     const problems2 = pre.ok ? [] : pre.issues.map((i) => `config.json: ${i}`);
@@ -10417,7 +10876,7 @@ async function cmdValidate(argv) {
   const take = await loadTake(target);
   const problems = [];
   const warnings = [];
-  if (!existsSync14(take.paths.recording))
+  if (!existsSync15(take.paths.recording))
     problems.push("missing recording.webm (re-run record)");
   if (!take.doc) problems.push("missing doc.json (run plan)");
   if (take.doc) {
@@ -10429,6 +10888,36 @@ async function cmdValidate(argv) {
     );
     problems.push(...probe.problems);
     warnings.push(...probe.warnings);
+    if (flags.picture === true && (take.doc.overlays ?? []).some((o) => o.kind === "html")) {
+      const doc = take.doc;
+      const times = [
+        ...new Set(
+          (doc.overlays ?? []).filter((o) => o.kind === "html").map((o) => +(o.start + Math.min(0.35, o.duration / 2)).toFixed(3))
+        )
+      ];
+      const browser = await launchBrowser();
+      try {
+        const frames = await footageFrames(
+          browser,
+          target,
+          doc,
+          times,
+          framesTake
+        );
+        const findings = await groundFindings(
+          doc,
+          async (t) => frames.get(+t.toFixed(3)) ?? null
+        );
+        for (const f of findings) {
+          if (f.level === "problem") problems.push(`doc.json: ${f.message}`);
+          else if (f.level === "warning")
+            warnings.push(`doc.json: ${f.message}`);
+          else r.event({ event: "ground", ...f });
+        }
+      } finally {
+        await browser.close();
+      }
+    }
   }
   if (problems.length) {
     r.done(
@@ -10545,6 +11034,8 @@ async function run(argv) {
         return await cmdOpen(rest);
       case "validate":
         return await cmdValidate(rest);
+      case "callout":
+        return await cmdCallout(rest);
       case "judge":
         return await cmdJudge(rest);
       case "fetch":
@@ -10628,4 +11119,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-APVJ4MDJ.js.map
+//# sourceMappingURL=chunk-6O55OD6D.js.map