@vosjs/cli 0.13.1 → 0.14.0

package/schema/doc.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://vos.so/schemas/doc.schema.json",
-  "title": "vosso doc.json (the studio document \u2014 a recording document or a program document)",
-  "description": "The editable document a vos carries beside its config: a RECORDING document (a take: `source` plus the tracks and layers) or a PROGRAM document (`program.config` plus the shared layers). Time is SECONDS everywhere. Edit this file, then re-run `vos render` \u2014 renders are deterministic, only your edits change the output. `vos validate <dir>` checks these contracts plus semantic lints (overlap, footage bounds).",
+  "title": "vosso doc.json (the studio document — a recording document or a program document)",
+  "description": "The editable document a vos carries beside its config: a RECORDING document (a take: `source` plus the tracks and layers) or a PROGRAM document (`program.config` plus the shared layers). Time is SECONDS everywhere. Edit this file, then re-run `vos render` — renders are deterministic, only your edits change the output. `vos validate <dir>` checks these contracts plus semantic lints (overlap, footage bounds).",
   "oneOf": [
     {
       "title": "Recording document",
@@ -22,7 +22,7 @@
       "properties": {
         "source": {
           "type": "object",
-          "description": "The recording this doc edits. Written by record/plan \u2014 treat as read-only except videoKey/camKey/micKey when relinking assets. micKey (extension takes recorded after the audio split) is a separately-recorded mic sidecar: the voice, gained by micGain; the recording's own audio track is then system/tab audio, gained by systemGain.",
+          "description": "The recording this doc edits. Written by record/plan — treat as read-only except videoKey/camKey/micKey when relinking assets. micKey (extension takes recorded after the audio split) is a separately-recorded mic sidecar: the voice, gained by micGain; the recording's own audio track is then system/tab audio, gained by systemGain.",
           "additionalProperties": true
         },
         "segments": {
@@ -30,7 +30,10 @@
           "description": "Kept SOURCE-time footage spans; the output timeline is their concatenation. Trim dead time by shrinking spans. Empty array = untrimmed. Never carry `rate` here (only lowered/derived segments do).",
           "items": {
             "type": "object",
-            "required": ["in", "out"],
+            "required": [
+              "in",
+              "out"
+            ],
             "properties": {
               "in": {
                 "type": "number",
@@ -41,6 +44,12 @@
                 "type": "number",
                 "exclusiveMinimum": 0,
                 "description": "SOURCE seconds, > in"
+              },
+              "hold": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 10,
+                "description": "freeze on this segment's last frame for these OUTPUT seconds (the beat before a cut, the ground for the end card)"
               }
             },
             "additionalProperties": true
@@ -51,10 +60,17 @@
         },
         "zoom": {
           "type": "array",
-          "description": "Zoom regions (SOURCE time, footage-anchored, non-overlapping). The camera ramps in around `in`, holds until `out`, ramps out \u2014 or pans straight to the next span when the gap is short. Planner-made spans have source:'auto' (replaced on re-plan); set source:'manual' on any span you add or edit so it survives.",
+          "description": "Zoom regions (SOURCE time, footage-anchored, non-overlapping). The camera ramps in around `in`, holds until `out`, ramps out — or pans straight to the next span when the gap is short. Planner-made spans have source:'auto' (replaced on re-plan); set source:'manual' on any span you add or edit so it survives.",
           "items": {
             "type": "object",
-            "required": ["id", "in", "out", "level", "cx", "cy"],
+            "required": [
+              "id",
+              "in",
+              "out",
+              "level",
+              "cx",
+              "cy"
+            ],
             "properties": {
               "id": {
                 "type": "string",
@@ -67,13 +83,13 @@
               },
               "out": {
                 "type": "number",
-                "description": "SOURCE seconds, > in (\u2265 0.3s span reads well)"
+                "description": "SOURCE seconds, > in (≥ 0.3s span reads well)"
               },
               "level": {
                 "type": "number",
                 "minimum": 1,
                 "maximum": 5,
-                "description": "zoom level; 1.4\u20132.8 reads well"
+                "description": "zoom level; 1.4–2.8 reads well"
               },
               "cx": {
                 "type": "number",
@@ -92,28 +108,47 @@
                 "description": "arrival ease (@vosjs/timeline EASINGS name). Absent = the style's default ramp."
               },
               "transition": {
-                "enum": ["instant", "fast", "smooth", "slow"],
-                "description": "transition SPEED for this span's ramps (in, out, and a chained pan arriving here). Absent = 'smooth' (the camera style's stock motion); 'instant' = hard cut; 'fast' \u2248 half, 'slow' \u2248 1.6\u00d7."
+                "enum": [
+                  "instant",
+                  "fast",
+                  "smooth",
+                  "slow"
+                ],
+                "description": "transition SPEED for this span's ramps (in, out, and a chained pan arriving here). Absent = 'smooth' (the camera style's stock motion); 'instant' = hard cut; 'fast' ≈ half, 'slow' ≈ 1.6×."
               },
               "focusMode": {
-                "enum": ["manual", "auto"],
+                "enum": [
+                  "manual",
+                  "auto"
+                ],
                 "description": "'auto' = camera follows the cursor through the span (needs a cursor track); absent/'manual' = fixed cx/cy"
               },
               "source": {
-                "enum": ["auto", "manual"],
+                "enum": [
+                  "auto",
+                  "manual"
+                ],
                 "description": "'auto' = planner suggestion, replaced by re-plan; 'manual' = user/agent work, always preserved"
               },
               "anchor": {
                 "type": "object",
-                "required": ["step"],
+                "required": [
+                  "step"
+                ],
                 "additionalProperties": false,
                 "properties": {
                   "step": {
-                    "type": ["string", "integer"],
+                    "type": [
+                      "string",
+                      "integer"
+                    ],
                     "description": "the actions.json step: its `id` when it has one, else its record-time index (meta.steps)"
                   },
                   "at": {
-                    "enum": ["start", "end"],
+                    "enum": [
+                      "start",
+                      "end"
+                    ],
                     "description": "which edge of the step the span's `in` is measured from (default start)"
                   },
                   "offset": {
@@ -121,7 +156,7 @@
                     "description": "seconds from that edge to the span's `in` (negative = before it)"
                   }
                 },
-                "description": "Re-record tie: `vos plan --reuse` re-times this span onto a NEW recording of the same script by resolving the step in the new meta.steps. Metadata only \u2014 `in`/`out` stay authoritative and lowering never reads it, so it costs nothing at render time"
+                "description": "Re-record tie: `vos plan --reuse` re-times this span onto a NEW recording of the same script by resolving the step in the new meta.steps. Metadata only — `in`/`out` stay authoritative and lowering never reads it, so it costs nothing at render time"
               }
             },
             "additionalProperties": true
@@ -138,7 +173,7 @@
             "cut",
             "none"
           ],
-          "description": "Camera style preset driving planner + camera motion. Absent = 'glide'. 'none' disables auto-zoom planning (manual spans keep default motion). 'keynote' and 'drift' are tilt-forward styles: they carry a tilt personality (keynote = medium lean toward each zoom's focus with tilt ramps matched to the zoom ramps; drift = subtle lean, slower 1.6s ramps, longer chains) \u2014 in the studio, picking one stamps tiltStyle and plans auto tilt spans; in doc.json, set tiltStyle + tilt spans yourself (the style still shapes tilt MOTION at render)."
+          "description": "Camera style preset driving planner + camera motion. Absent = 'glide'. 'none' disables auto-zoom planning (manual spans keep default motion). 'keynote' and 'drift' are tilt-forward styles: they carry a tilt personality (keynote = medium lean toward each zoom's focus with tilt ramps matched to the zoom ramps; drift = subtle lean, slower 1.6s ramps, longer chains) — in the studio, picking one stamps tiltStyle and plans auto tilt spans; in doc.json, set tiltStyle + tilt spans yourself (the style still shapes tilt MOTION at render)."
         },
         "zoomParams": {
           "type": "object",
@@ -147,15 +182,21 @@
         },
         "speedParams": {
           "type": "object",
-          "description": "Auto-speed planner overrides: idleMin/idleRate/typingMin/typingRate/scrollMin/scrollRate. Absent = defaults (idle \u22655s\u21924\u00d7, typing \u22653s\u21923\u00d7, scroll \u22652.5s\u21922\u00d7).",
+          "description": "Auto-speed planner overrides: idleMin/idleRate/typingMin/typingRate/scrollMin/scrollRate. Absent = defaults (idle ≥5s→4×, typing ≥3s→3×, scroll ≥2.5s→2×).",
           "additionalProperties": true
         },
         "tilt": {
           "type": "array",
-          "description": "Card tilt regions (SOURCE time, footage-anchored, non-overlapping). While a span is active the 3D card leans to its pose; between spans it returns to FLAT (there is no static card pose: a lean is a moment on the timeline). Ramps ~0.9s in / ~0.8s out; spans \u2264 ~1.35s apart swing pose-to-pose. Direction: +rx brings the TOP edge toward the camera, +ry the LEFT edge \u2014 to lean toward a right-side focus use NEGATIVE ry. Wand-made spans have source:'auto' (replaced when Dynamic tilt re-runs); set source:'manual' on spans you add or edit.",
+          "description": "Card tilt regions (SOURCE time, footage-anchored, non-overlapping). While a span is active the 3D card leans to its pose; between spans it returns to FLAT (there is no static card pose: a lean is a moment on the timeline). Ramps ~0.9s in / ~0.8s out; spans ≤ ~1.35s apart swing pose-to-pose. Direction: +rx brings the TOP edge toward the camera, +ry the LEFT edge — to lean toward a right-side focus use NEGATIVE ry. Wand-made spans have source:'auto' (replaced when Dynamic tilt re-runs); set source:'manual' on spans you add or edit.",
           "items": {
             "type": "object",
-            "required": ["id", "in", "out", "rx", "ry"],
+            "required": [
+              "id",
+              "in",
+              "out",
+              "rx",
+              "ry"
+            ],
             "properties": {
               "id": {
                 "type": "string",
@@ -168,13 +209,13 @@
               },
               "out": {
                 "type": "number",
-                "description": "SOURCE seconds, > in (\u2265 0.8s so the pose can settle)"
+                "description": "SOURCE seconds, > in (≥ 0.8s so the pose can settle)"
               },
               "rx": {
                 "type": "number",
                 "minimum": -45,
                 "maximum": 45,
-                "description": "pose DEGREES about the horizontal axis (+ = top edge toward camera). NOT radians, NOT fractions; \u00b15..18\u00b0 reads premium."
+                "description": "pose DEGREES about the horizontal axis (+ = top edge toward camera). NOT radians, NOT fractions; ±5..18° reads premium."
               },
               "ry": {
                 "type": "number",
@@ -187,24 +228,40 @@
                 "description": "arrival ease (@vosjs/timeline EASINGS name). Absent = the house tilt ease."
               },
               "transition": {
-                "enum": ["instant", "fast", "smooth", "slow"],
+                "enum": [
+                  "instant",
+                  "fast",
+                  "smooth",
+                  "slow"
+                ],
                 "description": "transition SPEED for this span's ramps. Absent = 'smooth' (~0.9s in / ~0.8s out); 'instant' snaps the card to the pose."
               },
               "source": {
-                "enum": ["auto", "manual"],
+                "enum": [
+                  "auto",
+                  "manual"
+                ],
                 "description": "'auto' = Dynamic-tilt suggestion, replaced by re-plan; 'manual' = user/agent work, always preserved"
               },
               "anchor": {
                 "type": "object",
-                "required": ["step"],
+                "required": [
+                  "step"
+                ],
                 "additionalProperties": false,
                 "properties": {
                   "step": {
-                    "type": ["string", "integer"],
+                    "type": [
+                      "string",
+                      "integer"
+                    ],
                     "description": "the actions.json step: its `id` when it has one, else its record-time index (meta.steps)"
                   },
                   "at": {
-                    "enum": ["start", "end"],
+                    "enum": [
+                      "start",
+                      "end"
+                    ],
                     "description": "which edge of the step the span's `in` is measured from (default start)"
                   },
                   "offset": {
@@ -212,29 +269,43 @@
                     "description": "seconds from that edge to the span's `in` (negative = before it)"
                   }
                 },
-                "description": "Re-record tie: `vos plan --reuse` re-times this span onto a NEW recording of the same script by resolving the step in the new meta.steps. Metadata only \u2014 `in`/`out` stay authoritative and lowering never reads it, so it costs nothing at render time"
+                "description": "Re-record tie: `vos plan --reuse` re-times this span onto a NEW recording of the same script by resolving the step in the new meta.steps. Metadata only — `in`/`out` stay authoritative and lowering never reads it, so it costs nothing at render time"
               }
             },
             "additionalProperties": true
           }
         },
         "tiltStyle": {
-          "enum": ["off", "subtle", "medium", "strong"],
-          "description": "Dynamic-tilt wand intensity: derives source:'auto' tilt spans FROM the zoom spans, leaning toward each zoom's focus (max 5/9/14\u00b0 per axis). 'off'/absent = no auto tilt; manual spans work either way."
+          "enum": [
+            "off",
+            "subtle",
+            "medium",
+            "strong"
+          ],
+          "description": "Dynamic-tilt wand intensity: derives source:'auto' tilt spans FROM the zoom spans, leaning toward each zoom's focus (max 5/9/14° per axis). 'off'/absent = no auto tilt; manual spans work either way."
         },
         "rejected": {
           "type": "array",
           "description": "Deleted planner proposals, kept so no re-plan proposes them again (\"not this one\"). Each entry is the lane and the SOURCE extent of an auto span you deleted; a fresh proposal on that lane overlapping the extent by half of the shorter span is dropped by vos plan, by plan --reuse (which re-times these like manual spans) and by the studio's re-plans. Manual spans never need this: a re-plan keeps them by contract. The renderer never reads it.",
           "items": {
             "type": "object",
-            "required": ["id", "lane", "in", "out"],
+            "required": [
+              "id",
+              "lane",
+              "in",
+              "out"
+            ],
             "properties": {
               "id": {
                 "type": "string",
                 "description": "stable identity (`r{n}`)"
               },
               "lane": {
-                "enum": ["zoom", "tilt", "speed"],
+                "enum": [
+                  "zoom",
+                  "tilt",
+                  "speed"
+                ],
                 "description": "which planner's proposals this rejects"
               },
               "in": {
@@ -249,15 +320,23 @@
               "anchor": {
                 "type": "object",
                 "description": "the deleted span's step anchor, when it had one, so a re-record re-times the rejection the same way",
-                "required": ["step"],
+                "required": [
+                  "step"
+                ],
                 "additionalProperties": false,
                 "properties": {
                   "step": {
-                    "type": ["string", "integer"],
+                    "type": [
+                      "string",
+                      "integer"
+                    ],
                     "description": "the actions.json step: its `id` when it has one, else its record-time index (meta.steps)"
                   },
                   "at": {
-                    "enum": ["start", "end"],
+                    "enum": [
+                      "start",
+                      "end"
+                    ],
                     "description": "which edge of the step the span's `in` is measured from (default start)"
                   },
                   "offset": {
@@ -287,24 +366,28 @@
           "type": "number",
           "minimum": 0,
           "maximum": 1,
-          "description": "master gain for the recording's own system/tab audio track \u2014 split takes (source.micKey) only; legacy takes have one track on micGain. Absent = 1. 0 = muted."
+          "description": "master gain for the recording's own system/tab audio track — split takes (source.micKey) only; legacy takes have one track on micGain. Absent = 1. 0 = muted."
         },
         "cursor": {
           "type": "object",
-          "description": "Cursor rendering (visible, hideWhenIdle, smoothing, size, click effects). See CursorStyle in @vosjs/studio-core. `visible: false` hides the drawn dot only \u2014 the track still drives cursor-follow zoom, and click effects keep drawing (silence those with clickFx.style: \"none\"). `hideWhenIdle` (default true) fades the dot out after ~1s parked and back in when it moves; scrolling is not movement, and it is always back at full opacity on a click.",
+          "description": "Cursor rendering (visible, hideWhenIdle, smoothing, size, click effects). See CursorStyle in @vosjs/studio-core. `visible: false` hides the drawn dot only — the track still drives cursor-follow zoom, and click effects keep drawing (silence those with clickFx.style: \"none\"). `hideWhenIdle` (default true) fades the dot out after ~1s parked and back in when it moves; scrolling is not movement, and it is always back at full opacity on a click.",
           "additionalProperties": true
         },
         "cam": {
           "type": "object",
-          "description": "Webcam bubble style + SOURCE-time window \u2014 the bubble's REST pose. Only applies when the take has a cam track. Placement: x/y (bubble CENTER as frame fractions, the zoom cx/cy convention) when present, else the `position` corner anchor; size = diameter as a fraction of frame height. Look: shape circle|rounded; radius (rounded corner, design px, default 18); border { width design px (default 3; 0 = none), color } (default white at 0.9); shadow none|soft|strong (default soft). Animate the pose over time with camMotion spans.",
+          "description": "Webcam bubble style + SOURCE-time window — the bubble's REST pose. Only applies when the take has a cam track. Placement: x/y (bubble CENTER as frame fractions, the zoom cx/cy convention) when present, else the `position` corner anchor; size = diameter as a fraction of frame height. Look: shape circle|rounded; radius (rounded corner, design px, default 18); border { width design px (default 3; 0 = none), color } (default white at 0.9); shadow none|soft|strong (default soft). Animate the pose over time with camMotion spans.",
           "additionalProperties": true
         },
         "camMotion": {
           "type": "array",
-          "description": "Animated cam layout (SOURCE time, footage-anchored, non-overlapping): while a span is active the webcam bubble holds its pose; outside spans it rests at doc.cam; spans \u2264 ~1.2s apart in output time morph pose-to-pose. Ramps ~0.65s, settled at span start (a cam move frames what follows). Absent pose fields inherit the rest pose, so a span may move without resizing. Only renders when the take has a cam track (source.camKey).",
+          "description": "Animated cam layout (SOURCE time, footage-anchored, non-overlapping): while a span is active the webcam bubble holds its pose; outside spans it rests at doc.cam; spans ≤ ~1.2s apart in output time morph pose-to-pose. Ramps ~0.65s, settled at span start (a cam move frames what follows). Absent pose fields inherit the rest pose, so a span may move without resizing. Only renders when the take has a cam track (source.camKey).",
           "items": {
             "type": "object",
-            "required": ["id", "in", "out"],
+            "required": [
+              "id",
+              "in",
+              "out"
+            ],
             "properties": {
               "id": {
                 "type": "string",
@@ -317,7 +400,7 @@
               },
               "out": {
                 "type": "number",
-                "description": "SOURCE seconds, > in (\u2265 0.5s so the move can settle)"
+                "description": "SOURCE seconds, > in (≥ 0.5s so the move can settle)"
               },
               "x": {
                 "type": "number",
@@ -342,12 +425,20 @@
                 "description": "arrival ease (@vosjs/timeline EASINGS name, e.g. 'power2.out'). Absent = the house settle ease."
               },
               "transition": {
-                "enum": ["instant", "fast", "smooth", "slow"],
+                "enum": [
+                  "instant",
+                  "fast",
+                  "smooth",
+                  "slow"
+                ],
                 "description": "transition SPEED for this span's morphs. Absent = 'smooth' (~0.65s); 'instant' jump-cuts the bubble to its pose (the layout-cut)."
               },
               "source": {
                 "type": "string",
-                "enum": ["auto", "manual"],
+                "enum": [
+                  "auto",
+                  "manual"
+                ],
                 "description": "reserved for a future planner; spans you add or edit are 'manual'"
               }
             }
@@ -360,15 +451,25 @@
           "properties": {
             "background": {
               "type": "string",
-              "description": "CSS background (gradient/color) \u2014 the underlay/fallback, always painted under backgroundMedia"
+              "description": "CSS background (gradient/color) — the underlay/fallback, always painted under backgroundMedia"
             },
             "backgroundMedia": {
-              "type": ["object", "null"],
-              "description": "Optional media layer drawn OVER the CSS background and UNDER the card: a vos animation baked to a seamless loop, or a still image. Video time is OUTPUT-anchored modulo the loop (bgT = t % duration) \u2014 trims/speed never retime it. Draws outside the zoom transform. `key` may be a file inside the take dir (e.g. \"/bg.webm\"), a public https://assets.vos.so/... loop, or an /api/... URL. Fail-open: if it can't load, the CSS background still shows.",
-              "required": ["kind", "key", "dim"],
+              "type": [
+                "object",
+                "null"
+              ],
+              "description": "Optional media layer drawn OVER the CSS background and UNDER the card: a vos animation baked to a seamless loop, or a still image. Video time is OUTPUT-anchored modulo the loop (bgT = t % duration) — trims/speed never retime it. Draws outside the zoom transform. `key` may be a file inside the take dir (e.g. \"/bg.webm\"), a public https://assets.vos.so/... loop, or an /api/... URL. Fail-open: if it can't load, the CSS background still shows.",
+              "required": [
+                "kind",
+                "key",
+                "dim"
+              ],
               "properties": {
                 "kind": {
-                  "enum": ["video", "image"]
+                  "enum": [
+                    "video",
+                    "image"
+                  ]
                 },
                 "key": {
                   "type": "string",
@@ -377,7 +478,7 @@
                 "duration": {
                   "type": "number",
                   "exclusiveMinimum": 0,
-                  "description": "loop length in seconds (video only \u2014 required for the modulo loop)"
+                  "description": "loop length in seconds (video only — required for the modulo loop)"
                 },
                 "vosId": {
                   "type": "string",
@@ -400,7 +501,7 @@
                   "type": "number",
                   "minimum": 0,
                   "maximum": 100,
-                  "description": "V2: blur radius in design px \u2014 softens the media behind the card"
+                  "description": "V2: blur radius in design px — softens the media behind the card"
                 }
               },
               "additionalProperties": true
@@ -414,7 +515,46 @@
             "shadow": {
               "type": "number",
               "minimum": 0,
-              "maximum": 1
+              "maximum": 1,
+              "description": "ambient shadow strength: the wide soft layer under the card (blur 60, offset 24 design px)"
+            },
+            "shadowContact": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "contact shadow strength: a second tight layer (blur 10, offset 3 design px) over the ambient one, what makes a light card sit on a light ground. Absent = 0"
+            },
+            "shadowColor": {
+              "type": "string",
+              "pattern": "^#[0-9a-fA-F]{6}$",
+              "description": "shadow colour as #rrggbb; the strengths are its alpha. Absent = black"
+            },
+            "inset": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "per-side card placement as FRACTIONS of the frame (left/right of its width, top/bottom of its height), each overriding `padding` on its side; a NEGATIVE side bleeds the card past the frame edge (headroom above, the window running off the bottom). Absent sides keep padding. Under contain the card centres inside the inset area; under cover the inset area is the card",
+              "properties": {
+                "top": {
+                  "type": "number",
+                  "minimum": -2,
+                  "maximum": 0.9
+                },
+                "right": {
+                  "type": "number",
+                  "minimum": -2,
+                  "maximum": 0.9
+                },
+                "bottom": {
+                  "type": "number",
+                  "minimum": -2,
+                  "maximum": 0.9
+                },
+                "left": {
+                  "type": "number",
+                  "minimum": -2,
+                  "maximum": 0.9
+                }
+              }
             },
             "border": {
               "type": "number",
@@ -443,8 +583,11 @@
             },
             "fit": {
               "type": "string",
-              "enum": ["contain", "cover"],
-              "description": "How footage meets an off-ratio frame. contain (default) letterboxes the card onto the background; cover makes the padded area the card and fills it with footage, cropped around `focus` \u2014 what a 440x280 store tile or a 2.5:1 marquee demands"
+              "enum": [
+                "contain",
+                "cover"
+              ],
+              "description": "How footage meets an off-ratio frame. contain (default) letterboxes the card onto the background; cover makes the padded area the card and fills it with footage, cropped around `focus` — what a 440x280 store tile or a 2.5:1 marquee demands"
             },
             "focus": {
               "type": "object",
@@ -472,6 +615,36 @@
                   "description": "'mac' | 'windows' | 'minimal' | 'none' | 'original' (window takes with a chrome crop)"
                 }
               }
+            },
+            "entrance": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "kind"
+              ],
+              "properties": {
+                "kind": {
+                  "enum": [
+                    "tilt-in",
+                    "pull-out",
+                    "rise",
+                    "none"
+                  ]
+                },
+                "seconds": {
+                  "type": "number",
+                  "minimum": 0.2,
+                  "maximum": 3
+                }
+              },
+              "description": "how the card ENTERS at t = 0: tilt-in swings in from a perspective pose while the card settles up and in; pull-out opens zoomed in and pulls out; rise settles up and in flat. Lowered into the tilt or zoom track's head plus a card-pose track. Absent = none"
+            },
+            "focusFollow": {
+              "type": "string",
+              "enum": [
+                "camera"
+              ],
+              "description": "under fit: cover, the crop follows the zoom track's focus (a 9:16 cut of a 16:9 take keeps the affordance in frame). Absent = focus, or the centre"
             }
           }
         },
@@ -483,6 +656,27 @@
         },
         "export": {
           "$ref": "#/definitions/export"
+        },
+        "endCard": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "seconds": {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 8
+            },
+            "headline": {
+              "type": "string"
+            },
+            "sub": {
+              "type": "string"
+            },
+            "wordmark": {
+              "type": "string"
+            }
+          },
+          "description": "the end card the clip closes on: a hold on the last frame (default 2.5 s) while the card recedes and the words rise as the house title, caption and label overlays. The clip's last frame is its poster"
         }
       }
     },
@@ -490,7 +684,9 @@
       "title": "Program document",
       "description": "A program plus the shared layers. `program.config` is THE user's config (functions as strings), untouched; the platform stores the COMPOSED config (the config plus the studio stack entry) as what plays. In a program DIRECTORY the CLI keeps `program.config` in config.json and omits it here. Minted only when a program gains a layer, a tween edit, a speed span or its own length; a bare program has no doc.",
       "type": "object",
-      "required": ["program"],
+      "required": [
+        "program"
+      ],
       "additionalProperties": true,
       "properties": {
         "program": {
@@ -537,17 +733,27 @@
   "definitions": {
     "overlays": {
       "type": "array",
-      "description": "Compositor v2 (V1): screen-space text clips drawn ABOVE the card, outside the zoom transform. OUTPUT-anchored (start is final-cut seconds \u2014 trims/speed never retime a title). Optional; absent = none.",
+      "description": "Compositor v2 (V1): screen-space text clips drawn ABOVE the card, outside the zoom transform. OUTPUT-anchored (start is final-cut seconds — trims/speed never retime a title). Optional; absent = none.",
       "items": {
         "type": "object",
-        "required": ["id", "kind", "start", "duration", "transform"],
+        "required": [
+          "id",
+          "kind",
+          "start",
+          "duration",
+          "transform"
+        ],
         "additionalProperties": true,
         "properties": {
           "id": {
             "type": "string"
           },
           "kind": {
-            "enum": ["text", "image", "video"]
+            "enum": [
+              "text",
+              "image",
+              "video"
+            ]
           },
           "start": {
             "type": "number",
@@ -563,7 +769,11 @@
             "description": "content; \\n breaks lines"
           },
           "preset": {
-            "enum": ["title", "caption", "label"],
+            "enum": [
+              "title",
+              "caption",
+              "label"
+            ],
             "description": "house style: title = Lexend 600 64px, caption = Lexend 400 32px, label = JetBrains Mono 22px"
           },
           "size": {
@@ -578,20 +788,24 @@
           },
           "family": {
             "type": "string",
-            "description": "font family override \u2014 a catalog family name (GET https://vos.so/api/fonts). Unknown names fail open to the preset stack on the render fleet"
+            "description": "font family override — a catalog family name (GET https://vos.so/api/fonts). Unknown names fail open to the preset stack on the render fleet"
           },
           "weight": {
             "type": "number",
             "minimum": 100,
             "maximum": 900,
-            "description": "weight override \u2014 snapped to the nearest weight the catalog hosts for the family (weights are files, not synthesis)"
+            "description": "weight override — snapped to the nearest weight the catalog hosts for the family (weights are files, not synthesis)"
           },
           "italic": {
             "type": "boolean",
             "description": "synthesized oblique (no italic files are hosted)"
           },
           "align": {
-            "enum": ["left", "center", "right"],
+            "enum": [
+              "left",
+              "center",
+              "right"
+            ],
             "description": "multi-line alignment within the block (default center)"
           },
           "letterSpacing": {
@@ -608,7 +822,10 @@
           },
           "stroke": {
             "type": "object",
-            "required": ["color", "width"],
+            "required": [
+              "color",
+              "width"
+            ],
             "additionalProperties": false,
             "description": "text outline drawn under the fill",
             "properties": {
@@ -625,7 +842,9 @@
           },
           "box": {
             "type": "object",
-            "required": ["color"],
+            "required": [
+              "color"
+            ],
             "additionalProperties": false,
             "description": "background pill behind the text block (text only; absent = none). Paddings/radius are EMs of the resolved font size",
             "properties": {
@@ -660,19 +879,22 @@
           },
           "transform": {
             "type": "object",
-            "required": ["x", "y"],
+            "required": [
+              "x",
+              "y"
+            ],
             "properties": {
               "x": {
                 "type": "number",
                 "minimum": -0.5,
                 "maximum": 1.5,
-                "description": "anchor CENTER as a FRACTION of the frame width [0..1] (0.5 = center at ANY aspect \u2014 the zoom cx/cy convention; NOT pixels)"
+                "description": "anchor CENTER as a FRACTION of the frame width [0..1] (0.5 = center at ANY aspect — the zoom cx/cy convention; NOT pixels)"
               },
               "y": {
                 "type": "number",
                 "minimum": -0.5,
                 "maximum": 1.5,
-                "description": "anchor CENTER as a FRACTION of the frame height [0..1] (lower-third \u2248 0.82; NOT pixels)"
+                "description": "anchor CENTER as a FRACTION of the frame height [0..1] (lower-third ≈ 0.82; NOT pixels)"
               },
               "scale": {
                 "type": "number",
@@ -693,12 +915,19 @@
             "description": "text kind: wrap budget as a FRACTION of the frame width (greedy word wrap at measured widths; absent = lines break only on \\n; no intra-word breaks)"
           },
           "shadow": {
-            "enum": ["none", "soft", "strong"],
+            "enum": [
+              "none",
+              "soft",
+              "strong"
+            ],
             "description": "media kinds: the card shadow. Absent = 'soft' (the house picture-in-picture look); 'strong' floats harder; 'none' is a flat cutout"
           },
           "border": {
             "type": "object",
-            "required": ["color", "width"],
+            "required": [
+              "color",
+              "width"
+            ],
             "properties": {
               "color": {
                 "type": "string",
@@ -714,19 +943,29 @@
             "description": "media kinds: an outline stroke over the clipped media edge. Absent = none"
           },
           "enter": {
-            "enum": ["none", "fade", "rise"],
+            "enum": [
+              "none",
+              "fade",
+              "rise"
+            ],
             "description": "default rise (~0.35s); IGNORED while fx is set (fx owns the entrance)"
           },
           "exit": {
-            "enum": ["none", "fade", "rise"],
+            "enum": [
+              "none",
+              "fade",
+              "rise"
+            ],
             "description": "default fade (~0.35s); stays clip-level even with fx"
           },
           "motion": {
             "type": "array",
-            "description": "Pose keyframes (MO): the clip's transform animated over CLIP-LOCAL time. Values interpolate across the gap between poses (~symmetric in-out ease; a hold is two identical poses); the base transform is the value before the first pose, and absent pose fields inherit it. Pure f(t) \u2014 scrub, export and chunked server renders agree.",
+            "description": "Pose keyframes (MO): the clip's transform animated over CLIP-LOCAL time. Values interpolate across the gap between poses (~symmetric in-out ease; a hold is two identical poses); the base transform is the value before the first pose, and absent pose fields inherit it. Pure f(t) — scrub, export and chunked server renders agree.",
             "items": {
               "type": "object",
-              "required": ["at"],
+              "required": [
+                "at"
+              ],
               "properties": {
                 "at": {
                   "type": "number",
@@ -769,25 +1008,40 @@
           },
           "fx": {
             "type": "object",
-            "description": "text kind only: entrance animation evaluated per unit \u2014 pure f(t), segmentation baked at lowering (scrub/seek/server chunks agree by construction)",
+            "description": "text kind only: entrance animation evaluated per unit — pure f(t), segmentation baked at lowering (scrub/seek/server chunks agree by construction)",
             "properties": {
               "fx": {
-                "enum": ["fade", "rise", "pop", "blur", "typewriter"],
+                "enum": [
+                  "fade",
+                  "rise",
+                  "pop",
+                  "blur",
+                  "typewriter"
+                ],
                 "description": "the entrance; typewriter is a step reveal by unit count"
               },
               "unit": {
-                "enum": ["block", "line", "word", "char"],
-                "description": "what animates as one thing (default block \u2014 the whole text; char is grapheme-safe)"
+                "enum": [
+                  "block",
+                  "line",
+                  "word",
+                  "char"
+                ],
+                "description": "what animates as one thing (default block — the whole text; char is grapheme-safe)"
               },
               "direction": {
-                "enum": ["forward", "reverse", "center"],
+                "enum": [
+                  "forward",
+                  "reverse",
+                  "center"
+                ],
                 "description": "unit start order (default forward; center ripples outward)"
               },
               "stagger": {
                 "type": "number",
                 "minimum": 0,
                 "maximum": 2,
-                "description": "seconds between unit starts (defaults: typewriter 0.05, others 0.06 when unit \u2260 block; clamped so the entrance fits the clip)"
+                "description": "seconds between unit starts (defaults: typewriter 0.05, others 0.06 when unit ≠ block; clamped so the entrance fits the clip)"
               },
               "duration": {
                 "type": "number",
@@ -796,18 +1050,20 @@
                 "description": "per-unit seconds (default 0.35); typewriter ignores it"
               }
             },
-            "required": ["fx"],
+            "required": [
+              "fx"
+            ],
             "additionalProperties": false
           },
           "key": {
             "type": "string",
-            "description": "image/video kinds: media URL or take-dir file (e.g. \"/logo.png\", \"/clip.webm\") \u2014 required for media"
+            "description": "image/video kinds: media URL or take-dir file (e.g. \"/logo.png\", \"/clip.webm\") — required for media"
           },
           "width": {
             "type": "number",
             "exclusiveMinimum": 0,
             "maximum": 1,
-            "description": "media kinds: base width as a FRACTION of the frame width (default 0.35); height follows the media's aspect; \u00d7 transform.scale"
+            "description": "media kinds: base width as a FRACTION of the frame width (default 0.35); height follows the media's aspect; × transform.scale"
           },
           "radius": {
             "type": "number",
@@ -829,10 +1085,14 @@
     },
     "objects": {
       "type": "array",
-      "description": "Compositor v2 (V3): world-space 3D props between the card and the overlays \u2014 the drafted V4 engine spec. Curated primitives, GLB models by key, and extruded 3D text (TX7).",
+      "description": "Compositor v2 (V3): world-space 3D props between the card and the overlays — the drafted V4 engine spec. Curated primitives, GLB models by key, and extruded 3D text (TX7).",
       "items": {
         "type": "object",
-        "required": ["id", "asset", "transform3d"],
+        "required": [
+          "id",
+          "asset",
+          "transform3d"
+        ],
         "additionalProperties": true,
         "properties": {
           "id": {
@@ -840,13 +1100,24 @@
           },
           "asset": {
             "type": "object",
-            "required": ["kind"],
+            "required": [
+              "kind"
+            ],
             "properties": {
               "kind": {
-                "enum": ["primitive", "gltf", "text3d"]
+                "enum": [
+                  "primitive",
+                  "gltf",
+                  "text3d"
+                ]
               },
               "shape": {
-                "enum": ["cube", "sphere", "torus", "knot"],
+                "enum": [
+                  "cube",
+                  "sphere",
+                  "torus",
+                  "knot"
+                ],
                 "description": "primitive kind"
               },
               "color": {
@@ -855,7 +1126,7 @@
               },
               "key": {
                 "type": "string",
-                "description": "gltf kind: GLB URL or take-dir file (e.g. \"/model.glb\") \u2014 bbox-normalized so scale means the same as primitives"
+                "description": "gltf kind: GLB URL or take-dir file (e.g. \"/model.glb\") — bbox-normalized so scale means the same as primitives"
               },
               "text": {
                 "type": "string",
@@ -867,7 +1138,12 @@
                 "description": "text3d kind: a 3D typeface catalog slug or family name (e.g. \"bebas-neue\", \"Playfair Display\"); unknown names fall back to the house face"
               },
               "material": {
-                "enum": ["standard", "metal", "glass", "neon"],
+                "enum": [
+                  "standard",
+                  "metal",
+                  "glass",
+                  "neon"
+                ],
                 "description": "text3d kind: fleet-audited material preset (single-sided, no dispersion; default standard)"
               },
               "depth": {
@@ -899,7 +1175,10 @@
           },
           "transform3d": {
             "type": "object",
-            "required": ["x", "y"],
+            "required": [
+              "x",
+              "y"
+            ],
             "properties": {
               "x": {
                 "type": "number",
@@ -934,15 +1213,21 @@
             "additionalProperties": true
           },
           "animation": {
-            "enum": ["spin", "float", null],
-            "description": "curated deterministic motion \u2014 composes ADDITIVELY on top of motion poses"
+            "enum": [
+              "spin",
+              "float",
+              null
+            ],
+            "description": "curated deterministic motion — composes ADDITIVELY on top of motion poses"
           },
           "motion": {
             "type": "array",
             "description": "Pose keyframes (MO) over transform3d, CLIP-LOCAL time (seconds from span.start; 0 when span-less). Values interpolate across the gap between poses; absent pose fields inherit transform3d; spin/float presets compose additively. Pure f(t).",
             "items": {
               "type": "object",
-              "required": ["at"],
+              "required": [
+                "at"
+              ],
               "properties": {
                 "at": {
                   "type": "number",
@@ -1066,17 +1351,31 @@
     },
     "export": {
       "type": "object",
-      "required": ["resolution", "fps", "format"],
+      "required": [
+        "resolution",
+        "fps",
+        "format"
+      ],
       "properties": {
         "resolution": {
-          "enum": ["720p", "1080p", "2k", "4k"],
+          "enum": [
+            "720p",
+            "1080p",
+            "2k",
+            "4k"
+          ],
           "description": "names the SHORT edge. Presets above the footage's capture width upscale (validate warns)."
         },
         "fps": {
-          "enum": [30, 60]
+          "enum": [
+            30,
+            60
+          ]
         },
         "format": {
-          "enum": ["mp4"],
+          "enum": [
+            "mp4"
+          ],
           "description": "doc-level default; the CLI render's --format flag (webm|mp4) overrides"
         }
       },
@@ -1084,10 +1383,15 @@
     },
     "speed": {
       "type": "array",
-      "description": "Speed-change spans (SOURCE time, footage-anchored, non-overlapping). Absent = all 1\u00d7. The planner proposes source:'auto' spans for typing passages, scroll runs and idle gaps (ids s0\u2026); set source:'manual' on spans you add or edit so they survive a re-plan (absent source also counts as manual).",
+      "description": "Speed-change spans (SOURCE time, footage-anchored, non-overlapping). Absent = all 1×. The planner proposes source:'auto' spans for typing passages, scroll runs and idle gaps (ids s0…); set source:'manual' on spans you add or edit so they survive a re-plan (absent source also counts as manual).",
       "items": {
         "type": "object",
-        "required": ["id", "in", "out", "rate"],
+        "required": [
+          "id",
+          "in",
+          "out",
+          "rate"
+        ],
         "properties": {
           "id": {
             "type": "string"
@@ -1106,20 +1410,31 @@
             "description": "playback rate: 2 = twice as fast"
           },
           "source": {
-            "enum": ["auto", "manual"],
+            "enum": [
+              "auto",
+              "manual"
+            ],
             "description": "'auto' = planner suggestion (typing/scroll/idle), replaced by re-plan; 'manual' (or absent) = user/agent work, always preserved"
           },
           "anchor": {
             "type": "object",
-            "required": ["step"],
+            "required": [
+              "step"
+            ],
             "additionalProperties": false,
             "properties": {
               "step": {
-                "type": ["string", "integer"],
+                "type": [
+                  "string",
+                  "integer"
+                ],
                 "description": "the actions.json step: its `id` when it has one, else its record-time index (meta.steps)"
               },
               "at": {
-                "enum": ["start", "end"],
+                "enum": [
+                  "start",
+                  "end"
+                ],
                 "description": "which edge of the step the span's `in` is measured from (default start)"
               },
               "offset": {
@@ -1127,7 +1442,7 @@
                 "description": "seconds from that edge to the span's `in` (negative = before it)"
               }
             },
-            "description": "Re-record tie: `vos plan --reuse` re-times this span onto a NEW recording of the same script by resolving the step in the new meta.steps. Metadata only \u2014 `in`/`out` stay authoritative and lowering never reads it, so it costs nothing at render time"
+            "description": "Re-record tie: `vos plan --reuse` re-times this span onto a NEW recording of the same script by resolving the step in the new meta.steps. Metadata only — `in`/`out` stay authoritative and lowering never reads it, so it costs nothing at render time"
           }
         },
         "additionalProperties": true