@vosjs/cli 0.27.0 → 0.28.0

package/README.md

@@ -77,15 +77,15 @@ vos record --actions actions.json --out take --strict   # footage replaced; the
 vos plan take --reuse                                   # re-time that cut onto the new recording; what could not follow is named
 ```
 
-| Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                                                                         |
-| `create` | The `record` flags plus the render flags (`--width` `--height` `--fps` `--format` `--parallel` `--draft` `--frame` `--set`), no `--range`. With `--strict` an incomplete recording exits 2 before anything is rendered                                                                                                                                                                                                           |
-| `plan`   | `--fresh` (discard the current plan) `--reuse` `--from <doc.json>` (defaults to `<take>/doc.prev.json`) `--style <doc.json\|take\|vosId>` `--with <doc.json\|take\|vosId>[@end\|@start\|@step:<id>\|@<seconds>]` (a template, repeatable) `--background` `--motion` (re-propose the motion) `--headline` `--kicker` `--launch` `--brand` `--music` `--entrance` `--end-card on\|none\|<ref>` `--captions` `--clicks` `--release` |
-| `digest` | `--out <take>/digest` `--full 960` `--crop 640` (image long edges, the token budget) `--no-frames` `--transcript <file>` (Whisper-shaped segments merged as `said`) `--style <ref>` (report a reference document's style fields)                                                                                                                                                                                                 |
-| `frames` | `--times 0,25%,50%,75%,100%` (the default selector, output seconds or percent) `--frame <t>` `--at-zooms` `--at-moments` `--size WxH` `--out <take>/stills` `--background` `--set …`; writes `stills.json`                                                                                                                                                                                                                       |
-| `render` | `--width` `--height` `--fps` `--format webm\|mp4` `--parallel N` (1..16 sessions) `--range a..b` (output seconds; keeps its audio) `--draft` `--frame <kind>` `--background` `--set …`; `out` defaults to `<take>/out.<format>`                                                                                                                                                                                                  |
-| `open`   | `--studio http://localhost:6060` `--print` (print the URL, do not launch a browser)                                                                                                                                                                                                                                                                                                                                              |
+| Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                                                                                                                  |
+| `create` | The `record` flags plus the render flags (`--width` `--height` `--fps` `--format` `--parallel` `--draft` `--frame` `--set`), no `--range`. With `--strict` an incomplete recording exits 2 before anything is rendered                                                                                                                                                                                                                                                    |
+| `plan`   | `--fresh` (discard the current plan) `--reuse` `--from <doc.json>` (defaults to `<take>/doc.prev.json`) `--style <doc.json\|take\|vosId>` `--with <doc.json\|take\|vosId>[@end\|@start\|@step:<id>\|@<seconds>]` (a template, repeatable) `--background` `--motion` (re-propose the motion) `--headline` `--kicker` `--launch` `--brand` `--music` `--entrance` `--transitions slide\|fade\|scale\|none` `--end-card on\|none\|<ref>` `--captions` `--clicks` `--release` |
+| `digest` | `--out <take>/digest` `--full 960` `--crop 640` (image long edges, the token budget) `--no-frames` `--transcript <file>` (Whisper-shaped segments merged as `said`) `--style <ref>` (report a reference document's style fields)                                                                                                                                                                                                                                          |
+| `frames` | `--times 0,25%,50%,75%,100%` (the default selector, output seconds or percent) `--frame <t>` `--at-zooms` `--at-moments` `--size WxH` `--out <take>/stills` `--background` `--set …`; writes `stills.json`                                                                                                                                                                                                                                                                |
+| `render` | `--width` `--height` `--fps` `--format webm\|mp4` `--parallel N` (1..16 sessions) `--range a..b` (output seconds; keeps its audio) `--draft` `--frame <kind>` `--background` `--set …`; `out` defaults to `<take>/out.<format>`                                                                                                                                                                                                                                           |
+| `open`   | `--studio http://localhost:6060` `--print` (print the URL, do not launch a browser)                                                                                                                                                                                                                                                                                                                                                                                       |
 
 **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.
 
@@ -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. **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.
+**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`, `fade` or `slide` and leaving by `recede` or `fade`), a text, image or video clip, a prop, and a FOOTAGE clip at its boundaries (`segments[].anim`: `exit` is how it leaves at the boundary after it, `enter` how it arrives at the one before, by `slide`, `fade` or `scale`; a slide names its `side`, a step its `seconds`, never longer than half the shorter clip). An exit and the next clip's enter at one boundary run together as a push: the incoming clip plays live while the outgoing, frozen on its last frame, moves away, the camera rests through the window, and one cursor dot crosses from the outgoing card's last point to the incoming's. A page change inside one recording is the same primitive: two clips of one media, the load between them cut. 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, a transition at every page change the recorder marked (`meta.steps[].navigated`: the outgoing clip ends on the frame before the change, the incoming begins once the page has settled; `transitions: slide|fade|scale|none`, slide by default), from LAUNCH.md's `entrance`, `transitions`, `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-IJ5A4TL3.js → chunk-T35XY4YW.js}

@@ -185,6 +185,12 @@ import {
   CAM_SIZE_MIN,
   CAM_SPAN_MIN,
   CARD_ENTER_KINDS,
+  SEGMENT_ENTER_KINDS,
+  SEGMENT_EXIT_KINDS,
+  enterOf,
+  exitOf,
+  segmentOutputExtents,
+  transitionSeconds,
   CARD_EXIT_KINDS,
   EXPORT_RESOLUTION_OPTIONS,
   FREEZE_SECONDS_MAX,
@@ -219,8 +225,11 @@ var STEP_KINDS_ALL = [
   "typewriter",
   "tilt-in",
   "pull-out",
-  "recede"
+  "recede",
+  "slide",
+  "scale"
 ];
+var STEP_SIDES = ["left", "right", "up", "down"];
 var STEP_UNITS = ["block", "line", "word", "char"];
 var STEP_DIRS = ["forward", "reverse", "center"];
 function lintAnim(name, anim, kinds, problems) {
@@ -270,6 +279,14 @@ function lintAnim(name, anim, kinds, problems) {
       if (key === "stagger" && (typeof obj.stagger !== "number" || obj.stagger < 0 || obj.stagger > 2))
         problems.push(`${name}.anim.${side}.stagger must be seconds in 0..2`);
     }
+    if (obj.side !== void 0) {
+      if (kind !== "slide")
+        problems.push(`${name}.anim.${side}.side is for a slide`);
+      else if (typeof obj.side !== "string" || !STEP_SIDES.includes(obj.side))
+        problems.push(
+          `${name}.anim.${side}.side must be ${STEP_SIDES.join(" | ")}`
+        );
+    }
   }
   if (a.idle !== void 0 && a.idle !== null) {
     if (!kinds.idle) problems.push(`${name}.anim.idle is for props only`);
@@ -547,6 +564,56 @@ function lintDoc(docIn) {
       problems.push("segments must be an array of {in, out} spans");
     }
     checkByMedia(entries(doc.segments), "segment");
+    const segs = Array.isArray(doc.segments) ? doc.segments.filter(isObj) : [];
+    segs.forEach((seg, i) => {
+      lintAnim(
+        `segments[${i}]`,
+        seg.anim,
+        {
+          enter: SEGMENT_ENTER_KINDS,
+          exit: SEGMENT_EXIT_KINDS,
+          idle: null,
+          words: false
+        },
+        problems
+      );
+    });
+    if (segs.length && segs.every((s) => isNum(s.in) && isNum(s.out))) {
+      const anims = segs.map(
+        (s) => s.anim
+      );
+      if (enterOf(anims[0]) && enterOf(anims[0]).kind !== "none")
+        warnings.push(
+          "segments[0].anim.enter is ignored: the first clip arrives with the card (frame.anim.enter)"
+        );
+      const last = segs.length - 1;
+      if (last > 0 && exitOf(anims[last]) && exitOf(anims[last]).kind !== "none")
+        warnings.push(
+          `segments[${last}].anim.exit is ignored: the last clip leaves with the card (frame.anim.exit)`
+        );
+      let extents = [];
+      try {
+        extents = segmentOutputExtents(doc);
+      } catch {
+        extents = [];
+      }
+      for (let i = 0; i + 1 < segs.length && extents.length === segs.length; i++) {
+        const cap = Math.min(
+          extents[i].end - extents[i].start,
+          extents[i + 1].end - extents[i + 1].start
+        ) / 2;
+        const exitS = transitionSeconds(exitOf(anims[i]));
+        const enterS = transitionSeconds(enterOf(anims[i + 1]));
+        if (exitS > cap + EPS)
+          problems.push(
+            `segments[${i}].anim.exit: ${exitS}s is longer than half the shorter clip at that boundary (${cap.toFixed(2)}s); the clip must be seen still before it moves`
+          );
+        if (enterS > cap + EPS)
+          problems.push(
+            `segments[${i + 1}].anim.enter: ${enterS}s is longer than half the shorter clip at that boundary (${cap.toFixed(2)}s); the clip must be seen still before it moves`
+          );
+      }
+    }
   }
   const speed = entries(doc.speed);
   checkByMedia(speed, "speed");
@@ -3564,6 +3631,43 @@ var BED_ID = "bed";
 var CLICK_ID_PREFIX = "click-";
 var CAPTION_ID_PREFIX = "caption-";
 var off = (v) => v !== void 0 && /^(none|off|false|no)$/i.test(v.trim());
+var round3 = (v) => Math.round(v * 1e3) / 1e3;
+var TRANSITION_CLIP_MIN = 1;
+function proposeTransitions(input, kind) {
+  const doc = structuredClone(input);
+  const skipped = [];
+  let count = 0;
+  const steps = doc.source.meta.steps ?? [];
+  for (const step of steps) {
+    if (!step.navigated || step.skipped) continue;
+    const name = step.id ?? String(step.step);
+    const wait = step.do === "wait";
+    const outEnd = round3(wait ? step.tStart : step.tEnd);
+    const inStart = round3(wait ? step.tEnd : step.tEnd + STEP_SETTLE_SECONDS);
+    const segs = doc.segments;
+    if (segs.some(
+      (s) => !s.media && Math.abs(s.out - outEnd) < 0.05 && s !== segs.at(-1)
+    ))
+      continue;
+    const i = segs.findIndex(
+      (s) => !s.media && outEnd >= s.in + TRANSITION_CLIP_MIN && inStart <= s.out - TRANSITION_CLIP_MIN
+    );
+    if (i < 0) {
+      skipped.push(
+        `no transition at step ${name}: the page change sits too close to a clip's edge`
+      );
+      continue;
+    }
+    const seg = segs[i];
+    const before = { ...seg, out: outEnd, anim: { exit: kind } };
+    const after = { ...seg, in: inStart, anim: { enter: kind } };
+    if (seg.anim?.enter !== void 0) before.anim.enter = seg.anim.enter;
+    if (seg.anim?.exit !== void 0) after.anim.exit = seg.anim.exit;
+    doc.segments = [...segs.slice(0, i), before, after, ...segs.slice(i + 1)];
+    count++;
+  }
+  return { doc, count, skipped };
+}
 function pickTrack(catalog, ask) {
   if (!catalog || !ask || off(ask)) return null;
   const want = ask.trim().toLowerCase();
@@ -3634,6 +3738,14 @@ function proposeMotion(input, opts) {
     if (Object.keys(rest).length) doc.frame.anim = rest;
     else delete doc.frame.anim;
   }
+  const trRole = launch.transitions;
+  if (!off(trRole)) {
+    const trKind = trRole && /^(slide|fade|scale)$/.test(trRole.trim()) ? trRole.trim() : "slide";
+    const made = proposeTransitions(doc, trKind);
+    doc = made.doc;
+    if (made.count) notes.push(`${made.count} transition(s) ${trKind}`);
+    for (const n of made.skipped) skipped.push(n);
+  }
   const endCardRole = launch.endCard;
   doc = dropTemplate(doc, END_CARD_FROM);
   const templates = (opts.templates ?? []).filter(
@@ -5704,6 +5816,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     }
     const stepStart = now();
     const skippedBefore = skipped.length;
+    const urlBefore = page.url();
     switch (step.do) {
       case "wait":
         await sleep(clampWait(step.ms, now(), maxSeconds));
@@ -5835,7 +5948,8 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       ...stepInfo.selector ? { selector: stepInfo.selector } : {},
       tStart: +(stepStart / 1e3).toFixed(3),
       tEnd: +(now() / 1e3).toFixed(3),
-      ...skipped.length > skippedBefore ? { skipped: true } : {}
+      ...skipped.length > skippedBefore ? { skipped: true } : {},
+      ...page.url() !== urlBefore ? { navigated: true } : {}
     });
   }
   if (!capped) await sleep(600);
@@ -9034,7 +9148,7 @@ 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] [--still <t>] [--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|slide|none] [--transitions slide|fade|scale|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] [--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]
@@ -9180,7 +9294,7 @@ 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
+take has no mic. LAUNCH.md's entrance, transitions, endCard, captions, music and clicks
 roles, or the flags, change or switch each off; a deleted proposal stays
 deleted on a refresh. deliver applies each destination's MECHANICS and
 nothing more: the README loop drops the card's motion, every clip a
@@ -9609,6 +9723,7 @@ async function releaseInputs(dir, flags, r, withRefs = []) {
   for (const [flag, role] of [
     ["music", "music"],
     ["entrance", "entrance"],
+    ["transitions", "transitions"],
     ["end-card", "endCard"],
     ["captions", "captions"],
     ["clicks", "clicks"]
@@ -10421,4 +10536,4 @@ export {
   convertAgentBrowser,
   run
 };
-//# sourceMappingURL=chunk-IJ5A4TL3.js.map
+//# sourceMappingURL=chunk-T35XY4YW.js.map