@scenerok/sdk 0.26.0 → 0.28.0

package/skills/scenerok/references/choosing.md

@@ -0,0 +1,111 @@
+# Choosing tools for a beat
+
+SceneRok's blocks, motion, transitions, filters and media are a repertoire,
+not a checklist. Nothing is required, nothing is decoration by default: each
+beat gets what its job calls for. `repertoire.md` says what every tool looks
+like, what it is for, and what it fights. This file is how to use that.
+
+## The procedure
+
+For each beat:
+
+1. **Name its job** with one word from the job list in `repertoire.md`
+   (announce, count, quote, code, prove, demo, establish, cta, ...), and the one
+   thing the viewer must take away.
+2. **Put the material on the table.** What do you actually have for this beat:
+   the source's photos, screenshots, footage, logo, the exact numbers and words?
+   You can only choose a picture you have looked at.
+3. **List the candidates** under that job in `repertoire.md` → Find tools by job.
+   Plain `text` and "nothing extra" are always candidates.
+4. **Drop what fights.** Read each candidate's *Fights* against your content
+   (length of the words, busyness of the picture), its neighbours (the beat
+   before and after, anything else moving) and the frame (9:16 or 16:9: read
+   *Fit*).
+5. **Choose by the look.** Read *Looks* for the survivors and pick the frame you
+   want the viewer to see. When two would do, take the simpler.
+6. **Write one line**: `<beat>: <tool> because <reason>`. If you can't finish
+   the sentence, choose something plainer.
+7. **Verify by looking.** After rendering, open a frame of that beat. If it
+   doesn't look like the *Looks* you chose for, the description or your
+   placement is wrong. Fix the placement, and report the description.
+
+## When plain text on a still frame is right, and when it is not
+
+Right, when:
+
+- the words are the content: a quote, a definition, a price, a command, a
+  legal line;
+- the viewer needs reading time, and anything moving would compete;
+- the design is typographic on purpose (a brand that speaks in type);
+- there is no honest picture: an abstract claim, an internal change with no
+  UI. A stock or generated image would only pretend.
+
+Wrong, when:
+
+- the source has pictures that show the thing (a product page, an app, a repo
+  with a UI) and the beat's job is demo, prove or establish;
+- several beats in a row are text on the same flat colour, so the video turns
+  into a slideshow;
+- the text says what a picture could show ("sleek design", "easy to use").
+
+The same goes for motion: a still frame is right when the eye should rest.
+Motion is for arrival, emphasis and time passing, and one moving thing at a
+time is easier to follow than three.
+
+## Worked choices
+
+**Product promo, hook (9:16).** Job: establish. Material: three lifestyle
+photos from the product page, a 500 px hero shot on white. Candidates: a page
+photo, `xai.imagine`, `animations.liquid_glass_notification`, `text`.
+Dropped: `xai.imagine` fights facts (it would invent a different robot); the
+liquid-glass block is fixed artwork in rainbow colours. Chosen: the lifestyle
+photo as a band over a blurred copy of itself, with a 3 s push, because a still
+held for 3 s reads as a slide and the push gives it time. Headline: `text`
+with `riseIn`.
+
+**Customer review (any aspect).** Job: quote. Material: one two-sentence review
+from the page. Candidates: `text_typewriter_quote`, `x_post`, `reddit_post`,
+`text`. Dropped: `x_post` and `reddit_post` would dress the review as a post on
+a platform it never appeared on; the typewriter takes three seconds to type
+what a reader takes two to read. Chosen: plain `text` on a flat dark frame with
+a muted attribution, no motion, held 5 s.
+
+**Breaking change in release notes.** Job: announce. Material: one sentence
+from the changelog. Chosen: plain `text`, no entrance, no grade change, held
+4 s. Gravity is the point; any flourish would make a warning read like
+marketing. Nothing else was considered necessary, and that is a valid outcome
+of step 3.
+
+**A stat (9:16).** Job: count. Material: "12 bug fixes" counted from the
+release body. Candidates: `text_counter_stat`, `apple_money_count`, `text` with
+`popIn`. Dropped: `apple_money_count` is money on a white slab. Chosen:
+`text_counter_stat` with `suffix: ""` (its default `+` would turn 12 into
+"12+", which is false).
+
+**Code in 9:16.** Job: code. Material: a five-line before/after. Candidates:
+`code_typing`, `code_diff`, a `code_snippet_*` theme, `text` lines. Dropped:
+`code_typing` (in 9:16 its code shrinks to about 17 px). Chosen: `code_diff`,
+which has its own 9:16 layout and keeps the removed line on screen with
+`keep_removed: true`, so the change reads as a before/after. Its *Looks* says it
+sits in the upper half, so the beat's headline goes in the empty lower half
+instead of on top of the code.
+
+**Cut between two lifestyle shots in a calm promo.** Job: transition.
+Candidates: every `tr.*`, and a hard cut. Dropped: everything whose *Fights*
+says "calm or premium edits"; `flash` (flicker). Chosen: a hard cut, because
+the shots differ enough to read as a new beat. `dissolve` only if the two shots
+share a subject. A transition is a candidate, not a default.
+
+**Talking head, key line.** Job: emphasize. Material: a 16:9 interview, the
+line "it paid for itself". Candidates: a punch-in (scale the clip),
+`text_kinetic_words`, `blend_caption`, `text_glitch_title`. Dropped: kinetic
+words fight a sentence that must be read whole; glitch fights the tone.
+Chosen: a punch-in on the speaker with a two-word caption card in the accent
+colour.
+
+## Before you trust a description
+
+The records come from the block source and the catalog previews. Some previews
+predate a block's 9:16 layout, and a few are blank (see each record's *Fit*).
+When a choice rests on a block you have never seen rendered, render a short
+test or look at its preview before building the video around it.

package/skills/scenerok/references/editing-actions.md

@@ -462,8 +462,10 @@ input a = "log-footage.mp4"
 [0s .. 4s] = filter "cdl", slope: "1.1 1 0.9", offset: "0 0 0", power: "1 1 1", saturation: 1
 ```
 
-- `filter "lut"` applies a 3D `.cube` file next to the script (512 KB at
-  most, up to 33 points per axis). Use the `filter` line, not `Filter("lut")`.
+- `filter "lut"` applies a 3D `.cube` file (512 KB at most, up to 33 points
+  per axis). Use the `filter` line, not `Filter("lut")`. A hosted compile (CLI
+  render, web, MCP) can't read a local path: give an HTTPS URL or a `data:`
+  URI, or use `cdl`.
 - `filter "cdl"` takes ASC CDL `slope`, `offset`, `power` (three numbers each)
   and `saturation`.
 

package/skills/scenerok/references/intent-router.md

@@ -29,13 +29,13 @@ Defaults unless the user says otherwise:
 
 | Workflow | Load these slugs | Primary APIs (VidScript · SDK) |
 | --- | --- | --- |
-| **Product promo** | `ai-models.md`, `text-styles.md`, `music.md`, `workflow.md`, `brand-setup.md` (+ `sdk-guide.md` if TS) | `xai.imagine` / `await xai.genVideo(...)`, `motion.popIn` / `fadeIn`, `eleven.music` |
+| **Product promo** | `recipes.md`, `look-and-feel.md`, `brand-setup.md` (+ `ai-models.md` when the page has no usable pictures, `sdk-guide.md` if TS) | page images as `input` with a scale push, `motion.riseIn` / `popIn`, `solid` CTA button, `filter "cdl"`, `eleven.music` |
 | **Motion graphic** | `animations-picker.md` (+ `animations-catalog.md` if needed) | `animations.*` (VidScript HyperFrames; prefer VidScript for catalog blocks) |
 | **Social proof card** | `animations-picker.md` | `animations.x_post`, `reddit_post`, … (VidScript) |
 | **Edit existing footage** | `editing-actions.md` (+ `media-stdlib.md` to probe the clips, `transitions-catalog.md` for cuts) | `Trim` / `Speed` / `Loop` / `Crop` / `Mask` / `Overlay` / `Composite`, `blend:`, `duck_under:`, `filter "lut"` (VidScript only) |
 | **Scene montage** | `transitions-catalog.md`, `ai-models.md` (+ `sdk-guide.md` if TS loops) | `tr.dissolve` · SDK: `import tr from '@scenerok/transitions'` + `t[start][end] = tr.dissolve()` |
 | **Narrated explainer** | `tts.md`, `text-styles.md`, `music.md`, `workflow.md` (+ `sdk-guide.md` if TS) | `xai.tts` · `await xai.tts(...)` + `t.push(vo)` |
-| **Code demo / PR** | `animations-picker.md` (code rows) | `code_typing`, `code_diff` (VidScript) |
+| **Code demo / PR / release notes** | `recipes.md` (release notes), `animations-picker.md` (code rows) | 16:9: `code_typing`, `code_diff`; 9:16: a code card of `text` lines with `motion.typewriter` (VidScript) |
 | **Text animation / headline / stat** | `animations-picker.md` (text-anim rows) | `animations.text_*` (VidScript) · SDK kinetic: `text` + `fadeIn` / `popIn` |
 | **Kinetic title only** | `text-styles.md` (+ `sdk-guide.md` if TS) | `text` + `motion.*` · SDK: `text(..., { area })` + `.animate(fadeIn(...))` |
 | **Custom-authored animation (no block fits)** | `animations-catalog.md` → "Custom HTML" | `animations.custom_html` (VidScript) |
@@ -43,7 +43,7 @@ Defaults unless the user says otherwise:
 
 ## Staged routing
 
-1. **Classify** — workflow from table above
+1. **Classify** — workflow from table above, then the matching script in `recipes.md`
 2. **Choose authoring** — VidScript by default and for every editing action (masks, blends, crops, ducking, LUTs, timecode); `@scenerok/sdk` (`sdk-guide.md`) only for loops or computed timing (it has none of the editing actions)
 3. **Load catalogs** — only what that workflow needs (conditional loading)
 4. **Name block or API** — VidScript: pick `animations.<fn>` from `animations-picker.md`. SDK: factories (`video` / `loadVideo`, `text`, `fadeIn`) + AI imports (`@scenerok/xai`, …)

package/skills/scenerok/references/look-and-feel.md

@@ -0,0 +1,146 @@
+# Look and feel
+
+Decide the look before you write a block. Declare it as `let` values at the top
+of the script and use only those values below. `recipes.md` shows the whole
+system in use.
+
+## Palette
+
+Four colours, declared once:
+
+| Name | Use | Default (dark) |
+| --- | --- | --- |
+| `bg` | Canvas and plates behind cards | `#0A0C10` |
+| `ink` | Headlines and body copy | `#F4F6FA` |
+| `muted` | Secondary lines: ratings, URLs, captions | `#A3ADBD` |
+| `accent` | One brand colour: kicker, price, bullets, CTA button, highlight bar | sampled from the brand |
+
+Sample the accent from the brand's own pixels (a button or logo on the page)
+or from `brand-setup.md`. Don't invent one. Use at most three non-neutral text
+colours (`validate` warns above that).
+
+## Type
+
+Use two families: a display face and a body face. `font:` is one Google
+Fonts family, loaded at weight 400. A weight in the name (`"Inter Bold"`,
+`"Inter Black"`) is not a family: the render falls back to a default face.
+For heavy type, use a family that is heavy at 400.
+
+Rendered and checked: `Archivo Black` (display), `Inter` (body),
+`JetBrains Mono` (code; turns `=>` into a ligature). Other single-weight
+display families: `Anton`, `Bebas Neue`.
+
+Sizes in output pixels (`size:`). `validate` flags text under 2.2 % of the
+canvas height:
+
+| Role | 1080x1920 (9:16) | 1920x1080 (16:9) |
+| --- | --- | --- |
+| Hero / price | 120-150 | 120-140 |
+| Headline | 84-104 | 72-88 |
+| Bullet / caption card | 64-72 | 48-56 |
+| Body / kicker / URL (the floor) | 44-48 | 32-36 |
+
+Kickers: body face, accent colour, `letter_spacing: 6`-`10`, all caps.
+Validate's text geometry is an estimate. A display face can run 15-20 % wider
+than it predicts, so check the rendered frame before trusting a line to fit.
+
+## Layout and safe areas
+
+- Text `x`/`y` place the text's centre (`anchor: "left"` places its
+  left-centre). Prefer `area:` when a named region fits. Use explicit pixels
+  for designed layouts like the recipes.
+- 9:16: keep copy between y 220 and y 1500 and x 72 to 1008. Feed UI covers
+  the top ~8 %, the bottom ~20 % and a right-hand icon rail.
+- 16:9: keep copy inside a 96 px margin. Put the picture on one side and the
+  copy on the other.
+- Margins: 48 px at the edge of a card; cards use `radius: 32`-`48`.
+- Show at most 3 text overlays at once, except the lines of a code card.
+
+## Pictures
+
+Whether a beat gets a picture is a choice (`choosing.md`). When it does, the
+sources rank like this:
+
+1. **Real**: product photos, logos, app screenshots, footage, screen
+   recordings. They prove things; nothing else does.
+2. **Generated**: `xai.image`, `xai.imageToVideo` from a real photo,
+   `xai.imagine` (`ai-models.md`; prompts forbid text). They set a mood and
+   invent everything else.
+3. **Made**: a brand-colour glow or gradient rendered with ffmpeg (recipes →
+   Release notes). Atmosphere without a subject.
+
+Placing stills in a frame of a different shape:
+
+- **Card**: the still at its own aspect, `radius:` and `blend: "normal"`, on
+  a plain or blurred plate (a product on white in a 900 px card).
+- **Band + blurred fill**: a wide crop as a full-width band, over a blurred,
+  darkened 9:16 copy of the same shot. This works for small or landscape stills.
+- **Cover**: oversize the clip to fill, e.g. 16:9 into 9:16 at
+  `width: 3413, height: 1920, x: -1166`. This keeps transitions legal, which
+  `Crop` doesn't.
+
+Prepare stills with ffmpeg before you place them. Crop out baked-in
+captions, make the blurred fill, and probe the result:
+
+```bash
+ffmpeg -i in.jpg -vf "crop=W:H:X:Y,scale=1080:-2" band.jpg
+ffmpeg -i in.jpg -vf "crop=W:H:X:Y,scale=1080:1920,boxblur=40:2,eq=brightness=-0.18" fill.jpg
+sips -g pixelWidth -g pixelHeight band.jpg
+```
+
+Use `.Crop()` for video footage. A `.Crop()` on a remote still rendered as
+nothing in testing, so crop stills with ffmpeg.
+
+## Sourcing imagery
+
+Collect pictures before you write copy:
+
+| Source | How |
+| --- | --- |
+| Product page | Image URLs from `og:image`, the JSON-LD `Product.image`, Shopify `/products/<handle>.json` → `images`, Amazon `#landingImage` `data-old-hires` and the gallery `m.media-amazon.com/images/I/…` URLs |
+| Page screenshot | Browser tool at 1440x900 (desktop) and 390x844 (mobile). Crop to the hero, the price card, or the feature you name; never use a full page as a background |
+| Logo | The site's header SVG/PNG, `apple-touch-icon`, or the GitHub org avatar (`https://avatars.githubusercontent.com/u/<id>`) |
+| App or site in motion | A screen recording (QuickTime, `ffmpeg -f avfoundation`, a browser recorder) as an `input` clip |
+| Nothing usable | `xai.image` / `xai.imageToVideo` (`ai-models.md`) |
+
+Local `input` files upload with `scenerok render`. Probe every file
+(`sips`, `ffprobe`) and size placements from the measured aspect.
+
+## Files the server must read
+
+`filter "lut", file:` and `captions("…srt")` are read by the compiler. On a
+hosted compile (CLI, web, MCP) a local path fails with `local asset not
+found`. Pass an HTTPS URL or a `data:` URI, or grade with `filter "cdl"`,
+which needs no file.
+
+## Motion
+
+When you do use motion, these timings read well. What each primitive looks
+like is in `repertoire.md`.
+
+| Phase | Typical choice | Timing |
+| --- | --- | --- |
+| Entrance | `motion.riseIn(0.5s, 40-80)` for copy and cards, `motion.popIn(0.4-0.6s)` for prices, buttons, logos, `motion.typewriter` for code, `motion.fadeIn(0.4s)` for secondary lines | Stagger items 0.3-0.6 s apart |
+| Hold | Nothing (rest the eye), or a push on a still `{ type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }`, or `motion.float(3s, 10-14)` on a logo or product | A still hold beyond ~3 s should be one you meant: reading time, gravity |
+| Exit | A cut, or `motion.fadeOut(0.3s)` when the element should leave softly | The last 0.3 s of the block |
+
+A push on a soft gradient is invisible, so it adds nothing. Fast moves can take
+`motion_blur:` (`editing-actions.md`).
+
+## Pacing
+
+- First visible picture and words by 0.3 s; the hook reads in under 1 s.
+- Beats last 2.5-4.5 s each. A 15 s promo is 4 beats; a 30 s video is 6-8.
+- One idea per beat: the hook, the product, three features, the price, and the call to action.
+- Close on the call to action for at least 2.5 s.
+
+## What premium tends to mean
+
+Tendencies, not requirements; each is a choice you can argue against.
+
+- Real pictures where the subject has them; type alone where the words are the point.
+- One accent, used sparingly; everything else is ink and muted on dark (or the reverse).
+- Big type with tight copy: 3-6 words a line, rarely a paragraph.
+- Restraint: one thing moving at a time, consistent entrances, stillness where the eye should rest.
+- A grade only if the pictures need tying together: `filter "cdl"` warmth or coolness, a `vignette` of about 0.3.
+- Sound that fits the use: many feeds play muted, so the picture must work without it.

package/skills/scenerok/references/plugins.md

@@ -7,7 +7,11 @@ cheaper than hand-composing. **Never assume which plugins exist** — discover
 them at run time; the catalog grows and changes.
 
 Plugins are the reuse-first path: check `intent-router.md` for the workflow
-match, and prefer a plugin whenever the user pasted structured source data.
+match. Review a plugin's video with the same questions as your own (`SKILL.md` →
+Review). Draft first and read the filled script. Today the first-party
+`listing-promo` and `release-video` templates set every beat as text over a
+flat colour and leave the product images unused. When the request calls for
+more, change those beats before `render-draft`.
 
 ## Workflow (MCP)
 

package/skills/scenerok/references/recipes.md

@@ -0,0 +1,223 @@
+# Recipes
+
+Three complete scripts, each rendered and reviewed. They show one set of
+choices for one brief; the comments say why each tool is there, so you can tell
+which choices carry over to yours and which don't. Choose for your own beats
+with `choosing.md`.
+
+## Product promo (9:16, 15 s)
+
+Four beats: hook, hero, features, then price and CTA. The images are the
+product page's own (Amazon `landingImage`, `og:image`, or JSON-LD `image`;
+see `look-and-feel.md` → Sourcing imagery). Prepare them before you write the
+script. Amazon stills are 500 px squares with baked-in captions, so crop to a
+clean region and make a blurred 9:16 backdrop from the same shot:
+
+```bash
+ffmpeg -i room.jpg -vf "crop=500:185:0:95,scale=1080:-2" room-band.jpg
+ffmpeg -i room.jpg -vf "crop=104:185:140:95,scale=1080:1920,boxblur=40:2,eq=brightness=-0.18" room-bg.jpg
+sips -g pixelWidth -g pixelHeight room-band.jpg   # 1080x398: place at 984x363
+```
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+import eleven from "@elevenlabs/music"
+
+# Look: one palette, two fonts, one accent.
+let bg = "#0A0C10"
+let ink = "#F4F6FA"
+let muted = "#A3ADBD"
+let accent = "#3D8BFF"
+let display = "Archivo Black"
+let body = "Inter"
+
+# Assets: the product page's own images, cropped and blurred with ffmpeg first.
+input hero = "hero.jpg"               # 483x472, product on white
+input roomBand = "room-band.jpg"      # 1080x398, crop of a lifestyle shot
+input roomBg = "room-bg.jpg"          # 1080x1920, same shot, blurred + darkened
+input closeBand = "closeup-band.jpg"  # 1080x368
+input closeBg = "closeup-bg.jpg"      # 1080x1920
+
+# A slow push on the stills: these photos hold 3-4 s each, and a push keeps a held
+# photo from reading as a slide.
+let push = { type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }
+
+# 1. Hook (0-3 s): lifestyle shot; the headline lands in the first second.
+[0s .. 3s] = roomBg, width: 1080, height: 1920, x: 0, y: 0, animate: push
+[0s .. 3s] = roomBand, width: 984, height: 363, x: 48, y: 820, radius: 36, blend: "normal", animate: [motion.riseIn(0.5s, 80), push, motion.fadeOut(0.3s)]
+[0.2s .. 3s] = text "Vacuums. Mops.\nEmpties itself.", font: display, size: 104, color: ink, line_height: 1.05, x: "50%", y: "27%", max_width: "86%", align: center, shadow_color: "#000000", shadow_blur: 24, animate: [motion.riseIn(0.6s, 50), motion.fadeOut(0.3s)]
+
+# 2. Hero (3-7 s): the product on its own white card.
+[3s .. 7s] = solid(bg)
+[3s .. 7s] = hero, width: 900, height: 880, x: 90, y: 300, radius: 48, blend: "normal", animate: [motion.fadeIn(0.4s), push, motion.fadeOut(0.3s)]
+[3.3s .. 7s] = text "ECOVACS", font: body, size: 44, color: accent, letter_spacing: 10, x: "50%", y: "64.5%", align: center, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+[3.5s .. 7s] = text "DEEBOT T30e OMNI", font: display, size: 72, color: ink, x: "50%", y: "71%", max_width: "88%", align: center, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+
+# 3. Features (7-11 s): a close-up band, then one bullet every 0.6 s.
+[7s .. 11s] = closeBg, width: 1080, height: 1920, x: 0, y: 0, animate: push
+[7s .. 11s] = closeBand, width: 984, height: 335, x: 48, y: 300, radius: 36, blend: "normal", animate: [motion.fadeIn(0.4s), push, motion.fadeOut(0.3s)]
+[7.4s .. 11s] = solid(accent, width: 24, height: 24, x: 96, y: 868, radius: 12), animate: [motion.popIn(0.4s), motion.fadeOut(0.3s)]
+[7.4s .. 11s] = text "25,000 Pa suction", font: display, size: 64, color: ink, x: 150, y: 880, anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+[8.0s .. 11s] = solid(accent, width: 24, height: 24, x: 96, y: 1028, radius: 12), animate: [motion.popIn(0.4s), motion.fadeOut(0.3s)]
+[8.0s .. 11s] = text "ZeroTangle 3.0 brush", font: display, size: 64, color: ink, x: 150, y: 1040, anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+[8.6s .. 11s] = solid(accent, width: 24, height: 24, x: 96, y: 1188, radius: 12), animate: [motion.popIn(0.4s), motion.fadeOut(0.3s)]
+[8.6s .. 11s] = text "Self-emptying dock", font: display, size: 64, color: ink, x: 150, y: 1200, max_width: "80%", anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+
+# 4. Price and CTA (11-15 s). The button is a solid with a radius under the label.
+[11s .. 15s] = solid(bg)
+[11s .. 15s] = hero, width: 560, height: 548, x: 260, y: 260, radius: 40, blend: "normal", animate: [motion.popIn(0.5s), motion.float(3s, 10)]
+[11.3s .. 15s] = text "₹44,999", font: display, size: 150, color: ink, x: "50%", y: "50%", align: center, animate: motion.popIn(0.5s)
+[11.6s .. 15s] = text "★ 4.4  ·  166 ratings", font: body, size: 48, color: muted, x: "50%", y: "58.5%", align: center, animate: motion.fadeIn(0.4s)
+[12s .. 15s] = solid(accent, width: 660, height: 132, x: 210, y: 1210, radius: 66), animate: motion.popIn(0.5s)
+[12s .. 15s] = text "Shop on Amazon", font: display, size: 56, color: "#FFFFFF", x: "50%", y: 1276, align: center, animate: motion.fadeIn(0.4s)
+
+# Grade: warm the whole frame, pull the edges down.
+[0s .. 15s] = filter "cdl", slope: "1.04 1.0 0.96", offset: "0 0 0", power: "1 1 1", saturation: 1.08
+[0s .. 15s] = filter "vignette", intensity: 0.3
+
+# Sound: a bed under everything.
+let bed = eleven.music("Bright, modern electronic product-ad bed, confident pulse, clean ending", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.5, fade_out: 1s
+
+output to "promo.mp4", resolution: "1080x1920", fps: 30, background: "#0A0C10"
+```
+
+`validate` warns `too-many-animations` at the bullets: the three bullets
+leave together on one 0.3 s fade, and the linter counts each exit as motion.
+Accept that warning here and fix any other.
+
+Variations: replace the hook band with
+`xai.imageToVideo(hero, "slow orbit around the product, …", aspect_ratio: "9:16", duration: 3)`
+for a moving hero shot (`ai-models.md`). For 16:9, use the 16:9 type scale
+and put the product on the right and the copy on the left.
+
+## Release notes / changelog (9:16, 18 s)
+
+Four beats: version hook, the one new feature as typed code with a
+highlight, a stat, and an outro. Facts come from the release body
+(`gh api repos/<owner>/<repo>/releases/latest --jq .body`); count the
+`fix`/`feat` lines rather than estimating. The logo is the project's own
+(`https://avatars.githubusercontent.com/u/<id>`, or the README image). The
+background is a brand glow made with ffmpeg:
+
+```bash
+ffmpeg -f lavfi -i "color=c=black:s=1080x1920,format=rgb24" -frames:v 1 \
+  -vf "geq=r='11+90*exp(-((X-760)^2+(Y-520)^2)/180000)':g='11+30*exp(-((X-760)^2+(Y-520)^2)/180000)':b='15+4*exp(-((X-760)^2+(Y-520)^2)/180000)'" glow.png
+```
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+import animations from "@scenerok/animations"
+import eleven from "@elevenlabs/music"
+
+let ink = "#F5F5F7"
+let muted = "#9CA3AF"
+let accent = "#FF5B11"
+let display = "Archivo Black"
+let mono = "JetBrains Mono"
+
+input glow = "glow.png"    # 1080x1920, made with ffmpeg: brand-colour glow on near-black
+input flame = "flame.png"  # 460x460 RGBA, the project's logo
+
+# Ambient layer: the background drifts for the whole video.
+[0s .. 18s] = glow, width: 1080, height: 1920, x: 0, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.15 }, easing: "linear" }
+
+# 1. Hook (0-3.5 s)
+[0s .. 3.5s] = flame, width: 460, height: 460, x: 310, y: 340, blend: "normal", animate: [motion.popIn(0.6s), motion.float(2.9s, 14), motion.fadeOut(0.3s)]
+[0.3s .. 3.5s] = text "RELEASE NOTES", font: mono, size: 44, color: accent, letter_spacing: 8, x: "50%", y: "50%", align: center, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+[0.5s .. 3.5s] = text "hono v4.13.14", font: display, size: 120, color: ink, x: "50%", y: "57%", max_width: "88%", align: center, animate: [motion.riseIn(0.6s, 60), motion.fadeOut(0.3s)]
+
+# 2. The new feature as code (3.5-10 s): headline, card, then the code types itself.
+[3.5s .. 10s] = text "NEW IN BEARER-AUTH", font: mono, size: 44, color: accent, letter_spacing: 6, x: 96, y: 300, anchor: "left", align: left, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+[3.6s .. 10s] = text "Error messages can\nreturn a Response", font: display, size: 84, color: ink, line_height: 1.1, x: 96, y: 440, anchor: "left", align: left, animate: [motion.riseIn(0.5s, 40), motion.fadeOut(0.3s)]
+[4s .. 10s] = solid("#16161D", width: 960, height: 700, x: 60, y: 620, radius: 32), animate: [motion.riseIn(0.5s, 60), motion.fadeOut(0.3s)]
+# One text layer per code line: a tall multi-line block can clip. Indent with x, not spaces.
+[4.4s .. 10s] = text "bearerAuth({ token,", font: mono, size: 44, color: ink, x: 108, y: 760, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[4.9s .. 10s] = text "invalidToken: {", font: mono, size: 44, color: ink, x: 164, y: 836, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[5.4s .. 10s] = text "message: (c) =>", font: mono, size: 44, color: accent, x: 220, y: 912, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[5.9s .. 10s] = text "c.json(problem, 401),", font: mono, size: 44, color: accent, x: 276, y: 988, anchor: "left", align: left, animate: [motion.typewriter(0.5s), motion.fadeOut(0.3s)]
+[6.4s .. 10s] = text "}})", font: mono, size: 44, color: ink, x: 108, y: 1064, anchor: "left", align: left, animate: [motion.typewriter(0.3s), motion.fadeOut(0.3s)]
+# Highlight beat: a bar sweeps under the changed lines once the code is typed.
+[7.2s .. 10s] = solid(accent, width: 900, height: 158, x: 90, y: 872, radius: 16, opacity: 0.16), animate: [{ type: "slideX", from: { x: -1000 }, to: { x: 0 }, start: 0, end: 0.5, easing: "easeOutCubic" }, motion.fadeOut(0.3s)]
+[7.4s .. 10s] = text "Any content type, e.g. problem+json", font: mono, size: 44, color: muted, x: 108, y: 1220, anchor: "left", align: left, animate: [motion.fadeIn(0.4s), motion.fadeOut(0.3s)]
+
+# 3. Highlight (10-14 s): one number, then three rows. suffix: "" because the block defaults to "+".
+[10s .. 14s] = animations.text_counter_stat("12", "BUG FIXES", suffix: "", accent: accent)
+[11s .. 14s] = text "serve-static: GET and HEAD only", font: mono, size: 44, color: ink, x: "50%", y: "70%", align: center, animate: [motion.riseIn(0.4s, 30), motion.fadeOut(0.3s)]
+[11.4s .. 14s] = text "css: safer url() minifying", font: mono, size: 44, color: ink, x: "50%", y: "74.5%", align: center, animate: [motion.riseIn(0.4s, 30), motion.fadeOut(0.3s)]
+[11.8s .. 14s] = text "trie-router: keep first param", font: mono, size: 44, color: ink, x: "50%", y: "79%", align: center, animate: [motion.riseIn(0.4s, 30), motion.fadeOut(0.3s)]
+
+# 4. Outro (14-18 s)
+[14s .. 18s] = flame, width: 320, height: 320, x: 380, y: 520, blend: "normal", animate: [motion.popIn(0.5s), motion.float(3s, 12)]
+[14.3s .. 18s] = solid("#1C1C24", width: 860, height: 120, x: 110, y: 950, radius: 60), animate: motion.popIn(0.5s)
+[14.3s .. 18s] = text "npm i hono@4.13.14", font: mono, size: 48, color: ink, x: "50%", y: 1010, align: center, animate: motion.fadeIn(0.4s)
+[14.8s .. 18s] = text "github.com/honojs/hono", font: mono, size: 44, color: muted, x: "50%", y: 1150, align: center, animate: motion.fadeIn(0.4s)
+
+# Grade
+[0s .. 18s] = filter "cdl", slope: "1.03 1.0 0.97", offset: "0 0 0", power: "1 1 1", saturation: 1.05
+[0s .. 18s] = filter "vignette", intensity: 0.35
+
+let bed = eleven.music("Minimal driving synth pulse for a developer product update, clean and modern", duration: 18, instrumental: true)
+[0s .. 18s] = audio bed, volume: 0.5, fade_out: 1.5s
+
+output to "release.mp4", resolution: "1080x1920", fps: 30, background: "#0B0B0F"
+```
+
+`validate` warns `crowded-text-overlays` and `too-many-animations` on the
+code card, because each code line counts as an overlay. Accept those two
+there; fix any other warning. This recipe builds its own code card so the
+headline, card and caption can share one frame. The `code_snippet_*` themes and
+`code_diff` also have 9:16 layouts of their own (see their records in
+`repertoire.md`): reach for them when the code is the whole beat.
+
+## Talking head with captions (9:16, 14 s)
+
+A 16:9 interview cut for a vertical feed: fill the frame by oversizing the
+clip (no `Crop`, so transitions stay legal), punch in on the key line, cut
+away to b-roll with a whip pan, and burn in short, timed caption cards.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+import animations from "@scenerok/animations"
+import tr from "@scenerok/transitions"
+
+let ink = "#FFFFFF"
+let accent = "#FFD43B"
+let display = "Archivo Black"
+
+input talk = "https://cdn.example.com/interview-16x9.mp4"  # 1920x1080, probed
+input broll = "https://cdn.example.com/broll-16x9.mp4"     # 1920x1080, probed
+input bed = "https://cdn.example.com/music.mp3"
+
+# Fill 9:16 from 16:9: scale to 1920 tall (3413 wide) and centre it, x = (1080 - 3413) / 2.
+# Cut 1: wide, with a slow push. Cut 2: punch in on the key line. Cut 3: b-roll. Cut 4: back to the speaker.
+[0s .. 4s] = talk.Trim(12s, 16s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.05 }, easing: "linear" }
+[4s .. 7s] = talk.Trim(16s, 19s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1.18 }, to: { scale: 1.22 }, easing: "linear" }
+[6.8s .. 7.2s] = tr.whip_pan()
+[7.2s .. 10s] = broll.Trim(0s, 2.8s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1.1 }, to: { scale: 1 }, easing: "linear" }
+[9.8s .. 10.2s] = tr.dissolve()
+[10.2s .. 14s] = talk.Trim(22.2s, 26s), width: 3413, height: 1920, x: -1166, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.05 }, easing: "linear" }
+
+# Name card from the catalog (it has a native 9:16 layout).
+[0.6s .. 4s] = animations.lt_kicker_name("FOUNDER", "Asha Rao", accent: accent)
+
+# Captions: 2-4 words per card, timed to the transcript, the key words in the accent colour.
+[0.2s .. 1.4s] = text "We shipped it", font: display, size: 72, color: ink, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+[1.4s .. 2.8s] = text "in nine days", font: display, size: 72, color: accent, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+[4s .. 5.6s] = text "and it paid", font: display, size: 72, color: ink, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+[5.6s .. 7s] = text "for itself", font: display, size: 72, color: accent, stroke: "#000000", stroke_width: 6, x: "50%", y: "70%", max_width: "84%", align: center, animate: motion.popIn(0.25s)
+
+# Sound: the speaker's own audio, with music ducked under it.
+[0s .. 7s] = audio talk.Trim(12s, 19s)
+[10.2s .. 14s] = audio talk.Trim(22.2s, 26s)
+[0s .. 14s] = audio bed, volume: 0.5, duck_under: talk, fade_out: 1s
+
+[0s .. 14s] = filter "cdl", slope: "1.02 1.0 0.98", offset: "0 0 0", power: "1 1 1", saturation: 1.05
+
+output to "talk.mp4", resolution: "1080x1920", fps: 30
+```
+
+With a transcript in an SRT file, `captions("talk.srt", font: display, size: 72, area: "caption")`
+replaces the caption lines (`editing-actions.md` → Text and titles). On a
+hosted render the file must be an HTTPS URL; see `look-and-feel.md` → Files the
+server must read.