@vosjs/cli 0.25.1 → 0.26.0

package/README.md

@@ -93,7 +93,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; 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.
+**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. **The frame that STANDS for a take** is `still` (output seconds; `vos plan --still <t>`, LAUNCH.md `still:`), else the take's own last freeze (a poster's rest; a template's freezes, stamped `from`, never count), else the hero moment after the card and the opening clips have entered: the shelf's cover, the kit's card stills and `vos frames --at-still` all read that one derivation, and a plan never moves a still the author set. 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-GHJ2BFQG.js → chunk-I3UUIBSH.js}

@@ -203,6 +203,7 @@ import {
   ZOOM_LEVEL_MIN,
   ZOOM_SPAN_MIN,
   docCardLayout,
+  outputEnd,
   ratedSegments,
   recommendedExportResolution,
   spanOutputExtent,
@@ -456,6 +457,22 @@ function lintDoc(docIn) {
         );
       }
     }
+    if (recording && doc.still !== void 0) {
+      const st = doc.still;
+      if (!isNum(st) || st < 0) {
+        problems.push("still must be a number \u2265 0 (OUTPUT seconds)");
+      } else {
+        const rated = ratedSegments(doc);
+        const end = outputEnd(
+          doc,
+          rated.reduce((a, s) => a + (s.out - s.in) / (s.rate ?? 1), 0)
+        );
+        if (st > end + 1e-6)
+          problems.push(
+            `still=${String(st)} is past the output's end (${end.toFixed(2)}s)`
+          );
+      }
+    }
     for (const [i, seg] of (Array.isArray(doc.segments) ? doc.segments : []).entries()) {
       const hold = seg.hold;
       if (hold === void 0) continue;
@@ -1419,6 +1436,7 @@ import { existsSync as existsSync4 } from "fs";
 import { join as join4, resolve as resolve2 } from "path";
 import { compileVosConfig } from "@vosjs/core";
 import {
+  docStillTime,
   lowerToComposition,
   momentsFromDoc as momentsFromDoc2,
   planForDigest as planForDigest2,
@@ -2751,10 +2769,12 @@ async function framesTake(browser, dir, opts) {
       shots.push({ time: clamp(m.outputAt), kind: "moment", momentId: m.id });
     }
   }
+  if (opts.atStill)
+    shots.push({ time: clamp(docStillTime(doc)), kind: "still" });
   shots.sort((a, b) => a.time - b.time);
   if (!shots.length)
     throw new Error(
-      "no frame times \u2014 pass --times/--frame, --at-zooms or --at-moments"
+      "no frame times \u2014 pass --times/--frame, --at-zooms, --at-moments or --at-still"
     );
   const outDir = resolve2(opts.outDir ?? join4(dir, "stills"));
   await mkdir3(outDir, { recursive: true });
@@ -3625,15 +3645,15 @@ function proposeMotion(input, opts) {
       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 || !sameMedia(f.media, lastSeg.media)
-        );
+        const atEnd = (f) => Math.abs(f.at - lastSeg.out) <= 1e-9 && sameMedia(f.media, lastSeg.media);
+        const kept2 = (doc.freeze ?? []).find((f) => atEnd(f) && !f.from);
+        const own = (doc.freeze ?? []).filter((f) => !atEnd(f));
         const taken = new Set(own.map((f) => f.id));
         let n = 0;
         while (taken.has(`f${n}`)) n++;
         doc.freeze = [
           ...own,
-          {
+          kept2 ? { ...kept2, seconds: Math.max(kept2.seconds, END_CARD_SECONDS) } : {
             id: `f${n}`,
             at: lastSeg.out,
             seconds: END_CARD_SECONDS,
@@ -3800,13 +3820,11 @@ 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,
+  docStillTime as docStillTime2,
   migrateHostedDoc,
   overlayRect,
-  ratedSegments as ratedSegments5,
   resolveOverlayStyle
 } from "@vosjs/studio-core";
 
@@ -4046,11 +4064,7 @@ async function findPosterDocs(takeDir, launchRoles) {
   return out;
 }
 function posterStillTime(doc, duration) {
-  const rest = docRestTime(doc);
-  if (rest != null) return rest;
-  const footage = totalDuration(ratedSegments5(doc));
-  const end = footage > 0 ? Math.min(duration, footage) : duration;
-  return Math.max(0, end - 1 / 30);
+  return Math.max(0, Math.min(duration, docStillTime2(doc)));
 }
 var DESIGN_H = 1080;
 function designFrame(px) {
@@ -6245,6 +6259,8 @@ 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.still !== void 0) doc.still = prev.still;
+    if (opts.still != null) doc.still = opts.still;
     await writeJson(take.paths.doc, doc, true);
     return {
       doc,
@@ -6323,6 +6339,7 @@ async function planTake(dir, opts = {}) {
     doc = proposed.doc;
     motion = { notes: proposed.notes, skipped: proposed.skipped };
   }
+  if (opts.still != null) doc.still = opts.still;
   await writeJson(take.paths.doc, doc, true);
   return {
     doc,
@@ -8969,6 +8986,7 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "draft",
   "at-zooms",
   "at-moments",
+  "at-still",
   "no-frames",
   "media",
   "print",
@@ -8983,9 +9001,9 @@ 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>] [--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 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] [--still <t>] [--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 frames <take> [--times 0,25%,50%,75%,100%] [--frame <t>] [--at-zooms] [--at-moments] [--at-still] [--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]
   vos digest <take> [--out dir] [--full 960] [--crop 640] [--no-frames] [--transcript <file.json>] [--style <doc.json|vosId>] [--json]
   vos brand <url> [--out BRAND.md] [--json]
@@ -9477,12 +9495,19 @@ async function cmdPlan(argv) {
   const backdrop = hasDoc ? null : await takeBackdrop(flags, r);
   const release = await releaseInputs(dir, flags, r, multi.with ?? []);
   const motionWanted = !hasDoc || flags.motion === true || flags.fresh === true;
+  const stillRaw = strFlag(flags, "still") ?? release.launchRoles.still;
+  const still = stillRaw === void 0 ? null : Number(stillRaw);
+  if (still !== null && !(Number.isFinite(still) && still >= 0))
+    throw new UsageError(
+      `--still expects output seconds \u2265 0, got "${stillRaw}"`
+    );
   const s = await planTake(dir, {
     ...style ? { style } : {},
     ...reuse ? { reuse } : {},
     backdrop,
     words: release.words,
     mark: release.mark,
+    ...still !== null ? { still } : {},
     ...motionWanted ? {
       motion: {
         words: release.words,
@@ -9730,6 +9755,7 @@ async function cmdFrames(argv) {
   const timesRaw = strFlag(flags, "times");
   const atZooms = flags["at-zooms"] === true;
   const atMoments = flags["at-moments"] === true;
+  const atStill = flags["at-still"] === true;
   let times;
   try {
     times = frameRaw !== void 0 ? parseTimes(frameRaw, duration) : timesRaw !== void 0 ? parseTimes(timesRaw, duration) : atZooms || atMoments ? [] : parseTimes("0,25%,50%,75%,100%", duration);
@@ -9743,6 +9769,7 @@ async function cmdFrames(argv) {
       times,
       atZooms,
       atMoments,
+      atStill,
       width: size?.width,
       height: size?.height,
       outDir: strFlag(flags, "out"),
@@ -10361,4 +10388,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-GHJ2BFQG.js.map
+//# sourceMappingURL=chunk-I3UUIBSH.js.map