@scenerok/sdk 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/sdk",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "TypeScript-first SceneRok authoring SDK — build IRTimeline for complex agent-authored scenes",
   "type": "module",
   "main": "./dist/index.js",

package/skills/scenerok/SKILL.md

@@ -35,15 +35,16 @@ Copy this checklist into your notes and work through it:
 
 ```text
 - [ ] 1. Identify the environment (web editor, CLI, ChatGPT, MCP, chat without tools)
-- [ ] 2. Pick the closest recipe in recipes.md and read look-and-feel.md
-- [ ] 3. Gather pictures: page images, screenshots, logo, footage, or generated
-        stills (look-and-feel.md → Sourcing imagery). Probe each one; crop with ffmpeg
-- [ ] 4. Decide the look: palette, two fonts, type sizes, beats. Write them as `let`s
-- [ ] 5. Write the script from the recipe; read other references only as needed
-- [ ] 6. Validate. Fix every error and aesthetic warning; validate again until clean
+- [ ] 2. List the beats. For each: its job and the one thing the viewer takes away
+- [ ] 3. Put the material on the table before choosing: the source's own pictures,
+        screenshots, logo, footage, numbers, words. Probe each file
+- [ ] 4. Choose each beat's tools with choosing.md; write one line of why per beat
+- [ ] 5. Decide the look (palette, fonts, sizes) as `let`s: look-and-feel.md
+- [ ] 6. Write the script (recipes.md has complete ones). Validate: fix every error;
+        read every aesthetic warning as a question about your choice
 - [ ] 7. Uses TTS or generated media: deep-validate and fix the report (CLI only)
-- [ ] 8. Render, pull one frame per beat, look at them, run the freeze check
-- [ ] 9. Fix what the frames show and render again. Done = the quality gate passes
+- [ ] 8. Render, pull one frame per beat, look, and answer the review questions
+- [ ] 9. Fix what the frames show and render again
 ```
 
 With the CLI:
@@ -58,12 +59,12 @@ scenerok lint-video <render-id> --cost medium --json            # billed
 `scenerok render script.vid --validate` renders and checks the MP4 in one step.
 
 With marketplace plugins: search, inspect, dry-run, then run a pinned ref
-(full workflow in [plugins.md](references/plugins.md)). A plugin's output must
-pass the same quality gate. When a plugin's template is text over a flat
-colour, draft it (`scenerok plugin draft … --out draft.vid`), add the
-pictures and motion from [recipes.md](references/recipes.md), then
-`scenerok plugin render-draft <id> --vidscript draft.vid`. Today that covers
-the first-party `listing-promo` and `release-video` templates.
+(full workflow in [plugins.md](references/plugins.md)). Review a plugin's
+output with the same questions as your own work. 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, draft (`scenerok plugin draft … --out draft.vid`), change the beats that
+need it, then `scenerok plugin render-draft <id> --vidscript draft.vid`.
 
 ```bash
 scenerok plugin search "product promo"
@@ -101,42 +102,46 @@ ChatGPT, and MCP have their own validate and render calls but no deep
 validation or MP4 check, and can't read local files:
 [environments.md](references/environments.md).
 
-## Quality gate
-
-`validate` tells you the script is valid, not that the video is good. A video
-is done only when all of these hold. Text over a flat colour fails, however
-clean the script.
-
-1. **A picture under every beat.** Each beat shows a real asset (product
-   photo, screenshot, logo, footage, screen recording) or a generated image or
-   video. No beat is type on a plain colour.
-2. **Nothing stands still.** Every picture and text line has `animate:` with an
-   entrance; anything that leaves before the end also has an exit. Stills get a
-   slow push; logos float. After rendering, this prints nothing (no hold of 3 s
-   or longer; a `freeze_start` with no `freeze_end` runs to the end):
-   `ffmpeg -hide_banner -i out.mp4 -vf freezedetect=n=0.003:d=3 -map 0:v -f null - 2>&1 | grep freeze_start`
-3. **A deliberate look.** The script opens with `let` values for its palette
-   (bg, ink, muted, one accent) and its two fonts. Sizes follow the type scale
-   in [look-and-feel.md](references/look-and-feel.md): at least 44 px on a
-   1920 px tall canvas.
-4. **One grade.** `filter "cdl"` and/or `vignette` (or a LUT from an HTTPS
-   URL) spans the whole video.
-5. **Sound.** A music bed, a voiceover, or the footage's own audio, unless the
-   user asked for silence.
-6. **Validate clean.** Fix every error and every aesthetic warning, or write
-   down why a warning doesn't apply (each recipe names the warnings it accepts
-   and why).
-7. **Looked at.** Render, pull one frame per beat, open the frames, and fix what
-   you see: wrapped or colliding text, black boxes where a picture should be,
-   a fallback font, empty bands. Then render again. Validate's text sizes are
-   estimates, so only the frames show the real result.
+## Review: look, then ask
+
+`validate` tells you the script is valid. Only the rendered frames tell you
+whether the video works. Render, pull one frame per beat, open the frames, and
+ask:
+
+1. **Does each beat do its job at a glance?** A viewer on a phone with the sound
+   off gets the beat's point in under two seconds. If not, the job is unclear
+   or the tool fights the content.
+2. **Is every element a choice?** For each picture, motion, transition, grade
+   and sound, you can say what it does for its beat. If the honest answer is
+   "the recipe had one", cut it. A beat of plain text on a still frame is a
+   good choice when you can say why (see `choosing.md`).
+3. **Did you look at what the source offered?** If the user gave a page, a repo,
+   footage or a brand, put its pictures on the table before choosing. Not using
+   them can be right. Never having looked is the failure that produced
+   text-only videos.
+4. **Can it be read?** Text is at least 2.2 % of the frame height (44 px at
+   1920), inside the safe area, contrasted against what is behind it, and on
+   screen long enough to read.
+5. **Does the frame match your intent?** Look for wrapped or colliding text,
+   black boxes where a picture should be, fallback fonts, letterbox bands, a
+   block smaller than you pictured.
+6. **Is it true?** Every claim, price and number comes from the source.
+
+Questions 4 and 6 are facts, not taste: fix them. The rest call for judgement.
+Answer them, change what you would defend poorly, and render again.
 
 ```bash
 for t in 1.5 5 9 13; do ffmpeg -loglevel error -y -ss $t -i out.mp4 -frames:v 1 frame-$t.png; done
 ```
 
-Without a shell (web editor, ChatGPT, MCP), check 1-6 against the script and
-ask the user to watch the preview before you call it done.
+A diagnostic you can run when you intended motion: this lists every stretch
+of 3 s or more where the picture doesn't change (a `freeze_start` with no
+`freeze_end` runs to the end). A held quote, price or line of code can be
+right, so treat the list as information, not a verdict.
+`ffmpeg -hide_banner -i out.mp4 -vf freezedetect=n=0.003:d=3 -map 0:v -f null - 2>&1 | grep freeze_`
+
+Without a shell (web editor, ChatGPT, MCP), ask questions 1-4 and 6 of the
+script itself, and have the user watch the preview.
 
 ## Rules that prevent most failures
 
@@ -168,7 +173,9 @@ Read the ones the task needs. Paths are relative to this file.
 
 | Task | Read |
 | --- | --- |
-| Any video | [recipes.md](references/recipes.md) and [look-and-feel.md](references/look-and-feel.md) (always): complete product promo, release notes and talking-head scripts; palette, type scale, safe areas, motion, sourcing pictures |
+| Any video | [choosing.md](references/choosing.md) (always): how to pick tools for a beat, with worked choices |
+| What a tool looks like, is for, and fights; tools by job | [repertoire.md](references/repertoire.md) (generated; search it by job or name) |
+| Complete scripts to adapt; palette, type scale, safe areas, sourcing pictures | [recipes.md](references/recipes.md), [look-and-feel.md](references/look-and-feel.md) |
 | Any VidScript | [vidscript-strict.md](references/vidscript-strict.md) (always) |
 | Editing and compositing: trims, speed, reverse, freeze, picture-in-picture, blend modes, masks, crops, split screens, audio mixing and ducking, grading and LUTs, captions, timecode | [editing-actions.md](references/editing-actions.md) |
 | Full grammar | [vidscript-guide.md](references/vidscript-guide.md) |
@@ -196,25 +203,33 @@ chat apps are there too: `consumer-chat-apps.md`,
 `chatgpt-gpt-instructions.md`, `gemini-gem-instructions.md`, `grok-skill.md`.
 Previews of every catalog item: https://scenerok.com/catalog.
 
-## One beat, done properly
+## Two beats, two choices
 
-The smallest unit that passes the gate: a real picture with a push, copy that
-enters and leaves, a grade, and sound. A video is several of these; the full
-scripts are in [recipes.md](references/recipes.md).
+Each beat gets the tools its job calls for and nothing else. Below, an
+"establish" beat uses a real photo: the push gives a 4 s still a sense of time.
+A "quote" beat is plain text on a flat colour with no motion, because the words
+are the content and the reader needs to be left alone with them. Both are
+finished. `choosing.md` walks through more choices like these.
 
 ```vidscript
 import motion from "@scenerok/basic-animations"
 
+let bg = "#0A0C10"
 let ink = "#F4F6FA"
+let muted = "#A3ADBD"
 let display = "Archivo Black"
+let body = "Inter"
 
 input shot = "https://cdn.example.com/product-lifestyle.jpg"   # 1080x1920, probed
-input bed = "https://cdn.example.com/music.mp3"
 
+# Establish: the product in its place. A slow push, a headline that arrives.
 [0s .. 4s] = shot, width: 1080, height: 1920, x: 0, y: 0, animate: { type: "scale", from: { scale: 1 }, to: { scale: 1.08 }, easing: "linear" }
-[0.2s .. 4s] = text "Cleans while you're out", font: display, size: 96, color: ink, x: "50%", y: "28%", max_width: "86%", align: center, shadow_color: "#000000", shadow_blur: 24, animate: [motion.riseIn(0.5s, 60), motion.fadeOut(0.3s)]
-[0s .. 4s] = filter "vignette", intensity: 0.3
-[0s .. 4s] = audio bed, volume: 0.5, fade_out: 0.5s
+[0.2s .. 4s] = text "Cleans while you're out", font: display, size: 96, color: ink, x: "50%", y: "28%", max_width: "86%", align: center, shadow_color: "#000000", shadow_blur: 24, animate: motion.riseIn(0.5s, 60)
+
+# Quote: someone's words, held still long enough to read twice.
+[4s .. 9s] = solid(bg)
+[4s .. 9s] = text "\"Simplicity is the ultimate sophistication.\"", font: body, size: 64, color: ink, x: "50%", y: "45%", max_width: "80%", align: center
+[4s .. 9s] = text "Leonardo da Vinci (attributed)", font: body, size: 44, color: muted, x: "50%", y: "56%", align: center
 output to "video.mp4", resolution: "1080x1920", fps: 30
 ```
 

package/skills/scenerok/references/animations-picker.md

@@ -52,7 +52,7 @@ Param resolution: **named > positional > default**.
 | Maps / liquid-glass / app-showcase | Ignore user params | Use for demo aesthetic only, or hand-author |
 | Adapter blocks | No inline audio/text siblings | Put `audio`, `text`, `filter` on separate time blocks |
 | `logo_outro` | Renders upstream demo's Figma-style mark when no logo param given | Pass `brand: "scenerok"` or `logoUrl: "<image url>"` |
-| `code_*` and most blocks in 9:16 | Designed at 1920x1080 and scaled to fit: 56 % size with empty bands above and below (lower thirds have native 9:16 layouts) | Use them in 16:9; in 9:16 build a code card from `text` lines (`recipes.md` → Release notes) |
+| Most blocks in 9:16 | Designed at 1920x1080 and scaled to fit: 56 % size in a centred band. The `code_snippet_*` VS Code themes, `code_diff` and most lower thirds have their own 9:16 layouts | Each record in `repertoire.md` says how it behaves at 9:16 |
 | `text_counter_stat` | `suffix` defaults to `"+"`, so 12 reads "12+" | Pass `suffix: ""` unless the number really is a floor |
 
 ## Two-phase compose recipe