@vosjs/cli 0.19.0 → 0.21.0

package/dist/{chunk-4LLBPFCW.js → chunk-4IWHZBIY.js}

@@ -9,8 +9,7 @@ import {
 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 { totalDuration as totalDuration2 } from "@vosjs/timeline";
-import { migrateHostedDoc as migrateHostedDoc5, ratedSegments as ratedSegments6 } from "@vosjs/studio-core";
+import { docOutputDuration as docOutputDuration3, migrateHostedDoc as migrateHostedDoc5 } from "@vosjs/studio-core";
 
 // src/plugin/args.ts
 var UsageError = class extends Error {
@@ -189,6 +188,8 @@ import {
   TEXT_ENTER_KINDS,
   TEXT_EXIT_KINDS,
   EXPORT_RESOLUTION_OPTIONS,
+  FREEZE_SECONDS_MAX,
+  FREEZE_SECONDS_MIN,
   SPEED_RATE_MAX,
   SPEED_RATE_MIN,
   TILT_DEG_MAX,
@@ -399,14 +400,45 @@ function lintDoc(docIn) {
     }
     for (const [i, seg] of (Array.isArray(doc.segments) ? doc.segments : []).entries()) {
       const hold = seg.hold;
-      if (hold !== void 0 && (!isNum(hold) || hold < 0 || hold > 10)) {
+      if (hold === void 0) continue;
+      if (!isNum(hold) || hold < 0 || hold > FREEZE_SECONDS_MAX) {
         problems.push(
-          `segments[${i}].hold must be 0..10 output seconds (got ${String(hold)})`
+          `segments[${i}].hold must be 0..${FREEZE_SECONDS_MAX} output seconds (got ${String(hold)})`
+        );
+      } else if (hold > 0) {
+        warnings.push(
+          `segments[${i}].hold is a legacy spelling, read as a freeze at ${String(seg.out)}s (doc.freeze); vos plan writes that shape`
+        );
+      }
+    }
+    if (doc.freeze !== void 0 && !Array.isArray(doc.freeze)) {
+      problems.push("freeze must be an array of {id, at, seconds}");
+    }
+    const freezes = Array.isArray(doc.freeze) ? doc.freeze : [];
+    const freezeIds = /* @__PURE__ */ new Set();
+    for (const [i, raw] of freezes.entries()) {
+      const f = raw;
+      const name = `freeze[${i}]${typeof f.id === "string" ? ` (${f.id})` : ""}`;
+      if (typeof f.id !== "string" || !f.id)
+        problems.push(`${name}: id must be a string`);
+      else if (freezeIds.has(f.id)) problems.push(`${name}: duplicate id`);
+      else freezeIds.add(f.id);
+      if (!isNum(f.at) || f.at < 0 || f.at > duration + EPS) {
+        problems.push(
+          `${name}: at must be a SOURCE moment inside the recording (0..${duration.toFixed(2)}s, got ${String(f.at)})`
+        );
+      }
+      if (!isNum(f.seconds) || f.seconds < FREEZE_SECONDS_MIN - EPS || f.seconds > FREEZE_SECONDS_MAX + EPS) {
+        problems.push(
+          `${name}: seconds must be ${FREEZE_SECONDS_MIN}..${FREEZE_SECONDS_MAX} output seconds (got ${String(f.seconds)})`
         );
       }
     }
     const endCard = doc.endCard;
     if (endCard !== void 0) {
+      warnings.push(
+        "endCard is a legacy spelling, read as clips after the footage plus a card exit (frame.anim.exit); vos plan writes that shape"
+      );
       if (typeof endCard !== "object" || endCard === null) {
         problems.push(
           "endCard must be an object: {seconds?, headline?, sub?, wordmark?}"
@@ -653,6 +685,9 @@ function lintDoc(docIn) {
       }
       const ent = frame.entrance;
       if (ent !== void 0) {
+        warnings.push(
+          "frame.entrance is a legacy spelling; write frame.anim.enter"
+        );
         const kinds = ["tilt-in", "pull-out", "rise", "none"];
         if (typeof ent !== "object" || ent === null || !kinds.includes(String(ent.kind))) {
           problems.push(
@@ -925,6 +960,10 @@ function lintDoc(docIn) {
         problems.push(`${name}.${key} must be one of ${TRANSITIONS.join("|")}`);
       }
     }
+    if (o.enter !== void 0 || o.exit !== void 0 || o.fx !== void 0)
+      warnings.push(
+        `${name}: enter, exit and fx are legacy spellings; write anim.enter / anim.exit`
+      );
     lintAnim(
       name,
       o.anim,
@@ -1072,6 +1111,8 @@ function lintDoc(docIn) {
     if (o.animation !== void 0 && o.animation !== null && o.animation !== "spin" && o.animation !== "float") {
       problems.push(`${name}.animation must be "spin" | "float" | null`);
     }
+    if (o.animation !== void 0)
+      warnings.push(`${name}.animation is a legacy spelling; write anim.idle`);
     lintAnim(
       name,
       o.anim,
@@ -2759,7 +2800,6 @@ async function writeIndexJson(result) {
 import { mkdir as mkdir4, mkdtemp, rename as rename4, rm as rm3, stat, writeFile as writeFile6 } from "fs/promises";
 import { tmpdir } from "os";
 import { join as join7, relative, resolve as resolve4 } from "path";
-import { totalDuration } from "@vosjs/timeline";
 import { existsSync as existsSync6 } from "fs";
 import { readFile as readFile6 } from "fs/promises";
 import { parseFrontmatter } from "@vosjs/shared/frontmatter";
@@ -2771,7 +2811,7 @@ import {
   houseLook,
   isLookKind,
   lookFromBrand,
-  ratedSegments as ratedSegments5
+  docOutputDuration as docOutputDuration2
 } from "@vosjs/studio-core";
 
 // src/plugin/renderTake.ts
@@ -3387,7 +3427,18 @@ function pickMoments(measured, opts = {}) {
 }
 
 // src/plugin/motionPlan.ts
-import { ratedSegments as ratedSegments4, spanOutputExtent as spanOutputExtent4 } from "@vosjs/studio-core";
+import {
+  END_CARD_FROM,
+  END_CARD_RECEDE,
+  END_CARD_SECONDS,
+  applyTemplate,
+  docOutputDuration,
+  dropTemplate,
+  endCardClips,
+  migrateMotion,
+  ratedSegments as ratedSegments4,
+  spanOutputExtent as spanOutputExtent4
+} from "@vosjs/studio-core";
 var SOUND_DESTINATIONS = /* @__PURE__ */ new Set([
   "x-feed-cut",
   "youtube-main-demo",
@@ -3422,41 +3473,103 @@ var outputLength = (doc) => ratedSegments4(doc).reduce((acc, s) => {
   const rate = s.rate && s.rate > 0 ? s.rate : 1;
   return acc + (s.out - s.in) / rate;
 }, 0);
+function templateWords(words) {
+  const headline = (words.headline ?? "").trim();
+  const kicker = (words.kicker ?? "").trim();
+  const brand = (words.brand ?? "").trim();
+  const sub = [brand, (words.release ?? "").trim()].filter(Boolean).join(" ");
+  const out = {};
+  if (headline) {
+    out["stage-title"] = headline;
+    out["endcard-title"] = headline;
+  }
+  if (kicker) out["stage-kicker"] = kicker;
+  if (brand) {
+    out["stage-brand"] = brand;
+    out["endcard-mark"] = brand;
+  }
+  if (sub && sub !== headline) out["endcard-sub"] = sub;
+  return out;
+}
+function resolveAnchor(doc, at2) {
+  if (typeof at2 !== "object") return at2;
+  const steps = doc.source.meta.steps ?? [];
+  const step = steps.find((s) => s.id === at2.step || String(s.step) === at2.step);
+  if (!step || step.skipped) return null;
+  const t = stepOutputTime(ratedSegments4(doc), step, 0.2);
+  return t === null ? null : +t.toFixed(3);
+}
+var anchorWord = (at2) => typeof at2 === "object" ? `step ${at2.step}` : typeof at2 === "number" ? `${at2}s` : `the ${at2}`;
+var onWord = (v) => v === void 0 || /^(on|yes|true)$/i.test(v.trim());
 function proposeMotion(input, opts) {
-  const doc = structuredClone(input);
+  let doc = migrateMotion(structuredClone(input));
   const { words, launch, catalog } = opts;
   const notes = [];
   const skipped = [];
-  const length = outputLength(doc);
-  const range = [0, length];
+  const footage = outputLength(doc);
+  const range = [0, footage];
   const entrance = launch.entrance;
+  delete doc.frame.entrance;
   if (!off(entrance)) {
-    const kind = entrance && /^(tilt-in|pull-out|rise)$/.test(entrance.trim()) ? entrance.trim() : "tilt-in";
-    doc.frame.entrance = { kind };
-    notes.push(`entrance ${kind}`);
-  } else {
-    delete doc.frame.entrance;
-  }
-  if (!off(launch.endCard)) {
+    const kind = entrance && /^(tilt-in|pull-out|rise|fade)$/.test(entrance.trim()) ? entrance.trim() : "tilt-in";
+    doc.frame.anim = { ...doc.frame.anim ?? {}, enter: kind };
+    notes.push(`enter ${kind}`);
+  } else if (doc.frame.anim?.enter !== void 0) {
+    const { enter: _enter, ...rest } = doc.frame.anim;
+    if (Object.keys(rest).length) doc.frame.anim = rest;
+    else delete doc.frame.anim;
+  }
+  const tWords = templateWords(words);
+  const keys = opts.mark ? { "stage-mark": opts.mark.key, "endcard-markimg": opts.mark.key } : void 0;
+  for (const t of opts.templates ?? []) {
+    const at2 = resolveAnchor(doc, t.at);
+    if (at2 === null) {
+      skipped.push(`${t.from}: ${anchorWord(t.at)} was not recorded`);
+      continue;
+    }
+    const applied = applyTemplate(t.doc, doc, {
+      at: at2,
+      from: t.from,
+      words: tWords,
+      keys
+    });
+    doc = applied.doc;
+    notes.push(`${t.from} at ${anchorWord(t.at)}`);
+    for (const n of applied.notes) skipped.push(`${t.from}: ${n}`);
+  }
+  const endCardRole = launch.endCard;
+  doc = dropTemplate(doc, END_CARD_FROM);
+  if (off(endCardRole)) {
+    if (doc.frame.anim?.exit !== void 0) {
+      const { exit: _exit, ...rest } = doc.frame.anim;
+      if (Object.keys(rest).length) doc.frame.anim = rest;
+      else delete doc.frame.anim;
+    }
+  } else if (onWord(endCardRole)) {
     const headline = (words.headline ?? "").trim();
     const brand = (words.brand ?? "").trim();
     const sub = [brand, (words.release ?? "").trim()].filter(Boolean).join(" ");
     if (headline || brand) {
-      const card = { seconds: 2.5 };
+      const card = { seconds: END_CARD_SECONDS };
       if (opts.ink) card.ink = opts.ink;
       if (headline) card.headline = headline;
       if (sub && sub !== headline) card.sub = sub;
       if (brand) card.wordmark = brand;
       if (opts.mark) card.mark = opts.mark;
-      doc.endCard = card;
+      doc.overlays = [
+        ...doc.overlays ?? [],
+        ...endCardClips(card, doc, outputLength(doc))
+      ];
+      doc.frame.anim = {
+        ...doc.frame.anim ?? {},
+        exit: { kind: "recede", seconds: END_CARD_RECEDE }
+      };
       notes.push("end card");
     } else {
       skipped.push(
         "no end card (no headline or wordmark in LAUNCH.md, BRAND.md or the flags)"
       );
     }
-  } else {
-    delete doc.endCard;
   }
   const kept = (doc.overlays ?? []).filter(
     (o) => !o.id.startsWith(CAPTION_ID_PREFIX)
@@ -3471,17 +3584,16 @@ function proposeMotion(input, opts) {
       );
       if (!step || step.skipped) continue;
       const t = stepOutputTime(rated, step, 0.2);
-      if (t === null || t < 0 || t > length - 1) continue;
+      if (t === null || t < 0 || t > footage - 1) continue;
       captionClips.push({
         id: `${CAPTION_ID_PREFIX}${c.step}`,
         kind: "text",
         text: c.caption,
         preset: "caption",
         start: +t.toFixed(3),
-        duration: Math.min(3.5, Math.max(2.5, length - t - 0.2)),
+        duration: Math.min(3.5, Math.max(2.5, footage - t - 0.2)),
         transform: { x: 0.5, y: 0.86, scale: 1, rotation: 0 },
-        enter: "rise",
-        exit: "fade",
+        anim: { enter: "rise", exit: "fade" },
         align: "center",
         box: { color: "rgba(17,17,17,0.72)" }
       });
@@ -3491,6 +3603,7 @@ function proposeMotion(input, opts) {
   const overlays = [...kept, ...captionClips];
   if (overlays.length) doc.overlays = overlays;
   else delete doc.overlays;
+  const length = docOutputDuration(doc);
   const clips = (doc.audio ?? []).filter(
     (a) => a.id !== BED_ID && !a.id.startsWith(CLICK_ID_PREFIX)
   );
@@ -3550,8 +3663,8 @@ function destinationMechanics(d, doc) {
   const sound = SOUND_DESTINATIONS.has(d.id);
   const portrait = d.px.w / d.px.h < 0.9;
   if (loop) {
-    unset.push("frame.entrance", "endCard");
-    notes.push("loop: no entrance, no end card");
+    unset.push("frame.anim", "frame.entrance", "endCard");
+    notes.push("loop: no card motion");
   }
   if (loop || !sound) {
     set.push("audio=[]");
@@ -3559,11 +3672,11 @@ function destinationMechanics(d, doc) {
   }
   if (loop || d.text === "none") {
     const kept = (doc.overlays ?? []).filter(
-      (o) => !o.id.startsWith(CAPTION_ID_PREFIX)
+      (o) => !o.id.startsWith(CAPTION_ID_PREFIX) && !(loop && o.from)
     );
     if (kept.length !== (doc.overlays ?? []).length) {
       set.push(`overlays=${JSON.stringify(kept)}`);
-      notes.push("no captions");
+      notes.push(loop ? "no template clips, no captions" : "no captions");
     }
   }
   if (portrait) {
@@ -4087,7 +4200,7 @@ async function deliverTake(browser, dir, opts) {
   const take = await loadTake(dir);
   if (!take.doc) throw new Error(`${dir} has no doc.json \u2014 run plan first`);
   const doc = take.doc;
-  const duration = totalDuration(ratedSegments5(doc));
+  const duration = docOutputDuration2(doc);
   const videoSeconds = opts.range ? Math.min(opts.range[1], duration) - Math.min(opts.range[0], duration) : duration;
   const outDir = resolve4(opts.outDir ?? join7(dir, "kit"));
   await mkdir4(outDir, { recursive: true });
@@ -4145,7 +4258,7 @@ async function deliverTake(browser, dir, opts) {
     }
     posterCardIds.add(d.id);
     const label = `${d.channel} ${d.asset}`;
-    const posterDuration = totalDuration(ratedSegments5(ref.doc));
+    const posterDuration = docOutputDuration2(ref.doc);
     const time = posterStillTime(ref.doc, posterDuration);
     opts.onPhase?.(
       `${label} (${specWords(d)}) from ${ref.from}${ref.vosId ? ` ${ref.vosId}` : ""}, the rest at ${time.toFixed(2)}s`
@@ -5701,10 +5814,12 @@ import {
   planAutoSpeed,
   planAutoZoom,
   projectFromArtifact,
-  withBackdrop
+  withBackdrop,
+  migrateMotion as migrateMotion2
 } from "@vosjs/studio-core";
 
 // src/plugin/reuse.ts
+import { docFreezes } from "@vosjs/studio-core";
 var MIN_SPAN = 0.15;
 function matchStep(old, newSteps) {
   const usable = (s) => !!s && s.skipped !== true;
@@ -5763,7 +5878,7 @@ function buildStepMap(oldSteps, newSteps, oldDuration, newDuration) {
   };
   return { map, unmatched, matched };
 }
-function resolveAnchor(anchor, newSteps) {
+function resolveAnchor2(anchor, newSteps) {
   const step = typeof anchor.step === "string" ? newSteps.find((s) => s.id === anchor.step) : newSteps.find((s) => s.step === anchor.step);
   if (!step || step.skipped) return null;
   const base = anchor.at === "end" ? step.tEnd : step.tStart;
@@ -5775,7 +5890,7 @@ function retimeSpans(kind, spans, stepMap, newSteps, newDuration, report) {
     const length = span.out - span.in;
     let nextIn = null;
     if (span.anchor) {
-      nextIn = resolveAnchor(span.anchor, newSteps);
+      nextIn = resolveAnchor2(span.anchor, newSteps);
       if (nextIn === null) {
         report.flagged.push(
           `${kind} ${span.id}: its anchored step (${String(span.anchor.step)}) is missing or skipped in the new recording \u2014 fell back to the step map`
@@ -5866,6 +5981,30 @@ function retimeCut(prev, newSteps, newDurationMs) {
     newDuration,
     report
   );
+  const freeze = [];
+  for (const f of docFreezes(prev)) {
+    let at2 = null;
+    if (f.anchor) {
+      at2 = resolveAnchor2(f.anchor, newSteps);
+      if (at2 === null) {
+        report.flagged.push(
+          `freeze ${f.id}: its anchored step (${String(f.anchor.step)}) is missing or skipped in the new recording \u2014 fell back to the step map`
+        );
+      } else report.anchored++;
+    }
+    if (at2 === null) {
+      at2 = stepMap.map(f.at);
+      report.mapped++;
+    }
+    if (at2 < 0 || at2 > newDuration) {
+      report.flagged.push(
+        `freeze ${f.id}: lands outside the new recording (${at2.toFixed(2)}s) \u2014 dropped`
+      );
+      continue;
+    }
+    freeze.push({ ...f, at: +at2.toFixed(3) });
+  }
+  freeze.sort((a, b) => a.at - b.at);
   const rejected = [];
   for (const lane of ["zoom", "tilt", "speed"]) {
     rejected.push(
@@ -5879,7 +6018,7 @@ function retimeCut(prev, newSteps, newDurationMs) {
       )
     );
   }
-  return { segments, zoom, speed, tilt, rejected, report };
+  return { segments, zoom, speed, freeze, tilt, rejected, report };
 }
 
 // src/plugin/plan.ts
@@ -5908,7 +6047,7 @@ function patchStageWords(doc, words) {
 }
 function applyStyle(seed, doc, opts) {
   const parts = layoutOf(seed);
-  const carries = parts.clips.length > 0 || parts.lean || parts.hold;
+  const carries = parts.clips.length > 0 || parts.lean || parts.freeze;
   if (!carries) return { doc: copyStyle(seed, doc), layout: void 0 };
   const keys = opts.mark ? { "stage-mark": opts.mark.key } : void 0;
   const { doc: next, notes } = copyLayout(seed, copyStyle(seed, doc), { keys });
@@ -5924,7 +6063,7 @@ async function planTake(dir, opts = {}) {
   let fresh;
   let layout;
   if (opts.reuse) {
-    const prev = opts.reuse.doc;
+    const prev = migrateMotion2(opts.reuse.doc);
     const artifact = {
       videoKey: RECORDING_NAME,
       cursor,
@@ -5934,10 +6073,7 @@ async function planTake(dir, opts = {}) {
     doc = copyStyle(prev, doc);
     const rt = retimeCut(prev, meta.steps ?? [], meta.durationMs);
     doc.segments = rt.segments;
-    const prevHold = prev.segments.at(-1)?.hold;
-    const last = doc.segments.at(-1);
-    if (typeof prevHold === "number" && prevHold > 0 && last)
-      last.hold = prevHold;
+    if (rt.freeze.length) doc.freeze = rt.freeze;
     if (rt.rejected.length) doc.rejected = rt.rejected;
     const manualZoom = rt.zoom;
     const autoZoom = planAutoZoom(doc.source.cursor, {
@@ -5959,7 +6095,6 @@ async function planTake(dir, opts = {}) {
     if (prev.objects?.length) doc.objects = prev.objects;
     if (prev.audio.length) doc.audio = prev.audio;
     if (prev.camMotion?.length) doc.camMotion = prev.camMotion;
-    if (prev.endCard) doc.endCard = structuredClone(prev.endCard);
     await writeJson(take.paths.doc, doc, true);
     return {
       doc,
@@ -8657,7 +8792,7 @@ var HELP = `vos \u2014 record a browser flow, plan effects, render a product vid
 Take pipeline
   vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--max-duration <s>] [--background <slug|url|none>] [render flags] [--json]
   vos record --actions actions.json [--url <url>] [--out take] [--strict] [--max-duration <s>] [--background <slug|url|none>] [--json]
-  vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--background <slug|url|none>] [--motion] [--headline "\u2026"] [--kicker "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md] [--music <slug|mood|none>] [--entrance tilt-in|pull-out|rise|none] [--end-card none] [--captions none] [--clicks none] [--release v2.1] [--json]
+  vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--with <doc.json|vosId>[@end|@start|@step:<id>|@<s>]]... [--background <slug|url|none>] [--motion] [--headline "\u2026"] [--kicker "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md] [--music <slug|mood|none>] [--entrance tilt-in|pull-out|rise|fade|none] [--end-card on|none|<doc.json|vosId>] [--captions none] [--clicks none] [--release v2.1] [--json]
   vos render <take> [out.webm] [--width] [--height] [--fps] [--format webm|mp4] [--parallel N] [--range a..b] [--draft] [--frame <kind>] [--background <url|slug>] [--set <path=value>]... [--json]
   vos frames <take> [--times 0,25%,50%,75%,100%] [--frame <t>] [--at-zooms] [--at-moments] [--size WxH] [--out dir] [--background <url|slug>] [--set <path=value>]... [--json]
   vos deliver <take> --to cws,producthunt,x,linkedin,og,github,youtube (or all) [--launch LAUNCH.md] [--look plate|gradient|dark|none] [--brand BRAND.md] [--composed] [--set path=value] [--release v2.1] [--out dir] [--times a,b] [--range a..b] [--parallel N] [--json]
@@ -8772,7 +8907,7 @@ Screenshot-genre stills never take a look.
 A POSTER is a document, never a template: a plain take whose card sits
 where the poster wants it (frame.inset), leans (the tilt track), carries
 the words and the mark as clips (ids stage-title, stage-kicker,
-stage-brand, stage-mark) and ends on a trailing hold whose start is the
+stage-brand, stage-mark) and ends on a trailing freeze whose start is the
 still. Card-genre destinations (OG, LinkedIn, X, YouTube thumbnail, the
 CWS tile + marquee, GitHub social preview) render from the poster
 document of their aspect CLASS (landscape, square, portrait, tile), found
@@ -8785,20 +8920,28 @@ deliver renders and verifies; it composes nothing. The composition is
 made with plan --style <poster>, which copies a poster's layout onto a
 take (its card placement, its stage clips with the release's words
 patched in from LAUNCH.md's headline and kicker roles or --headline and
---kicker, its rest lean, its hold), or by hand in doc.json.
-The cut's MOTION is the document's too. plan proposes it on a fresh plan
-(--motion re-proposes onto an existing doc.json, replacing only its own
-proposals): the card's ENTRANCE (tilt-in by default: the card swings in
-from a perspective pose and settles), the END CARD (the last frame holds
-2.5 s while the card recedes and the headline, the release line and the
-wordmark rise; the brand's mark from BRAND.md logoUrl above them), a
-CAPTION per actions.json step at the step's moment, a music BED from
-LAUNCH.md's music role (a catalog slug or a mood) and a click sound on
-every press when the take has no mic. LAUNCH.md's entrance, endCard,
-captions, music and clicks roles, or the flags, change or switch each
-off; a deleted proposal stays deleted on a refresh. deliver applies each
-destination's MECHANICS and nothing more: the README loop plays no
-entrance, end card or sound; a channel that autoplays muted drops the
+--kicker, its rest lean, its freeze), or by hand in doc.json.
+The cut's MOTION is the document's too, in ONE vocabulary: every visual
+thing (the card, a text, image or video clip, a prop) carries anim.enter,
+anim.exit and anim.idle; the output lasts until the last clip ends, and
+past its footage the card holds its last frame at the pose its exit
+settled into. There is no end-card field and no entrance field: a
+COMPONENT is a TEMPLATE, a plain take on a shelf whose clips carry stable
+ids, laid onto the take at an anchor (LAUNCH.md with: <ref>[@end|@start|
+@step:<id>|@<s>], comma list; --with the same, repeatable; endCard: <ref>
+names one at the end), its clips stamped with where they came from
+(from). plan proposes on a fresh plan (--motion re-proposes, replacing
+only its own work): the card's ENTER (tilt-in by default), the templates
+named, the house END CARD when endCard is on or absent (clips after the
+footage: the headline, the release line, the wordmark, the mark from
+BRAND.md logoUrl, over a card that recedes; from: endcard), a CAPTION per
+actions.json step at the step's moment, a music BED from LAUNCH.md's music
+role (a catalog slug or a mood) and a click sound on every press when the
+take has no mic. LAUNCH.md's entrance, endCard, captions, music and clicks
+roles, or the flags, change or switch each off; a deleted proposal stays
+deleted on a refresh. deliver applies each destination's MECHANICS and
+nothing more: the README loop drops the card's motion, every clip a
+template placed and every sound; a channel that autoplays muted drops the
 bed; the 9:16 cut is a reframe, not a letterbox, and the crop follows
 the camera. Screenshot-genre
 destinations (CWS screenshots, the PH gallery) are the real page at that
@@ -9109,11 +9252,15 @@ async function cmdCreate2(argv) {
   }
 }
 async function cmdPlan(argv) {
-  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS5);
+  const { positionals, flags, multi } = parseArgs(
+    argv,
+    BOOLEAN_FLAGS5,
+    /* @__PURE__ */ new Set(["with"])
+  );
   const dir = positionals[0];
   if (!dir)
     throw new UsageError(
-      'vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--motion] [--headline "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md]'
+      'vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--with <doc.json|vosId>[@end|@start|@step:<id>|@<seconds>]]... [--motion] [--headline "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md]'
     );
   const r = createReporter(flags.json === true);
   if (flags.fresh === true) {
@@ -9136,7 +9283,7 @@ async function cmdPlan(argv) {
   const style = await resolveStyleRef(flags);
   const hasDoc = existsSync14(join17(dir, "doc.json"));
   const backdrop = hasDoc ? null : await takeBackdrop(flags, r);
-  const release = await releaseInputs(dir, flags, r);
+  const release = await releaseInputs(dir, flags, r, multi.with ?? []);
   const motionWanted = !hasDoc || flags.motion === true || flags.fresh === true;
   const s = await planTake(dir, {
     ...style ? { style } : {},
@@ -9152,6 +9299,7 @@ async function cmdPlan(argv) {
         mark: release.mark,
         captions: release.captions,
         catalog: release.catalog,
+        templates: release.templates,
         again: flags.motion === true
       }
     } : {}
@@ -9160,7 +9308,7 @@ async function cmdPlan(argv) {
   layout from ${s.styleFrom}: ${[
     s.layout.clips.length ? `${s.layout.clips.length} stage clip(s)` : "",
     s.layout.lean ? "the rest lean" : "",
-    s.layout.hold ? "the hold" : ""
+    s.layout.freeze ? "the freeze" : ""
   ].filter(Boolean).join(", ")}` + (s.layout.notes.length ? `
     ${s.layout.notes.join("\n    ")}` : "") : "";
   const motionLines = s.motion ? (s.motion.notes.length ? `
@@ -9188,7 +9336,7 @@ async function cmdPlan(argv) {
   );
   return EXIT_OK;
 }
-async function releaseInputs(dir, flags, r) {
+async function releaseInputs(dir, flags, r, withRefs = []) {
   let lookPick;
   try {
     lookPick = await resolveLook(dir, {
@@ -9243,13 +9391,36 @@ async function releaseInputs(dir, flags, r) {
     const step = st;
     return typeof step.caption === "string" && step.caption.trim() ? [{ step: i, id: step.id, caption: step.caption.trim() }] : [];
   });
+  const refs = [];
+  const parseRef = (raw, fallback) => {
+    const m = /^(.*?)(?:@(end|start|step:[^@\s]+|\d+(?:\.\d+)?))?$/.exec(
+      raw.trim()
+    );
+    const ref = m?.[1]?.trim() ?? raw.trim();
+    const anchor = m?.[2];
+    const at2 = !anchor ? fallback : anchor === "end" || anchor === "start" ? anchor : anchor.startsWith("step:") ? { step: anchor.slice(5) } : Number(anchor);
+    if (ref) refs.push({ ref, at: at2 });
+  };
+  for (const raw of withRefs) parseRef(raw, "end");
+  for (const raw of (launchRoles.with ?? "").split(","))
+    if (raw.trim()) parseRef(raw, "end");
+  const endCardRole = launchRoles.endCard;
+  if (endCardRole && !/^(none|off|no|false|on|yes|true)$/i.test(endCardRole.trim()))
+    parseRef(endCardRole, "end");
+  const templates = [];
+  for (const { ref, at: at2 } of refs) {
+    const found = await resolveDocRef(ref, flags, "--with");
+    templates.push({ from: found.from, doc: found.doc, at: at2 });
+    r.log(`template: ${found.from}`);
+  }
   return {
     words,
     launchRoles,
     ink: endCardInk(lookPick.look, lookPick.roles),
     mark,
     captions,
-    catalog
+    catalog,
+    templates
   };
 }
 async function cmdRender(argv) {
@@ -9344,7 +9515,7 @@ async function cmdFrames(argv) {
     if (!m) throw new UsageError("--size expects WxH (e.g. --size 1280x800)");
     size = { width: Number(m[1]), height: Number(m[2]) };
   }
-  const duration = totalDuration2(ratedSegments6(take.doc));
+  const duration = docOutputDuration3(take.doc);
   const frameRaw = strFlag(flags, "frame");
   const timesRaw = strFlag(flags, "times");
   const atZooms = flags["at-zooms"] === true;
@@ -9431,7 +9602,7 @@ async function cmdDeliver(argv) {
   }
   const take = await loadTake(dir);
   if (!take.doc) throw new UsageError(`${dir} has no doc.json \u2014 run plan first`);
-  const duration = totalDuration2(ratedSegments6(take.doc));
+  const duration = docOutputDuration3(take.doc);
   const timesRaw = strFlag(flags, "times");
   let times;
   if (timesRaw !== void 0) {
@@ -9509,6 +9680,10 @@ Store uploads stay manual: hand the human this directory and the manifest.`
 async function resolveStyleRef(flags) {
   const styleRef = strFlag(flags, "style");
   if (!styleRef) return null;
+  return resolveDocRef(styleRef, flags, "--style");
+}
+async function resolveDocRef(ref, flags, what) {
+  const styleRef = ref;
   const file = existsSync14(styleRef) ? resolve9(
     styleRef,
     existsSync14(join17(styleRef, "doc.json")) ? "doc.json" : ""
@@ -9516,7 +9691,9 @@ async function resolveStyleRef(flags) {
   if (file && existsSync14(file)) {
     return {
       from: file,
-      doc: JSON.parse(await readFile14(file, "utf8"))
+      doc: migrateHostedDoc5(
+        JSON.parse(await readFile14(file, "utf8"))
+      )
     };
   }
   const origin = platformOrigin({
@@ -9528,7 +9705,7 @@ async function resolveStyleRef(flags) {
   const head = meta.body.vos?.currentVersionId;
   if (meta.status !== 200 || !head)
     throw new UsageError(
-      `--style: ${styleRef} is neither a doc.json nor a vos I can read`
+      `${what}: ${styleRef} is neither a doc.json nor a vos I can read`
     );
   const doc = await apiJson(
     origin,
@@ -9536,7 +9713,7 @@ async function resolveStyleRef(flags) {
     { key }
   );
   if (doc.status !== 200)
-    throw new UsageError(`--style: ${styleRef} carries no doc (is it a take?)`);
+    throw new UsageError(`${what}: ${styleRef} carries no doc (is it a take?)`);
   return {
     from: `${origin}/vos/${styleRef}`,
     doc: migrateHostedDoc5(doc.body)
@@ -9960,4 +10137,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-4LLBPFCW.js.map
+//# sourceMappingURL=chunk-4IWHZBIY.js.map