@vosjs/cli 0.20.0 → 0.22.0

package/README.md

@@ -89,9 +89,9 @@ vos plan take --reuse                                   # re-time that cut onto
 
 **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.
+**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, 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.
+**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 house end card when `endCard` is on or absent (a freeze of the last frame for the card's seconds, the card receding over it, and the headline, the release line, the wordmark and BRAND.md's mark as clips over the freeze, every one `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 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.
+**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 (where its last freeze begins, 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 freeze; 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-ZONOZZZY.js → chunk-CRZTGWF3.js}

@@ -188,6 +188,8 @@ import {
   TEXT_ENTER_KINDS,
   TEXT_EXIT_KINDS,
   EXPORT_RESOLUTION_OPTIONS,
+  FREEZE_SECONDS_MAX,
+  FREEZE_SECONDS_MIN,
   SPEED_RATE_MAX,
   SPEED_RATE_MIN,
   TILT_DEG_MAX,
@@ -398,9 +400,37 @@ function lintDoc(docIn) {
     }
     for (const [i, seg] of (Array.isArray(doc.segments) ? doc.segments : []).entries()) {
       const hold = seg.hold;
-      if (hold !== void 0 && (!isNum(hold) || hold < 0 || hold > 10)) {
+      if (hold === void 0) continue;
+      if (!isNum(hold) || hold < 0 || hold > FREEZE_SECONDS_MAX) {
         problems.push(
-          `segments[${i}].hold must be 0..10 output seconds (got ${String(hold)})`
+          `segments[${i}].hold must be 0..${FREEZE_SECONDS_MAX} output seconds (got ${String(hold)})`
+        );
+      } else if (hold > 0) {
+        warnings.push(
+          `segments[${i}].hold is a legacy spelling, read as a freeze at ${String(seg.out)}s (doc.freeze); vos plan writes that shape`
+        );
+      }
+    }
+    if (doc.freeze !== void 0 && !Array.isArray(doc.freeze)) {
+      problems.push("freeze must be an array of {id, at, seconds}");
+    }
+    const freezes = Array.isArray(doc.freeze) ? doc.freeze : [];
+    const freezeIds = /* @__PURE__ */ new Set();
+    for (const [i, raw] of freezes.entries()) {
+      const f = raw;
+      const name = `freeze[${i}]${typeof f.id === "string" ? ` (${f.id})` : ""}`;
+      if (typeof f.id !== "string" || !f.id)
+        problems.push(`${name}: id must be a string`);
+      else if (freezeIds.has(f.id)) problems.push(`${name}: duplicate id`);
+      else freezeIds.add(f.id);
+      if (!isNum(f.at) || f.at < 0 || f.at > duration + EPS) {
+        problems.push(
+          `${name}: at must be a SOURCE moment inside the recording (0..${duration.toFixed(2)}s, got ${String(f.at)})`
+        );
+      }
+      if (!isNum(f.seconds) || f.seconds < FREEZE_SECONDS_MIN - EPS || f.seconds > FREEZE_SECONDS_MAX + EPS) {
+        problems.push(
+          `${name}: seconds must be ${FREEZE_SECONDS_MIN}..${FREEZE_SECONDS_MAX} output seconds (got ${String(f.seconds)})`
         );
       }
     }
@@ -3399,7 +3429,6 @@ function pickMoments(measured, opts = {}) {
 // src/plugin/motionPlan.ts
 import {
   END_CARD_FROM,
-  END_CARD_RECEDE,
   END_CARD_SECONDS,
   applyTemplate,
   docOutputDuration,
@@ -3526,13 +3555,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 {
@@ -3593,7 +3641,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}`);
@@ -3649,6 +3697,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}');
@@ -3679,11 +3732,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";
 
@@ -3925,7 +3980,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) {
@@ -5789,6 +5846,7 @@ import {
 } from "@vosjs/studio-core";
 
 // src/plugin/reuse.ts
+import { docFreezes } from "@vosjs/studio-core";
 var MIN_SPAN = 0.15;
 function matchStep(old, newSteps) {
   const usable = (s) => !!s && s.skipped !== true;
@@ -5950,6 +6008,30 @@ function retimeCut(prev, newSteps, newDurationMs) {
     newDuration,
     report
   );
+  const freeze = [];
+  for (const f of docFreezes(prev)) {
+    let at2 = null;
+    if (f.anchor) {
+      at2 = resolveAnchor2(f.anchor, newSteps);
+      if (at2 === null) {
+        report.flagged.push(
+          `freeze ${f.id}: its anchored step (${String(f.anchor.step)}) is missing or skipped in the new recording \u2014 fell back to the step map`
+        );
+      } else report.anchored++;
+    }
+    if (at2 === null) {
+      at2 = stepMap.map(f.at);
+      report.mapped++;
+    }
+    if (at2 < 0 || at2 > newDuration) {
+      report.flagged.push(
+        `freeze ${f.id}: lands outside the new recording (${at2.toFixed(2)}s) \u2014 dropped`
+      );
+      continue;
+    }
+    freeze.push({ ...f, at: +at2.toFixed(3) });
+  }
+  freeze.sort((a, b) => a.at - b.at);
   const rejected = [];
   for (const lane of ["zoom", "tilt", "speed"]) {
     rejected.push(
@@ -5963,7 +6045,7 @@ function retimeCut(prev, newSteps, newDurationMs) {
       )
     );
   }
-  return { segments, zoom, speed, tilt, rejected, report };
+  return { segments, zoom, speed, freeze, tilt, rejected, report };
 }
 
 // src/plugin/plan.ts
@@ -5992,7 +6074,7 @@ function patchStageWords(doc, words) {
 }
 function applyStyle(seed, doc, opts) {
   const parts = layoutOf(seed);
-  const carries = parts.clips.length > 0 || parts.lean || parts.hold;
+  const carries = parts.clips.length > 0 || parts.lean || parts.freeze;
   if (!carries) return { doc: copyStyle(seed, doc), layout: void 0 };
   const keys = opts.mark ? { "stage-mark": opts.mark.key } : void 0;
   const { doc: next, notes } = copyLayout(seed, copyStyle(seed, doc), { keys });
@@ -6018,10 +6100,7 @@ async function planTake(dir, opts = {}) {
     doc = copyStyle(prev, doc);
     const rt = retimeCut(prev, meta.steps ?? [], meta.durationMs);
     doc.segments = rt.segments;
-    const prevHold = prev.segments.at(-1)?.hold;
-    const last = doc.segments.at(-1);
-    if (typeof prevHold === "number" && prevHold > 0 && last)
-      last.hold = prevHold;
+    if (rt.freeze.length) doc.freeze = rt.freeze;
     if (rt.rejected.length) doc.rejected = rt.rejected;
     const manualZoom = rt.zoom;
     const autoZoom = planAutoZoom(doc.source.cursor, {
@@ -8855,7 +8934,7 @@ Screenshot-genre stills never take a look.
 A POSTER is a document, never a template: a plain take whose card sits
 where the poster wants it (frame.inset), leans (the tilt track), carries
 the words and the mark as clips (ids stage-title, stage-kicker,
-stage-brand, stage-mark) and ends on a trailing hold whose start is the
+stage-brand, stage-mark) and ends on a trailing freeze whose start is the
 still. Card-genre destinations (OG, LinkedIn, X, YouTube thumbnail, the
 CWS tile + marquee, GitHub social preview) render from the poster
 document of their aspect CLASS (landscape, square, portrait, tile), found
@@ -8868,7 +8947,7 @@ deliver renders and verifies; it composes nothing. The composition is
 made with plan --style <poster>, which copies a poster's layout onto a
 take (its card placement, its stage clips with the release's words
 patched in from LAUNCH.md's headline and kicker roles or --headline and
---kicker, its rest lean, its hold), or by hand in doc.json.
+--kicker, its rest lean, its freeze), or by hand in doc.json.
 The cut's MOTION is the document's too, in ONE vocabulary: every visual
 thing (the card, a text, image or video clip, a prop) carries anim.enter,
 anim.exit and anim.idle; the output lasts until the last clip ends, and
@@ -9256,7 +9335,7 @@ async function cmdPlan(argv) {
   layout from ${s.styleFrom}: ${[
     s.layout.clips.length ? `${s.layout.clips.length} stage clip(s)` : "",
     s.layout.lean ? "the rest lean" : "",
-    s.layout.hold ? "the hold" : ""
+    s.layout.freeze ? "the freeze" : ""
   ].filter(Boolean).join(", ")}` + (s.layout.notes.length ? `
     ${s.layout.notes.join("\n    ")}` : "") : "";
   const motionLines = s.motion ? (s.motion.notes.length ? `
@@ -10085,4 +10164,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-ZONOZZZY.js.map
+//# sourceMappingURL=chunk-CRZTGWF3.js.map