reelkit-cli 0.6.0 → 0.10.0

package/skill/reference/backgrounds.md

@@ -0,0 +1,63 @@
+---
+name: backgrounds
+description: Use when choosing what sits behind the whole film - a flat or mesh ground, an animated ground drawn in code, a looping video, a picture, or pictures that change from scene to scene - and how to get and use one.
+---
+
+# Grounds
+
+The ground is what is under everything. Choose one for the whole film and keep it: a film with a new look in every scene reads as a collage.
+
+## Which ground
+
+- A flat colour or `BgMesh`: for interface and data films, where the product is the picture and the ground must stay out of the way.
+- An animated ground drawn in code (`BgAurora`, `BgBeams`, and for a technical film `BgGrid`; `BgGrain` for a still, filmic ground): when the frame would otherwise be empty. No media is needed and they are cheap to render.
+- A video ground (`BgVideo`): for mood and brand films. Always dim it (0.3 to 0.5) or blur it, and never put small text over it.
+- Pictures that change (`BgSequence`): a set of related pictures that change on scene starts, never in the middle of a sentence and no more than once every few seconds. Keep one `dim` and one `tint` across all of them so the film stays one film. Use "fade" by default and "zoom" or "blur" for an energetic film.
+
+## Grade and Vignette darken a ground
+
+`Grade` and `Vignette` laid over the film darken everything under them, and a ground drawn in code loses the most: a ground that looked right alone can go muddy under them, and on a near-black base it can all but vanish. `BgAurora`, `BgBeams`, `BgGrid` and `BgGrain` take `intensity` (0 to 1, default 0.6, which reads on a phone on its own). Raise it to 0.8 when Grade and Vignette sit on top, or when the base is near-black; lower it to 0.3 to 0.4 when type sits right on the colour fields and has to stay readable. Look at a preview frame with the whole film's layers on, not the ground alone.
+
+## Getting one
+
+Search the library first: `reelkit assets search "<mood> abstract background" --kind clip`, and also `--kind overlay` and `--kind image`. Pull a good fit as the film's ground with `reelkit assets pull <id> --background`; for a picture that is one scene's ground, add `--scene <id>`. A video is only ever the ground of the whole film.
+
+Generate only when nothing fits, because a clip uses the clip quota: `reelkit assets gen clip --background "<look>"` makes an abstract, slow, seamless clip with no people or text, and `reelkit assets gen image --background --scene <id>` a picture. For a set of pictures, give every prompt the same style sentence so that they look related. The user's own file: `reelkit assets upload <file> --background`.
+
+All of these record the ground in `assets/background.json`. The composition reads it as `manifest.background` (`key` and, for a video, `durationSec`) and `manifest.scenes[i].background` (`key`).
+
+## Keeping the accent
+
+Tint the ground with the film's one accent colour (`tint={palette.hero}`), so that a clip you did not make still belongs to the film.
+
+## Readable type
+
+`reelkit check` notes a `BgVideo` with a `dim` under 0.2 when the plan has on-screen text, and a recorded ground the composition never draws. Preview the frames: if type is hard to read anywhere, raise `dim`, add `blur`, or move the type.
+
+## Example
+
+```tsx
+import React from "react";
+import { AbsoluteFill } from "reelkit/frame";
+import { BgImage, BgSequence, BgVideo, SceneFrame, bgPerScene, palettes } from "reelkit/kit";
+import type { VideoProps } from "reelkit/kit";
+
+export const Video: React.FC<VideoProps> = ({ manifest, urls }) => {
+  const palette = palettes.darkTech;
+  const scenesWithPictures = manifest.scenes.some((s) => s.background);
+  return (
+    <AbsoluteFill>
+      {scenesWithPictures ? (
+        <BgSequence items={bgPerScene(manifest.scenes, manifest.scenes.map((s) => (s.background ? urls[s.background.key] : undefined)))} tint={palette.hero} dim={0.4} />
+      ) : manifest.background ? (
+        <BgVideo src={urls[manifest.background.key]} durationSec={manifest.background.durationSec} dim={0.4} tint={palette.hero} />
+      ) : (
+        <BgImage src={urls["assets/bg-film.png"]} dim={0.4} drift="left" />
+      )}
+      {manifest.scenes.map((s) => (
+        <SceneFrame key={s.id} from={s.startFrame} durationInFrames={s.durationFrames}>{null}</SceneFrame>
+      ))}
+    </AbsoluteFill>
+  );
+};
+```

package/skill/reference/beat-sync.md

@@ -8,47 +8,53 @@ A video with music feels edited when things happen on the beat. The CLI puts the
 
 Then `manifest.json` has `music: { key, bpm, beatFrames }`. `beatFrames` are the beats as composition frames. If a track has no clear tempo there is no `bpm`, `beatFrames` is empty, and nothing below applies: the scenes stay where the narration puts them.
 
-## 2. Scene changes are on the beat already
+## 2. Scene changes: the voice first, the beat when it is close
 
-When the track has a tempo, each scene is held a little at its end, by less than one beat, so the next scene starts exactly on a beat. The narration and its word times do not move. `reelkit preview` says how many scene changes land on the beat. Do not shift `startFrame` yourself.
+With a narrator, the narration sets where a scene ends: the next scene starts after the plan's `gap` of silence (`tight` 0.2 s, `normal` 0.3 s, `relaxed` 0.5 s; the last scene keeps 0.7 s after its last word). When the track has a tempo, a scene change moves to the nearest beat only if that is at most 4 frames away either way and leaves at least 2 frames after the last word; the next scene's voice starts with it. Every other change stays where the voice puts it. `reelkit assets voiceover` and `reelkit preview` say how many changes are on the beat ("3 of 5 scene changes land on the beat; the others follow the voice"): that is the truth, not a fault to fix. Do not shift `startFrame` yourself, and do not pad a scene to reach a beat: that is dead air. A film with no voice puts its cuts on the beat (`reference/launch-film.md`).
 
-## 3. Inside a scene: bring each element in on a beat
+## 3. Inside a scene: the voice is the clock, the beat is for decoration
 
-`beatFrames` are composition frames and a scene's clock starts at 0, so subtract the scene's `startFrame`. For an element that belongs to a word, take the beat nearest the frame where the word starts, then turn it into a `delay`:
+With a narrator, anything that shows or names a word goes on that word: a number, an icon, a list item, a headline, a banner. The voice is the clock for it, and a beat never moves it more than a few frames. The beat is the clock for what has no word: scene changes, a decorative pulse, a sound under a move, and every element of a film with no voice. Do not count words by hand and do not write your own index helper: the kit finds the word for you (`reference/voice-sync.md` has the whole method).
 
-- the word starts at `wordFrame = s.startFrame + Math.round(s.words[2].startSec * fps)`
-- `beat = nearestBeat(manifest.music.beatFrames, wordFrame)`
-- `delay = beat - s.startFrame`
+- `wordFrame(s, "tasks")` is the frame inside the scene where the word starts (a phrase such as "whole week" gives its first word; `{ nth: 2 }` the second time it is said; `{ edge: "end" }` where it ends; `{ absolute: true }` adds `s.startFrame`). A word the scene does not say throws and lists the scene's words, so a typo stops the render and `reelkit check` reports it before then.
+- `onWord(s, "tasks")` is the frame to START an entrance so that it is seen landing on the word: `wordFrame` minus 3 (`lead`), never below 0.
+- `onWordBeat(s, "tasks", manifest.music)` is the same, with one rule for beat and word together: the entrance lands on a beat only if a beat falls within 3 frames AFTER the word starts (`window`); otherwise the word wins. It is never earlier than `onWord`, so a thing is never on screen more than 3 frames before the word that names it. Use it for the hero element when a track is set; use plain `onWord` for everything that must be exact.
 
-Use `nextBeat` when the element must not come before the word. Prefer the beat nearest the word it belongs to over one that is merely free. Put the biggest move (the hero, the number, the reveal) on a strong beat: every fourth beat counts from the scene's first beat. `beatPulse(beatFrames, frame)` is 1 on a beat and falls to 0; use it sparingly, for a small scale or glow on the hero element only, never on everything.
+Nearest-beat snapping is wrong for an element that illustrates a word: the nearest beat is as often before the word as after it, and a banner that appears before "meeting" is said is a mistake. `nearestBeat`, `nextBeat` and `beatPulse` stay for the things the beat owns: `beatPulse(beatFrames, frame)` is 1 on a beat and falls to 0; use it sparingly, for a small scale or glow on the hero element only, never on everything. Put a decorative move on a strong beat (every fourth beat counts from the scene's first beat).
 
-Sound effects go on beats too: the `at` of an `Sfx` is a frame from the scene start, so use the same `delay` arithmetic.
+Sound effects: the `at` of an `Sfx` is a frame from the scene start. A sound for a word's visual goes at that visual's frame (`onWord(s, "tasks") + 2`), under the voice at 0.3 or less (see "Sound levels" below).
 
 ```tsx
-import { Entrance, Music, nearestBeat, SceneFrame, Voiceover } from "reelkit/kit";
+import { Entrance, Music, onWord, onWordBeat, SceneFrame, sceneById, Voiceover } from "reelkit/kit";
 
-const beats = manifest.music?.beatFrames ?? [];
-// Frames from the scene start to the beat nearest the word at index i.
-const onBeat = (s: { startFrame: number; words: { startSec: number }[] }, i: number) => {
-  const word = s.startFrame + Math.round((s.words[i]?.startSec ?? 0) * manifest.fps);
-  return (nearestBeat(beats, word) ?? word) - s.startFrame;
-};
+const s = sceneById(manifest, "meet");
 
 <SceneFrame from={s.startFrame} durationInFrames={s.durationFrames}>
-  <Entrance delay={onBeat(s, 2)}><Card /></Entrance>
+  {/* exact: the list item lands on its word */}
+  <Entrance delay={onWord(s, "tasks")}><Card /></Entrance>
+  {/* the hero: lands on a beat when one is within 3 frames after the word, otherwise on the word */}
+  <Entrance delay={onWordBeat(s, "builds", manifest.music)}><Card /></Entrance>
   {s.voiceoverKey ? <Voiceover src={urls[s.voiceoverKey]} /> : null}
 </SceneFrame>
 // Once, outside the scenes:
 {manifest.music ? <Music src={urls[manifest.music.key]} /> : null}
 ```
 
+`onBeat(s, i)` with a hand-counted word index (the old way: `nearestBeat` of the word at index `i`) still works if you wrote it yourself, but do not start new work with it.
+
 `Music` ducks under the voice by itself and fades out over the last second; do not set its volume per scene.
 
+## Hits go where the eye sees the change
+
+A `SceneFrame` transition (a zoom-through, blur, push or whip) is complete on the scene boundary, but the picture changes most half the transition's frames earlier: 4 frames before the boundary for the default 8, 3 for `transitionFrames={6}`. A hit on the boundary lands after the change and reads as late; the sound report measures it as a miss. Put the hit on the visual peak: `cuesOnChanges(scenes, { impact, whoosh })` does it for every change (the impact on the peak, the whoosh so that it ends there), and `changeFrame(scene)` gives the peak for one. The scene's `startFrame` still sits on the beat, so a hit 3 or 4 frames before it is within a tenth of a second of the beat too.
+
+A camera zoom, a `zoomTo` and a punch are picture changes as well: put a hit on each with `cueOnCamera(frame)` (for a key: about 9 frames before the key's frame) or `cueOnCamera(frame, { punch: true })` (just after the punch's frame). A `Camera` inside a `SceneFrame` counts frames from the scene's start, so add the scene's `startFrame` for the absolute frame a cue needs.
+
 ## Sound levels
 
 Every sound you pull (`sfx` and `music`) is measured when it is pulled and levelled: a sound effect shorter than 3 seconds to a peak of -3 dBFS, a longer sound and the music to about -18 LUFS, never more than 18 dB either way. The gain is in `assets/library.json` (`gainDb`) and in the manifest's `soundGain`, and `Sfx` and `Music` apply it by themselves, so the same `volume` number sounds equally loud for every file. Then:
 
 - the voiceover is `1` (the default);
-- a sound effect is `0.2` to `0.45`; the default `0.35` is right for most, and a small tick can go lower;
-- the music is `0.5` when it plays alone and drops to `0.12` under the voice by itself (`volume` and `duckTo` on `Music`); leave both alone unless a preview of the sound is clearly wrong;
+- a sound effect is `0.2` to `0.45`; the default `0.35` is right for most, and a small tick can go lower (a film with no voice uses the levels in `reference/launch-film.md` instead);
+- the music is `0.5` when it plays alone and sits at `0.18` under the voice by itself (`volume` and `duckTo` on `Music`). It stays steady across the 0.2 to 0.5 s between sentences and comes up only in a real pause of 1.2 s or more (rising over 0.4 s, back down 0.25 s before the next word), so it does not pump; leave both alone unless `reelkit sound` says the music under the voice is outside 10 to 22 dB below it;
 - the render is mastered at the end to -14 LUFS with peaks under -1 dBTP, so do not try to make the whole video louder: balance the parts against each other.

package/skill/reference/brand-motion.md

@@ -0,0 +1,62 @@
+---
+name: brand-motion
+description: Choose branded transformations and 3D reveals by what the shot communicates, then pair their landing frames with sound.
+---
+
+# Brand motion: what changes, when, and why
+
+Use the user's actual name, logo, colours and product material. A branded transition should connect two ideas: a mark becomes the product surface, a product turns toward the viewer, or separate parts resolve into one name. Write that connection in the scene's notes before choosing the effect. Keep the settled identity readable; an effect is the journey, not the brand.
+
+## Choose the move by its purpose
+
+| What the viewer needs to understand | Use | Why it fits | Sound |
+|---|---|---|---|
+| Recognise a product or wordmark as it faces them | `BrandTransform3D mode="turn"` | A restrained turn exposes the front, then stops | Soft sweep into one lock hit |
+| Follow the same object from one position or idea to another | `mode="arc"`, or `Carry` / `Screen3D` across scenes | The curved arrival preserves the object as the visual thread | A short sweep, with a landing only if the new state matters |
+| Feel the step from setup into the launch or payoff | `mode="launch"` | An object approaches from depth and settles at its final size | A rising sweep into an impact; duck the music around the hit |
+| See parts becoming a whole | `Assemble3D` | Construction explains the relationship, rather than hiding it in a cut | Sparse build ticks and one lock at `assembleEnd` |
+| Read a detailed screen, a sentence or a Hebrew wordmark | A 2D image or text with `Entrance` / `Carry` | Detail remains sharp and faces the viewer | Usually a small tap or silence |
+| Notice a factual before/after or a new chapter | A clear cut or `SceneFrame` transition | Separation makes the change easier to compare | `cuesOnChanges`, or silence for a deliberate break |
+
+Choose 3D when depth explains the product, reveals its shape, or makes the requested brand moment distinctive. A flat change is often better for reading, comparison and rapid instructions. More 3D shots are appropriate when the user requests a brand film or showreel; give them different jobs instead of repeating the same spin.
+
+## Keep the identity intact
+
+- Use the supplied logo image without stretching, recolouring or replacing it with a guessed text logo. `Card3D src={urls[key]}` can carry the image in space; match its card proportions to the asset, and end with the actual mark facing the viewer. A flat `Img` is the best closing hold when the card frame would distract.
+- `Text3D` and `Hero3D kind="logo"` are Latin word treatments, not faithful reconstructions of a supplied logo. Use them for a requested word treatment, and keep Hebrew or other unsupported scripts in 2D.
+- Choose the light mood and surface finish from the agreed look: studio for a clear product, night for restrained premium depth, neon for an explicit tech look. Keep the brand palette across all shots.
+- Finish the move before the reading hold. Budget the move plus about 1.5 seconds for a short name; longer copy needs longer. If that cannot fit, shorten the move, simplify the copy or choose 2D.
+- Avoid moving the camera and object in opposite directions at once. Start with a fixed camera; add a small push only when it improves the shot.
+
+## A move and its sounds use one clock
+
+`BrandTransform3D` goes **inside** `Scene3D`. It transforms its children and ends in a neutral pose; it does not generate sound or invent a logo. `brandTransformFrames` returns the same local `start` and `settle` used by the component. `cuesFor([start, settle], "transform")` places a sweep before the landing and a lock on it. Add the scene's `startFrame` exactly once when the cues are rendered outside that scene.
+
+```tsx
+import { BrandTransform3D, Scene3D, SceneFrame, SoundCues, Text3D, brandTransformFrames, cuesFor } from "reelkit/kit";
+
+const timing = { from: 6, frames: 32 };
+const event = brandTransformFrames(timing);
+const cues = cuesFor([event.start, event.settle], "transform", {
+  offset: s.startFrame, voice: true, sweepFrames: 10,
+});
+
+// These elements sit beside each other on the video's timeline.
+<SceneFrame from={s.startFrame} durationInFrames={s.durationFrames}>
+  <Scene3D mood="studio">
+    <BrandTransform3D mode="turn" {...timing}>
+      <Text3D text="Reelkit" color={palette.hero} fit={0.72} />
+    </BrandTransform3D>
+  </Scene3D>
+</SceneFrame>
+<SoundCues cues={cues} sounds={{
+  "transform-sweep": urls["assets/lib/<whoosh-id>/clip.mp3"],
+  "transform-lock": urls["assets/lib/<impact-id>/clip.mp3"],
+}} />
+```
+
+Search and pull real sound files first. `sweepFrames` is the time from the file's start to its audible landing: listen to the chosen file and adjust it, instead of assuming every whoosh peaks at ten frames. Use `voice: true` while narration is heard. A build, a transformation and the final resolve are different events; do not stack all their hits on one landing.
+
+## Before changing an existing shot
+
+Identify the observable problem: the logo is unreadable, the result arrives before its spoken word, the movement has no relationship to the next shot, or the sound lands late. Change that problem first. Keep a deliberate cut, an existing brand treatment and the user's chosen look when they already work. Render the start, middle, landing and held state, then listen to the final video. A sound report helps find missed hits; its density targets are guidance, not a reason to add noise to every movement.

package/skill/reference/captions.md

@@ -17,10 +17,16 @@ The plan's `captions` field says: `"none"`, `"word"` (one word at a time) or `"p
 
 With `"none"` the component draws nothing; better still, leave `<Captions>` out of the composition altogether. `reelkit check` notes a composition that renders `<Captions>` when the plan says `"none"`, and one that renders none when the plan asks for words.
 
+## What the user's answer means
+
+- "No subtitles": `"none"`.
+- "A few words at a time", "a phrase at a time", "a line", or no preference: `"phrase"` (the default). This is the group mode: a few words, never a whole sentence, never one word.
+- "One word at a time", "word by word", "like the big pop captions": `"word"`. Only then is a single word shown. Do not pick `"word"` for "a few words": one word at a time is hard to read on a busy picture and the user did not ask for it.
+
 ## How words are grouped (`group`)
 - `"word"`: exactly one word on screen at a time. Larger text, the most energy.
-- `"phrase"`: words are grouped the way they are spoken, never by a fixed count that cuts a sentence. A group ends at the end of a sentence, at a comma or a dash once it has three words, and at a pause of 0.35 s or more between words. It never holds more than 6 words or about 32 characters; when it must break it does so after a comma or before a short joining word ("and", "of", "to") where it can, and a lone last word is joined to the line before it. Hebrew and Arabic sentence marks work the same way.
-- Without `group`, `perLine` counts the words as it always did. Use `group` for every new video.
+- `"phrase"`: words are grouped the way they are spoken. A group ends at the end of a sentence (`.`, `?` or `!`: a group never spans two sentences), at a comma or a dash once it has three words, and at a pause of 0.35 s or more between words. It holds at most 3 words by default (`maxWords={4}` for more, up to 6) and about 32 characters; when it must break it does so after a comma or before a short joining word ("and", "of", "to") where it can. Hebrew and Arabic sentence marks work the same way.
+- Without `group` (and without `perLine`) the groups are the same as `"phrase"`: 3 words, never one. Only `group="word"` (the plan's `"captions": "word"`) shows one word. `perLine` alone counts the words as it always did; use `group` for every new video.
 - `mode` (below) still decides how the words inside the group look.
 
 ## Pick one style for the whole video
@@ -35,10 +41,10 @@ With `"none"` the component draws nothing; better still, leave `<Captions>` out
 <Captions words={s.words} mode="pop" highlight={palette.hero} uppercase />
 ```
 
-Do not mix modes between scenes. Set `highlight` to the palette's hero colour (captions are the one exception to the one-hero-element rule) or to a high-contrast yellow on busy footage.
+Do not mix modes between scenes. Set `highlight` to the palette's hero colour (captions are the one exception to the one-hero-element rule): any accent works, because the word is on a chip with its own ink; leave it out for a yellow.
 
 ## Words per screen
-- With `group="phrase"` the groups are at most 6 words, and about 32 characters, by themselves. With `group="word"` it is one.
+- With `group="phrase"` (or no `group`) the groups are at most 3 words, and about 32 characters, by themselves; `maxWords` raises it to at most 6. With `group="word"` it is one.
 - With `perLine` instead: `pop` 1 to 3 words; `highlight` and `karaoke` 3 to 5 words for vertical video, up to 6 for landscape; in Hebrew at most 4.
 - Never show a full sentence at once. Word-level timing reads better than sentence captions.
 
@@ -61,7 +67,7 @@ Do not mix modes between scenes. Set `highlight` to the palette's hero colour (c
 
 ## Legibility
 - Heavy sans-serif weight, large: about 5.5 percent of the width for line captions, 7.5 percent for pop. The component sets these.
-- Contrast of at least 4.5 to 1 against whatever is behind. The component adds a dark outline and shadow; on very bright footage also dim the footage.
+- Contrast of at least 4.5 to 1 against whatever is behind, on any ground, with no colour chosen by you: the component puts the words on a dark rounded plate (about 58% opaque) in white, and the spoken word sits on a chip of `highlight` (the accent) with white or dark ink, whichever reads better on it (a `karaoke` fill has no chip: it uses the accent mixed toward white until it reads on the plate). Measured on the render: white ink on the plate is about 5:1 over a cream ground, 5:1 over a bright busy picture and 20:1 over a dark one. Do not set `color` to anything but white, and do not draw your own outline or box.
 - `uppercase` suits `pop` and short hooks; avoid it for long lines.
 
 ## Emphasis effects, with limits

package/skill/reference/clips.md

@@ -28,7 +28,7 @@ A clip is a few seconds of generated video. It is the most expensive thing Reelk
 ## B-roll rules
 - The clip shows exactly what the sentence says, at the moment it says it. If the sentence is abstract, the clip is the wrong tool.
 - Never the same clip twice in a video, and no two clip scenes in a row that look alike.
-- Speech never runs more than 3 seconds without something changing on screen: a new clip, a new text beat, a cut to a graphic. A 5-second clip under a 9-second scene needs a text change or a second visual in the middle.
+- Hold a clip while its action or emotion carries the speech. Add another visual when meaning or readability needs it; do not interrupt a useful hold to satisfy a change quota.
 - Text over a clip must stay legible. Use `<ClipLayer src={urls[s.clipKey]} dim={0.25} />` to darken it, keep headlines in the calm part of the picture, and look at the preview frames for contrast on both the early and the late frame.
 
 ## Green screen
@@ -40,7 +40,7 @@ A green-screen clip is a subject filmed on a flat pure green background. It is f
 - Layer it above the scene's background and below the captions:
 
 ```tsx
-import { Img } from "remotion";
+import { Img } from "reelkit/frame";
 import { Captions, KeyedClip, SceneFrame } from "reelkit/kit";
 
 <SceneFrame from={s.startFrame} durationInFrames={s.durationFrames}>
@@ -82,7 +82,7 @@ A keyed clip is what makes real depth possible: things can sit behind the subjec
 - Check both preview frames for a green fringe on the edges and for the subject hiding something that must be read.
 
 ```tsx
-import { AbsoluteFill } from "remotion";
+import { AbsoluteFill } from "reelkit/frame";
 import { BgMesh, Captions, KeyedClip, SceneFrame, fonts } from "reelkit/kit";
 
 <SceneFrame from={s.startFrame} durationInFrames={s.durationFrames}>

package/skill/reference/component-authoring.md

@@ -10,7 +10,7 @@ Run `reelkit assets search "<description>" --kind component`. If a library compo
 
 ## Rules for a component file
 - One component per file. File `NumberBadge.tsx` exports `export const NumberBadge: React.FC<NumberBadgeProps>`.
-- Imports only from `react`, `remotion` and `reelkit/kit`. A component never imports another component file.
+- Imports only from `react`, `reelkit/frame` and `reelkit/kit`. A component never imports another component file.
 - Everything specific comes in through props: text, numbers, colours, timing. No baked-in copy, brand names, user details or asset paths.
 - Give every visual prop a sensible default so `<NumberBadge value={1} />` works on its own.
 - Size relative to `useVideoConfig()`, never fixed pixels.

package/skill/reference/continuity.md

@@ -1,15 +1,15 @@
 ---
 name: continuity
-description: Use before the plan and again when writing the composition - how to keep a video from feeling like a slideshow, with three concepts to offer the user, what to carry across every scene change, how to vary rhythm, and how to read the continuity and rhythm numbers the CLI reports.
+description: Use before the plan and again when writing the composition - how to keep a video from feeling like a slideshow, with concepts chosen from the brief, what to carry across every scene change, how to vary rhythm, and how to read the continuity and rhythm numbers the CLI reports.
 ---
 
 # Continuity and rhythm
 
 A slideshow is a row of separate pictures: each scene replaces the one before it, and every scene lasts about the same time. Two things cure it. Continuity means that at every scene change something on screen survives and visibly moves, grows or turns into the next scene. Rhythm means shot lengths differ a lot, the picture sometimes rests, and not everything moves all the time.
 
-## Three concepts before a plan
+## A concept before a new plan
 
-A concept is one sentence about the picture, not about the product. Before you write `plan.json`, offer the user three concepts that differ in their central idea, and let them pick. For each one say the opening frame, what carries each scene change, and what it rules out.
+A concept is one sentence about the picture, not about the product. Before a new `plan.json`, recommend the strongest concept that fits the brief; offer alternatives if the user wants a comparison. Keep an already chosen concept for revisions. For each one say the opening frame, what carries each scene change, and what it rules out.
 
 Ideas to draw from (invent your own when the topic asks for it):
 
@@ -19,7 +19,7 @@ Ideas to draw from (invent your own when the topic asks for it):
 - **One surface the whole video lives on.** A desk, a phone screen, a page, a map. Everything is placed on it and the camera or the objects move across it. Rules out backgrounds that change per scene.
 - **A before-and-after split.** The frame is divided from the start; the dividing line moves, and what was on one side becomes the other. Rules out stories that have no contrast to show.
 
-Write each concept as: "Opens on a plain card with the price. The card slides up and becomes the header of the comparison; the comparison's winning row grows into the call to action. No stock backgrounds." The user picks; write the choice into the first scene's `notes`, next to the look.
+Write each concept as: "Opens on a plain card with the price. The card slides up and becomes the header of the comparison; the comparison's winning row grows into the call to action. No stock backgrounds." Honor the chosen direction; write it into the first scene's `notes`, next to the look.
 
 ## Carry at every scene change
 
@@ -32,13 +32,13 @@ Ways to do it with the kit:
 - A container that grows into the next scene's background. The card of one scene becomes the full-frame ground of the next.
 - A shared colour field that one scene's object expands into. The new scene is the colour the old object grew to.
 
-A hard cut is a choice. Use it for a burst of fast hits, or for the end card, and know that you are doing it. It is not the default.
+A hard cut is a choice. Use it for a burst of fast hits, or for the end card, and know that you are doing it. It is not the default. Say so in the plan: give the scene that begins on the cut `"cutIn": true`. `reelkit preview` then reports that change as `cut (intended)` and leaves it out of the score.
 
 `SceneFrame` fades each scene in and out over its first and last few frames. Anything that must stay on screen through a change therefore lives outside it, in a `Carry` layer (or inside a `Camera` that wraps all the scenes). This example holds a price card through two scenes: it is large in the first, then shrinks into a badge that the second scene is built around.
 
 ```tsx
 import React from "react";
-import { AbsoluteFill } from "remotion";
+import { AbsoluteFill } from "reelkit/frame";
 import { BgMesh, Carry, Entrance, fonts, palettes, SceneFrame } from "reelkit/kit";
 import type { VideoProps } from "reelkit/kit";
 
@@ -90,10 +90,29 @@ For product pictures, the default is a small element on a big ground: the card,
 
 ## Reading the numbers
 
-`reelkit preview` also saves the two frames around each scene change (`b01-end-<scene>.jpg`, then `b01-start-<scene>.jpg`, and so on) and prints a continuity report: a line such as "3 of 5 scene changes carry something across", and a line for each change where nothing does. The frames are the last and first ones at full strength, because `SceneFrame` fades the very last and first. The measure compares edges, the outlines of what is on screen: when at least a quarter of the earlier frame's outlines are still there, nearby, in the later frame, the change is `carried`; otherwise it is a `cut`. A change where the earlier frame is nearly empty is not counted.
+`reelkit preview` also saves the two frames around each scene change (`b01-end-<scene>.jpg`, then `b01-start-<scene>.jpg`, and so on) and prints a continuity report: a line such as "3 of 5 scene changes carry something across", and a line for each change where nothing does. The frames are the last and first ones at full strength, because `SceneFrame` fades the very last and first. The measure compares edges, the outlines of what is on screen: when at least a quarter of the earlier frame's outlines are still there, nearby, in the later frame, the change is `carried`; otherwise it is a `cut`. A change where the earlier frame is nearly empty is not counted. The later scene is sampled twice, at its first fully visible frame and about six frames on, and the better of the two is taken, so a plate that settles into a card is not called a cut. A scene with `cutIn: true` is reported as `cut (intended)` and not counted.
 
 Read it as a smoke alarm, not a grade. A `cut` is a prompt to fix the change or to say in the notes why it is a cut. A `carried` change can still be wrong (an element that stays but means nothing), so look at the pair of frames. The report is advice and never makes `preview` fail. Aim for most changes carried, with the cuts that remain on purpose.
 
 `reelkit plan check` reads the rhythm from the narration: with four scenes or more, it adds a line under "Worth improving" when the scenes are about equally long, or when none is shorter than half the average. It quotes the shortest and the longest. Its data holds `sceneSeconds` for each scene and `lengthVariation`, the spread of the lengths over their mean; below 0.25 is too even. The cure is in the line itself: make one or two scenes much shorter, a hit of a few words, and let one run long.
 
 When the video follows a reference, `reelkit ref analyze` gives targets to match. `pacing.shotLengthVariation` is the same spread for the reference's shots (left out when it has fewer than three), and `stillness` holds `share`, the part of the time in which the picture barely changes from frame to frame, and `longestSec`, the longest such hold. If the reference's shots vary by 0.8 and it is still a third of the time, plan scene lengths that vary about that much, and let the picture rest about that often. A video that moves every frame, against a reference that holds, will feel busier than the reference, whatever else you copy.
+
+## Transitions
+
+`SceneFrame` fades by default. Choose another transition with `enter` and `exit` (the same kind on both sides of a change), `transitionFrames` (8 by default, at most 20) and, for a zoom, `origin` (where it aims, as fractions of the frame). Each is complete exactly at the scene boundary, so the cut stays on the beat. A transition is a choice with a meaning:
+
+- `zoom-through`: going INTO something. The old scene rushes toward a point and the new one arrives from there: into a screen, a detail, a product.
+- `push-left`, `push-right`, `push-up`, `push-down`: moving along a sequence, such as the next step or the next card in a row.
+- `whip-left`, `whip-right`: a quick list, one item after another, with a smear that carries the eye.
+- `turn`: a before and after, or two sides of the same thing.
+- `zoom-in`, `zoom-out`, `blur`: a soft change of subject or mood.
+- `cut`: a burst of hits, where speed matters more than smoothness (mark it with `cutIn` in the plan).
+- `fade`: the default, for a calm change.
+
+Rules: use at most two kinds in one video. Never the same exit twice in a row for different meanings: a push that always means "next" is a rhythm, but a push for one thing and a push for another is noise. A carried element (`Carry`, `Camera`) beats any transition: if something stays on screen and moves into the next scene, the change needs no transition at all, so leave it `fade` or `cut`. `reelkit preview` takes its boundary frames clear of a literal `transitionFrames={N}` in the code.
+
+```tsx
+<SceneFrame from={a.startFrame} durationInFrames={a.durationFrames} exit="zoom-through" origin={{ x: 0.5, y: 0.45 }}>...</SceneFrame>
+<SceneFrame from={b.startFrame} durationInFrames={b.durationFrames} enter="zoom-through" origin={{ x: 0.5, y: 0.45 }}>...</SceneFrame>
+```

package/skill/reference/delivery-review.md

@@ -0,0 +1,40 @@
+---
+name: delivery-review
+description: Verify a finished Reelkit export: layout, word and sound timing, phone playback, platform margins, media integrity and honest delivery reporting.
+---
+
+# Verify the deliverable
+
+Review against the original request and actual source material. A render completing proves that a file was encoded; it does not prove that the edit works. Fix observed defects and inspect the changed moments. Stop when the requested result is achieved, without mandatory review rounds or a made-up quality score.
+
+## Before a full render
+
+Run `reelkit check` and `reelkit preview`. Inspect `out/preview/sheet.jpg`, then the important individual frames: opening, both sides of cuts, spoken triggers, transformation landing, readable hold and ending. The normal early and late samples can miss a brief overlap, so inspect the moving export or extract additional frames around a suspicious event. Do not invent a preview timestamp flag.
+
+- Does each moment have a clear focal point and a reason to be there?
+- Are text, captions and supplied logos readable, correctly spelled and clear of faces or controls?
+- Does each claim match the user's facts and source? Are illustrative surfaces distinguishable from the real product?
+- Do objects settle when their words or events happen? Do old labels leave before the replacement is readable?
+- Are empty states, media edges and transparency intentional? Is the ending held long enough to read?
+
+Preview holds as well as entrances. For a loop, compare the first frame with the loop boundary and check audio continuity; matching stills alone does not prove a seamless moving loop.
+
+## Phone and destination layout
+
+Default a new short-form video to 9:16 unless the destination or user specifies otherwise. Keep critical content clear of likely platform chrome. For 1080x1920, a conservative working region leaves about 250px at the top, 350px at the bottom, 80px on the sides and extra room on the lower right. These are starting margins, not a guarantee for every app, device or caption expansion. Scale with the output dimensions and inspect the named destination when available. Do not add two platform versions automatically.
+
+If variants are requested, change the layout in the source and render each variant; moving a finished frame can crop another element. Keep filenames explicit and retain earlier deliverables when revising. Do not publish or upload the result as part of a local export request.
+
+## Check the finished file
+
+Confirm the file exists. Use `ffprobe` when available to check actual codecs, dimensions, frame rate and duration against the requested result; decode with `ffmpeg` when corruption or missing media is suspected. Reelkit normally renders H.264/AAC MP4 and masters the mix near -14 LUFS. Inspect the reported result before applying another loudness pass. A duration mismatch may be a short audio tail; investigate before changing scene timing.
+
+Play the export when playback is available, and listen to its speech, music and effects. Speech must be intelligible; intended music and cues must actually be present. Check the first hit, a middle word, the reveal landing and the ending for sync, unexpected silence, truncated tails and clipping. Check the final mix, not only the source stems. Avoid certifying subjective audio quality when you only ran measurements; state what was verified and what could not be auditioned.
+
+`reelkit sound --detail` reports measurable hits, swells and nearby picture changes. Use it to locate a suspected mismatch, not to fill a quota. A calm hold can have no effect, and repeated music beats can inflate hit counts. Audition a small-speaker or reduced-bass mix when available; if only analysis is possible, look for music that vanishes without its bass and report the limitation. Do not treat a fixed energy percentage or a stem-correlation threshold as proof that the mix sounds good.
+
+If a speed change or cut shifted timing, correct the source event map and rerender. Do not offset the whole audio track to repair one bad cue. If clipping exists before mastering, lower overlapping source levels; loudness normalization cannot restore an already clipped waveform.
+
+## Deliver
+
+Link or display the final video and give its project path. Briefly explain the main creative choices and why they fit, including the music when used. Report checks actually performed, material limitations and generator usage only when known. Do not claim credits were measured when the provider only exposes a remaining allowance. Keep the plan, source and media together so the edit can be revised.

package/skill/reference/hebrew-rtl.md

@@ -15,7 +15,7 @@ Most broken Hebrew videos break in the same few ways. These rules are for text d
 
 ## Direction
 - Give every Hebrew text container `direction: "rtl"`. Without it the full stop, comma and exclamation mark jump to the wrong end of the line.
-- Digits and Latin words inside a Hebrew sentence order themselves when the base direction is RTL. A label that is entirely Latin or digits gets `direction: "ltr"`.
+- Isolate Latin terms, URLs and technical identifiers in their own LTR span or bidi-isolated element inside the RTL container. A label that is entirely Latin or digits gets `direction: "ltr"`. Check numbers and punctuation in the rendered sentence, not just the source.
 - Everything laid out in reading order runs right to left: the first word on the right, the first list item on the right or top, tabs, chat bubbles, steps, and charts over time (the first day on the right).
 - **The exception:** progress bars, sliders, loading bars and media timelines still fill left to right, as every player does.
 - A typing effect adds characters in reading order; the caret sits at the left end of the text, where it grows.
@@ -29,8 +29,7 @@ Most broken Hebrew videos break in the same few ways. These rules are for text d
 - This overrides the masked rise that `reference/motion-design.md` recommends for Latin headlines.
 
 ## Hyphens and punctuation
-- **Never join two Hebrew words with a hyphen on screen**, in headlines, labels or interface text. Write the two words with a space.
-- No em dash and no en dash on screen. Use a comma, a full stop or a new line.
+- For newly written display copy, prefer clear punctuation and breaks rather than joining words with decorative dashes. Preserve the user's exact supplied wording; do not silently remove a hyphen or punctuation from a quote.
 - A prefix letter before a number or a Latin word ("ב-2026") is correct Hebrew, but on screen prefer wording that avoids it.
 - Quote the user's text exactly, letter for letter. Never "fix" spelling, add vowel points or swap a final letter.
 
@@ -45,7 +44,7 @@ Most broken Hebrew videos break in the same few ways. These rules are for text d
 
 ## Check before you show
 1. Every word in the right order, right to left, spelled exactly as given.
-2. No hyphen between words, no long dash.
+2. Punctuation matches the supplied wording and renders at the correct end of the phrase.
 3. No letter cut by the frame edge or by a mask, in the early frame or the late one.
 4. Progress bars fill left to right; everything else runs right to left.
 5. The full stop and exclamation mark sit at the left end of the last word.

package/skill/reference/{remotion-composition.md → hyperframes-composition.md}

@@ -1,14 +1,16 @@
 ---
-name: remotion-composition
+name: hyperframes-composition
 description: Use when writing Video.tsx - the file rules, timing model and media rules every composition must follow.
 ---
 
 # Writing the composition
 
+Reelkit uses HyperFrames with a seekable React adapter. Author TSX in `src/Video.tsx`; `reelkit/frame` supplies the frame clock, sequences, media, and animation math. The generated HTML exposes HyperFrames' seek protocol for capture and rendering.
+
 ## Files
 - `Video.tsx` is required and must contain `export const Video: React.FC<VideoProps> = ({ manifest, urls }) => ...`.
 - Extra component files are flat siblings, PascalCase, one component per file: `NumberBadge.tsx` exports `NumberBadge`. Import them in Video.tsx as `./NumberBadge`.
-- Video.tsx may import only `react`, `remotion`, `reelkit/kit` and sibling components. No other packages, no network, no file access, no `process`.
+- Video.tsx may import only `react`, `reelkit/frame`, `reelkit/kit` and sibling components. No other packages, no network, no file access, no `process`.
 
 ## What the composition receives
 `Video` gets two props, `{ manifest, urls }` (type `VideoProps`, exported by `reelkit/kit`). `manifest` is the content of `manifest.json` in the project, rewritten by `reelkit assets voiceover`, `check`, `preview` and `render` from `plan.json` and the recorded voiceovers. It is not hand-edited. `urls` is separate: it is built at render time and is not in `manifest.json`.
@@ -22,13 +24,13 @@ description: Use when writing Video.tsx - the file rules, timing model and media
 
 Each `scenes` entry:
 - `id`: the scene id from `plan.json`.
-- `startFrame`, `durationFrames`: frames on the whole video's timeline. A scene lasts its narration plus 0.4 s of breathing room, rounded up to a whole frame.
+- `startFrame`, `durationFrames`: frames on the whole video's timeline. A scene lasts until its last word has ended plus the plan's `gap` (0.3 s by default; the next scene's voice starts on the scene's first frame), rounded up to a whole frame; the last scene keeps 0.7 s. A change may move up to 4 frames to reach a beat.
 - `voiceoverKey`: the project path of the narration audio.
-- `words`: one entry per spoken word, `{ word, startSec, endSec }`, in seconds from the start of that scene (not of the video, and not frames). Convert with `Math.round(sec * fps)` for a frame inside the scene; `<Captions words={s.words} />` takes them as they are.
+- `words`: one entry per spoken word, `{ word, startSec, endSec }`, in seconds from the start of that scene (not of the video, and not frames). Do not convert them yourself: `wordFrame(s, "word")` and `onWord(s, "word")` give the frame inside the scene (reference/voice-sync.md); `<Captions words={s.words} />` takes them as they are.
 - `imageKey`: only on an illustration scene that has its image; the project path of the image.
 - `userAssetKeys`: project paths of the user's own files that the plan assigned to this scene (an empty array when none).
 
-`urls` maps a project path (every file under `assets/`, except `.json` files) to the address Remotion can load it from. Pass paths from the manifest, or one you pulled, such as `urls["assets/lib/<id>/clip.mp3"]`; never build an address yourself.
+`urls` maps a project path (every file under `assets/`, except `.json` files) to the address HyperFrames can load it from. Pass paths from the manifest, or one you pulled, such as `urls["assets/lib/<id>/clip.mp3"]`; never build an address yourself.
 
 ```json
 {
@@ -49,13 +51,14 @@ Each `scenes` entry:
 
 ## Media
 - Reference media only as `urls[path]`, where `path` is the file's project path, using the paths in the manifest: `s.voiceoverKey`, `s.imageKey`, `s.clipKey`, `s.clipKeyedKey`, `s.userAssetKeys`, `manifest.footageKey`. Never hard-code a URL.
-- A scene with narration has `s.voiceoverKey`: give it exactly one `<Voiceover src={urls[s.voiceoverKey]} />` inside its SceneFrame, and `<Captions words={s.words} />` unless the notes say otherwise.
+- A scene with narration has `s.voiceoverKey`: give it exactly one `<Voiceover src={urls[s.voiceoverKey]} />` inside its SceneFrame, and `<Captions words={s.words} />` unless the notes say otherwise. In a plan with `voice: "none"` no scene has a `voiceoverKey` and `s.words` is empty, so render no `<Voiceover>` and no `<Captions>` (`manifest.captions` is `"none"`); keep the guard `s.voiceoverKey ? ... : null` so the same code works either way.
 - Footage mode (`manifest.footageKey` is set): one `<FootageLayer>` at the bottom, outside the scenes.
-- User images: `<Img src={urls[key]} />` from remotion.
+- User images: `<Img src={urls[key]} />` from reelkit/frame.
+- Write a media path as one plain string, so that `reelkit check` can verify the file exists. A path built with a template string or by joining parts (`` `assets/lib/${id}/hit.mp3` ``) cannot be checked and is reported as missing. Write `"assets/lib/sfx-ab12/hit.mp3"` in full, or read the key from the manifest.
 
 ## Layer stack (every video, bottom to top)
-1. Background: `<BgMesh>` from the kit, or `<FootageLayer>` in footage mode. Never a flat solid colour.
-2. Images: `<KenBurnsImage>` inside its scene. Every still image moves; alternate `direction` between consecutive image scenes.
+1. Background: a chosen field, picture, `<BgMesh>` or `<FootageLayer>` in footage mode. A flat colour is valid when it serves the design.
+2. Images: `<KenBurnsImage>` when a camera move helps, or a stable image for reading and comparison. Keep important details in frame.
 3. Clips: `<ClipLayer>` inside its scene (a clip scene's picture); a green-screen `<KeyedClip>` above the scene's background and below its type and captions. See `reference/clips.md`.
 4. Graphics and type, inside each scene's SceneFrame.
 5. Anything that must survive a scene change: a `<Carry>` layer beside the scenes and above them (outside the SceneFrame fades), and `<Camera>` around the scenes when one camera moves through all of them. See `reference/continuity.md`.
@@ -69,9 +72,9 @@ Each `scenes` entry:
 - Run `reelkit assets pull <id>` before referencing an overlay. It lands in `assets/lib/<id>/`; reference it as `urls["assets/lib/<id>/<file>"]`, and read its duration from `assets/library.json`.
 
 ## Animation rules
-- **No linear motion.** Every `interpolate()` takes an `easing` from the kit's `ease` and both `extrapolateLeft: "clamp"` and `extrapolateRight: "clamp"`. Entrances use `spring()` with a kit `springs` preset.
+- Choose easing or a spring to fit the move; linear interpolation is valid for steady motion. Clamp finite interpolation ranges with `extrapolateLeft: "clamp"` and `extrapolateRight: "clamp"` so elements do not drift beyond their intended pose.
 - **Entrances move two or three properties together** (opacity, position, scale). Wrap content in `<Entrance>` rather than fading alone.
-- **Stagger, never simultaneous.** Words 3 frames apart, list items and cards 4 to 5, big blocks 6.
+- Stagger related items when that improves hierarchy; simultaneous motion is valid for one coordinated action. Spoken words follow their real timestamps rather than a fixed stagger.
 - **Exits exist and are faster than entrances** (about 10 frames against 20). Use `<Entrance exitAt={...}>` or the SceneFrame fade.
 - **A missing clamp shows elements before their entrance or after their exit.** Check for it.
 - Derive timing from `fps` in `useVideoConfig()`, not bare frame counts, when you express a duration in seconds.
@@ -90,3 +93,7 @@ Each `scenes` entry:
 1. `reelkit assets search "<description>" --kind component`, and `reelkit assets pull <id>` for any you plan to use (it lands in `src/`).
 2. Write each new component in `src/`, then `src/Video.tsx`.
 3. `reelkit check`. Fix every error it reports and check again until it passes.
+
+## Revising a shot in HyperFrames
+
+Every pose must be computable from the current frame, including a direct seek to the landing or held state. Use `reelkit/frame` timing helpers; avoid CSS animations, wall-clock timers, and state accumulated by previous frames. Derive sound from the same event frames as the visual. Inside a `SceneFrame` timing is local; outside it add `startFrame` once. For a branded arrival use `BrandTransform3D` and `brandTransformFrames` (`reference/brand-motion.md`). Preview early, middle and held states after retiming, and listen to the rendered file after changing sound.