@vosjs/cli 0.20.0 → 0.21.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; 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.
 
 **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-4IWHZBIY.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)})`
         );
       }
     }
@@ -5789,6 +5819,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 +5981,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 +6018,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 +6047,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 +6073,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 +8907,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 +8920,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 +9308,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 +10137,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-ZONOZZZY.js.map
+//# sourceMappingURL=chunk-4IWHZBIY.js.map