@scenerok/sdk 0.27.0 → 0.29.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/intent-router.md

@@ -29,13 +29,13 @@ Defaults unless the user says otherwise:
 
 | Workflow | Load these slugs | Primary APIs (VidScript · SDK) |
 | --- | --- | --- |
-| **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` |
+| **Product promo** | `plugins.md` (run `listing-promo`), `recipes.md` for the visual moves, `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 / 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) |
+| **Code demo / PR / release notes** | `plugins.md` (run `release-video`), `recipes.md` (the code beat), `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, then the matching script in `recipes.md`
+1. **Classify** — workflow from table above, then the matching pattern in `recipes.md` (a plugin's README owns its beat order)
 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

@@ -58,13 +58,16 @@ than it predicts, so check the rendered frame before trusting a line to fit.
 
 ## Pictures
 
-Every beat has a picture under its type. In order of preference:
-
-1. **Real**: product photos, logos, app screenshots, footage, screen recordings.
-2. **Generated**: `xai.image`, `xai.imageToVideo` from a real photo, `xai.imagine`
-   (`ai-models.md`; prompts forbid text).
+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), as a background behind real pictures, never as the only picture.
+   Release notes). Atmosphere without a subject.
 
 Placing stills in a frame of a different shape:
 
@@ -112,15 +115,17 @@ which needs no file.
 
 ## Motion
 
-| Phase | Use | Timing |
+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 | Stills: a push `{ type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }`. Logos and products: `motion.float(3s, 10-14)` | A static hold lasts 3 s at most |
-| Exit | `motion.fadeOut(0.3s)` on everything that leaves before the end | The last 0.3 s of the block |
+| 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 doesn't count as motion: give it a still, footage,
-or a floating element to move. Fast moves can take `motion_blur:`
-(`editing-actions.md`).
+A push on a soft gradient is invisible, so it adds nothing. Fast moves can take
+`motion_blur:` (`editing-actions.md`).
 
 ## Pacing
 
@@ -129,11 +134,13 @@ or a floating element to move. Fast moves can take `motion_blur:`
 - 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 means here
+## What premium tends to mean
+
+Tendencies, not requirements; each is a choice you can argue against.
 
-- A real picture fills or anchors every beat; no beat is text on a flat colour.
+- 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, never a paragraph.
-- Every element arrives, holds with a little motion, and leaves.
-- One grade ties it together: `filter "cdl"` warmth or coolness plus a `vignette` of about 0.3.
-- Sound under all of it: a music bed, a voiceover, or both.
+- 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,10 +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. A plugin's video must still pass the quality gate in `SKILL.md`. Draft
-first, read the filled script, and if a beat is text over a flat colour, add
-the pictures and motion from `recipes.md` before `render-draft`. Today that
-applies to the first-party `listing-promo` and `release-video` templates.
+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

@@ -1,221 +1,90 @@
-# Recipes
+# Visual patterns
 
-Three complete scripts that pass the quality gate in `SKILL.md`. Each uses
-the look system in `look-and-feel.md`. Copy the one that fits, then swap in
-your own assets, copy, and palette. Keep the structure: a picture under every
-beat, motion on everything, and a grade and sound over the whole video.
+Composition moves that lift any script, whichever plugin produced it. They are
+not a story: a **plugin owns its domain's story** — the order of beats, the copy
+rules and the template — and this file owns how a beat is *made to look*.
 
-## Product promo (9:16, 15 s)
+| Domain | Its story lives in |
+| --- | --- |
+| Product promo | [`plugins/listing-promo/README.md`](../../../plugins/listing-promo/README.md#story-and-copy) |
+| Changelog / release notes | [`plugins/release-video/README.md`](../../../plugins/release-video/README.md#story) |
+| Talking head with captions | [`plugins/voiceover-booth/README.md`](../../../plugins/voiceover-booth/README.md#story) |
 
-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:
+Use the plugin for the story, then use these patterns — and the records in
+[repertoire.md](repertoire.md) — to make each beat read on a phone. Every
+pattern says when it earns its place and what it fights; none of them is
+required.
 
-```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
-```
+## A held still needs a push
+
+A still that sits unchanged for three seconds reads as a slide, however good the
+photo is. A 1.08 scale over the hold keeps the eye engaged without movement you
+notice. Fights: a second moving element in the same beat, or a photo whose edges
+carry detail you want still.
 
 ```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
-
-# Slow push-in for every still, so no frame is ever frozen.
+input still = "https://cdn.example.com/photo.jpg"
+
+# 8% over four seconds is enough to read as alive and not as a zoom.
 let push = { type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }
+[0s .. 4s] = still, width: 1080, height: 1920, x: 0, y: 0, animate: push
 
-# 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"
+output to "beat.mp4", resolution: "1080x1920", fps: 30
 ```
 
-`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.
+## A product belongs on a card over its own context
 
-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.
+Cutting straight from a lifestyle shot to a plain background loses the thing the
+shot was selling. Keep a blurred, darkened copy as the field and put the product
+on a rounded card above it: the eye reads "this object, in that place".
 
-## Release notes / changelog (9:16, 18 s)
+```vidscript
+input hero = "https://cdn.example.com/product.jpg"
+input room = "https://cdn.example.com/room.jpg"
 
-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:
+# The background is the same shot, blurred and darkened ahead of time with
+# ffmpeg, so the card sits in context instead of on a flat colour.
+input roomBg = "https://cdn.example.com/room-bg.jpg"
 
-```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
-```
+[0s .. 4s] = roomBg, width: 1080, height: 1920, x: 0, y: 0
+[0.4s .. 4s] = hero, width: 900, height: 880, x: 90, y: 300, radius: 48
+[0.8s .. 4s] = text "The product name", size: 72, color: "#F5F5F7", x: "50%", y: "71%", max_width: "88%", align: center
 
-```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"
+output to "card.mp4", resolution: "1080x1920", fps: 30
 ```
 
-`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. The `code_*` catalog blocks are 1920x1080
-designs: use them in 16:9, where they fill the frame. In 9:16 they shrink to
-56 % with empty bands above and below.
+Fights: a busy background behind the card (blur it more), or a product shot that
+is already on white — then the card is redundant and a plain field is better.
 
-## Talking head with captions (9:16, 14 s)
+## A code beat needs one line to land
 
-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.
+A file on screen is not a beat; the line that matters is. Put the code in a
+card, keep four to six lines, and let one line carry the highlight. Use
+`animations.code_snippet_dark_2026` (or a portrait variant — see the record) for
+the card, and place the changed line as its own text layer when it must be the
+loudest thing in the frame. Use the `code` job in
+[repertoire.md](repertoire.md#find-tools-by-job) to compare the card options.
 
-```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
-```
+Fights: more than ~7 lines on a phone, a second animation in the same beat, or
+copy that repeats the code's meaning.
+
+## A number deserves a count
+
+When the beat is "how much", the number is the picture. A counter block
+(`text_counter_stat`, `apple_money_count`) makes the eye follow the change;
+static type makes it a caption. Fights: numbers that are not the point, or two
+counters in one video.
+
+## A type-led beat is a legitimate beat
+
+Some content *is* the words: a quote, a price, a definition, a breaking change,
+a legal line. Still type on a quiet field, with generous margins and no motion,
+respects the reader. Reach for it when motion would compete; do not treat it as
+the safe default for a beat that has a real picture available.
+
+## Cut, unless the cut is the problem
 
-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.
+A hard cut is the strongest transition and the one an audience never notices. A
+transition earns its place when it carries meaning — a wipe across a change of
+place, a match on shape, a dissolve on a memory. Otherwise it delays the beat.
+Compare the `transition` records before choosing one.