@scenerok/sdk 0.27.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/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,9 +1,9 @@
 # Recipes
 
-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.
+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)
 
@@ -38,7 +38,8 @@ 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.
+# 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.
@@ -164,9 +165,10 @@ 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. 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.
+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)