@scenerok/sdk 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/sdk",
-  "version": "0.26.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,14 +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. Classify the request; read only the references it needs (table below)
-- [ ] 3. Branded promo with unknown colors or logo: ask once
-- [ ] 4. Probe real assets: type, width, height, duration
-- [ ] 5. Write the script
-- [ ] 6. Validate. Fix every error and 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
-- [ ] 9. Check the rendered MP4; fix and repeat from step 6 if it reports problems (CLI only)
+- [ ] 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:
@@ -56,9 +58,13 @@ 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 (fastest when the user pasted structured source data):
-search, inspect, dry-run, then run a pinned ref — full workflow in
-[plugins.md](references/plugins.md):
+With marketplace plugins: search, inspect, dry-run, then run a pinned ref
+(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"
@@ -96,6 +102,47 @@ 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).
 
+## 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
+```
+
+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
 
 1. **Import before calling.** `import xai from "@scenerok/xai"`, then
@@ -114,6 +161,11 @@ validation or MP4 check, and can't read local files:
 6. **Use only documented syntax.** Don't invent functions or parameters. A
    validation error names the problem; fix that line rather than rewriting the
    script.
+7. **`font:` is a Google Fonts family name.** `"Inter Bold"` is not a family
+   and falls back. For heavy type use a heavy family such as
+   `"Archivo Black"`.
+8. **Crop stills with ffmpeg, not `.Crop()`.** Prepare images before you place
+   them; a cropped remote still rendered as nothing in testing.
 
 ## References
 
@@ -121,6 +173,9 @@ Read the ones the task needs. Paths are relative to this file.
 
 | Task | Read |
 | --- | --- |
+| 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) |
@@ -148,14 +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.
 
-## Minimal VidScript
+## Two beats, two choices
+
+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"
 
-input hero = "https://cdn.example.com/clip.mp4"
-[0s .. 4s] = hero.Trim(1s, 5s)
-[0s .. 3s] = text "Hello", style: title, color: "#FFFFFF", area: "title", animate: motion.fadeIn(0.8s)
+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
+
+# 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)
+
+# 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-catalog.md

@@ -98,6 +98,15 @@ overlays (composite over video/scenes), honor every param, and scale to any outp
 Prefer these over hand-authoring when a headline/caption/stat treatment fits; see the
 `text-anim` rows in `animations-picker.md` for intent mapping.
 
+## Code blocks in vertical video
+
+At a 9:16 output the 12 VS Code theme `code_snippet_*` blocks and `code_diff` switch to a
+native 1080x1920 layout: no desktop chrome, ~40px type that wraps instead of shrinking, a
+line-by-line reveal with a moving focus bar and caret (a +/− count and a focus ring for
+`code_diff`), a camera that scrolls long code, and a lift-and-fade exit timed to the
+placement. Same params, same theme palettes; 16:9 is unchanged. It still reads best with
+3–12 short lines: put the one change that matters on screen, not the whole file.
+
 ## Custom HTML (bring your own animation)
 
 `animations.custom_html(...)` renders **your own HTML/CSS/JS** through the same HyperFrames

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

@@ -47,10 +47,13 @@ Param resolution: **named > positional > default**.
 | Block / family | Issue | Fix |
 | --- | --- | --- |
 | `code_diff` | Line indices may be 0-based in adapter | Match sample in `animations-catalog.md` |
+| Code blocks in 9:16 | Only the VS Code theme `code_snippet_*` blocks and `code_diff` have a portrait layout; `code_typing`, `code_morph`, the terminal blocks, etc. are scaled down from 16:9 and read small | Prefer `code_snippet_<theme>` / `code_diff` for vertical video; pass 3–12 short lines, not a file |
 | Unverified blocks | `scenerok validate` warns `verified:false` | Accept demo render or switch to verified family |
 | 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>"` |
+| 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