@vosjs/cli 0.25.1 → 0.27.0

package/README.md

@@ -89,11 +89,11 @@ 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.
 
-**Many media in one take (concat).** `doc.json` may carry `media: [{ id, videoKey, cursor, meta, … }]`, the take's OTHER recordings or uploads, each the `source` shape with an `id`; a segment on one (`{ in, out, media: "m1" }`) plays it, and a zoom, tilt, speed, freeze or cam-move span names the media its source seconds belong to (absent = the primary, `source`). The Video row shows the clips in order, a span is drawn where its media plays, `vos plan` proposes zoom and speed spans on every media from its own cursor track, `vos validate` measures each span against its own media's length, and `vos push` and `vos pull --media` carry every media through the recording door. A media wears its OWN card: `media[].frame` carries the card-owned fields (its placement and size as `inset`, the browser bar, the corner, the shadow, the border, the cover fit and its focus) over the take's frame while it plays; the bar names that media's recorded page, an upload with no page wears none, and the frame-wide fields (the aspect, the padding, the ground, the backdrop, the card's animation) stay the take's. Sound: the primary's tracks play at the primary's moments; another media's own audio is not spliced into the cut yet.
+**Many media in one take (concat).** `doc.json` may carry `media: [{ id, videoKey, cursor, meta, … }]`, the take's OTHER recordings or uploads, each the `source` shape with an `id`; a segment on one (`{ in, out, media: "m1" }`) plays it, and a zoom, tilt, speed, freeze or cam-move span names the media its source seconds belong to (absent = the primary, `source`). The Video row shows the clips in order, a span is drawn where its media plays, `vos plan` proposes zoom and speed spans on every media from its own cursor track, `vos validate` measures each span against its own media's length, and `vos push` and `vos pull --media` carry every media through the recording door. A media wears its OWN card: `media[].frame` carries the card-owned fields (its placement and size as `inset`, the browser bar, the corner, the shadow, the border, the cover fit and its focus) over the take's frame while it plays; the bar names that media's recorded page, an upload with no page wears none, and the frame-wide fields (the aspect, the padding, the ground, the backdrop, the card's animation) stay the take's. Sound: the primary's tracks play at the primary's moments; another media's own audio is not spliced into the cut yet. **Many cards**: an image or video overlay may show a document media by reference (`key: "media:<id>"`, `media:` alone the primary; its cursor track and recorded page come with it) and wear a card (`frame`: `browserBar`, a `lean` `{rx, ry}` in degrees, `shadow`, `shadowContact`, `shadowColor`, `cursor`), drawn by the card painter on its own plane above the primary card with the media's cursor dot and click rings inside it; a layer without `frame` stays the flat picture. The primary card stays primary: the sequence, the camera and the cut are its.
 
 **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-IJ5A4TL3.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;
@@ -971,6 +988,39 @@ function lintDoc(docIn) {
       if (o.fx !== void 0) {
         problems.push(`${name}.fx is text-only (media clips have enter/exit)`);
       }
+      if (typeof o.key === "string" && o.key.startsWith("media:")) {
+        const ref = o.key.slice("media:".length);
+        const ids = new Set(
+          (Array.isArray(doc.media) ? doc.media : []).map((m) => typeof m.id === "string" ? m.id : "")
+        );
+        if (ref !== "" && !ids.has(ref))
+          problems.push(
+            `${name}.key names media "${ref}", which is not one of media[].id (media: alone is the primary)`
+          );
+      }
+      const lcf = o.frame;
+      if (lcf !== void 0) {
+        if (!isObj(lcf)) {
+          problems.push(`${name}.frame must be an object (the layer's card)`);
+        } else {
+          const LCF = [
+            "browserBar",
+            "lean",
+            "shadow",
+            "shadowContact",
+            "shadowColor",
+            "cursor"
+          ];
+          for (const k of Object.keys(lcf))
+            if (!LCF.includes(k))
+              problems.push(
+                `${name}.frame.${k}: not a layer card field (${LCF.join(", ")})`
+              );
+          const lean = lcf.lean;
+          if (lean !== void 0 && (!isObj(lean) || !isNum(lean.rx) || !isNum(lean.ry)))
+            problems.push(`${name}.frame.lean must be { rx, ry } in degrees`);
+        }
+      }
       if (typeof o.key !== "string" || o.key.length === 0) {
         problems.push(
           `${name}.key must be a non-empty media URL or take-dir file (e.g. "/logo.png")`
@@ -1419,6 +1469,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 +2802,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 +3678,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 +3853,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 +4097,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 +6292,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 +6372,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,
@@ -6364,7 +6414,7 @@ var KEYS = [
   { key: "camKey", file: CAM_NAME }
 ];
 function isTakeRelativeKey(key) {
-  return !!key && !/^(https?:|blob:|data:|\/\/)/.test(key) && !key.startsWith("/api/");
+  return !!key && !/^(https?:|blob:|data:|media:|\/\/)/.test(key) && !key.startsWith("/api/");
 }
 var takeRelativeFile = (key) => key.replace(/^\/+/, "");
 function docMediaRefs(doc, keep = isTakeRelativeKey) {
@@ -8969,6 +9019,7 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "draft",
   "at-zooms",
   "at-moments",
+  "at-still",
   "no-frames",
   "media",
   "print",
@@ -8983,9 +9034,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 +9528,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 +9788,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 +9802,7 @@ async function cmdFrames(argv) {
       times,
       atZooms,
       atMoments,
+      atStill,
       width: size?.width,
       height: size?.height,
       outDir: strFlag(flags, "out"),
@@ -10361,4 +10421,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-GHJ2BFQG.js.map
+//# sourceMappingURL=chunk-IJ5A4TL3.js.map