# Engine

Time, motion, music, reading and transitions, imported from @intentface-launch/core.

`import { … } from "@intentface-launch/core"`. Everything is a pure function of
the frame, so any frame renders alone.

## Video and time

| Tool | What it does |
| --- | --- |
| `defineVideo` | Declares a video: shots end to end, overlapped by their transitions, with audio, formats and variants. |
| `useFrame` | The current frame, counted from the enclosing shot or `Sequence` (`{ from: "ask" }` counts from another shot). |
| `useSeconds` | Seconds since the start of the enclosing shot or `Sequence`. |
| `useVideoInfo` | The video's fps, size, format on screen and variant, and `duration`: the length of the enclosing shot in frames. |
| `useVariant` | The variant on screen and its `data`. |
| `Sequence` | Shows its children for a range of frames, with the clock restarting at 0. |
| `waitFor` | Holds the frame until a promise settles (image decode, data load). Pass a label to name it in stall reports. |
| `withVariant`, `withFormat` | The video as one of its variants or formats. |

## Motion

| Tool | What it does |
| --- | --- |
| `interpolate` | Maps a value through piecewise segments, eased per segment. |
| `progress` | 0 to 1 over a duration from a start frame. The workhorse for reveals. |
| `ease`, `bezier` | Named easing curves, and CSS cubic-bezier easing. |
| `overshootEase` | An entrance that passes its target once and settles, landing on time. |
| `spring`, `springs` | A closed-form damped spring, and named presets. |
| `springTo` | A value that changes target many times, keeping its speed through each change. Also takes points. |
| `springEase` | A spring as an easing that still arrives when the key says. |
| `springVelocity`, `springToVelocity` | A spring's speed at a frame: what a move hands to the next shot at a cut. |
| `settleFrames` | Frames until a spring stays near its target: when the next beat can start. |
| `landed` | A spring-driven position that lands on whole pixels: fractional while it moves, the rounded target once within 0.2 px. Rounding every frame makes the slow tail step. |
| `springFeel`, `springsAt` | Springs as `{ duration, bounce }` in frames. |
| `motion`, `personalities` | One easing family, spring, duration and stagger per video: `premium`, `energetic`, `playful`. |
| `durations`, `staggers` | Named durations and staggers, scaled to the frame rate or a tempo. |
| `random` | Seeded random numbers, the same in every worker. |
| `lerp` | Linear interpolation. |
| `toOklch`, `mixColor`, `formatOklch` | Colours in OKLCH, mixed the short way round the hue. |
| `springColor` | `springTo` for a colour, in OKLCH. From or to a near neutral it moves straight in OKLab, so it never passes through other hues. |

## Music and sound

| Tool | What it does |
| --- | --- |
| `tempo` | Musical time: `t.beats(16)` in frames. Pick a BPM whose beat is a whole number of frames. |
| `beatGrid` | Detected beats from `beats.json` as frames, for tracks that drift from their tempo. |
| `findBreaths` | Quiet stretches in a track, for the silence before a reveal. |
| `editBeats` | Beat times after an `audio.edit` replays passages. |
| `audioLevels` | Reads a levels file: `at`, `smooth`, `pulse`, `accumulate`, `phraseAt`. For things that move with the sound. |

## Text, captions and formats

| Tool | What it does |
| --- | --- |
| `readingTime` | How long a text must hold to be read. |
| `readingTimeOnBeats` | The same, rounded up to whole beats. |
| `wordTimings` | The frame each word appears at, for kinetic type without a voice-over. |
| `lintText` | Flags headlines over 6 words and lines over 42 characters. |
| `declareText` | Tells `check` what text a canvas or WebGL stage paints, so it is checked like DOM text. |
| `resolveCaptions`, `cueAt`, `wrapLines` | Caption cues as frames, wrapped and kept from overlapping. |
| `clearArea`, `platformZones` | Where text can go in a vertical cut, clear of TikTok, Reels and Shorts UI (what `check` holds 9:16 text to). |
| `safeZone`, `SAFE_ZONES` | One rectangle for laying out a vertical cut that works on every app: `organic` (790 × 1200 at 1080 × 1920) or `ads` (660 × 980). Dated October 2026. |

## Transitions

`import { transitions } from "@intentface-launch/core"`, set as a shot's `transition`.

| Transition | What it does |
| --- | --- |
| `fade` | A plain cross-dissolve. Safe over 3D. |
| `blur` | Dissolve with the outgoing shot blurring away. The house transition. |
| `zoom` | The outgoing shot falls back while the next rises in front. |
| `push` | Both shots travel together, like a pan. |
| `whip` | A fast whip pan, blurred along the move. 12 to 18 frames. |
| `wipe` | A straight, feathered edge at any angle. |
| `iris` | A circle opening from a point. |
| `shape` | Any SVG shape (a star, the product's mark) growing from a point. |
| `clock` | A clock hand sweeping round. |
| `sweep` | A band of light crosses the frame and the cut happens under it. |
| `zoomInto` | Pushes into an element that becomes the next scene. |
| `matchCut` | Places the incoming element where the outgoing one was, then springs it home at the speed it had. |
| `displace` | Dissolve through a liquid distortion. |
| `luma` | The next shot appears through noise, darkest first, like ink. |
| `chromatic` | A glitchy RGB split. 12 to 20 frames. |
| `honest` | A short dissolve where the edit skips time, so a slow result does not look instant. |
| `wipeMask`, `circleMask`, `clockMask` | The same reveals as CSS masks, for any layer. |

## Capture scripts and config

| Tool | What it does |
| --- | --- |
| `defineCapture` | From `@intentface-launch/core/capture`: a script that drives the running product, frame-stepped, with snapshots and marks. |
| `secret` | An API key or demo login from the environment or the env file `secrets` names. Never printed, and replaced in snapshots and manifests. |
| `defineConfig` | From `@intentface-launch/core/config`: `launch.config.ts`, with the product, linked products, secrets and check thresholds. |