@vosjs/cli 0.19.0 → 0.20.0

package/README.md

@@ -77,21 +77,21 @@ vos record --actions actions.json --out take --strict   # footage replaced; the
 vos plan take --reuse                                   # re-time that cut onto the new recording; what could not follow is named
 ```
 
-| Verb     | Flags                                                                                                                                                                                                                                                                                                            |
-| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                         |
-| `create` | The `record` flags plus the render flags (`--width` `--height` `--fps` `--format` `--parallel` `--draft` `--frame` `--set`), no `--range`. With `--strict` an incomplete recording exits 2 before anything is rendered                                                                                           |
-| `plan`   | `--fresh` (discard the current plan) `--reuse` `--from <doc.json>` (defaults to `<take>/doc.prev.json`) `--style <doc.json\|take\|vosId>` `--background` `--motion` (re-propose the motion) `--headline` `--kicker` `--launch` `--brand` `--music` `--entrance` `--end-card` `--captions` `--clicks` `--release` |
-| `digest` | `--out <take>/digest` `--full 960` `--crop 640` (image long edges, the token budget) `--no-frames` `--transcript <file>` (Whisper-shaped segments merged as `said`) `--style <ref>` (report a reference document's style fields)                                                                                 |
-| `frames` | `--times 0,25%,50%,75%,100%` (the default selector, output seconds or percent) `--frame <t>` `--at-zooms` `--at-moments` `--size WxH` `--out <take>/stills` `--background` `--set …`; writes `stills.json`                                                                                                       |
-| `render` | `--width` `--height` `--fps` `--format webm\|mp4` `--parallel N` (1..16 sessions) `--range a..b` (output seconds; keeps its audio) `--draft` `--frame <kind>` `--background` `--set …`; `out` defaults to `<take>/out.<format>`                                                                                  |
-| `open`   | `--studio http://localhost:6060` `--print` (print the URL, do not launch a browser)                                                                                                                                                                                                                              |
+| Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                                                                         |
+| `create` | The `record` flags plus the render flags (`--width` `--height` `--fps` `--format` `--parallel` `--draft` `--frame` `--set`), no `--range`. With `--strict` an incomplete recording exits 2 before anything is rendered                                                                                                                                                                                                           |
+| `plan`   | `--fresh` (discard the current plan) `--reuse` `--from <doc.json>` (defaults to `<take>/doc.prev.json`) `--style <doc.json\|take\|vosId>` `--with <doc.json\|take\|vosId>[@end\|@start\|@step:<id>\|@<seconds>]` (a template, repeatable) `--background` `--motion` (re-propose the motion) `--headline` `--kicker` `--launch` `--brand` `--music` `--entrance` `--end-card on\|none\|<ref>` `--captions` `--clicks` `--release` |
+| `digest` | `--out <take>/digest` `--full 960` `--crop 640` (image long edges, the token budget) `--no-frames` `--transcript <file>` (Whisper-shaped segments merged as `said`) `--style <ref>` (report a reference document's style fields)                                                                                                                                                                                                 |
+| `frames` | `--times 0,25%,50%,75%,100%` (the default selector, output seconds or percent) `--frame <t>` `--at-zooms` `--at-moments` `--size WxH` `--out <take>/stills` `--background` `--set …`; writes `stills.json`                                                                                                                                                                                                                       |
+| `render` | `--width` `--height` `--fps` `--format webm\|mp4` `--parallel N` (1..16 sessions) `--range a..b` (output seconds; keeps its audio) `--draft` `--frame <kind>` `--background` `--set …`; `out` defaults to `<take>/out.<format>`                                                                                                                                                                                                  |
+| `open`   | `--studio http://localhost:6060` `--print` (print the URL, do not launch a browser)                                                                                                                                                                                                                                                                                                                                              |
 
 **Digest first.** `vos digest <take>` is how an agent sees a recording without reading the video. It writes `digest/digest.json`: one moment per thing the cursor track says mattered (click clusters, typing sessions, scroll runs, dwells, idle gaps, head, tail, and frame-diff scene changes), each with source and output extents, a normalized `focus` and `rect` you can copy into a zoom span, per-second `activity`, and the planners' `proposed` span ids; plus one footage frame and a crop around the target per moment, and `sheet.png`, the contact sheet. Read the JSON, then the sheet, then a crop only where you must decide. `vos validate` then warns when a zoom does not contain what was clicked under it, and `vos frames --at-moments` renders the composed output at every moment so a still and its footage crop share an id.
 
 **A series shares its look by data.** `vos plan <take> --style <seed doc.json | vosId>` copies the seed's `zoomStyle`, `zoomParams`, `speedParams`, `tiltStyle`, `frame`, `cursor`, `cam` and `export` onto a new take (never its spans, overlays or audio) and re-plans the automatic spans under them. A seed that is a POSTER carries its layout too: its card placement, its `stage-*` clips by id (with the release's words from LAUNCH.md's `headline` and `kicker` roles, BRAND.md's `wordmark`, or `--headline` and `--kicker` patched in; the brand's mark from BRAND.md `logoUrl` fetched into `<take>/brand/` for `stage-mark`), its rest lean, its trailing hold. What could not follow is said in words.
 
-**The cut's motion is the document's.** A fresh `vos plan` proposes the card's entrance, the end card, a caption per `actions.json` step, a music bed and click sounds from LAUNCH.md's `entrance`, `endCard`, `captions`, `music` and `clicks` roles (or the flags), as data in doc.json with stable ids (`bed`, `click-<n>`, `caption-<step>`), so the studio shows what the kit will render; a refresh never re-proposes (a deleted end card stays deleted) and `--motion` re-proposes on purpose, replacing only its own proposals.
+**The cut's motion is the document's, in one vocabulary.** Every visual thing carries `anim` (`enter`, `exit`, `idle`; a kind, or a step with its seconds and, for words, `unit`, `direction`, `stagger`): the card (`frame.anim`, entering by `tilt-in`, `pull-out`, `rise` or `fade` and leaving by `recede` or `fade`), a text, image or video clip, a prop. The output lasts until the last clip ends; past its footage the card holds its last frame at the pose its exit settled into, and a segment's `hold` is the freeze primitive. 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 a take at an anchor and stamped `from` with where its clips came from. A fresh `vos plan` proposes the card's enter, the templates the recipe names (`LAUNCH.md` `with: <ref>[@end|@start|@step:<id>|@<seconds>], …` or `--with`, repeatable; `endCard: <ref>` names one at the end), the house end card when `endCard` is on or absent (the headline, the release line, the wordmark and BRAND.md's mark as clips after the footage over a receding card, `from: endcard`), a caption per `actions.json` step, a music bed and click sounds, from LAUNCH.md's `entrance`, `endCard`, `with`, `captions`, `music` and `clicks` roles (or the flags), as data in doc.json with stable ids (`bed`, `click-<n>`, `caption-<step>`), so the studio shows what the kit will render; a refresh never re-proposes (a deleted clip stays deleted) and `--motion` re-proposes on purpose, replacing only its own work. A document written in the older spellings (`frame.entrance`, `endCard`, a clip's `enter`/`exit`/`fx`, a prop's `animation`) is read into the vocabulary and `vos validate` says so.
 
 **A fresh take opens on a backdrop.** `create`, `record` and `plan` put the first ready loop from `GET /api/backdrops` behind the card (its ground colour as `frame.background`); `--background <slug|url|none>` overrides it, and offline the frame stays bare with a note.
 
@@ -186,7 +186,7 @@ vos brand https://your.app --out BRAND.md                      # the brand kit,
 
 [`schema/channel-specs.json`](./schema/channel-specs.json) holds per-channel launch-asset specs: dimensions, byte and duration ceilings, and a genre per image destination (`screenshot` is the real page from the take, full bleed; `card` is a composed cover). Channels: `cws`, `producthunt` (`ph`), `x`, `linkedin` (`li`), `og`, `github` (`gh`), `youtube` (`yt`), `shorts-linkedin` (`shorts`), or `all`. `vos deliver <take> --to <channels>` loops them in one pass and writes `kit.json`, the manifest the `launch-kit` skill builds the rest of the release around; an asset that misses its spec lands in `skipped[]` with the reason, and the verb exits 1 when nothing was produced. Flags: `--release <tag>`, `--out <take>/kit`, `--times`, `--range`, `--parallel`, `--launch LAUNCH.md`, `--look`, `--brand`, `--composed` (keep the cut's camera and chrome on screenshot stills instead of the full-bleed page), `--set`, `--background`. `vos validate` reads a kit back from its bytes (a `.png` that is WebP, a lying size or duration, a set under its count, a byte ceiling).
 
-**A poster is a document, and deliver renders it.** A card-genre destination (OG, LinkedIn, X, the YouTube thumbnail, the CWS tile and marquee, the GitHub social preview) renders from the poster document of its aspect class (`landscape`, `square`, `portrait`, `tile`), found beside the take as `poster/<class>/doc.json` (`poster/doc.json` serves every class) or named in LAUNCH.md (`poster: <path>`, `poster-<class>: <path>`, a path to a doc.json or to a pulled poster take), at the document's REST (the trailing hold's start, the composed frame before nothing moves). The poster is a plain take document: the card placed by `frame.inset`, leaned by the tilt track, the words and the mark as `stage-*` clips, a trailing `hold`; an agent writes it with `vos plan --style <poster>` from a poster on a shelf, or by hand, and pushes it like any take. `kit.json` records `source: "poster"`, the class, the file, the vos it tracks, the shot rect and the text boxes read from the document. A class with no document is the take's own frame, said once. Deliver composes nothing; it applies each video destination's mechanics (the README loop plays no entrance, end card, captions or sound; a channel that autoplays muted drops the bed; the 9:16 cut reframes and follows the camera) and verifies.
+**A poster is a document, and deliver renders it.** A card-genre destination (OG, LinkedIn, X, the YouTube thumbnail, the CWS tile and marquee, the GitHub social preview) renders from the poster document of its aspect class (`landscape`, `square`, `portrait`, `tile`), found beside the take as `poster/<class>/doc.json` (`poster/doc.json` serves every class) or named in LAUNCH.md (`poster: <path>`, `poster-<class>: <path>`, a path to a doc.json or to a pulled poster take), at the document's REST (the trailing hold's start, the composed frame before nothing moves). The poster is a plain take document: the card placed by `frame.inset`, leaned by the tilt track, the words and the mark as `stage-*` clips, a trailing `hold`; an agent writes it with `vos plan --style <poster>` from a poster on a shelf, or by hand, and pushes it like any take. `kit.json` records `source: "poster"`, the class, the file, the vos it tracks, the shot rect and the text boxes read from the document. A class with no document is the take's own frame, said once. Deliver composes nothing; it applies each video destination's mechanics (the README loop drops the card's motion, every clip a template placed, the captions and the sound; a channel that autoplays muted drops the bed; the 9:16 cut reframes and follows the camera) and verifies.
 
 `vos brand <url>` reads the site's `/design.md` first (the convention beside `/llms.txt`), then `/llms.txt`, then witnesses one page, and writes `BRAND.md`: the palette, faces, marks and the avoid list, with the provenance of every value, so a brand is resolved before any asset is authored.
 

package/dist/{chunk-4LLBPFCW.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 {
@@ -407,6 +406,9 @@ 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?}"
@@ -653,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(
@@ -925,6 +930,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 +1081,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 +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";
@@ -2771,7 +2781,7 @@ import {
   houseLook,
   isLookKind,
   lookFromBrand,
-  ratedSegments as ratedSegments5
+  docOutputDuration as docOutputDuration2
 } from "@vosjs/studio-core";
 
 // src/plugin/renderTake.ts
@@ -3387,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",
@@ -3422,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)
@@ -3471,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)" }
       });
@@ -3491,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)
   );
@@ -3550,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=[]");
@@ -3559,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) {
@@ -4087,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 });
@@ -4145,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`
@@ -5701,7 +5784,8 @@ import {
   planAutoSpeed,
   planAutoZoom,
   projectFromArtifact,
-  withBackdrop
+  withBackdrop,
+  migrateMotion as migrateMotion2
 } from "@vosjs/studio-core";
 
 // src/plugin/reuse.ts
@@ -5763,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;
@@ -5775,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`
@@ -5924,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,
@@ -5959,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,
@@ -8657,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]
@@ -8786,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
@@ -9109,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) {
@@ -9136,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 } : {},
@@ -9152,6 +9247,7 @@ async function cmdPlan(argv) {
         mark: release.mark,
         captions: release.captions,
         catalog: release.catalog,
+        templates: release.templates,
         again: flags.motion === true
       }
     } : {}
@@ -9188,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, {
@@ -9243,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) {
@@ -9344,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;
@@ -9431,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) {
@@ -9509,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" : ""
@@ -9516,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({
@@ -9528,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,
@@ -9536,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)
@@ -9960,4 +10085,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-4LLBPFCW.js.map
+//# sourceMappingURL=chunk-ZONOZZZY.js.map