@shotstack/cli 0.3.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Command-line interface for the Shotstack video rendering API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/shotstack/shotstack-cli",
@@ -28,7 +28,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "@shotstack/schemas": "^1.12.2",
+    "commander": "^12.1.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/references/fonts.md

@@ -2,11 +2,9 @@
 
 The Shotstack render engine ships a small built-in font set; everything else must be loaded as a custom font via `timeline.fonts[]`. Per the [Shotstack docs](https://shotstack.io/docs/guide/architecting-an-application/rich-text.md), **prefer custom Google Fonts** for predictable rendering and full typographic range.
 
-## Contents
+## CRITICAL: never fabricate font URLs
 
-- The custom-font workflow (preferred)
-- Built-in fonts (fallback)
-- Why system fonts (Arial, Helvetica) fail
+**Do NOT construct or reconstruct Google Fonts URLs from memory.** Google rotates the version segment (`v26 → v31 → …`) and the hashed filename changes with each version, so any URL you assemble from training data is almost certainly a 404 — and a missing font fails the render. **Copy a URL verbatim** from the verified catalogue below, or from the live Studio SDK catalogue (linked further down). If the exact font you want isn't available verbatim, pick the closest verified match rather than inventing one.
 
 ## Custom-font workflow (preferred)
 
@@ -24,7 +22,7 @@ Load a font from a public URL via `timeline.fonts[]`, then reference its **file
           "asset": {
             "type": "rich-text",
             "text": "Hello",
-            "font": { "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c", "size": 60, "color": "#ffffff" }
+            "font": { "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c", "size": 60, "weight": "700", "color": "#ffffff" }
           },
           "start": 0, "length": 3
         }]
@@ -34,38 +32,42 @@ Load a font from a public URL via `timeline.fonts[]`, then reference its **file
 }
 ```
 
-The `font.family` value is the URL's filename without extension.
+The `font.family` value is the URL's filename without extension, and it **must** match the URL's basename exactly. For URL `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf`, family = `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`. If `family` and the URL basename diverge, the font silently fails to load.
 
-For URL `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf`, family = `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`.
+## Verified font catalogue (12 fonts)
 
-### Where to find Google Fonts URLs
+Copied verbatim from the Studio SDK catalogue. Paste the **url** into `timeline.fonts[].src`, paste the **family** into `asset.font.family`.
 
-The Shotstack Studio SDK ships a curated catalogue of ~400 Google Fonts at <https://github.com/shotstack/shotstack-studio-sdk/blob/main/src/core/fonts/google-fonts.ts>. Each entry has a fastest-served Google Fonts CDN URL.
+| Font (style) | family (use in `font.family`) | url (use in `timeline.fonts[].src`) |
+|---|---|---|
+| Inter (sans, variable) | `UcCo3FwrK3iLTfvlaQc78lA2` | `https://fonts.gstatic.com/s/inter/v20/UcCo3FwrK3iLTfvlaQc78lA2.ttf` |
+| Roboto (sans, variable) | `KFOmCnqEu92Fr1Me5WZLCzYlKw` | `https://fonts.gstatic.com/s/roboto/v50/KFOmCnqEu92Fr1Me5WZLCzYlKw.ttf` |
+| Open Sans (sans, variable) | `mem8YaGs126MiZpBA-U1UpcaXcl0Aw` | `https://fonts.gstatic.com/s/opensans/v44/mem8YaGs126MiZpBA-U1UpcaXcl0Aw.ttf` |
+| Montserrat (sans, variable) | `JTUSjIg1_i6t8kCHKm45xW5rygbi49c` | `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf` |
+| Poppins (sans) | `pxiEyp8kv8JHgFVrFJDUc1NECPY` | `https://fonts.gstatic.com/s/poppins/v24/pxiEyp8kv8JHgFVrFJDUc1NECPY.ttf` |
+| DM Sans (sans, variable) | `rP2Hp2ywxg089UriOZSCHBeHFl0` | `https://fonts.gstatic.com/s/dmsans/v17/rP2Hp2ywxg089UriOZSCHBeHFl0.ttf` |
+| Nunito (sans, variable) | `XRXV3I6Li01BKof4MuyAbsrVcA` | `https://fonts.gstatic.com/s/nunito/v32/XRXV3I6Li01BKof4MuyAbsrVcA.ttf` |
+| Raleway (sans, variable) | `1Ptug8zYS_SKggPN-CoCTqluHfE` | `https://fonts.gstatic.com/s/raleway/v37/1Ptug8zYS_SKggPN-CoCTqluHfE.ttf` |
+| Oswald (display, variable) | `TK3iWkUHHAIjg75GHjUHte5fKg` | `https://fonts.gstatic.com/s/oswald/v57/TK3iWkUHHAIjg75GHjUHte5fKg.ttf` |
+| Bebas Neue (display) | `JTUSjIg69CK48gW7PXooxW5rygbi49c` | `https://fonts.gstatic.com/s/bebasneue/v16/JTUSjIg69CK48gW7PXooxW5rygbi49c.ttf` |
+| Anton (display) | `1Ptgg87LROyAm0K08i4gS7lu` | `https://fonts.gstatic.com/s/anton/v27/1Ptgg87LROyAm0K08i4gS7lu.ttf` |
+| Playfair Display (serif, variable) | `nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU` | `https://fonts.gstatic.com/s/playfairdisplay/v40/nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU.ttf` |
 
-Common picks:
+Variable fonts (most of the above) cover the full weight range (100–900) from a single URL — set `font.weight` in the clip. For the non-variable fonts (Poppins, Bebas Neue, Anton) the registered URL is weight 400; the SDK falls back gracefully when you request a bolder weight.
 
-| Font | URL |
-|---|---|
-| Montserrat 700 | `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf` |
-| Roboto 400 | `https://fonts.gstatic.com/s/roboto/v48/KFOmCnqEu92Fr1Mu4mxKKTU1Kg.ttf` |
-| Inter 700 | `https://fonts.gstatic.com/s/inter/v20/UcCo3FwrK3iLTfvlaQc78lA2.ttf` |
-| Bangers | `https://fonts.gstatic.com/s/bangers/v25/FeVQS0BTqb0h60ACL5la2bxii28.ttf` |
-| Luckiest Guy | `https://fonts.gstatic.com/s/luckiestguy/v25/_gP_1RrxsjcxVyin9l9n_j2RStR3qDpraA.ttf` |
-| Open Sans 400 | `https://fonts.gstatic.com/s/opensans/v40/memSYaGs126MiZpBA-UvWbX2vVnXBbObj2OVZyOOSr4dVJWUgsjZ0B4gaVc.ttf` |
-| Poppins 700 | `https://fonts.gstatic.com/s/poppins/v22/pxiByp8kv8JHgFVrLCz7Z1xlFQ.ttf` |
+### Sourcing more fonts
 
-For other fonts, find the family on <https://fonts.google.com>, view the CSS, and copy the `.ttf` URL from the `@font-face` `src`.
+The Studio SDK ships a curated catalogue of ~400 Google Fonts at <https://github.com/shotstack/shotstack-studio-sdk/blob/main/src/core/fonts/google-fonts.ts>. Copy the `url` and `family` for an entry **verbatim** — do not hand-edit the version or hash. For a font not in that catalogue, open it on <https://fonts.google.com>, view the CSS, and copy the exact `.ttf` URL from the `@font-face` `src` (again, verbatim).
 
 ### Multiple weights / styles
 
-Each weight or style is a separate URL — load each one you need:
+Each weight or style is a **separate URL** — load every one you reference. Look each up in the SDK catalogue rather than guessing the hash:
 
 ```json
 {
   "timeline": {
     "fonts": [
-      { "src": "https://fonts.gstatic.com/s/roboto/v48/KFOmCnqEu92Fr1Mu4mxKKTU1Kg.ttf" },
-      { "src": "https://fonts.gstatic.com/s/roboto/v48/KFOlCnqEu92Fr1MmEU9fBBc4.ttf" }
+      { "src": "https://fonts.gstatic.com/s/roboto/v50/KFOmCnqEu92Fr1Me5WZLCzYlKw.ttf" }
     ]
   }
 }

package/references/html5-snippets.md

@@ -0,0 +1,145 @@
+# HTML5 snippet pack — drop-in motion graphics
+
+Copy-paste `html5` clips that "pop" — kinetic type, count-ups, shine sweeps,
+pulsing CTAs, grain. Each is a **single clip**: paste it into a track's
+`clips[]`, set `start`/`length`, and position with `offset`.
+
+Read [`html5.md`](html5.md) first for the rules these obey. The non-negotiables:
+
+- **Seekable animation only.** GSAP timelines, GSAP tweens (incl. `onUpdate`), anime.js, Lottie, or CSS `@keyframes`. **Never** `setTimeout`/`setInterval`/`requestAnimationFrame`/`Date.now()`/`gsap.call()` — the renderer seeks by absolute time, it doesn't play.
+- **Size the clip to the content, not the canvas.** `html, body` pinned to the clip's `width`/`height`; place with `offset` (`{x:0,y:0}` is centred, `y` positive is up). Use **px**, never `vw`/`vh`/`%`.
+- **The body is transparent by default** — the clip composites over the layers below (only set an opaque background if you want one).
+- **No `<canvas>`** — Studio capture serialises the DOM; canvas bitmaps come through empty. Use SVG or positioned DOM.
+- **No network.** gsap/anime/d3/lottie are preloaded; external `<script src>`, `fetch`, remote `<img>`, and remote fonts are all CSP-blocked — inline everything as `data:` URIs.
+- **Fonts:** `timeline.fonts[]` does **not** reach `html5` and remote `@font-face` is blocked. These snippets name a display font first but render in the `system-ui` fallback unless you inline the font as a `data:` `@font-face`.
+
+Coordinates below assume a **1080×1920 vertical** canvas; adjust `offset` for other sizes. Colours use a neutral ink/accent — swap for your palette.
+
+---
+
+## 1. Kinetic headline (word-by-word rise)
+
+Big title where each word springs up in sequence. GSAP timeline, fully seekable.
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"h\"><span>JUST</span> <span>DROPPED</span></div>",
+    "css": "html,body{margin:0;width:980px;height:420px;overflow:hidden;background:transparent;font-family:'Anton',system-ui,sans-serif}.h{display:flex;flex-wrap:wrap;gap:0 18px;align-items:center;justify-content:center;width:980px;height:420px;text-transform:uppercase;line-height:0.9}.h span{display:inline-block;font-size:150px;font-weight:800;color:#141414;transform:translateY(120%);opacity:0}",
+    "js": "const tl=gsap.timeline();gsap.utils.toArray('.h span').forEach((el,i)=>{tl.to(el,{y:0,opacity:1,duration:0.6,ease:'back.out(1.7)'},i*0.18)});tl.to({},{duration:1.2});"
+  },
+  "start": 0,
+  "length": 3,
+  "width": 980,
+  "height": 420,
+  "offset": { "x": 0, "y": 0.02 }
+}
+```
+
+Each word is a `<span>` starting `translateY(120%)`; the trailing empty tween holds the title still before the clip ends. `Anton` falls back to `system-ui` unless you inline it (see Fonts above): `@font-face{font-family:'Anton';src:url('data:font/woff2;base64,…') format('woff2')}`.
+
+---
+
+## 2. Count-up number / price odometer
+
+Animate a value from 0 to its target. Seek-safe because the count lives in a **tweened object with `onUpdate`** (fires on seek), never a timer.
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"wrap\"><span class=\"cur\">$</span><span id=\"n\">0</span></div>",
+    "css": "html,body{margin:0;width:620px;height:220px;overflow:hidden;background:transparent;font-family:system-ui,sans-serif}.wrap{display:flex;align-items:baseline;justify-content:center;width:620px;height:220px;color:#141414;font-weight:800;font-variant-numeric:tabular-nums}.cur{font-size:70px;margin-right:6px}#n{font-size:150px;letter-spacing:-2px}",
+    "js": "const o={v:0};const out=document.getElementById('n');const tl=gsap.timeline();tl.to(o,{v:395,duration:1.4,ease:'power2.out',onUpdate:()=>{out.textContent=Math.round(o.v)}});tl.to({},{duration:1.0});"
+  },
+  "start": 0,
+  "length": 3,
+  "width": 620,
+  "height": 220,
+  "offset": { "x": 0, "y": -0.1 }
+}
+```
+
+Swap `v:395` for any target. For thousands separators use `Math.round(o.v).toLocaleString()`. Pair with a static label on an adjacent `rich-text` track ("FROM", "AUD").
+
+---
+
+## 3. Shine / gloss sweep
+
+A specular highlight that slides across text or a card — premium product gloss. Pure CSS keyframe (WAAPI-seekable). Put this clip **above** the thing it shines on, or wrap the content in the same clip.
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"plate\"><div class=\"label\">UTOPIA</div><div class=\"shine\"></div></div>",
+    "css": "html,body{margin:0;width:860px;height:280px;overflow:hidden;background:transparent;font-family:'Anton',system-ui,sans-serif}.plate{position:relative;width:860px;height:280px;display:flex;align-items:center;justify-content:center;overflow:hidden}.label{font-size:200px;font-weight:800;letter-spacing:6px;color:#141414;text-transform:uppercase}.shine{position:absolute;top:0;left:0;width:240px;height:280px;background:linear-gradient(100deg,transparent,rgba(255,255,255,0.85),transparent);mix-blend-mode:overlay;transform:translateX(-300px) skewX(-12deg);animation:sweep 2.4s ease-in-out 0.4s 1 both}@keyframes sweep{to{transform:translateX(1100px) skewX(-12deg)}}",
+    "js": ""
+  },
+  "start": 0,
+  "length": 3,
+  "width": 860,
+  "height": 280,
+  "offset": { "x": 0, "y": 0 }
+}
+```
+
+`mix-blend-mode: overlay` makes the sweep read as a real highlight rather than a white bar. No JS needed.
+
+---
+
+## 4. Pulsing CTA button
+
+A "SHOP NOW" pill with a soft breathing glow — draws the eye on an end card. CSS keyframes loop and seek cleanly.
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"cta\">SHOP NOW</div>",
+    "css": "html,body{margin:0;width:620px;height:170px;overflow:hidden;background:transparent;font-family:system-ui,sans-serif}.cta{width:560px;height:128px;margin:21px auto;display:flex;align-items:center;justify-content:center;border-radius:16px;background:#5c3a21;color:#fff;font-size:46px;font-weight:700;letter-spacing:4px;text-transform:uppercase;box-shadow:0 0 0 0 rgba(92,58,33,0.5);animation:pulse 1.6s ease-in-out 0s infinite both}@keyframes pulse{0%,100%{transform:scale(1);box-shadow:0 0 0 0 rgba(92,58,33,0.45)}50%{transform:scale(1.04);box-shadow:0 0 36px 8px rgba(92,58,33,0.35)}}",
+    "js": ""
+  },
+  "start": 0,
+  "length": 4,
+  "width": 620,
+  "height": 170,
+  "offset": { "x": 0, "y": -0.4 }
+}
+```
+
+The clip is wider/taller than the pill so the glow has room (`overflow:hidden` would otherwise clip it). For a non-looping single pop, replace `infinite` with `1`.
+
+---
+
+## 5. Film-grain / texture overlay
+
+A subtle moving grain over the whole frame — adds a moody, analogue feel (great over dark scenes). SVG `feTurbulence`, animated by shifting a slightly-oversized layer so it never reveals an edge. Size this one **to the canvas** and put it on a top track at low opacity.
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"grain\"></div>",
+    "css": "html,body{margin:0;width:1080px;height:1920px;overflow:hidden;background:transparent}.grain{position:absolute;top:-5%;left:-5%;width:110%;height:110%;opacity:0.12;background-image:url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='200' height='200'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/></filter><rect width='200' height='200' filter='url(%23n)'/></svg>\");background-size:240px 240px;animation:drift 0.6s steps(4) 0s infinite both}@keyframes drift{0%{transform:translate(0,0)}25%{transform:translate(-12px,8px)}50%{transform:translate(10px,-10px)}75%{transform:translate(-8px,-6px)}100%{transform:translate(0,0)}}",
+    "js": ""
+  },
+  "start": 0,
+  "length": 10,
+  "width": 1080,
+  "height": 1920,
+  "offset": { "x": 0, "y": 0 }
+}
+```
+
+A `data:` URI is fine **inside an html5 asset's CSS** (it's iframe content, not an `asset.src` the render workers fetch). Tune `opacity` (0.06–0.18) and `baseFrequency` (higher = finer grain). `steps(4)` gives a filmic stutter rather than smooth slide.
+
+---
+
+## Composing these
+
+- Each snippet is one clip on its own track. Layer order is top-track-first (see `agent-core.md`) — grain and shine go in **early** tracks, backgrounds in **late** ones.
+- They don't overlap on a single track, so `shotstack validate <file>` stays clean. Run it before rendering.
+- Reuse text via top-level `merge[]` (`{{title}}` in the HTML) — see the lower-third example in `html5.md`.
+- Heavier motion = longer render. Preview in `shotstack studio <file>` before spending credits.

package/references/html5.md

@@ -0,0 +1,252 @@
+# HTML5 asset guide
+
+The `html5` asset type renders a self-contained HTML/CSS/JS page inside a video clip. Use it for animated overlays, data visualisations, motion graphics, and anything you'd build as a tiny single-page web app.
+
+This is the **modern replacement for the deprecated `html` asset.** `html5` runs in a real browser iframe with a JS runtime, library preloads, and deterministic frame capture — the old `html` asset should never be used.
+
+## Contents
+
+- Required and optional fields
+- Preloaded libraries
+- The browser harness (deterministic auto-seek)
+- Sandbox restrictions: no network, inline everything (incl. fonts)
+- Sizing
+- Worked example: animated lower-third (GSAP)
+- Worked example: animated bar chart (D3 + GSAP)
+- Worked example: 10-second countdown (pure CSS)
+- Common mistakes
+- When to use `html5` vs `rich-text`/`svg`
+
+## Required and optional fields
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| `type` | Yes | `"html5"` | Discriminator. |
+| `html` | Yes | string | Body markup. Supports merge fields (`{{title}}`). |
+| `css` | No | string | Stylesheet. Inlined into the iframe `<head>`. |
+| `js` | No | string | Script. Runs after libraries are preloaded. |
+
+Clip-level `width` and `height` set the iframe's pixel dimensions. They default to the edit's natural size.
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"card\"><h1>{{title}}</h1></div>",
+    "css": ".card { font-family: 'Inter'; padding: 32px; color: #fff; }",
+    "js": "gsap.to('.card', { x: 200, duration: 1 });"
+  },
+  "start": 0,
+  "length": 4,
+  "width": 1920,
+  "height": 1080
+}
+```
+
+## Preloaded libraries
+
+Four libraries are always available — no `<script src=>` tags needed:
+
+- **GSAP** (`window.gsap`) — primary animation library. Use timelines (`gsap.timeline()`) over loose tweens; the harness seeks timelines correctly.
+- **anime.js** (`window.anime`) — alternative animation library.
+- **D3** (`window.d3`) — for data binding, scales, and SVG/DOM construction. Pair with GSAP for the actual animation; D3's transitions work too but GSAP is more reliable under seek.
+- **Lottie** (`window.lottie`) — Bodymovin JSON player (SVG-renderer build; `renderer: "canvas"` is unavailable).
+
+These cover ~95% of motion-graphics use cases. **You can't load other libraries via `<script src=>`** — the iframe's CSP blocks all external scripts and network access (see *Sandbox restrictions* below).
+
+## The browser harness (deterministic auto-seek)
+
+Frames are captured by **seeking** the animation to each timestamp, not by playing in real time — so your animation must be **seekable**. GSAP (timelines or tweens), anime.js, Lottie, and CSS (`@keyframes`, transitions, `Element.animate()`) are all driven automatically. Anything time-driven that isn't seekable gives a frozen or wrong frame: never use `setTimeout`, `setInterval`, `requestAnimationFrame` loops, `Date.now()` / `performance.now()`, or `gsap.call()`. For "different content at different times" (countdowns, tickers, scene swaps) use the staggered-CSS pattern (see the countdown example) or an `onUpdate` tween (see the count-up snippet).
+
+**Duration comes from the clip's `length`** — there's no animation-duration auto-detection. Size your animation to run within (or fill) the clip's `length`.
+
+## Sandbox restrictions: no network, inline everything
+
+The iframe renders under a strict Content-Security-Policy (`default-src 'none'`), in both Studio preview and cloud render. Nothing is fetched from the network at render time:
+
+- **No external `<script src=>`.** Only the bundled GSAP/anime.js/D3/Lottie run (they're inlined for you). Another library would have to be inlined into your `js` — and must be seekable.
+- **No `fetch` / `XMLHttpRequest`** (`connect-src 'none'`). Bundle any data inline — e.g. the JS array in the bar-chart example.
+- **No remote images** (`img-src 'self' data: blob:`). Embed images as `data:` URIs. A `data:image/svg+xml` background is fine.
+- **No remote fonts** (`font-src 'self' data:`) — see below.
+
+### Fonts in HTML5
+
+`timeline.fonts[]` does **not** apply to `html5` assets (it loads fonts for `rich-text` / `rich-caption` only), and a remote `@font-face` URL (Google Fonts, etc.) is CSP-blocked. Two ways to get a custom font into an `html5` clip:
+
+1. **Inline it as a `data:` `@font-face`** — base64-encode the `.woff2` / `.ttf`:
+   ```css
+   @font-face { font-family: 'Brand'; src: url('data:font/woff2;base64,<…>') format('woff2'); }
+   .title { font-family: 'Brand', sans-serif; }
+   ```
+2. **Use a system family** (`system-ui`, `Arial`, `Georgia`, …) — resolves in the render browser with no load.
+
+An unresolved family silently falls back to the browser default — the render won't fail, but the text won't be your font. For a single styled line, a `rich-text` asset (which *does* use `timeline.fonts[]`; verified catalogue in `references/fonts.md`) is simpler than a `data:` font embed.
+
+## Sizing
+
+The single most important rule: **size the clip to the content, not to the canvas.** Then position with `offset`.
+
+The clip's `width` / `height` are the iframe's natural pixel dimensions — match them to the content's real size; every coordinate inside the iframe is in that pixel space. Sizing the clip to the whole canvas when the content is a small corner overlay wastes space and makes it harder to place — size to the content and move it with `offset`.
+
+**Right pattern:**
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"bar\">…</div>",
+    "css": "html,body{margin:0;padding:0;width:560px;height:120px;background:transparent;overflow:hidden}.bar{width:560px;height:120px;…}"
+  },
+  "width": 560,
+  "height": 120,
+  "offset": { "x": -0.29, "y": -0.33 }
+}
+```
+
+- Clip `width` / `height` matches the content's natural size (560 × 120 for a typical lower-third bar)
+- CSS `html, body` matches the clip dimensions exactly
+- The `.bar` (or whatever the root visual is) fills the body — no `position: absolute; left: …` inside the iframe
+- `offset` positions the clip on the canvas (`{x: 0, y: 0}` is centred; `x` ±0.5 is the canvas edges; `y` positive is up, negative is down)
+
+**Reserved for the canvas-spanning case:** sizing the clip to the full output (`width: 1920, height: 1080`) is correct only when the content really fills the frame — animated charts, scene transitions, full-screen titles. For overlays (lower-thirds, badges, watermarks, callouts), always size to the content.
+
+**General rules either way:**
+
+- Use **fixed pixel values throughout** (`px`, not `vw` / `vh` / `%` on root). The capture happens at the iframe's natural size, not a viewport.
+- The harness already applies a reset — `margin:0; padding:0; box-sizing:border-box; overflow:hidden`, and `body { background: transparent }` — so you mainly need to pin the explicit `width`/`height` on `html, body`. The body is transparent by default; it composites over the track below.
+- The iframe doesn't know about the clip — every internal coordinate is in iframe-pixel space.
+
+## Worked example: animated lower-third (GSAP)
+
+Slide-in name + role bar with subtle accent. **Clip sized to the bar (560×120), positioned via `offset`.** 5 seconds.
+
+```json
+{
+  "timeline": {
+    "tracks": [
+      {
+        "clips": [
+          {
+            "asset": {
+              "type": "html5",
+              "html": "<div class=\"bar\"><div class=\"accent\"></div><div class=\"text\"><div class=\"name\" id=\"name\">{{name}}</div><div class=\"role\" id=\"role\">{{role}}</div></div></div>",
+              "css": "html,body{margin:0;padding:0;width:560px;height:120px;overflow:hidden;font-family:system-ui,sans-serif;background:transparent}.bar{display:flex;align-items:center;width:560px;height:120px;padding:0 32px;box-sizing:border-box;background:rgba(15,23,42,0.92);border-radius:12px;box-shadow:0 12px 40px rgba(0,0,0,0.45);opacity:0}.accent{width:6px;height:72px;background:linear-gradient(180deg,#22d3ee,#a78bfa);border-radius:3px;margin-right:24px;transform:scaleY(0);transform-origin:top}.text{display:flex;flex-direction:column;color:#fff}.name{font-size:44px;font-weight:700;letter-spacing:-0.5px;opacity:0;transform:translateX(-12px)}.role{font-size:22px;font-weight:500;color:#94a3b8;margin-top:4px;opacity:0;transform:translateX(-12px)}",
+              "js": "const tl=gsap.timeline();tl.to('.bar',{opacity:1,duration:0.5,ease:'power2.out'},0).to('.accent',{scaleY:1,duration:0.5,ease:'power3.out'},0.2).to('#name',{opacity:1,x:0,duration:0.5,ease:'power2.out'},0.35).to('#role',{opacity:1,x:0,duration:0.5,ease:'power2.out'},0.5).to({},{duration:3.5}).to('.bar',{opacity:0,duration:0.5,ease:'power2.in'});"
+            },
+            "start": 0,
+            "length": 5,
+            "width": 560,
+            "height": 120,
+            "offset": { "x": -0.29, "y": -0.39 }
+          }
+        ]
+      }
+    ]
+  },
+  "merge": [
+    { "find": "name", "replace": "Sarah Chen" },
+    { "find": "role", "replace": "Head of Product" }
+  ],
+  "output": { "format": "mp4", "resolution": "1080" }
+}
+```
+
+**Patterns to copy:**
+
+- **Clip is the size of the bar, not the canvas** — placement is one `offset` change.
+- **`html, body, .bar` all 560×120.** No absolute positioning inside the iframe — the bar IS the iframe content.
+- One GSAP timeline drives every animation.
+- Merge fields (`{{name}}`, `{{role}}`) in the HTML, populated by **top-level** `merge[]` (sibling of `timeline`/`output`, NOT a clip property). Keeps the asset reusable.
+- A trailing `.to({}, { duration: 3.5 })` holds the final state before the clip ends.
+
+## Worked example: animated bar chart (D3 + GSAP)
+
+D3 builds the SVG; GSAP animates the bars growing in. 6 seconds, 1080p.
+
+```json
+{
+  "timeline": {
+    "tracks": [
+      {
+        "clips": [
+          {
+            "asset": {
+              "type": "html5",
+              "html": "<div class=\"stage\"><h1>Sessions by country</h1><div class=\"sub\">Last 30 days</div><svg id=\"chart\" width=\"1600\" height=\"640\" viewBox=\"0 0 1600 640\"><defs><linearGradient id=\"g\" x1=\"0\" x2=\"0\" y1=\"0\" y2=\"1\"><stop offset=\"0%\" stop-color=\"#22d3ee\"/><stop offset=\"100%\" stop-color=\"#0891b2\"/></linearGradient></defs></svg></div>",
+              "css": "html,body{margin:0;padding:0;width:1920px;height:1080px;overflow:hidden;font-family:system-ui,sans-serif;background:radial-gradient(ellipse at 20% 0%,#0f172a 0%,#03020b 100%);color:#e2e8f0}.stage{position:relative;width:1920px;height:1080px;padding:96px 160px;box-sizing:border-box}h1{margin:0;font-size:64px;font-weight:800;letter-spacing:-2px;color:#fff;opacity:0}.sub{margin-top:12px;font-size:24px;color:#94a3b8;opacity:0}#chart{position:absolute;top:280px;left:160px;opacity:0}.bar{fill:url(#g)}.label{font-size:22px;font-weight:700;fill:#fff;font-variant-numeric:tabular-nums}.cat{font-size:18px;fill:#94a3b8;text-transform:uppercase;letter-spacing:1px}",
+              "js": "const data=[{c:'US',v:48230},{c:'IN',v:32140},{c:'GB',v:21670},{c:'DE',v:18450},{c:'BR',v:15890},{c:'JP',v:14210},{c:'AU',v:11630}];const W=1600,H=640,M={t:20,r:120,b:60,l:120};const iw=W-M.l-M.r,ih=H-M.t-M.b;const x=d3.scaleBand().domain(data.map(d=>d.c)).range([0,iw]).padding(0.28);const y=d3.scaleLinear().domain([0,d3.max(data,d=>d.v)*1.05]).range([ih,0]);const g=d3.select('#chart').append('g').attr('transform',`translate(${M.l},${M.t})`);const bars=g.selectAll('rect').data(data).enter().append('rect').attr('class','bar').attr('x',d=>x(d.c)).attr('y',ih).attr('width',x.bandwidth()).attr('height',0).attr('rx',8);const labels=g.selectAll('text.label').data(data).enter().append('text').attr('class','label').attr('x',d=>x(d.c)+x.bandwidth()/2).attr('y',ih).attr('text-anchor','middle').text(d=>d.v.toLocaleString()).style('opacity',0);const cats=g.selectAll('text.cat').data(data).enter().append('text').attr('class','cat').attr('x',d=>x(d.c)+x.bandwidth()/2).attr('y',ih+34).attr('text-anchor','middle').text(d=>d.c);const tl=gsap.timeline();tl.to('h1',{opacity:1,duration:0.6,ease:'power3.out'},0.1).to('.sub',{opacity:1,duration:0.5,ease:'power2.out'},0.5).to('#chart',{opacity:1,duration:0.4,ease:'power2.out'},0.7);bars.each(function(d,i){tl.to(this,{attr:{y:y(d.v),height:ih-y(d.v)},duration:0.7,ease:'power2.out'},1.0+i*0.08)});labels.each(function(d,i){tl.to(this,{attr:{y:y(d.v)-14},opacity:1,duration:0.4,ease:'power2.out'},1.4+i*0.08)});"
+            },
+            "start": 0,
+            "length": 6,
+            "width": 1920,
+            "height": 1080
+          }
+        ]
+      }
+    ]
+  },
+  "output": { "format": "mp4", "resolution": "1080" }
+}
+```
+
+**Patterns to copy:**
+
+- D3 builds DOM; **GSAP animates it**. D3's `.transition()` works but GSAP is the more reliable seek target.
+- Bars start at `y = ih, height = 0` (collapsed at the baseline); GSAP grows them up via `attr: { y, height }`.
+- Stagger via `1.0 + i * 0.08` per bar — each bar starts 80ms after the previous.
+
+## Worked example: 10-second countdown (pure CSS)
+
+A countdown is "show different content at different times" — the classic case where authors reach for `setTimeout` or `gsap.call()`. **Both are wrong** because the capture harness seeks by absolute time, not by playing through real time. The right pattern: render every state up-front, hide them with `opacity:0`, and use one CSS animation per state with staggered `animation-delay`.
+
+```json
+{
+  "asset": {
+    "type": "html5",
+    "html": "<div class=\"stage\"><div id=\"n10\" class=\"num\">10</div><div id=\"n9\" class=\"num\">9</div><div id=\"n8\" class=\"num\">8</div><div id=\"n7\" class=\"num\">7</div><div id=\"n6\" class=\"num\">6</div><div id=\"n5\" class=\"num\">5</div><div id=\"n4\" class=\"num\">4</div><div id=\"n3\" class=\"num\">3</div><div id=\"n2\" class=\"num\">2</div><div id=\"n1\" class=\"num\">1</div></div>",
+    "css": "html,body{margin:0;width:1920px;height:1080px;background:#000;font-family:system-ui,sans-serif;overflow:hidden}.stage{position:relative;width:1920px;height:1080px}.num{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:280px;font-weight:900;color:#fff;opacity:0}@keyframes pop{0%,100%{opacity:0;transform:scale(1.3)}10%,90%{opacity:1;transform:scale(1)}}#n10{animation:pop 1s linear 0s 1 both}#n9{animation:pop 1s linear 1s 1 both}#n8{animation:pop 1s linear 2s 1 both}#n7{animation:pop 1s linear 3s 1 both}#n6{animation:pop 1s linear 4s 1 both}#n5{animation:pop 1s linear 5s 1 both}#n4{animation:pop 1s linear 6s 1 both}#n3{animation:pop 1s linear 7s 1 both}#n2{animation:pop 1s linear 8s 1 both}#n1{animation:pop 1s linear 9s 1 both}"
+  },
+  "start": 0,
+  "length": 10,
+  "width": 1920,
+  "height": 1080
+}
+```
+
+No JS at all — each number is a CSS animation in its own time slot, so every captured frame shows whichever number is mid-pop.
+
+**Patterns to copy:**
+
+- **One element per state.** `<div id="n10">10</div>`, `<div id="n9">9</div>`, ... — never mutate `textContent` from JS.
+- **Stagger via `animation-delay`.** `0s, 1s, 2s, ...` lines each animation up to a unique slot.
+- **`animation-fill-mode: both`.** During the delay phase the element shows the `0%` keyframe (`opacity:0`); after the animation it shows the `100%` keyframe (`opacity:0`). Together with `position:absolute;inset:0`, only the currently-animating element is visible.
+
+The same pattern scales to scene transitions (each scene is a `<section>` with its own animation slot), tickers (each price is a `<div>` with a slot), animated lists, etc.
+
+## Common mistakes
+
+1. **`<canvas>` elements.** The Studio frame capture serialises the iframe's DOM via `XMLSerializer`. A `<canvas>` element's bitmap lives in the 2D-context backing store, NOT in the DOM — so the cloned canvas comes through empty and **the captured frames show nothing where the canvas was**. The cloud render (puppeteer) handles canvas correctly, but Studio playback won't, so the parity is broken. Use SVG or positioned HTML elements instead:
+
+   | Want | Replace `<canvas>` with |
+   |---|---|
+   | Particles / generative graphics | Positioned `<div>` elements animated with CSS transforms, or `<circle>` in SVG |
+   | Charts (line / bar / area) | D3 → `<svg>` (see the bar-chart worked example) |
+   | Pixel-level effects | CSS filters (`filter: blur(...) hue-rotate(...)`), `<feFilter>` in SVG |
+   | Free-form drawings | SVG `<path>` |
+
+   If you're building something that genuinely cannot be expressed without canvas, render it as a `<video>` or `<image>` asset instead of an `html5` clip.
+2. **Mismatched dimensions.** If `clip.width = 1920` and your CSS sets `body { width: 1280px }`, content gets cropped or stretched. Pin the iframe's `html, body` dimensions to the clip dimensions.
+
+## When to use `html5` vs `rich-text`/`svg`
+
+| Need | Use |
+|---|---|
+| Single line of styled text with a font, colour, and position | `rich-text` (faster, no iframe overhead) |
+| A few static shapes (rectangles, circles, paths) | `svg` (lighter than HTML5) |
+| Animated motion graphics (timeline of fades/slides/scales) | `html5` with GSAP |
+| Data visualisation (charts, dashboards, mock UIs) | `html5` with D3 + GSAP |
+| Lottie animation | `html5` with `lottie.loadAnimation(...)` |
+| Animated text effects beyond what `rich-text` offers | `html5` with GSAP |
+| Logo lockup with text + shapes (no animation) | `rich-text` + `svg` on adjacent tracks |
+
+Reach for `html5` when the alternative would be an unwieldy stack of separate tracks or when the design genuinely needs DOM-style layout (flexbox, grid, layered backgrounds with shadows). For static or single-property animation, the lighter assets render faster.

package/references/ingest.md

@@ -0,0 +1,121 @@
+# Ingesting local files (Ingest API)
+
+The `shotstack ingest` commands host your own media on Shotstack so it can be
+referenced from an Edit. This is the **Ingest API** — a separate service from
+the Edit (render) API, living at `https://api.shotstack.io/ingest/{env}`. The
+CLI targets it automatically; the same `SHOTSTACK_API_KEY` works for both.
+
+Use it when your footage, audio, images, fonts, or subtitle files live on your
+machine (or behind a URL) rather than already being on a public CDN. Sources
+are stored until you delete them.
+
+## The one rule that matters
+
+**An Edit can only reference media by URL.** A local path in an `asset.src`
+will not render. So the flow is always:
+
+```
+local file ──▶ shotstack ingest upload ──▶ hosted "source" URL ──▶ Edit asset.src ──▶ shotstack render
+```
+
+`shotstack ingest upload <file>` performs the two-step Ingest dance for you in
+one command: it asks the API for a pre-signed URL, then streams your file's
+bytes straight to storage.
+
+## Get the hosted URL: use `--watch`
+
+The bare command returns only a source **id** — the hosted URL does not exist
+until ingestion finishes. Pass `--watch` to poll until the source is `ready`
+and print its URL:
+
+```sh
+shotstack ingest upload ./intro.mp4 --watch --output json
+# → {"id":"zzytey4v-...","status":"importing"}
+# → {"id":"zzytey4v-...","status":"ready","source":"https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/.../source.mp4","width":1920,"height":1080,"duration":12.4}
+```
+
+The `source` field is the URL to drop into your Edit. In text mode the final
+line is just `ready  <url>`, easy to capture in a shell variable:
+
+```sh
+SRC=$(shotstack ingest upload ./intro.mp4 --watch --output json | tail -n1 | jq -r .source)
+```
+
+Without `--watch`, capture the id and poll it later:
+
+```sh
+ID=$(shotstack ingest upload ./intro.mp4 --output json | jq -r .id)
+shotstack ingest status "$ID" --watch --output json
+```
+
+## Worked example: upload then render
+
+```sh
+# 1. Upload a local clip and a local logo, capturing the hosted URLs.
+VIDEO=$(shotstack ingest upload ./clip.mp4 --watch --output json | tail -n1 | jq -r .source)
+LOGO=$(shotstack ingest upload ./logo.png  --watch --output json | tail -n1 | jq -r .source)
+
+# 2. Reference them in an Edit (asset.src), then render.
+cat > edit.json <<JSON
+{
+  "timeline": {
+    "tracks": [
+      { "clips": [ { "asset": { "type": "image", "src": "$LOGO" },  "start": 0, "length": 5 } ] },
+      { "clips": [ { "asset": { "type": "video", "src": "$VIDEO" }, "start": 0, "length": 5 } ] }
+    ]
+  },
+  "output": { "format": "mp4", "size": { "width": 1920, "height": 1080 } }
+}
+JSON
+
+shotstack render edit.json --watch
+
+or
+
+shotstack studio edit.json
+```
+
+Remember `tracks[0]` is the **top** layer (see `shared/agent-core.md`), so the
+logo track sits above the video.
+
+## Fetch a remote URL instead of uploading
+
+If the media is already at a URL but you want Shotstack to host its own copy
+(stable, no hot-linking), use `fetch`:
+
+```sh
+shotstack ingest fetch https://example.com/big-video.mp4 --watch --output json
+```
+
+This only works for fully validated urls. YouTube and similar video hosting  
+platforms are not supported.
+
+## Manage stored sources
+
+```sh
+shotstack ingest list --output json          # every source you've ingested
+shotstack ingest status <id> --output json   # one source's status + hosted URL
+shotstack ingest delete <id>                  # remove a source from storage
+```
+
+## Status values
+
+`queued` → `importing` → `ready` (terminal). A failed import ends in `failed`
+(exit code 1 under `--watch`). `deleted` and `overwritten` are also terminal.
+
+## Supported files
+
+Video, image, audio, font, and subtitle (`.srt`/`.vtt`) files. The CLI infers
+a `Content-Type` from the file extension; uncommon extensions still upload
+(the API sniffs the content) but naming files with a correct extension is
+safest.
+
+## Environments
+
+Sources are ingested into the environment you target (`--env stage` or `--env
+v1`, default `v1`), mirroring `render`. Override the base URL for local testing
+with `SHOTSTACK_INGEST_BASE_URL`.
+
+```sh
+shotstack ingest upload ./clip.mp4 --watch --env stage
+```