@vosjs/cli 0.21.0 → 0.23.0

package/README.md

@@ -91,7 +91,7 @@ vos plan take --reuse                                   # re-time that cut onto
 
 **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 freeze. What could not follow is said in words.
 
-**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. A FREEZE (`freeze: [{id, at, seconds}]`, a source moment held for output seconds, beside the speed spans on the retime lane) freezes the footage anywhere, the middle of the take included; a segment's older `hold` is read as a freeze at its end. 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.
+**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; the card is on screen exactly while its clip runs (the footage, freezes included) and leaves at its end, so its `exit` plays over the clip's last seconds like every clip's; past the footage the clips play over the ground alone. A FREEZE (`freeze: [{id, at, seconds}]`, a source moment held for output seconds, beside the speed spans on the retime lane) freezes the footage anywhere, the middle of the take included; a segment's older `hold` is read as a freeze at its end. 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 END CARD when `endCard` is on or absent: the official `End card` template on vos.so (the platform's `Templates` project, promoted; any official template resolves by its title, `--with "End card"`, `--style "Split cover, landscape"`), laid at the end with the release's words and BRAND.md's mark, stamped `from: endcard`; offline, the house clips stand in (a freeze of the last frame for the card's seconds, the card receding over it, the headline, the release line, the wordmark and the mark as clips over the freeze), 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.
 

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

@@ -9,7 +9,11 @@ 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 { docOutputDuration as docOutputDuration3, migrateHostedDoc as migrateHostedDoc5 } from "@vosjs/studio-core";
+import {
+  END_CARD_FROM as END_CARD_FROM2,
+  docOutputDuration as docOutputDuration3,
+  migrateHostedDoc as migrateHostedDoc5
+} from "@vosjs/studio-core";
 
 // src/plugin/args.ts
 var UsageError = class extends Error {
@@ -3429,7 +3433,6 @@ function pickMoments(measured, opts = {}) {
 // src/plugin/motionPlan.ts
 import {
   END_CARD_FROM,
-  END_CARD_RECEDE,
   END_CARD_SECONDS,
   applyTemplate,
   docOutputDuration,
@@ -3519,9 +3522,15 @@ function proposeMotion(input, opts) {
     if (Object.keys(rest).length) doc.frame.anim = rest;
     else delete doc.frame.anim;
   }
+  const endCardRole = launch.endCard;
+  doc = dropTemplate(doc, END_CARD_FROM);
+  const templates = (opts.templates ?? []).filter(
+    (t) => !(t.from === END_CARD_FROM && off(endCardRole))
+  );
+  const namedEndCard = templates.some((t) => t.from === END_CARD_FROM);
   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 ?? []) {
+  for (const t of templates) {
     const at2 = resolveAnchor(doc, t.at);
     if (at2 === null) {
       skipped.push(`${t.from}: ${anchorWord(t.at)} was not recorded`);
@@ -3537,15 +3546,13 @@ function proposeMotion(input, opts) {
     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)) {
+  } else if (onWord(endCardRole) && !namedEndCard) {
     const headline = (words.headline ?? "").trim();
     const brand = (words.brand ?? "").trim();
     const sub = [brand, (words.release ?? "").trim()].filter(Boolean).join(" ");
@@ -3556,13 +3563,32 @@ function proposeMotion(input, opts) {
       if (sub && sub !== headline) card.sub = sub;
       if (brand) card.wordmark = brand;
       if (opts.mark) card.mark = opts.mark;
+      const endStart = outputLength(doc);
+      const lastSeg = doc.segments.at(-1);
+      if (lastSeg) {
+        const own = (doc.freeze ?? []).filter(
+          (f) => Math.abs(f.at - lastSeg.out) > 1e-9
+        );
+        const taken = new Set(own.map((f) => f.id));
+        let n = 0;
+        while (taken.has(`f${n}`)) n++;
+        doc.freeze = [
+          ...own,
+          {
+            id: `f${n}`,
+            at: lastSeg.out,
+            seconds: END_CARD_SECONDS,
+            from: END_CARD_FROM
+          }
+        ].sort((a, b) => a.at - b.at);
+      }
       doc.overlays = [
         ...doc.overlays ?? [],
-        ...endCardClips(card, doc, outputLength(doc))
+        ...endCardClips(card, doc, endStart)
       ];
       doc.frame.anim = {
         ...doc.frame.anim ?? {},
-        exit: { kind: "recede", seconds: END_CARD_RECEDE }
+        exit: { kind: "recede", seconds: END_CARD_SECONDS }
       };
       notes.push("end card");
     } else {
@@ -3623,7 +3649,7 @@ function proposeMotion(input, opts) {
       fadeIn: 0.6,
       fadeOut,
       loop: track.duration < length,
-      loopLen: track.duration < length ? length : void 0,
+      loopLen: track.duration < length ? Math.round(length * 1e3) / 1e3 : void 0,
       duck: hasMic
     });
     notes.push(`bed ${track.slug}`);
@@ -3679,6 +3705,11 @@ function destinationMechanics(d, doc) {
       notes.push(loop ? "no template clips, no captions" : "no captions");
     }
   }
+  if (loop) {
+    const keptFreezes = (doc.freeze ?? []).filter((f) => !f.from);
+    if (keptFreezes.length !== (doc.freeze ?? []).length)
+      set.push(`freeze=${JSON.stringify(keptFreezes)}`);
+  }
   if (portrait) {
     set.push("frame.fit=cover");
     set.push('frame.inset={"left":0.06,"right":0.06,"top":0.17,"bottom":0.17}');
@@ -3709,11 +3740,13 @@ function isLightHexGround(hex2) {
 import { existsSync as existsSync5 } from "fs";
 import { readFile as readFile5 } from "fs/promises";
 import { isAbsolute, join as join6, resolve as resolve3 } from "path";
+import { totalDuration } from "@vosjs/timeline";
 import {
   computeCardLayout,
   docRestTime,
   migrateHostedDoc,
   overlayRect,
+  ratedSegments as ratedSegments5,
   resolveOverlayStyle
 } from "@vosjs/studio-core";
 
@@ -3955,7 +3988,9 @@ async function findPosterDocs(takeDir, launchRoles) {
 function posterStillTime(doc, duration) {
   const rest = docRestTime(doc);
   if (rest != null) return rest;
-  return Math.max(0, duration - 1 / 30);
+  const footage = totalDuration(ratedSegments5(doc));
+  const end = footage > 0 ? Math.min(duration, footage) : duration;
+  return Math.max(0, end - 1 / 30);
 }
 var DESIGN_H = 1080;
 function designFrame(px) {
@@ -4545,6 +4580,21 @@ async function fetchBrandMarks(takeDir, roles) {
   return out;
 }
 
+// src/plugin/officialTemplates.ts
+var OFFICIAL_END_CARD_TITLE = "End card";
+function templateKey(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function findOfficialByRef(rows, ref) {
+  const key = templateKey(ref);
+  if (!key) return null;
+  for (const row of rows) {
+    if (templateKey(row.title) === key) return row;
+    if (row.slug && templateKey(row.slug) === key) return row;
+  }
+  return null;
+}
+
 // src/plugin/music.ts
 async function fetchMusicCatalog(origin) {
   const base = origin.replace(/\/+$/, "");
@@ -8924,17 +8974,18 @@ patched in from LAUNCH.md's headline and kicker roles or --headline and
 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
+the card leaves with its clip (a freeze keeps it under what follows).
+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
+named, the END CARD when endCard is on or absent (the official End card
+template on vos.so, laid at the end with the release's words, the mark
+from BRAND.md logoUrl and a freeze of the last frame under it, from:
+endcard; offline, the house clips stand in), 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
@@ -9413,6 +9464,24 @@ async function releaseInputs(dir, flags, r, withRefs = []) {
     templates.push({ from: found.from, doc: found.doc, at: at2 });
     r.log(`template: ${found.from}`);
   }
+  if (!endCardRole || /^(on|yes|true)$/i.test(endCardRole.trim())) {
+    const origin = platformOrigin({
+      origin: strFlag(flags, "origin"),
+      api: strFlag(flags, "api")
+    });
+    const official = await officialTemplate(origin, OFFICIAL_END_CARD_TITLE);
+    if (official) {
+      try {
+        const found = await resolveDocRef(official.id, flags, "endCard");
+        templates.push({ from: END_CARD_FROM2, doc: found.doc, at: "end" });
+        r.log(`template: ${found.from} (the official end card)`);
+      } catch {
+        r.log(
+          "end card: the official template is unreadable here; the house clips stand in"
+        );
+      }
+    }
+  }
   return {
     words,
     launchRoles,
@@ -9703,10 +9772,14 @@ async function resolveDocRef(ref, flags, what) {
   const key = resolveCredential(strFlag(flags, "key"));
   const meta = await apiJson(origin, `/api/vos/${styleRef}`, { key });
   const head = meta.body.vos?.currentVersionId;
-  if (meta.status !== 200 || !head)
+  if (meta.status !== 200 || !head) {
+    const official = await officialTemplate(origin, styleRef);
+    if (official && official.id !== styleRef)
+      return resolveDocRef(official.id, flags, what);
     throw new UsageError(
-      `${what}: ${styleRef} is neither a doc.json nor a vos I can read`
+      `${what}: ${styleRef} is neither a doc.json, a vos I can read, nor an official template's title`
     );
+  }
   const doc = await apiJson(
     origin,
     `/api/vos/${styleRef}/versions/${head}/doc`,
@@ -9719,6 +9792,16 @@ async function resolveDocRef(ref, flags, what) {
     doc: migrateHostedDoc5(doc.body)
   };
 }
+async function officialTemplate(origin, ref) {
+  try {
+    const list = await apiJson(origin, "/api/vos/official", {});
+    if (list.status !== 200) return null;
+    const rows = list.body.voses ?? [];
+    return findOfficialByRef(rows, ref);
+  } catch {
+    return null;
+  }
+}
 async function cmdDigest(argv) {
   const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS5);
   const dir = positionals[0];
@@ -10137,4 +10220,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-4IWHZBIY.js.map
+//# sourceMappingURL=chunk-SLCQCRNI.js.map