@vosjs/cli 0.18.0 → 0.20.0

package/dist/{chunk-HYUVNBEM.js → chunk-ZONOZZZY.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 {
@@ -181,6 +180,13 @@ import {
   CAM_SIZE_MAX,
   CAM_SIZE_MIN,
   CAM_SPAN_MIN,
+  CARD_ENTER_KINDS,
+  CARD_EXIT_KINDS,
+  IDLE_KINDS,
+  MEDIA_ENTER_KINDS,
+  MEDIA_EXIT_KINDS,
+  TEXT_ENTER_KINDS,
+  TEXT_EXIT_KINDS,
   EXPORT_RESOLUTION_OPTIONS,
   SPEED_RATE_MAX,
   SPEED_RATE_MIN,
@@ -196,6 +202,79 @@ import {
   zoomCoversRect
 } from "@vosjs/studio-core";
 import { TYPEFACE_CATALOG, findFontFamily, findTypeface } from "@vosjs/shared";
+var STEP_KINDS_ALL = [
+  "none",
+  "fade",
+  "rise",
+  "pop",
+  "blur",
+  "typewriter",
+  "tilt-in",
+  "pull-out",
+  "recede"
+];
+var STEP_UNITS = ["block", "line", "word", "char"];
+var STEP_DIRS = ["forward", "reverse", "center"];
+function lintAnim(name, anim, kinds, problems) {
+  if (anim === void 0) return;
+  if (typeof anim !== "object" || anim === null || Array.isArray(anim)) {
+    problems.push(`${name}.anim must be { enter?, exit?, idle? }`);
+    return;
+  }
+  const a = anim;
+  for (const side of ["enter", "exit"]) {
+    const step = a[side];
+    if (step === void 0) continue;
+    const allowed = kinds[side];
+    const spelled = typeof step === "string" ? step : null;
+    const obj = typeof step === "object" && step !== null && !Array.isArray(step) ? step : null;
+    const kind = spelled ?? (obj ? obj.kind : void 0);
+    if (typeof kind !== "string" || !STEP_KINDS_ALL.includes(kind)) {
+      problems.push(
+        `${name}.anim.${side} must be a kind or { kind, seconds?${kinds.words ? ", unit?, direction?, stagger?" : ""} } (got ${JSON.stringify(step)})`
+      );
+      continue;
+    }
+    if (!allowed.includes(kind)) {
+      problems.push(
+        `${name}.anim.${side} cannot be "${kind}" here; one of ${allowed.join(" | ")}`
+      );
+    }
+    if (!obj) continue;
+    const secs = obj.seconds;
+    if (secs !== void 0 && (typeof secs !== "number" || !Number.isFinite(secs) || secs < 0.05 || secs > 3)) {
+      problems.push(`${name}.anim.${side}.seconds must be 0.05..3`);
+    }
+    for (const key of ["unit", "direction", "stagger"]) {
+      if (obj[key] === void 0) continue;
+      if (!kinds.words) {
+        problems.push(`${name}.anim.${side}.${key} is for words only`);
+        continue;
+      }
+      if (key === "unit" && (typeof obj.unit !== "string" || !STEP_UNITS.includes(obj.unit)))
+        problems.push(
+          `${name}.anim.${side}.unit must be ${STEP_UNITS.join("|")}`
+        );
+      if (key === "direction" && (typeof obj.direction !== "string" || !STEP_DIRS.includes(obj.direction)))
+        problems.push(
+          `${name}.anim.${side}.direction must be ${STEP_DIRS.join("|")}`
+        );
+      if (key === "stagger" && (typeof obj.stagger !== "number" || obj.stagger < 0 || obj.stagger > 2))
+        problems.push(`${name}.anim.${side}.stagger must be seconds in 0..2`);
+    }
+  }
+  if (a.idle !== void 0 && a.idle !== null) {
+    if (!kinds.idle) problems.push(`${name}.anim.idle is for props only`);
+    else if (typeof a.idle !== "string" || !kinds.idle.includes(a.idle))
+      problems.push(
+        `${name}.anim.idle must be ${kinds.idle.join(" | ")} | null`
+      );
+  }
+}
+function lintFrom(name, from, problems) {
+  if (from !== void 0 && (typeof from !== "string" || !from.length))
+    problems.push(`${name}.from must be the id of the template that placed it`);
+}
 var EPS = 1e-3;
 var isNum = (v) => typeof v === "number" && Number.isFinite(v);
 var isObj = (v) => typeof v === "object" && v !== null;
@@ -327,20 +406,31 @@ function lintDoc(docIn) {
     }
     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?}");
+        problems.push(
+          "endCard must be an object: {seconds?, headline?, sub?, wordmark?}"
+        );
       } else {
         const ec = endCard;
         if (ec.seconds !== void 0 && (!isNum(ec.seconds) || ec.seconds < 1 || ec.seconds > 8)) {
-          problems.push(`endCard.seconds must be 1..8 (got ${String(ec.seconds)}); absent = 2.5`);
+          problems.push(
+            `endCard.seconds must be 1..8 (got ${String(ec.seconds)}); absent = 2.5`
+          );
         }
         for (const k of ["headline", "sub", "wordmark"]) {
           if (ec[k] !== void 0 && typeof ec[k] !== "string") {
             problems.push(`endCard.${k} must be a string`);
           }
         }
-        if (!["headline", "sub", "wordmark"].some((k) => typeof ec[k] === "string" && ec[k].trim())) {
-          warnings.push("endCard carries no words: it holds the last frame and recedes the card over nothing");
+        if (!["headline", "sub", "wordmark"].some(
+          (k) => typeof ec[k] === "string" && ec[k].trim()
+        )) {
+          warnings.push(
+            "endCard carries no words: it holds the last frame and recedes the card over nothing"
+          );
         }
       }
     }
@@ -565,6 +655,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(
@@ -579,6 +672,17 @@ function lintDoc(docIn) {
           }
         }
       }
+      lintAnim(
+        "frame",
+        frame.anim,
+        {
+          enter: CARD_ENTER_KINDS,
+          exit: CARD_EXIT_KINDS,
+          idle: null,
+          words: false
+        },
+        problems
+      );
       if (frame.focusFollow !== void 0 && frame.focusFollow !== "camera") {
         problems.push(
           `frame.focusFollow must be "camera" (got ${String(frame.focusFollow)}); it reads under fit: cover only`
@@ -826,6 +930,27 @@ 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,
+      o.kind === "text" ? {
+        enter: TEXT_ENTER_KINDS,
+        exit: TEXT_EXIT_KINDS,
+        idle: null,
+        words: true
+      } : {
+        enter: MEDIA_ENTER_KINDS,
+        exit: MEDIA_EXIT_KINDS,
+        idle: null,
+        words: false
+      },
+      problems
+    );
+    lintFrom(name, o.from, problems);
     if (o.motion !== void 0) {
       if (!Array.isArray(o.motion)) {
         problems.push(`${name}.motion must be an array of poses`);
@@ -956,6 +1081,20 @@ 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,
+      {
+        enter: MEDIA_ENTER_KINDS,
+        exit: MEDIA_EXIT_KINDS,
+        idle: IDLE_KINDS,
+        words: false
+      },
+      problems
+    );
+    lintFrom(name, o.from, problems);
     if (o.motion !== void 0) {
       if (!Array.isArray(o.motion)) {
         problems.push(`${name}.motion must be an array of poses`);
@@ -2631,7 +2770,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";
@@ -2643,7 +2781,7 @@ import {
   houseLook,
   isLookKind,
   lookFromBrand,
-  ratedSegments as ratedSegments5
+  docOutputDuration as docOutputDuration2
 } from "@vosjs/studio-core";
 
 // src/plugin/renderTake.ts
@@ -3259,7 +3397,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",
@@ -3294,41 +3443,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)
@@ -3343,17 +3554,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)" }
       });
@@ -3363,6 +3573,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)
   );
@@ -3422,8 +3633,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=[]");
@@ -3431,11 +3642,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) {
@@ -3959,7 +4170,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 });
@@ -4017,7 +4228,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`
@@ -5573,7 +5784,8 @@ import {
   planAutoSpeed,
   planAutoZoom,
   projectFromArtifact,
-  withBackdrop
+  withBackdrop,
+  migrateMotion as migrateMotion2
 } from "@vosjs/studio-core";
 
 // src/plugin/reuse.ts
@@ -5635,7 +5847,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;
@@ -5647,7 +5859,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`
@@ -5796,7 +6008,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,
@@ -5831,7 +6043,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,
@@ -8529,7 +8740,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]
@@ -8658,19 +8869,27 @@ 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
+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
@@ -8981,11 +9200,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) {
@@ -9008,7 +9231,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 } : {},
@@ -9024,6 +9247,7 @@ async function cmdPlan(argv) {
         mark: release.mark,
         captions: release.captions,
         catalog: release.catalog,
+        templates: release.templates,
         again: flags.motion === true
       }
     } : {}
@@ -9060,7 +9284,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, {
@@ -9115,13 +9339,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) {
@@ -9216,7 +9463,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;
@@ -9303,7 +9550,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) {
@@ -9381,6 +9628,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" : ""
@@ -9388,7 +9639,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({
@@ -9400,7 +9653,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,
@@ -9408,7 +9661,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)
@@ -9832,4 +10085,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-HYUVNBEM.js.map
+//# sourceMappingURL=chunk-ZONOZZZY.js.map