@vosjs/cli 0.32.0 → 0.34.0

package/dist/{chunk-QJORXTJM.js → chunk-43FCXWNS.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,
@@ -156,6 +156,8 @@ function validateActions(value) {
       errors.push(`${at2}: ${s.do} needs a selector`);
     if (s.do === "wait" && typeof s.ms !== "number")
       errors.push(`${at2}: wait needs ms`);
+    if (s.ms !== void 0 && (typeof s.ms !== "number" || !Number.isFinite(s.ms) || s.ms < 0))
+      errors.push(`${at2}: ms must be a number of milliseconds \u2265 0`);
     if (s.do === "type" && typeof s.text !== "string")
       errors.push(`${at2}: type needs text`);
     if (s.do === "type" && s.focus !== void 0 && typeof s.focus !== "boolean")
@@ -214,6 +216,7 @@ import {
   findStep,
   outputEnd,
   pinBox,
+  pinCandidates,
   pinRectOnScreen,
   pinReferent,
   ratedSegments,
@@ -1611,6 +1614,17 @@ function framingWarnings(docIn, doc, zoom, overlays, warnings) {
       const tf = isObj(o.transform) ? o.transform : null;
       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(
@@ -5294,10 +5308,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;
@@ -5325,7 +5537,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);
@@ -5474,7 +5686,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);
@@ -5573,7 +5785,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",
@@ -5666,9 +5878,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) {
@@ -5687,7 +5899,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();
@@ -5708,7 +5920,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,
@@ -5727,8 +5939,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();
@@ -5754,7 +5966,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(
@@ -5864,7 +6076,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;
@@ -5910,9 +6122,99 @@ function cappedLine(capSeconds) {
   return `stopped at ${formatDurationCap(capSeconds)} (--max-duration ${capSeconds}); the remaining steps did not run`;
 }
 
+// src/plugin/pace.ts
+var POINTER_MS_PER_PX = 0.7;
+var POINTER_MIN_MS = 250;
+var POINTER_MAX_MS = 800;
+var MOTION_TICK_MS = 16;
+var SETTLE_MS = {
+  click: 150,
+  type: 150,
+  scroll: 200,
+  drag: 80
+};
+var PRESS_LEAD_MS = 80;
+var PRESS_HOLD_MS = 70;
+var SCROLL_SETTLE_MS = 120;
+var TRAILING_HOLD_MS = 400;
+function pointerTravelMs(dist) {
+  return Math.min(
+    POINTER_MAX_MS,
+    Math.max(POINTER_MIN_MS, Math.round(dist * POINTER_MS_PER_PX))
+  );
+}
+function settleMs(step) {
+  if (typeof step.ms === "number" && step.ms >= 0) return step.ms;
+  const d = step.do;
+  return SETTLE_MS[d] ?? 0;
+}
+var easeInOutCubic = (u) => u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2;
+async function clockMotion(dur, at2, clock) {
+  const start = clock.now();
+  let samples = 0;
+  for (; ; ) {
+    const elapsed = clock.now() - start;
+    if (elapsed >= dur) break;
+    await at2(easeInOutCubic(Math.min(1, elapsed / dur)));
+    samples++;
+    const next = start + Math.ceil((clock.now() - start) / MOTION_TICK_MS) * MOTION_TICK_MS;
+    const wait = Math.min(next, start + dur) - clock.now();
+    if (wait > 0) await clock.sleep(wait);
+  }
+  await at2(1);
+  return samples + 1;
+}
+async function clockTyping(chars, delay, type, clock) {
+  const start = clock.now();
+  for (let i = 0; i < chars.length; i++) {
+    await type(chars[i], i);
+    const due = start + (i + 1) * delay;
+    const wait = due - clock.now();
+    if (wait > 0 && i < chars.length - 1) await clock.sleep(wait);
+  }
+}
+function askedMs(step) {
+  switch (step.do) {
+    case "wait":
+      return step.ms ?? 0;
+    case "hover":
+      return step.ms ?? 700;
+    case "drag":
+      return step.ms ?? 700;
+    case "type":
+      return (step.text?.length ?? 0) * (step.delayMs ?? 40);
+    default:
+      return 0;
+  }
+}
+function paceReport(steps) {
+  const askedMs2 = steps.reduce((a, s) => a + s.askedMs, 0);
+  const gestureMs = steps.reduce((a, s) => a + s.gestureMs, 0);
+  const wallMs = steps.reduce((a, s) => a + s.wallMs, 0);
+  const overheadMs = Math.max(0, wallMs - askedMs2 - gestureMs);
+  const slow = steps.filter((s) => s.wallMs > (s.askedMs + s.gestureMs) * 1.34 + 60).map((s) => ({
+    step: s.step,
+    do: s.do,
+    askedMs: s.askedMs,
+    wallMs: s.wallMs
+  }));
+  return {
+    askedMs: askedMs2,
+    gestureMs,
+    wallMs,
+    overheadMs,
+    overheadPct: wallMs > 0 ? Math.round(overheadMs / wallMs * 100) : 0,
+    slow
+  };
+}
+function paceLine(r) {
+  const s = (ms) => `${(ms / 1e3).toFixed(1)} s`;
+  const slow = r.slow.length ? `; slow: ${r.slow.map((x) => `#${x.step} ${x.do} ${s(x.wallMs)} for ${s(x.askedMs)} asked`).join(", ")}` : "";
+  return `pace: the script asked ${s(r.askedMs)}, the gestures added ${s(r.gestureMs)}, the take ran ${s(r.wallMs)} (${r.overheadPct} % overhead${slow})`;
+}
+
 // src/plugin/recorder.ts
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-var easeInOutCubic = (u) => u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2;
 function jpegDims(buf) {
   let i = 2;
   while (i < buf.length - 9) {
@@ -5952,7 +6254,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(() => {
     });
@@ -5971,26 +6273,30 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const emit = (e) => events.push({ t: now(), ...e });
   await page.mouse.move(cur.x, cur.y);
   emit({ x: cur.x, y: cur.y, type: "move" });
+  const clock = { now: () => Date.now(), sleep };
   const moveTo = async (tx, ty) => {
     const dist = Math.hypot(tx - cur.x, ty - cur.y);
-    const dur = Math.min(1200, Math.max(350, dist * 1.4));
-    const steps = Math.max(6, Math.round(dur / 16));
     const from = { ...cur };
-    for (let i = 1; i <= steps; i++) {
-      const u = easeInOutCubic(i / steps);
-      cur.x = from.x + (tx - from.x) * u;
-      cur.y = from.y + (ty - from.y) * u;
-      await page.mouse.move(cur.x, cur.y);
-      emit({ x: Math.round(cur.x), y: Math.round(cur.y), type: "move" });
-      await sleep(14);
-    }
+    await clockMotion(
+      pointerTravelMs(dist),
+      async (u) => {
+        cur.x = from.x + (tx - from.x) * u;
+        cur.y = from.y + (ty - from.y) * u;
+        await page.mouse.move(cur.x, cur.y);
+        emit({ x: Math.round(cur.x), y: Math.round(cur.y), type: "move" });
+      },
+      clock
+    );
   };
   const boxOf = async (selector) => {
     const loc = page.locator(selector).first();
     try {
       await loc.waitFor({ state: "visible", timeout: 8e3 });
+      const before = await page.evaluate(() => [window.scrollX, window.scrollY]).catch(() => [0, 0]);
       await loc.scrollIntoViewIfNeeded();
-      await sleep(250);
+      const after = await page.evaluate(() => [window.scrollX, window.scrollY]).catch(() => before);
+      if (before[0] !== after[0] || before[1] !== after[1])
+        await sleep(SCROLL_SETTLE_MS);
       const bb = await loc.boundingBox();
       if (!bb) return null;
       return { x: bb.x, y: bb.y, w: bb.width, h: bb.height };
@@ -6001,7 +6307,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   };
   const clickAt = async (rect) => {
     await moveTo(rect.x + rect.w / 2, rect.y + rect.h / 2);
-    await sleep(120);
+    await sleep(PRESS_LEAD_MS);
     emit({
       x: Math.round(cur.x),
       y: Math.round(cur.y),
@@ -6010,7 +6316,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       rect
     });
     await page.mouse.down();
-    await sleep(90);
+    await sleep(PRESS_HOLD_MS);
     await page.mouse.up();
     emit({
       x: Math.round(cur.x),
@@ -6022,6 +6328,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   };
   const skipped = [];
   const stepSpans = [];
+  const paces = [];
   let capped = false;
   for (const [stepIdx, step] of actions.steps.entries()) {
     if (capReached(now(), maxSeconds)) {
@@ -6029,6 +6336,13 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       break;
     }
     const stepStart = now();
+    let gestureMs = 0;
+    const gesture = async (fn) => {
+      const t = now();
+      const out = await fn();
+      gestureMs += now() - t;
+      return out;
+    };
     const skippedBefore = skipped.length;
     const urlBefore = page.url();
     let stepRect = null;
@@ -6043,7 +6357,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
         const rect = await boxOf(step.selector);
         stepRect = rect;
         if (rect) {
-          await moveTo(rect.x + rect.w / 2, rect.y + rect.h / 2);
+          await gesture(() => moveTo(rect.x + rect.w / 2, rect.y + rect.h / 2));
           log(`hover ${step.selector}`);
           await sleep(step.ms ?? 700);
         } else
@@ -6054,9 +6368,9 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
         const rect = await boxOf(step.selector);
         stepRect = rect;
         if (rect) {
-          await clickAt(rect);
+          await gesture(() => clickAt(rect));
           log(`click ${step.selector}`);
-          await sleep(500);
+          await gesture(() => sleep(settleMs(step)));
         } else
           skipped.push({ step: stepIdx, do: step.do, selector: step.selector });
         break;
@@ -6065,7 +6379,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
         const rect = await boxOf(step.selector);
         stepRect = rect;
         if (rect) {
-          if (step.focus !== false) await clickAt(rect);
+          if (step.focus !== false) await gesture(() => clickAt(rect));
           const delay = step.delayMs ?? 40;
           const ping = () => emit({
             x: Math.round(rect.x + rect.w / 2),
@@ -6074,17 +6388,21 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
             rect
           });
           let lastPing = -Infinity;
-          for (const ch of step.text) {
-            if (now() - lastPing >= 350) {
-              lastPing = now();
-              ping();
-            }
-            await page.keyboard.type(ch);
-            await sleep(delay);
-          }
+          await clockTyping(
+            [...step.text],
+            delay,
+            async (ch) => {
+              if (now() - lastPing >= 350) {
+                lastPing = now();
+                ping();
+              }
+              await page.keyboard.type(ch);
+            },
+            clock
+          );
           ping();
           log(`type "${step.text}" into ${step.selector}`);
-          await sleep(300);
+          await gesture(() => sleep(settleMs(step)));
         } else
           skipped.push({ step: stepIdx, do: step.do, selector: step.selector });
         break;
@@ -6097,7 +6415,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
           emit({ x: Math.round(cur.x), y: Math.round(cur.y), type: "scroll" });
           await sleep(40);
         }
-        await sleep(400);
+        await gesture(() => sleep(settleMs(step)));
         break;
       }
       case "drag": {
@@ -6121,8 +6439,8 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
           start = { x: step.x, y: step.y };
         }
         if (!start) break;
-        await moveTo(start.x, start.y);
-        await sleep(140);
+        await gesture(() => moveTo(start.x, start.y));
+        await gesture(() => sleep(PRESS_LEAD_MS));
         emit({
           x: Math.round(cur.x),
           y: Math.round(cur.y),
@@ -6131,19 +6449,20 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
           rect
         });
         await page.mouse.down();
-        await sleep(90);
+        await gesture(() => sleep(PRESS_HOLD_MS));
         const dur = step.ms ?? 700;
-        const steps = Math.max(8, Math.round(dur / 16));
         const from = { ...cur };
-        for (let i = 1; i <= steps; i++) {
-          const u = easeInOutCubic(i / steps);
-          cur.x = from.x + (step.tx - from.x) * u;
-          cur.y = from.y + (step.ty - from.y) * u;
-          await page.mouse.move(cur.x, cur.y);
-          emit({ x: Math.round(cur.x), y: Math.round(cur.y), type: "move" });
-          await sleep(14);
-        }
-        await sleep(100);
+        await clockMotion(
+          dur,
+          async (u) => {
+            cur.x = from.x + (step.tx - from.x) * u;
+            cur.y = from.y + (step.ty - from.y) * u;
+            await page.mouse.move(cur.x, cur.y);
+            emit({ x: Math.round(cur.x), y: Math.round(cur.y), type: "move" });
+          },
+          clock
+        );
+        await gesture(() => sleep(settleMs({ do: "drag" })));
         await page.mouse.up();
         emit({
           x: Math.round(cur.x),
@@ -6178,8 +6497,15 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
         }
       } : {}
     });
+    paces.push({
+      step: stepIdx,
+      do: step.do,
+      askedMs: askedMs(step),
+      gestureMs,
+      wallMs: now() - stepStart
+    });
   }
-  if (!capped) await sleep(600);
+  if (!capped) await sleep(TRAILING_HOLD_MS);
   if (capped || capReached(now(), maxSeconds)) {
     capped = true;
     log(`   ${cappedLine(maxSeconds)}`);
@@ -6190,7 +6516,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,
@@ -6231,10 +6557,13 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   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)}`);
   return {
     events,
     frames,
     meta,
+    pace,
     skipped,
     navTimeout,
     freezes,
@@ -6298,9 +6627,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,
@@ -6522,10 +6851,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;
@@ -6735,17 +7064,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";
@@ -6869,8 +7198,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}`;
@@ -6895,8 +7224,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) {
@@ -6913,9 +7242,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),
@@ -6929,17 +7258,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"]);
@@ -7115,18 +7444,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",
@@ -7141,7 +7470,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) {
@@ -7149,7 +7478,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;
@@ -7161,7 +7490,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;
@@ -7278,7 +7607,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);
@@ -7310,7 +7639,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", {
@@ -7349,12 +7678,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", {
@@ -7490,9 +7819,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);
     }
@@ -7552,10 +7881,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);
@@ -7574,10 +7903,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,
@@ -7747,8 +8076,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)`
   );
@@ -7776,7 +8105,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 : "";
@@ -7801,12 +8130,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(", ")}` : "";
@@ -7919,7 +8248,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}`);
@@ -8160,10 +8489,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;
@@ -8196,7 +8525,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}`
@@ -8258,9 +8587,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;
@@ -8271,7 +8600,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
   };
@@ -9327,8 +9656,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, {
@@ -9382,7 +9711,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
@@ -9397,6 +9727,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]
@@ -9630,7 +9961,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:
@@ -9689,7 +10020,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" : "")
@@ -9732,11 +10063,12 @@ async function cmdRecord(argv) {
         freezes: rec.freezes,
         freezePct: rec.freezePct,
         capped: rec.capped,
+        pace: rec.pace,
         ...strictFail ? { strictFailed: true } : {}
       },
       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 {
@@ -9765,14 +10097,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" : "")
@@ -9863,24 +10195,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;
@@ -9938,7 +10270,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;
 }
@@ -10064,7 +10396,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");
@@ -10311,15 +10643,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"))
       )
     };
   }
@@ -10371,7 +10703,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;
@@ -10402,7 +10734,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,
@@ -10426,7 +10758,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(
@@ -10467,12 +10799,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}`
@@ -10487,12 +10819,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 });
@@ -10524,9 +10953,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}`);
@@ -10567,7 +10996,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) {
@@ -10579,6 +11008,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(
@@ -10695,6 +11154,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":
@@ -10778,4 +11239,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-QJORXTJM.js.map
+//# sourceMappingURL=chunk-43FCXWNS.js.map