@koda-sl/baker-cli 0.71.2 → 0.79.0

package/README.md

@@ -1661,7 +1661,7 @@ baker images find "office" --sources library,magnific --fallback --threshold 0.4
 baker images find "celebration" --sources library,giphy --auto-ingest 3
 ```
 
-Providers: `library`, `magnific`, `google`, `iconify`, `giphy`. Brandfetch is not part of the fanout — it takes a domain, not a query, so it lives at `baker images logo <domain>`. Response shape: `{ groups: { library, external }, ingested, meta: { counts, errors } }`. When `--auto-ingest` is used, `ingested[]` preserves successful external ingest order and matching external hits are enriched with the Baker-owned URL plus source provenance. Partial failures (one provider throws) return the successful providers plus a `meta.errors` array; the whole call never fails on a single provider error.
+Providers: `library`, `magnific`, `google`, `iconify`, `giphy`, `pinterest`. Brandfetch is not part of the fanout — it takes a domain, not a query, so it lives at `baker images logo <domain>`. (`pinterest` is photo-real/candid imagery — best for sourcing fresh people and sets, e.g. a recast creator or a pinned location in a video reproduction.) Response shape: `{ groups: { library, external }, ingested, meta: { counts, errors } }`. When `--auto-ingest` is used, `ingested[]` preserves successful external ingest order and matching external hits are enriched with the Baker-owned URL plus source provenance. Partial failures (one provider throws) return the successful providers plus a `meta.errors` array; the whole call never fails on a single provider error.
 
 **Flags:**
 
@@ -2219,6 +2219,60 @@ baker testimonials list --source google --sentiment positive --limit 20
 
 ---
 
+### Winning Ads (`baker winning-ads`)
+
+Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
+
+> Backend env: the Convex deployment must have `AD_DNA_API_TOKEN` set (`npx convex env set AD_DNA_API_TOKEN …`). `AD_DNA_API_URL` is optional and defaults to `https://ads.withbaker.com`.
+
+### `baker winning-ads search <query>`
+
+Semantic search (dense recall + BM25 + rerank). The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`; plus top-level `pool_size` and `match_confidence`. `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
+
+> `media_url` is the creative itself: for `static` it's the image, for `video` it's the video file. ad-dna stores **no separate poster** for videos, so a video result has only the video URL.
+
+> Results are already de-junked and winner-first: the corpus auto-drops measured failures (duds, thrash) and ranks `final = relevance^0.25 × winner_score^0.75`. So `--winner-category winner` is usually unnecessary — it's a stricter filter that also removes `untested` (unproven-but-maybe-fresh) ads. Rely on the default + `--min-relevance`; only add `--winner-category` to force-exclude unproven creatives. (Restricting to a single `--advertiser-id` turns the failure-exclusion off — you then see that brand's duds too.)
+
+```bash
+# Only LinkedIn video ads:
+baker winning-ads search "B2B lead gen demo" --platform linkedin --format video --output md
+# Cross-platform, exclude our own brand + an advertiser we already mined:
+baker winning-ads search "fintech onboarding" --exclude-advertiser adv_ourbrand,adv_usedbefore --output md
+# Similar-to a reference ad, recent only:
+baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00:00Z --limit 5 --output md
+```
+
+| Flag | Purpose |
+|---|---|
+| `query` (positional) | Free-text natural-language query |
+| `--ref-ad-id <id>` | Find ads similar to this ad (instead of free text) |
+| `--limit <n>` | Max results 1–100 (**default 10** — shortlist size) |
+| `--max-per-advertiser <n>` | Cap results per advertiser 1–50 (default 3) |
+| `--min-relevance <0-1>` | Relevance floor; trims weak matches |
+| `--platform <list>` | One or many of `meta,tiktok,linkedin,google_search,google_display,youtube,reddit,x,pinterest,snapchat` — pass a single value to search **only** that platform |
+| `--format <list>` | `video,static,carousel` |
+| `--winner-category <list>` | `winner,scaled_winner,evergreen,rising,untested,dud,…` (default: all) |
+| `--awareness <list>` | `unaware,problem_aware,solution_aware,product_aware,most_aware` |
+| `--advertiser-id <list>` | **Restrict to** these advertiser ids (browse one brand's winners) |
+| `--exclude-advertiser <list>` | **Drop** these advertiser ids — your own brand + already-used references |
+| `--country <list>` / `--language <list>` | Filter by country / language codes |
+| `--first-seen-after` / `--first-seen-before` | ISO datetime bounds (recency) |
+| `--output json\|md\|files` | Output format (default json) |
+| `--full` | Include DNA detail + longevity |
+
+Reading the scores: **`relevance`** (0–1) = match of the creative to your query; **`winner_score`** = how proven the ad is in-market. Pick references that are both relevant *and* proven.
+
+### `baker winning-ads advertisers <brand>`
+
+Resolve a brand name → `advertiser_id`(s) in the corpus. Use it to find **your own** advertiser (to `--exclude-advertiser`) or a **competitor** (to `--advertiser-id`). Returns `advertiser_id`, `label`, `active_ads`, `total_ads`.
+
+```bash
+baker winning-ads advertisers "Acme" --output md          # find our own advertiser id
+baker winning-ads advertisers "Deel" --platform meta --output md
+```
+
+---
+
 ### Scheduled Actions (`baker scheduled-actions`)
 
 Manage company-scoped scheduled recipes that spawn Work Actions later or on a cadence. `create`, `update`, and `delete` stage draft ops on `BAKER_CHAT_ID` and apply when the chat is published. `list` and `get` include draft state when `BAKER_CHAT_ID` is set. `trigger` runs immediately on a published scheduled action and does not require a chat id. Use a regular Work Action instead when there is no date or cadence.
@@ -2347,7 +2401,7 @@ A re-run with no changes hits the cache for every node — total runtime drops t
 
 1. **You write a JSON file** describing nodes and how they wire together (`$ref:other_node.output`).
 2. **The validator** checks the schema, every node's params against the model registry, and that every `{{slot}}` in a prompt has a wired input.
-3. **The engine** runs nodes in topological order. Local nodes (text, ffmpeg, imagemagick, hyperframe_*, font_specimen) execute in-process. Remote nodes (text_generate, image_generate, image_describe, image_search, video_generate, tts, music…) POST to the Convex backend.
+3. **The engine** runs nodes in topological order. Local nodes (text, ffmpeg, imagemagick, hyperframe_*, font_specimen) execute in-process. Remote nodes (text_generate, image_generate, image_describe, image_search, video_generate, tts, audio_voice_convert, music…) POST to the Convex backend. (`audio_voice_convert` is ElevenLabs Voice Changer / speech-to-speech — re-voices a clip's audio in one target voice while preserving timing; used to give Seedance native-audio talking heads a consistent brand voice.)
 4. **Outputs land on disk** the moment each node finishes — assets are downloaded from S3 and named `<node_id>__<slot>[__<index>].<ext>` inside the run dir.
 5. **The cache** is content-addressed by node params + input hashes. Edit a prompt, only the dependent nodes re-run.
 
@@ -2446,7 +2500,9 @@ Local ImageMagick passthrough. Identical schema and safety contract to `ffmpeg`;
 
 ##### `hyperframe_render`
 
-Render an HTML/CSS/GSAP composition to **mp4**. Quality, format, and worker count are fixed by the engine for ad-creative delivery — the canvas owns only the composition path and composition vars.
+Render an HTML/CSS/GSAP composition to **mp4** (default), or to a transparent **webm**/**mov** alpha overlay. Quality and worker count are fixed by the engine for ad-creative delivery; the canvas owns the composition path, the output format, and the composition vars.
+
+Before each render the engine runs a **pre-render quality gate** on the *substituted* composition — Hyperframes' own `lint` + `inspect`. Layout **overflow** (clipped text) and structural lint **errors block** the render; **low-contrast** text and missing brand fonts/assets only **warn** (logged as `hyperframe check warning …`). If the `hyperframes` binary or its subcommands are unavailable the gate degrades gracefully and the render proceeds.
 
 **Inputs**
 
@@ -2457,6 +2513,7 @@ Open record keyed by the composition's `meta.json` inputs (declared per composit
 | Name | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `composition` | string | yes | — | path to composition dir |
+| `format` | `mp4 \| webm \| mov` | no | `mp4` | `webm`/`mov` render WITH transparency (alpha) when the composition background is transparent — for overlays you composite elsewhere |
 | `timeout_ms` | number | no | 600000 | positive |
 | **composition vars** | per `meta.json` | per `meta.json` | per `meta.json` | substituted into `{{var}}` |
 
@@ -2464,7 +2521,7 @@ Open record keyed by the composition's `meta.json` inputs (declared per composit
 
 | Slot | Kind | MIME |
 |---|---|---|
-| `video` | video | `video/mp4` |
+| `video` | video | `video/mp4`, `video/webm`, or `video/quicktime` (by `format`) |
 
 See [authoring compositions](#authoring-compositions) for the composition file format.
 
@@ -2472,7 +2529,7 @@ See [authoring compositions](#authoring-compositions) for the composition file f
 
 ##### `hyperframe_snapshot`
 
-Render the same composition format to a **PNG** still at **2× device-scale** (retina). Output size = composition `meta.json` `width × height × 2`.
+Render the same composition format to a **PNG** still at **2× device-scale** (retina). Output size = composition `meta.json` `width × height × 2`. Runs the same pre-render `lint`/`inspect` gate as `hyperframe_render` (overflow/structural errors block; contrast/asset advisories warn).
 
 **Inputs**
 
@@ -3560,15 +3617,21 @@ Turn a reference video into a **runnable, self-validated reproduction canvas** i
 
 It then scaffolds the full pipeline: per scene, two **static-ad-grade frames** (`image_generate` with its **own self-contained `params.prompt`** — edit a frame node to change only that frame; `prompt.json` is wired as a demoted shared-style `target_blueprint`, a per-element reference legend, the real extracted frame as a composition anchor) → `video_generate` (Seedance first/last-frame, fed an ultra-detailed motion brief composed from the scene's action, camera, dialogue, and transcript; duration snapped to the nearest allowed clip length).
 
-**Sequenced audio.** Dialogue is a back-and-forth on one absolute timeline, so each **contiguous same-speaker turn** becomes its own `tts` placed at its real `start_s` — turns alternate and never stack (the earlier design concatenated each speaker's whole monologue at their earliest timestamp, so two voices played in parallel for the entire video). Each speaker is locked to one shared `voice_select` voice; a `sound_effect` per SFX and a `music` bed (styled after the AudD-identified track when available, ducked under the voices) round out the mix (`audio_timeline`). The final mux normalizes the soundtrack to **−14 LUFS (stereo)** so the output plays loud in every player — the raw mix is quiet mono, which reads as "no sound."
+**Sequenced audio.** Dialogue is a back-and-forth on one absolute timeline, so each **contiguous same-speaker turn** becomes its own `tts` placed at its real `start_s` — turns alternate and never stack (the earlier design concatenated each speaker's whole monologue at their earliest timestamp, so two voices played in parallel for the entire video). Each speaker is locked to one shared `voice_select` voice; a `sound_effect` per SFX and a `music` bed (styled after the AudD-identified track when available, ducked under the voices, and started at the reference's `music.starts_at_s` rather than always at 0) round out the mix (`audio_timeline`). The final mux normalizes the soundtrack to **−14 LUFS (stereo)** so the output plays loud in every player — the raw mix is quiet mono, which reads as "no sound."
+
+**Native talking heads (no post-hoc lip-sync).** Seedance 2.0 generates lip-synced speech **natively** — a scene with a **single on-camera speaker** (a `dialogue.speaker` that maps to a `global.cast` member, when `global.voiceover.mode` isn't pure `voiceover`/`none`) puts the line in the clip's prompt with `generate_audio`, so lips and voice are generated together (no `video_lipsync`/veed). Each native clip's audio is then re-voiced through `audio_voice_convert` (ElevenLabs Voice Changer) to **one brand voice** so every scene sounds like the same person, timing preserved so the lips stay matched. Off-camera narration keeps a sequenced `tts` per turn; scenes with two on-camera speakers stay native-per-clip and are flagged for you to split or pick a primary.
 
-**Lip-sync by default.** Seedance animates a generic mouth that won't track the separate voiceover, so any scene with a **single on-camera speaker** (a `dialogue.speaker` that maps to a `global.cast` member, when `global.voiceover.mode` isn't pure `voiceover`/`none`) routes its clip through `video_lipsync` against that scene's own turn audio (~20 cr/scene). Scenes with two on-camera speakers are left un-synced on purpose (one lip-sync track can't drive two faces) and flagged for you to split or pick a primary.
+**Native-audio drift guard.** Seedance paces a spoken line to fill the clip, so each native clip is generated **long enough for the estimated speech** (≈150 wpm) — not just the visual scene length — and its audio is extracted at the **full line length** rather than hard-trimmed to the scene, so a line that runs a beat long isn't cut mid-word (it continues over the next scene as natural VO). `metadata.video.talking_scenes` records each scene's `scene_s` vs `est_speech_s` so you can spot a line that overruns its cut.
 
 **Timeline-accurate picture.** Seedance can't render under 4s, so each clip is generated at the smallest allowed duration ≥ the scene length and then **trimmed back to the exact scene duration** before concat. This keeps the concatenated picture on the same timeline as the absolute-timed audio — without it, short scenes balloon to 4s, the spine runs far longer than the soundtrack, and every line plays over the wrong (slowed) scene so the lips never match. Frames are also prompted as **clean text-free plates** (no baked captions/lower-thirds/tickers/logos-as-text) so the overlay layer is the single source of on-screen text.
 
+**Scene transitions.** When the deconstruct flags a boundary as `fade`/`whip`/`zoom`/`dissolve`/`swipe` (`scene.transition_out`), the spine reproduces it as an ffmpeg **`xfade`** instead of a hard cut; plain `cut`/`match_cut` stay hard cuts. The overlap is consumed from **extra generated footage** (each transitioning clip is trimmed to `scene_s + transition` and the xfade `offset` lands on the cumulative scene start), so the total length still equals the sum of the scene lengths — the picture stays exactly on the audio timeline.
+
+**One person, multiple looks.** If a single individual plays multiple personas/wardrobes (e.g. a creator as a skeptic then a believer), the selection pass emits **one element per look** linked via `same_as` — each outfit gets its own reference slot, but the frame legend and the `el_*` TODO tell the generator they are the **same person** (keep the face identical, change only wardrobe). The always-on `metadata.todo.completeness_check` reminds you to split a person collapsed into a single slot.
+
 **Overlays are agent-painted HTML, not props.** The clips are concatenated, then the `video-overlay` composition (copied next to the canvas) composites the overlay layer. The scaffold **bakes the reference's overlays into that composition's `index.html` as real, editable HTML** (each overlay is a plain element with its text, a `.pos-*` position class, and `data-start`/`data-dur` timing); a tiny generic runtime only shows/hides each element at its timestamp (with an optional `data-anim` entrance). It makes **no styling decisions** — bars, tickers, colors, fonts, and a real logo `<img>` you drop into the dir all live in the HTML/CSS you edit. Floating elements (logo bugs) are seeded as commented `<img>` stubs so an un-edited render stays clean. Drop `brand-bold.otf`/`brand-regular.otf` for on-brand type.
 
-The emitted canvas is validated (`validateCanvasDeep`) before it's written, so it always runs. It also carries a **`metadata.video`** timing plan that `baker canvas validate` proves **statically, before any billed render**: no two voiceover turns overlap, the audio length ≈ the video length, and every single-on-camera-speaker scene has a lip-sync node. The full editable checklist is embedded as **`metadata.todo`** (with a step-by-step guide in `metadata.description`). stdout returns `{ ok, canvas_path, prompt_path, models, stats, checklist }`.
+The emitted canvas is validated (`validateCanvasDeep`) before it's written, so it always runs. It also carries a **`metadata.video`** timing plan that `baker canvas validate` proves **statically, before any billed render**: no two voiceover turns overlap, the audio length ≈ the video length, and every single-on-camera-speaker scene is a native talking head (its clip carries `generate_audio` and is wired to an `audio_voice_convert` node). The full editable checklist is embedded as **`metadata.todo`** (with a step-by-step guide in `metadata.description`). stdout returns `{ ok, canvas_path, prompt_path, models, stats, checklist }`.
 
 ```bash
 baker canvas scaffold-video ./reference-ad.mp4 --focus "competitor UGC ad for <brand>"
@@ -3582,6 +3645,8 @@ baker canvas run ./reference-ad.video.canvas.json
 |---|---|---|
 | `--out <path>` | `<video-dir>/<name>.video.canvas.json` | Where to write the canvas (composition is copied alongside). |
 | `--frames <mode>` | `generate` | `generate` regenerates frames anchored on the originals; `reuse` wires the real extracted frames straight into the clips (faithful, cheaper). |
+| `--ambient` | off | Give silent **b-roll** scenes native diegetic ambient (Seedance `generate_audio`), mixed deep under the music bed. Talking scenes already carry voice; check levels don't muddy the mix before keeping it. |
+| `--actor-sheets` | off | Lock a recast **person/animal that recurs across ≥2 scenes** to ONE multi-view turnaround (`image_reference_sheet`) that every frame grounds on — the strongest cross-scene identity lock. Costs extra credits per sheet; a fused sheet can over-polish, so eyeball it. |
 | `--max-scenes <n>` | all source scenes | **Cost lever that reduces fidelity** — caps the deconstruct, MERGING away every scene beyond the cap (fewer cuts, lost beats). Prints a warning when set; omit it to reproduce every scene. |
 | `--language <code>` | auto | Transcript/dialogue language hint (e.g. `fr`, `en`). |
 | `--focus <text>` | — | Known provenance/emphasis to ground the deconstruct. |
@@ -3590,6 +3655,8 @@ baker canvas run ./reference-ad.video.canvas.json
 | `--image-model <id>` | `openai/gpt-5.4-image-2` | Override the per-frame `image_generate` model (defaults to the strongest, matching `scaffold-static-ad`). |
 | `--video-model <id>` | `bytedance/seedance-2.0` | Override the `video_generate` model. |
 
+Each scene is captured in a **shoot mode** — `ugc_selfie` (talking heads, the default look), `ugc_broll`, `studio_product` (pack shot), `lifestyle_cinematic`, or `screen_ui`. The scaffold derives one per scene (UGC by default; the cinematic and screen lanes are opt-in) and bakes its capture block into the frame and a camera default into the clip; override per scene with a `shoot_mode` field in `prompt.json`. Capture aesthetic + depth-of-field follow the mode (UGC stays flat; studio/lifestyle allow shallow DoF). Clips also carry **diegetic native audio** — the scene's own ambience described in the Seedance prompt, never music (the music bed is a separate, ducked track); set a scene's `ambient` field to steer it.
+
 The two scaffold passes are billed (the full `video_deconstruct` is the heavy one); **running** the result then generates many image/video/audio assets and is not free. Defaults to vertical 1080×1920 overlays — copy + edit the composition for other aspect ratios. For on-brand overlay type, drop `brand-bold.otf`/`brand-regular.otf` into the copied `video-overlay-composition/` dir (wired via `@font-face`, with a system fallback). Richer transcription (punctuated words + paragraphs) is available via the deconstruct's `transcriber: "deepgram"` param when `DEEPGRAM_API_KEY` is set.
 
 #### `baker canvas scaffold-static-ad <image> [flags]`
@@ -4026,6 +4093,7 @@ For video rendering, use `hyperframe_render` instead — same composition format
 - **GSAP animations.** Use `gsap.set()` for visibility transitions — `fromTo(opacity)` silently fails under Hyperframes' screenshot capture.
 - **Single root timeline.** `window.__timelines["main"]` only. Sub-composition timelines aren't scrubbed.
 - **Cache invalidation.** The composition directory is hashed recursively; editing any file invalidates the cache automatically.
+- **Pre-render gate.** Both nodes run `hyperframes lint` + `inspect` on the substituted composition before rendering. Keep content inside its container (text/container **overflow blocks** the render — shrink the font, widen the container, or mark intentional bleed with `data-layout-allow-overflow`). Use auto-resolved fonts (generic families, `Arial`) or declare `@font-face` for named/brand fonts — an undeclared named font (`Impact`, `system-ui`, `Roboto`, …) raises a font warning. Low contrast and missing assets only warn.
 
 ---
 
@@ -4045,6 +4113,18 @@ Non-linear vertical scroll of a tall app screenshot, driven by a GSAP timeline.
 
 Output is a 720×1280 MP4 (modern phone aspect) intended to feed straight into an `ffmpeg` chromakey filter graph as the `app` overlay.
 
+#### Reusable motion-graphic "moves"
+
+A library of proven, parameterized motion graphics ships under `packages/cli/canvas/` so agents reuse them instead of authoring HTML/GSAP from scratch. Each is 1080×1920, `lint`/`inspect`-clean, and exposes a `@font-face` hook for `brand-bold.otf` / `brand-regular.otf`:
+
+- **`title-card-composition`** — kinetic kicker + headline (word-by-word rise) + subhead on a gradient.
+- **`lower-third-composition`** — animated name/title bar that wipes in, holds, slides out (transparent bg).
+- **`stat-counter-composition`** — a number that counts up to a value with prefix/suffix + label (transparent bg).
+- **`feature-reveal-composition`** — a check-marked feature list that staggers in (transparent bg).
+- **`end-card-composition`** — logo (inline SVG) + closing line + CTA pill.
+
+Render a still with `hyperframe_snapshot` or an animated clip with `hyperframe_render`; the transparent-bg moves render to an alpha overlay with `format: "webm"`.
+
 ---
 
 ### Programmatic use

package/canvas/end-card-composition/index.html

@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1080, height=1920" />
+    <script src="./gsap.min.js"></script>
+    <style>
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-bold.otf') format('opentype'), url('./brand-bold.ttf') format('truetype');
+        font-weight: 700 900;
+        font-display: swap;
+      }
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-regular.otf') format('opentype'), url('./brand-regular.ttf') format('truetype');
+        font-weight: 100 600;
+        font-display: swap;
+      }
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body { width: 1080px; height: 1920px; overflow: hidden; }
+      #root {
+        position: absolute; inset: 0; background: {{bg_color}};
+        font-family: 'BrandFont', Arial, sans-serif;
+        color: {{text_color}};
+        display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 56px; padding: 120px;
+        text-align: center;
+      }
+      .logo { width: 360px; max-height: 200px; opacity: 0; transform: translateY(20px); }
+      .logo svg { width: 100%; height: auto; display: block; }
+      .headline { font-size: 84px; font-weight: 900; line-height: 1.08; letter-spacing: -1px; max-width: 860px; text-wrap: balance; opacity: 0; transform: translateY(24px); }
+      .cta {
+        font-size: 46px; font-weight: 700; padding: 32px 64px; border-radius: 999px;
+        background: {{cta_bg}}; color: {{cta_text_color}}; opacity: 0; transform: scale(0.8);
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-duration="{{duration}}" data-width="1080" data-height="1920">
+      <div class="logo" id="logo">{{logo_svg}}</div>
+      <h1 class="headline" id="headline">{{headline}}</h1>
+      <div class="cta" id="cta">{{cta_text}}</div>
+    </div>
+
+    <script>
+      (() => {
+        var DURATION = parseFloat('{{duration}}') || 3;
+        var logoEl = document.getElementById('logo');
+        var ctaEl = document.getElementById('cta');
+        var hasLogo = (logoEl.innerHTML || '').trim().length > 0;
+        var hasCta = ((ctaEl.textContent) || '').trim().length > 0;
+        if (!hasLogo) logoEl.style.display = 'none';
+        if (!hasCta) ctaEl.style.display = 'none';
+
+        var tl = gsap.timeline({ paused: true });
+        if (hasLogo) tl.to('#logo', { opacity: 1, y: 0, duration: 0.5, ease: 'power3.out' }, 0.1);
+        tl.to('#headline', { opacity: 1, y: 0, duration: 0.5, ease: 'power3.out' }, 0.3);
+        if (hasCta) tl.to('#cta', { opacity: 1, scale: 1, duration: 0.45, ease: 'back.out(1.7)' }, 0.6);
+        tl.to({}, { duration: 0.01 }, Math.max(0.02, DURATION - 0.01));
+
+        window.__timelines = window.__timelines || {};
+        window.__timelines.main = tl;
+      })();
+    </script>
+  </body>
+</html>

package/canvas/end-card-composition/meta.json

@@ -0,0 +1,19 @@
+{
+  "id": "end-card",
+  "title": "End card — logo, closing line, CTA pill",
+  "description": "A closing/pack-shot card: optional inline-SVG wordmark, a closing headline, and a call-to-action pill that pops in. Renders a solid background, so it works as a final clip (mp4) or, with format=webm/mov, a transparent end band over a product shot. Drop brand-bold.otf / brand-regular.otf in this dir for on-brand type.",
+  "width": 1080,
+  "height": 1920,
+  "fps": 30,
+  "default_duration": 3,
+  "inputs": {},
+  "params": {
+    "logo_svg": { "kind": "string", "default": "", "description": "Raw inline <svg>…</svg> wordmark with fill set to text_color (optional)." },
+    "headline": { "kind": "string", "required": true, "description": "Closing line." },
+    "cta_text": { "kind": "string", "default": "", "description": "Call-to-action pill label (optional)." },
+    "bg_color": { "kind": "color", "default": "#0b1020" },
+    "text_color": { "kind": "color", "default": "#ffffff" },
+    "cta_bg": { "kind": "color", "default": "#5b8cff" },
+    "cta_text_color": { "kind": "color", "default": "#0b1020" }
+  }
+}

package/canvas/feature-reveal-composition/index.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1080, height=1920" />
+    <script src="./gsap.min.js"></script>
+    <style>
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-bold.otf') format('opentype'), url('./brand-bold.ttf') format('truetype');
+        font-weight: 700 900;
+        font-display: swap;
+      }
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-regular.otf') format('opentype'), url('./brand-regular.ttf') format('truetype');
+        font-weight: 100 600;
+        font-display: swap;
+      }
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body { width: 1080px; height: 1920px; overflow: hidden; background: transparent; }
+      #root {
+        position: absolute; inset: 0; background: transparent;
+        font-family: 'BrandFont', Arial, sans-serif;
+        color: {{text_color}};
+        display: flex; flex-direction: column; justify-content: center; padding: 130px 110px;
+      }
+      .title { font-size: 72px; font-weight: 900; line-height: 1.08; margin-bottom: 56px; text-wrap: balance; opacity: 0; transform: translateY(24px); }
+      .list { display: flex; flex-direction: column; gap: 36px; }
+      .item { display: flex; align-items: center; gap: 32px; opacity: 0; transform: translateX(-40px); }
+      .circle {
+        flex: 0 0 auto; width: 72px; height: 72px; border-radius: 50%;
+        background: {{accent_color}}; display: flex; align-items: center; justify-content: center;
+      }
+      .circle svg { width: 38px; height: 38px; }
+      .item .text { font-size: 52px; font-weight: 600; line-height: 1.15; }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-duration="{{duration}}" data-width="1080" data-height="1920">
+      <h2 class="title" id="title">{{title}}</h2>
+      <div class="list" id="list"></div>
+    </div>
+
+    <script>
+      (() => {
+        var DURATION = parseFloat('{{duration}}') || 5;
+        var STAGGER = parseFloat('{{stagger_s}}') || 0.18;
+        var features = {{features}};
+        var CHECK = '{{check_color}}';
+
+        var hasTitle = ((document.getElementById('title').textContent) || '').trim().length > 0;
+        if (!hasTitle) document.getElementById('title').style.display = 'none';
+
+        var list = document.getElementById('list');
+        (features || []).forEach(function (label) {
+          var item = document.createElement('div');
+          item.className = 'item';
+          var circle = document.createElement('div');
+          circle.className = 'circle';
+          circle.innerHTML = '<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M5 12.5l4.5 4.5L19 7" stroke="' + CHECK + '" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/></svg>';
+          var text = document.createElement('div');
+          text.className = 'text';
+          text.textContent = String(label);
+          item.appendChild(circle);
+          item.appendChild(text);
+          list.appendChild(item);
+        });
+
+        var items = Array.prototype.slice.call(list.querySelectorAll('.item'));
+        var tl = gsap.timeline({ paused: true });
+        if (hasTitle) tl.to('#title', { opacity: 1, y: 0, duration: 0.45, ease: 'power3.out' }, 0.1);
+        if (items.length) {
+          tl.to(items, { opacity: 1, x: 0, duration: 0.45, stagger: STAGGER, ease: 'power3.out' }, hasTitle ? 0.4 : 0.15);
+        }
+        tl.to({}, { duration: 0.01 }, Math.max(0.02, DURATION - 0.01));
+
+        window.__timelines = window.__timelines || {};
+        window.__timelines.main = tl;
+      })();
+    </script>
+  </body>
+</html>

package/canvas/feature-reveal-composition/meta.json

@@ -0,0 +1,18 @@
+{
+  "id": "feature-reveal",
+  "title": "Feature reveal — checklist items animate in staggered",
+  "description": "An optional title plus a list of check-marked feature lines that stagger in one by one, then hold. Transparent background — render with format=webm/mov for an alpha overlay over footage, or format=mp4 over a color. Drop brand-bold.otf / brand-regular.otf in this dir for on-brand type.",
+  "width": 1080,
+  "height": 1920,
+  "fps": 30,
+  "default_duration": 5,
+  "inputs": {},
+  "params": {
+    "title": { "kind": "string", "default": "", "description": "Optional heading above the list." },
+    "features": { "kind": "json", "required": true, "description": "Array of 1–6 short labels, e.g. [\"No setup fees\", \"Cancel anytime\"]." },
+    "text_color": { "kind": "color", "default": "#0b1020" },
+    "accent_color": { "kind": "color", "default": "#1f9d57", "description": "Check-circle fill." },
+    "check_color": { "kind": "color", "default": "#ffffff", "description": "The check mark inside the circle." },
+    "stagger_s": { "kind": "number", "default": 0.18, "min": 0.02, "max": 1, "description": "Seconds between each item." }
+  }
+}

package/canvas/lower-third-composition/index.html

@@ -0,0 +1,75 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1080, height=1920" />
+    <script src="./gsap.min.js"></script>
+    <style>
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-bold.otf') format('opentype'), url('./brand-bold.ttf') format('truetype');
+        font-weight: 700 900;
+        font-display: swap;
+      }
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-regular.otf') format('opentype'), url('./brand-regular.ttf') format('truetype');
+        font-weight: 100 600;
+        font-display: swap;
+      }
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body { width: 1080px; height: 1920px; overflow: hidden; background: transparent; }
+      #root {
+        position: absolute; inset: 0; background: transparent;
+        font-family: 'BrandFont', Arial, sans-serif;
+      }
+      .l3 {
+        position: absolute; left: 64px; bottom: {{from_bottom_px}}px;
+        display: flex; align-items: stretch; max-width: 900px;
+        filter: drop-shadow(0 12px 30px rgba(0,0,0,0.35));
+      }
+      .accent { width: 16px; background: {{accent_color}}; border-radius: 4px 0 0 4px; transform: scaleY(0); transform-origin: bottom; }
+      .panel {
+        background: {{bar_color}}; color: {{text_color}};
+        padding: 30px 44px; border-radius: 0 8px 8px 0; overflow: hidden;
+        clip-path: inset(0 100% 0 0);
+      }
+      .name { font-size: 60px; font-weight: 800; line-height: 1.05; white-space: nowrap; }
+      .title { font-size: 34px; font-weight: 500; opacity: 0.85; margin-top: 8px; white-space: nowrap; }
+      .name, .title { transform: translateY(20px); opacity: 0; }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-duration="{{duration}}" data-width="1080" data-height="1920">
+      <div class="l3" id="l3">
+        <div class="accent" id="accent"></div>
+        <div class="panel" id="panel">
+          <div class="name" id="name">{{name}}</div>
+          <div class="title" id="title">{{title}}</div>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      (() => {
+        var DURATION = parseFloat('{{duration}}') || 4;
+        var hasTitle = ((document.getElementById('title').textContent) || '').trim().length > 0;
+        if (!hasTitle) document.getElementById('title').style.display = 'none';
+
+        var tl = gsap.timeline({ paused: true });
+        // IN
+        tl.to('#accent', { scaleY: 1, duration: 0.35, ease: 'power3.out' }, 0.1);
+        tl.to('#panel', { clipPath: 'inset(0 0% 0 0)', duration: 0.45, ease: 'power3.out' }, 0.25);
+        tl.to('#name', { y: 0, opacity: 1, duration: 0.4, ease: 'power2.out' }, 0.45);
+        if (hasTitle) tl.to('#title', { y: 0, opacity: 0.85, duration: 0.4, ease: 'power2.out' }, 0.55);
+        // OUT — slide down + fade in the last 0.5s
+        var outAt = Math.max(1.0, DURATION - 0.5);
+        tl.to('#l3', { y: 60, opacity: 0, duration: 0.4, ease: 'power2.in' }, outAt);
+        tl.to({}, { duration: 0.01 }, Math.max(0.02, DURATION - 0.01));
+
+        window.__timelines = window.__timelines || {};
+        window.__timelines.main = tl;
+      })();
+    </script>
+  </body>
+</html>

package/canvas/lower-third-composition/meta.json

@@ -0,0 +1,18 @@
+{
+  "id": "lower-third",
+  "title": "Lower-third name bar — animated name + title",
+  "description": "A transparent name/title bar that wipes in, holds, and slides out. Renders on a transparent background, so render with format=webm (or mov) to get an alpha overlay you composite over footage in the ffmpeg node or an editor, or paste it into another composition. Drop brand-bold.otf / brand-regular.otf in this dir for on-brand type.",
+  "width": 1080,
+  "height": 1920,
+  "fps": 30,
+  "default_duration": 4,
+  "inputs": {},
+  "params": {
+    "name": { "kind": "string", "required": true, "description": "Primary line (person/brand name)." },
+    "title": { "kind": "string", "default": "", "description": "Secondary line (role/handle)." },
+    "bar_color": { "kind": "color", "default": "#0b1020" },
+    "text_color": { "kind": "color", "default": "#ffffff" },
+    "accent_color": { "kind": "color", "default": "#5b8cff", "description": "The leading accent block." },
+    "from_bottom_px": { "kind": "integer", "default": 220, "min": 0, "max": 1600, "description": "Distance of the bar from the bottom edge." }
+  }
+}

package/canvas/stat-counter-composition/index.html

@@ -0,0 +1,73 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1080, height=1920" />
+    <script src="./gsap.min.js"></script>
+    <style>
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-bold.otf') format('opentype'), url('./brand-bold.ttf') format('truetype');
+        font-weight: 700 900;
+        font-display: swap;
+      }
+      @font-face {
+        font-family: 'BrandFont';
+        src: url('./brand-regular.otf') format('opentype'), url('./brand-regular.ttf') format('truetype');
+        font-weight: 100 600;
+        font-display: swap;
+      }
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body { width: 1080px; height: 1920px; overflow: hidden; background: transparent; }
+      #root {
+        position: absolute; inset: 0; background: transparent;
+        font-family: 'BrandFont', Arial, sans-serif;
+        display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 80px;
+      }
+      .value {
+        font-size: 240px; font-weight: 900; line-height: 1; letter-spacing: -4px; color: {{value_color}};
+        font-variant-numeric: tabular-nums; text-align: center; transform: scale(0.9); opacity: 0;
+      }
+      .label { font-size: 48px; font-weight: 500; color: {{label_color}}; margin-top: 36px; text-align: center; max-width: 820px; text-wrap: balance; opacity: 0; }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-duration="{{duration}}" data-width="1080" data-height="1920">
+      <div class="value" id="value">{{prefix}}0{{suffix}}</div>
+      <div class="label" id="label">{{label}}</div>
+    </div>
+
+    <script>
+      (() => {
+        var DURATION = parseFloat('{{duration}}') || 3;
+        var TARGET = parseFloat('{{value}}') || 0;
+        var DECIMALS = parseInt('{{decimals}}', 10) || 0;
+        var COUNT_S = parseFloat('{{count_s}}') || 1.2;
+        var PREFIX = '{{prefix}}';
+        var SUFFIX = '{{suffix}}';
+        var valueEl = document.getElementById('value');
+        var hasLabel = ((document.getElementById('label').textContent) || '').trim().length > 0;
+        if (!hasLabel) document.getElementById('label').style.display = 'none';
+
+        function render(n) {
+          var fixed = Number(n).toFixed(DECIMALS);
+          // group thousands for readability
+          var parts = fixed.split('.');
+          parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+          valueEl.textContent = PREFIX + parts.join('.') + SUFFIX;
+        }
+        render(0);
+
+        var counter = { n: 0 };
+        var tl = gsap.timeline({ paused: true });
+        tl.to('#value', { scale: 1, opacity: 1, duration: 0.4, ease: 'back.out(1.6)' }, 0.1);
+        tl.to(counter, { n: TARGET, duration: COUNT_S, ease: 'power1.out', onUpdate: function () { render(counter.n); } }, 0.15);
+        if (hasLabel) tl.to('#label', { opacity: 1, duration: 0.4, ease: 'power2.out' }, 0.2 + COUNT_S * 0.5);
+        tl.to({}, { duration: 0.01 }, Math.max(0.02, DURATION - 0.01));
+
+        window.__timelines = window.__timelines || {};
+        window.__timelines.main = tl;
+      })();
+    </script>
+  </body>
+</html>

package/canvas/stat-counter-composition/meta.json

@@ -0,0 +1,20 @@
+{
+  "id": "stat-counter",
+  "title": "Animated stat counter — number counts up to a value",
+  "description": "A big number that counts up from zero to a target, with a prefix/suffix and a label underneath. Transparent background — render with format=webm/mov for an alpha overlay, or format=mp4 over a color. Good for data beats (\"$2.4M raised\", \"98% retention\"). Drop brand-bold.otf / brand-regular.otf in this dir for on-brand type.",
+  "width": 1080,
+  "height": 1920,
+  "fps": 30,
+  "default_duration": 3,
+  "inputs": {},
+  "params": {
+    "value": { "kind": "number", "required": true, "description": "Target number to count up to." },
+    "decimals": { "kind": "integer", "default": 0, "min": 0, "max": 4, "description": "Decimal places to display." },
+    "prefix": { "kind": "string", "default": "", "description": "e.g. \"$\"." },
+    "suffix": { "kind": "string", "default": "", "description": "e.g. \"%\", \"M\", \"x\"." },
+    "label": { "kind": "string", "default": "", "description": "Caption under the number." },
+    "value_color": { "kind": "color", "default": "#ffffff" },
+    "label_color": { "kind": "color", "default": "#9fb3d1" },
+    "count_s": { "kind": "number", "default": 1.2, "min": 0.2, "max": 6, "description": "Seconds spent counting up." }
+  }
+}