Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(components): M7 logo, backdrop, waveform, word cycle; M8 devices, touches, before/after, selection, card stack

okanaslf448807c2a37
diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
index 03a72296..7da42184 100644
--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
@@ -2683,7 +2683,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
(typeof target?.deflicker !== "object" || !target?.deflicker)
) {
if (scissorRect) {
- ctx.renderer.pushScissor(scissorRect);
+ // Nested containers clip inside their parents' clip.
+ ctx.renderer.pushScissorIntersect(scissorRect);
}
const res = await renderNodeTree(
nodeVM.children ?? [],
@@ -2756,7 +2757,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
let activeGroupView = groupView;
if (nodeVM.children && nodeVM.children.length > 0) {
if (scissorRect) {
- ctx.renderer.pushScissor(scissorRect);
+ // Nested containers clip inside their parents' clip.
+ ctx.renderer.pushScissorIntersect(scissorRect);
}
const res = await renderNodeTree(
nodeVM.children,
diff --git a/packages/components/SPEC.md b/packages/components/SPEC.md
index ce6d523e..a0ecb884 100644
--- a/packages/components/SPEC.md
+++ b/packages/components/SPEC.md
@@ -601,7 +601,7 @@ Captions({
| `placement` | `{ anchor: "bottom" \| "center" \| "top"; safeArea?: "portrait" \| "landscape" \| Rect; offset? }` | `bottom`, auto safe area | Portrait safe area keeps clear of platform UI overlays. |
| `avoid` | `Target[]` | `[]` | Move a phrase up/down when it would overlap a target, e.g. a tracked face. |
| `behind` | `{ video: string; mode?: "person" \| "subject" }` | — | Renders a vision cut-out of the clip **above** the captions, so text passes behind the speaker. |
-| `pulse` | `Signal \| false` | `false` | Active word scale = `1 + pulse × 0.08`. |
+| `pulse` | `AudioLevels \| false` | `false` | The voice's levels (§7.15, analysed from the same track the timings come from): the active word swells with the voice, scale `1 + level × pulseAmount` (default 0.12). Level frame 0 is the component's first frame. (M7; was a `Signal`.) |
| `font`, `fontSize`, `weight` | text props | theme `display`, auto | `fontSize` auto-fits the safe-area width at `maxChars`. |
**Styles (`CaptionStyle`)**
@@ -1019,6 +1019,353 @@ on the same value timeline as an optional `Counter`.
---
+### 7.13 `LogoReveal`
+
+The end-card lockup: a mark and a wordmark arriving as one designed move, with a glint
+on the name once it lands. The mark is an image or SVG file, or path data (which can draw
+itself on); the name is live text, flat or extruded in 3D.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `mark` | `string \| { d: string; viewBox: [w, h]; color? }` | — | A file (image or `.svg`) or path data in its own viewBox, scaled to `markSize`. |
+| `name` | `string` | — | One line. At least one of `mark` / `name`. |
+| `tagline` | `string` | — | Muted line under the name, rises in after it. |
+| `layout` | `"row" \| "stack"` | `"row"` | `row`: mark left of the name; `stack`: mark centred above. |
+| `style` | `"slide" \| "pop" \| "draw" \| "rise"` | `"slide"` | See below. |
+| `glint` | `boolean` | `true` | A light sweeps across the name's letters once the lockup lands, and the mark bumps. |
+| `depth` | `number` | `0` | Above 0 the name is extruded text that deep (px), swinging in on its Y axis. |
+| `material` | `"lit" \| "chrome" \| "glass"` | `"lit"` | Surface of extruded names. |
+| `markSize`, `nameSize`, `gap` | `number` | `150`, `120`, `0.32 × nameSize` (× scale) | |
+| `color`, `accent` | colours | theme `ink`, `accent` | Name colour; path-mark colour and glint tint. |
+| `fontFamily`, `fontWeight` | | theme `display`, `800` | |
+
+**Styles**
+
+| Style | Move |
+|---|---|
+| `slide` | The mark pops in at the lockup's centre, then glides to its place while the name wipes out from behind it (the name sits in a clip that opens with the glide). |
+| `pop` | The mark springs in with overshoot; the name's letters rise in after it, staggered. |
+| `draw` | Path marks draw their outline on, then fill; the name's letters rise in. Image marks fall back to `pop`. |
+| `rise` | Mark, name and tagline rise through masks, staggered. |
+
+Extruded names (`depth > 0`) always swing in (rotate Y −70° → 0 on a spring) whatever the
+style, and skip the letter glint: glyph animators don't reach meshes. Lighting is the
+scene's: add lights to the composition for shaded extrusions. 3D nodes ignore their 2D
+parents' offsets, so the name is placed in the root's parent coordinates (the root's own
+`x` / `y` added): give a 3D lockup a top-level, absolute placement.
+
+**Cues:** `hit` (the mark lands), `revealed` (the lockup is complete), `glint`.
+
+**Acceptance**
+
+- The lockup is centred in its measured box for both layouts, in every style (unit test
+ on the settled geometry).
+- `slide`: no letter of the name is visible before the mark starts gliding (render test).
+- A path mark's settled frame is identical in `draw` and `pop` (render test).
+
+---
+
+### 7.14 `Backdrop`
+
+The surface behind everything: a drifting mesh gradient, a grid or a dot field, with a
+vignette and film grain, looping exactly so it can sit under any length of scene.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `kind` | `"mesh" \| "grid" \| "dots" \| "solid"` | `"mesh"` | |
+| `colors` | `string[]` | theme `accent`, `accent2`, `highlight` | Mesh blob colours; grid / dot colour is the first. |
+| `background` | colour | theme `bg` | |
+| `loop` | `number` | `10 s` | Every motion is periodic in `loop`: frame `f` equals frame `f + loop`. |
+| `speed` | `number` | `1` | Scales drift amplitude, not the period (the loop stays exact). |
+| `cell` | `number` | `64 × scale` | Grid cell / dot pitch. |
+| `intensity` | `number` | `1` | Mesh blob opacity; line / dot opacity scale. |
+| `glow` | `boolean` | `true` (grid, dots) | A soft light drifting over the pattern. |
+| `vignette` | `number` | `0.45` | Edge darkening, 0–1. |
+| `grain` | `number \| false` | `0.35` | Film grain strength, 0–1. |
+
+Root covers the frame (`width` / `height`, default 1920 × 1080 × scale) from 0, 0 and
+clips. Open-ended: it lasts as long as its parent; motion is keyed for `duration` when
+given, otherwise for 60 s, in whole loops.
+
+**Implementation notes**
+
+- Mesh blobs are large radial-gradient boxes on Lissajous orbits (x at 1, y at 2 cycles
+ per loop, seeded phases); keys sit on each axis's extremes with `sine.inOut`, which is
+ an exact cosine (the pieces at the loop seam are `sine.out` / `sine.in`, close but not
+ exact), so a loop costs 3–5 keys per axis and long scenes stay inside the 128-key
+ limit. x and y live on separate nodes, each with its own limit.
+- The grid is one path and the dots one text node of `•` glyphs on the lattice (a path of
+ hundreds of circles renders in seconds; glyphs in milliseconds), each a cell larger than
+ the frame on every side, sliding one cell per loop and snapping back on the loop frame
+ (invisible: the pattern repeats).
+- Grain is the engine's `FilmGrain` on the root.
+
+**Acceptance**
+
+- Frame `f` and frame `f + loop` are identical for every kind, grain off (render test).
+- Seeds change blob phases; one seed renders identically twice (render test).
+
+---
+
+### 7.15 `Waveform`
+
+An audiogram: bars, mirrored bars, dots or a ring that move with a track's spectrum. The
+audio is analysed once, offline and deterministically, into plain data (`AudioLevels`);
+the component binds each bar to its band as a signal, so a minute of audio costs no
+keyframes.
+
+```ts
+const levels = await analyzeAudio("assets/voice.wav", { fps: 30, bands: 32 });
+comp.add([
+ Layer.audio("assets/voice.wav", { startFrame: 60 }),
+ Waveform({ audio: levels, audioStart: 60, kind: "mirror", x: 560, y: 700 }),
+]);
+```
+
+`analyzeAudio(source, { fps, bands, minHz, maxHz })` (framefields) decodes the file;
+`analyzeChannels(channels, sampleRate, options)` (components core, pure) does the work:
+a Hann-windowed FFT per frame, log-spaced bands, each band normalised to its own 98th
+percentile (floored 30 dB under the loudest band's, so a quiet band isn't stretched into
+noise; silence stays 0), an RMS `level` envelope, and onset `beats` from low-band flux.
+
+```ts
+interface AudioLevels {
+ fps: number;
+ frames: number; // length in frames
+ bands: number[][]; // [band][frame], 0–1, low → high
+ level: number[]; // [frame], 0–1
+ beats: number[]; // frames
+}
+```
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `audio` | `AudioLevels` | required | Its `fps` must equal the component's. |
+| `audioStart` | `number` | the component's `at` | Composition frame where the track starts. Signals read the composition's frame, so this is the audio layer's absolute `startFrame`. |
+| `kind` | `"bars" \| "mirror" \| "dots" \| "radial"` | `"mirror"` | `bars` grow up from a baseline, `mirror` from the centre line both ways, `dots` scale, `radial` grow outward from a ring. |
+| `bars` | `number` | `audio.bands.length` | Bands are resampled (averaged) to this count; mirrored bars place low bands in the middle. |
+| `width`, `height` | `number` | `800`, `200` (× scale); radial: `height` is the outer diameter | |
+| `gap`, `radius` | `number` | `0.45` of a bar's pitch, round | |
+| `floor` | `number` | `0.06` | Smallest bar, as a fraction of full height. |
+| `gain` | `number` | `1` | |
+| `smoothing` | `number` | `2` | Frames a bar takes to fall from a peak (offline; attack is instant). |
+| `color` | colour or `[from, to]` | theme `accent` | A pair grades the bars across. |
+
+Natural duration is the audio's length from `audioStart`; open-ended is false (the bars
+fall to the floor at the end).
+
+**Cues:** `beats` (component-local, from `audio.beats`).
+
+**Acceptance**
+
+- `analyzeChannels` finds a 440 Hz tone in the band holding 440 Hz, a 100 Hz kick's
+ onsets within one frame, and is identical on two runs (unit tests).
+- A bar's rendered height at frame `f` matches its band's level at `f − audioStart`
+ (render test).
+
+---
+
+### 7.16 `WordCycle`
+
+"Make videos *faster* / *together* / *in code*": one slot in a line cycles through words,
+the slot resizes to each word's measured width, and the rest of the line glides to fit.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | required | One line with one `{}` marking the slot, e.g. `"Make videos {}"`. |
+| `words` | `string[]` | required | At least two. |
+| `every` | `number` | `1.6 s` | Frames each word stays. |
+| `cycles` | `number` | `1` | Passes through `words`; the last word stays. |
+| `transition` | `"roll" \| "fade" \| "slide" \| "type"` | `"roll"` | `roll`: up through the slot's clip; `slide`: sideways; `type`: deletes and types. |
+| `align` | `"left" \| "center" \| "right"` | `"left"` | `center` / `right`: the text before the slot glides too. |
+| `slot` | `"plain" \| "pill" \| "underline"` | `"plain"` | A pill or underline behind / under the slot that resizes with it. |
+| `color`, `slotColor` | colours | theme `ink`, `accent` | |
+| `fontSize`, `fontFamily`, `fontWeight` | | `96 × scale`, theme `display`, `800` | |
+
+The root is as wide as the line with the longest word, so the layout never reflows
+outside it. Width and position changes ease over the transition (`theme.motion.ease.move`;
+`type` steps per character), two keys a change, so many cycles stay inside the key limit.
+
+**Cues:** `changes` (`{ frame, index, word }`, the frame each new word starts arriving).
+
+**Acceptance**
+
+- At rest, the gap between the slot and the text after it equals one space's measured
+ width for every word (unit test on the keys).
+- Exactly one word is visible in the slot at rest, and a `roll` never shows a word outside
+ the slot's clip (render test).
+
+---
+
+### 7.17 `DeviceFrame`
+
+A phone, tablet or laptop around a screen: the mobile counterpart of `AppFrame`. Content
+is authored in the device's own points (a phone screen is 393 × 852) and scaled into the
+screen, so a mock UI or recording made at device size drops in unchanged, and `at(x, y)`
+maps those points to the parent for pointers, touches and zooms.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `device` | `"phone" \| "tablet" \| "laptop"` | `"phone"` | |
+| `orientation` | `"portrait" \| "landscape"` | `"portrait"` | Phone and tablet. |
+| `content` | `LayoutNode \| LayoutNode[] \| string` | — | Layers in screen points, or a media path (fills the screen with `fit`). |
+| `fit` | `"cover" \| "contain" \| "fill"` | `"cover"` | Media content. |
+| `points` | `[w, h]` | phone 393 × 852, tablet 820 × 1180, laptop 1440 × 900 | Screen size content is authored in (swapped for landscape). |
+| `finish` | `"graphite" \| "silver" \| "midnight"` or colour | `"graphite"` | Body colour; edges and buttons follow. |
+| `island` | `boolean` | `true` | Phone: the camera island (a notch-less pill). |
+| `statusBar` | `boolean \| { time?: string; dark?: boolean }` | `true` | Phone and tablet: time, signal, Wi-Fi and battery, drawn (no glyph fonts needed). |
+| `screen` | colour | `#000000` | Screen background under the content. |
+| `tilt` | `false \| { rotateX?, rotateY? }` | `false` | A 3D presentation angle (box perspective). |
+| `elevation` | `0–3` | `2` | Shadow depth. |
+
+Size: give `height` (phone / tablet) or `width` (laptop); the other follows the device's
+proportions. Defaults: phone and tablet 860 × scale tall, laptop 1280 × scale wide.
+
+**API on the returned node:** `screenRect` (the screen in the parent's coordinates),
+`at(x, y)` (screen points → the parent's coordinates; ignores `tilt`) and `fill(...nodes)`.
+
+**Parts:** `body`, `bezel`, `screen`, `content`, `island`, `status`, `buttons`, `base`,
+`shadow`, `tilt`.
+
+**Acceptance**
+
+- `at(0, 0)` and `at(...points)` are the screen's corners for every device and orientation
+ (unit test).
+- Content authored at `points` fills the screen exactly (render test: a full-size box in
+ points covers the screen rect and nothing outside it).
+
+---
+
+### 7.18 `TouchPoint`
+
+Fingers on glass: taps, double taps, long presses and swipes, drawn the way screen
+recordings show touches (a soft disc that lands, presses and lifts, with a ripple). It
+pairs with `DeviceFrame` through `at()`.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `touches` | `Touch[]` | required | `Touch = { to: Target; at?: number; tap?: number; press?: number; swipe?: Target; dwell?: number }`. `tap`: tap count (default 1 unless `press` / `swipe`); `press`: hold frames (long press); `swipe`: drag to this target and lift. `at` omitted → after the previous touch plus a reading gap. |
+| `size` | `number` | `64 × scale` | Disc diameter. |
+| `color` | colour | `#ffffff` | |
+| `opacity` | `number` | `0.55` | |
+| `ripple` | `boolean` | `true` | A ring expanding from each tap and long press. |
+| `trail` | `boolean` | `true` | A short fading streak behind swipes. |
+
+Root covers the frame (like `Callout`). Between touches the finger is lifted: the disc is
+gone, so it never "travels" like a pointer.
+
+**Cues:** `taps` (`{ frame, point }`, each tap down), `presses` (`{ frame, end, point }`),
+`swipes` (`{ frame, end, from, to }`), `touches` (every touch-down).
+
+**Acceptance**
+
+- The disc is invisible before a touch's lead-in and after its lift (render test).
+- A swipe's disc is at `from` on the swipe cue's frame and at `to` on its `end` (unit test on
+ the keys).
+
+---
+
+### 7.19 `BeforeAfter`
+
+Two versions of one picture split by a moving divider: a clip with and without an effect
+or grade, a redesign, a cleanup. The `before` side is clipped to the divider; both sides
+are laid out at the full size, so they line up exactly.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `before`, `after` | `LayoutNode \| LayoutNode[] \| string` | required | Layers or media paths, laid out at the component's size. |
+| `split` | `number \| [frame, value, ease?][]` | a sweep: 0.5 → 0.15 → 0.85 → 0.5 | Divider position, 0–1 from the left (or top). |
+| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal`: a vertical divider moving left / right. |
+| `labels` | `[string, string] \| false` | `["Before", "After"]` | Corner pills; each fades as the divider covers it. |
+| `handle` | `boolean` | `true` | A round grip with arrows on the divider. |
+| `fit` | as `AppFrame` | `"cover"` | Media sides. |
+| `color` | colour | `#ffffff` | Divider and handle. |
+
+Default size 1280 × 720 × scale. Open-ended (a container).
+
+**Cues:** `settled` (the last split key).
+
+**Acceptance**
+
+- Left of the divider is exactly `before`, right of it exactly `after`, on every frame
+ (render test with two solid sides).
+
+---
+
+### 7.20 `Selection`
+
+A text selection or a marquee, the way an editor draws them, driven by a `MousePointer`
+drag: the highlight follows the pointer glyph by glyph (text) or corner by corner
+(marquee), and marquee items light up as the box covers them.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `kind` | `"text" \| "marquee"` | `"text"` | |
+| `target` | text target | — | `text`: `{ text, match? \| range? }` to select. |
+| `pointer` | a `MousePointer` | — | Follow its `positionAt()` during the drag. |
+| `drag` | `{ frame, end }` | `pointer.cues.drags[0]` | Frames of the drag (parent timeline). Without a pointer, the selection eases across the range in this window. |
+| `from`, `to` | `[x, y]` | the drag's | Marquee corners (parent coordinates). |
+| `items` | `Target[]` | `[]` | Marquee: these light up once covered. |
+| `clear` | `number` | — | Frame (parent timeline) the selection disappears. |
+| `color` | colour | theme `accent` | Fill at 30 %, marquee border at full. |
+
+Root covers the frame from 0, 0. Open-ended unless `clear`.
+
+**Cues:** `selected` (selection complete), `items` (`{ frame, index }`, each item covered).
+
+**Acceptance**
+
+- With a pointer, the selection's end on frame `f` is the glyph boundary nearest the
+ pointer's x on the line under it (unit test, fake host).
+- A selection over two lines draws one rect per line, matching `rangeRects` (unit test).
+
+---
+
+### 7.21 `CardStack`
+
+Cards in a depth stack that shuffle: the front card lifts away and the rest step forward,
+or cards are dealt onto the pile one by one. A testimonial carousel, feature cards, a deck
+of photos.
+
+**Props**
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `cards` | `(LayoutNode \| { title, body?, image?, accent? })[]` | required | Layers sized to the card, or simple cards drawn from the theme. At least two. |
+| `mode` | `"cycle" \| "deal"` | `"cycle"` | `cycle`: the front card flies off and returns to the back; `deal`: cards land one at a time onto the pile. |
+| `every` | `number` | `1.5 s` | Frames between moves. |
+| `cycles` | `number` | `1` | Passes (cycle mode). |
+| `visible` | `number` | `3` | Cards shown behind the front one. |
+| `flyTo` | `"up" \| "left" \| "right"` | `"left"` | Where the front card flies. |
+| `cardWidth`, `cardHeight` | `number` | `640 × 400` (× scale) | |
+| `tilt` | `false \| { rotateX?, rotateY? }` | `{ rotateX: 12 }` | Perspective on the stack. |
+
+**Cues:** `changes` (`{ frame, index }`: the card that is now in front).
+
+**Acceptance**
+
+- At rest the front card is drawn last and unscaled; card `k` behind it is scaled
+ `1 − 0.06 k` and offset `k` steps up (unit test).
+- After a full cycle the stack is the starting order (unit test on the keys).
+
+---
+
## 8. Waves 2 and 3
Specified at summary level now; each gets a full section (like §7) before its milestone
@@ -1151,6 +1498,15 @@ each component alone and forbids every other marker except those.
| TitleCard | 8 | 10 ms |
| LowerThird | 8 | 2 ms |
| Meter | 6 (segments / stars: 3 per cell) | 5 ms |
+| LogoReveal | 10 | 10 ms |
+| Backdrop | 8 (mesh: 4 + blobs) | 10 ms |
+| Waveform | bars + 2 | 5 ms (analysis: 1 s per 10 min of audio, offline) |
+| WordCycle | words + 6 | 5 ms |
+| DeviceFrame | 16 + content | 5 ms |
+| TouchPoint | 3 per touch | 5 ms |
+| BeforeAfter | 10 + both sides | 2 ms |
+| Selection | 2 per line (marquee: 3 + items) | 5 ms |
+| CardStack | 4 per card | 10 ms |
### 9.7 Docs and skills
@@ -1176,8 +1532,8 @@ Each milestone ends with a changeset for `framefields` (minor), docs, and its ex
| **M4 · Wave 2a** ✅ | `CodeBlock`, `TitleCard`, `LowerThird`, `Meter`. | Specs in §7.9–7.12; acceptance tests green (§16); no example film. |
| **M5 · Wave 2b** ✅ | `ChatThread`, `Callout`, `Spotlight`, `Confetti`, `Toasts`. | Built from the §8.1 rows; behaviour and acceptance in §17; no example film. |
| **M6 · Re-score** ✅ | Rank Wave 3 against usage and requests. | Updated §8.2 (no telemetry yet: evidence from the example films and engine features). |
-| **M7 · Wave 3a** | `LogoReveal`, `Backdrop`, `Waveform`, `WordCycle` (+ `Captions` `pulse` via audio signals). | Full specs written first (§8.2 → §7 format). |
-| **M8 · Wave 3b** | `DeviceFrame` + `TouchPoint`, `BeforeAfter`, `Selection`, `CardStack`. | As above. |
+| **M7 · Wave 3a** ✅ | `LogoReveal`, `Backdrop`, `Waveform`, `WordCycle` (+ `Captions` `pulse` via audio levels). | Specs in §7.13–7.16; acceptance tests green (§18); no example film. |
+| **M8 · Wave 3b** ✅ | `DeviceFrame` + `TouchPoint`, `BeforeAfter`, `Selection`, `CardStack`. | Specs in §7.17–7.21; acceptance tests green (§19); no example film. |
Housekeeping (done in M1): the stale `.changeset/components-mouse-pointer.md` described a
standalone package that never shipped; it is replaced by `framefields` changesets per
@@ -1325,7 +1681,8 @@ How it is built:
Deviations from §7.3 / §7.8:
- **Captions:** `pulse` (voice-driven active-word scale) and `avoid` are deferred: glyph
- signal selectors need a way to bind user signals into a text node. Phrase cues are
+ signal selectors need a way to bind user signals into a text node. (`pulse` landed in
+ M7 from analysed levels, §18.) Phrase cues are
`{ frame, end, text }`. The default font is the theme's display face at weight 800 (body
weight for `clean`).
- **Terminal:** the default prompt is `$ ` and spinners / checks are drawn, because common
@@ -1423,3 +1780,96 @@ Deviations from the §8.1 rows:
- Confetti paper doesn't flip in 3D: GPU particles have no per-particle rotation, so the
flutter comes from curl noise.
- Emoji need an emoji-capable font; the default theme fonts have none.
+
+## 18. M7 delivery notes
+
+What landed: `LogoReveal`, `Backdrop`, `Waveform`, `WordCycle` (§7.13–7.16), `Captions`
+`pulse`, audio analysis (`analyzeChannels` in core, `analyzeAudio` in framefields), unit
+tests for each, the components in `ids.test.ts` and the tree-shake table, and
+`m7.render.test.ts` (the slide's name hidden until the glide; draw and pop settle alike; an
+extruded name renders; every backdrop kind loops exactly; grain applies; seeds change the
+mesh; a bar follows its band on the composition's clock at two start frames; one word at
+rest and a roll that never leaves the slot; the pulse moves only the active word, and level
+0 matches no pulse).
+
+How they are built:
+
+- **Audio as plain data.** Analysis is offline and deterministic (`AudioLevels`: bands,
+ level, beats per frame). `Waveform` binds each band through `host.signal`
+ (`Signal.fromArray`), so long tracks cost no keyframes; `Captions` bakes the phrase's
+ level slice into its glyph expression table. The GPU `AudioSignal` extractor is not used:
+ it is async and its output is a runtime object, not data.
+- **Signals read the composition's frame**, not the layer's (checked with an offset parent),
+ hence `audioStart`. It defaults to the component's `at`, which is right whenever the
+ waveform starts with its track at the top level.
+- **Bars key `height` and `y`.** 2D boxes have no `scaleY` (only 3D models and glyph
+ animators do), so each bar takes two signals per band, shared by mirrored bars.
+- **LogoReveal** path marks accept any SVG path data: `transformPathData` now scales
+ relative commands and arcs. The mark is drawn last, so in `slide` the name wipes out from
+ behind it through its clip. The glint is a char-indexed light band (glyph `fillColor`).
+- **WordCycle** splits the line into before / slot / after; spaces at the slot are measured
+ (`"a a"` minus `"aa"`) rather than trusted to trailing whitespace. Words sit in a clip as
+ wide as the slot.
+- **Contract:** `BuildContext.requested` now carries `duration`, `at`, `x` and `y`
+ (Backdrop keys its loops for the window; Waveform defaults `audioStart`; LogoReveal
+ places 3D names).
+- **Host:** `signal` (`frameArraySignal` itself: the `Signal` namespace would add ~7.6 KB
+ to every component), `grain`, `extrudedText` (`Layer3D.extrudedText`), and `.svg` files
+ in `media` (`Layer.svg`). Effects attach only to media layers, so `grain` is its own
+ layer: a mid-grey SVG carrying `FilmGrain`, blended `soft-light`.
+- **Tree-shaking:** four new rows; the shared host grew ~1 KB, so MousePointer's budget
+ moves from 60 to 62 KB (it also carries the larger `transformPathData`).
+
+Deviations from the specs as first written:
+
+- Captions `pulse` takes `AudioLevels`, not a `Signal` (§7.3 updated); glyphs scale about
+ their own centres, so a pulsing word swells letter by letter.
+- Waveform smoothing is offline release smoothing, not the engine's signal smoothing.
+- WordCycle eases rather than springs (key budget); `type` re-centres a centred line once,
+ as the new word lands.
+- Backdrop's loop seam is close to, not exactly, the cosine (the loop itself is exact).
+- Keyframe `repeat` exists in the schema but nothing evaluates it, so loops are written out
+ in whole periods up to the 128-key limit per track (about 24 loops on the busiest track;
+ raise `loop` for very long scenes).
+
+## 19. M8 delivery notes
+
+What landed: `DeviceFrame`, `TouchPoint`, `BeforeAfter`, `Selection`, `CardStack`
+(§7.17–7.21), unit tests for each, the components in `ids.test.ts` and the tree-shake table,
+and `m8.render.test.ts` (device content in points fills exactly the screen; a touch leaves
+nothing before its lead-in or after its lift; each side of the split shows only on its side,
+static and moving; a selection draws only once its drag starts; a full card cycle returns to
+its first frame).
+
+How they are built:
+
+- **DeviceFrame** scales a content box authored in points into the screen (`scale`, anchored
+ top-left); the status bar and island sit in a second points-space box over it, drawn from
+ boxes and paths. `tilt` is box perspective. **AppFrame's `tilt`**, declared since M1 but
+ never applied, now works the same way.
+- **TouchPoint** has its own small planner (`planTouches`): fingers lift between touches, so
+ there is no travel to plan and the pointer planner isn't reused. Each touch is one disc
+ (plus ripples and swipe ghosts).
+- **BeforeAfter** clips the `before` side with an animated-width box over a full-size
+ `after`; the divider, grip and label fades are keyed from the same split keys.
+- **Selection** follows `pointer.positionAt()` frame by frame: the line under the pointer,
+ then the nearest glyph boundary. Text measurement is shared with targets
+ (`textLayout`, now exported from `core/targets.ts`).
+- **CardStack**: the renderer has no animated z-order (`zIndex` is schema and lint only), so
+ in `cycle` each card sits in a clip that shows only the strip above the card in front of
+ it. Draw order then never matters at rest, and the leaving card flies sideways, clear of
+ the stack. `deal` needs no clip: the newest card is last in the tree.
+
+Engine fix (`webgpu-renderers` + `node-compositor`): `overflow: hidden` clipped a container's
+children but not its grandchildren, because a nested container's scissor replaced its
+parent's instead of intersecting it. Containers now push `pushScissorIntersect`. This was
+needed for BeforeAfter, and it also stops nested content leaking out of AppFrame and
+DeviceFrame screens. There's a regression test in `overflow-clip.test.ts`.
+
+Deviations from §7.17–7.21:
+
+- DeviceFrame is a 2D body under a perspective tilt, not a `Layer3D` mesh.
+- CardStack uses eased keys, not physics; at the corners of the front card's rounded top a
+ card behind is clipped straight across (a sliver of background shows there).
+- Selection doesn't recolour selected glyphs; the highlight sits under the text when the
+ Selection is placed before the text layer.
diff --git a/packages/components/src/app-frame/index.ts b/packages/components/src/app-frame/index.ts
index 0db39c49..93a414d8 100644
--- a/packages/components/src/app-frame/index.ts
+++ b/packages/components/src/app-frame/index.ts
@@ -342,7 +342,23 @@ export const appFrame = /* @__PURE__ */ defineComponent({
duration: null,
cues: cues as AppFrameCues,
parts,
- children: build(width, height).children,
+ children: props.tilt
+ ? [
+ // The presentation angle: a perspective box round the whole frame.
+ host.box({
+ id: ctx.partId("tilt"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width,
+ height,
+ perspective: 1800 * s,
+ rotateX: props.tilt.rotateX,
+ rotateY: props.tilt.rotateY,
+ children: build(width, height).children,
+ }),
+ ]
+ : build(width, height).children,
api: (placement): AppFrameApi => {
const content = parts.content as Animatable<LayoutNode> & {
children?: LayoutNode[];
diff --git a/packages/components/src/backdrop/index.test.ts b/packages/components/src/backdrop/index.test.ts
new file mode 100644
index 00000000..bce55d68
--- /dev/null
+++ b/packages/components/src/backdrop/index.test.ts
@@ -0,0 +1,126 @@
+import type { KeyframeTuple } from "@framefields/compositions/program";
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { evaluateEase } from "../core/ease.js";
+import { fakeHost } from "../test/fake-host.js";
+import { backdrop, cosineKeys, slideKeys } from "./index.js";
+
+const make = () => bind(fakeHost(), backdrop);
+
+/** Evaluate keys the way the renderer does (destination key's ease). */
+function valueAt(keys: readonly KeyframeTuple[], f: number): number {
+ const first = keys[0] as KeyframeTuple;
+ if (f <= first[0]) return first[1] as number;
+ for (let i = 0; i < keys.length - 1; i++) {
+ const [f0, v0] = keys[i] as KeyframeTuple;
+ const [f1, v1, e] = keys[i + 1] as KeyframeTuple;
+ if (f >= f0 && f <= f1) {
+ const t = evaluateEase(e as string | undefined, (f - f0) / (f1 - f0));
+ return (v0 as number) + ((v1 as number) - (v0 as number)) * t;
+ }
+ }
+ return keys[keys.length - 1]?.[1] as number;
+}
+
+type Node = {
+ id?: string;
+ kind?: string;
+ children?: Node[];
+ matte?: { node: Node };
+ animation?: {
+ tracks: Array<{
+ prop: string;
+ keyframes: Array<{ frame: number; value: number }>;
+ }>;
+ };
+};
+const all = (n: Node, out: Node[] = []): Node[] => {
+ out.push(n);
+ for (const c of n.children ?? []) all(c, out);
+ return out;
+};
+
+describe("loop keys", () => {
+ it("cosine keys are exactly periodic and follow the cosine", () => {
+ const loop = 300;
+ const keys = cosineKeys(100, 50, 2, 1.1, loop, loop * 6);
+ for (const f of [0, 13, 77, 150, 299]) {
+ expect(valueAt(keys, f + loop)).toBeCloseTo(valueAt(keys, f), 6);
+ expect(valueAt(keys, f + loop * 4)).toBeCloseTo(valueAt(keys, f), 6);
+ }
+ // Between extremes it is the cosine (within rounding of extreme frames);
+ // the partial pieces at the loop seam are close, not exact.
+ const exact = (f: number) =>
+ 100 + 50 * Math.cos((2 * Math.PI * 2 * f) / loop + 1.1);
+ const extremes = keys.slice(1, 5).map((k) => k[0] as number);
+ for (let f = 0; f < loop; f += 3) {
+ const inner =
+ f >= (extremes[0] as number) &&
+ f <= (extremes[extremes.length - 1] as number);
+ expect(Math.abs(valueAt(keys, f) - exact(f))).toBeLessThan(
+ inner ? 0.6 : 4,
+ );
+ }
+ expect(keys.length).toBeLessThanOrEqual(120);
+ });
+
+ it("caps long spans under the key limit", () => {
+ expect(cosineKeys(0, 10, 2, 0.3, 30, 30 * 1000).length).toBeLessThanOrEqual(
+ 121,
+ );
+ expect(slideKeys(0, 10, 30, 30 * 1000).length).toBeLessThanOrEqual(121);
+ });
+
+ it("slides one cell a loop and snaps back on the loop frame", () => {
+ const keys = slideKeys(-64, 64, 100, 300);
+ expect(valueAt(keys, 0)).toBe(-64);
+ expect(valueAt(keys, 50)).toBeCloseTo(-32, 5);
+ expect(valueAt(keys, 100)).toBe(-64);
+ expect(valueAt(keys, 150)).toBeCloseTo(valueAt(keys, 50), 6);
+ });
+});
+
+describe("Backdrop", () => {
+ it("is open-ended, covers the frame and grains its surface", () => {
+ const b = make()({ id: "b" });
+ expect(b.span.end).toBe(Number.POSITIVE_INFINITY);
+ expect(b.width).toBe(1920);
+ const grain = all(b as unknown as Node).find((n) => n.id === "b-grain") as
+ | (Node & { strength?: number })
+ | undefined;
+ expect(grain?.strength).toBe(35);
+ expect(
+ all(b as unknown as Node).filter((n) => n.id?.match(/^b-blob-\d$/))
+ .length,
+ ).toBe(4);
+ const off = make()({ id: "b", grain: false, vignette: 0 });
+ const nodes = all(off as unknown as Node);
+ expect(nodes.find((n) => n.id === "b-grain")).toBeUndefined();
+ expect(nodes.find((n) => n.id === "b-vignette")).toBeUndefined();
+ });
+
+ it("keys motion for the window in whole loops", () => {
+ const b = make()({ id: "b", loop: 100, duration: 250 });
+ expect(b.cues.loops.map((c) => c.frame)).toEqual([0, 100, 200]);
+ });
+
+ it("seeds blob phases", () => {
+ const y = (seed: number) =>
+ all(make()({ id: "b", seed }) as unknown as Node)
+ .find((n) => n.id === "b-blob-0")
+ ?.animation?.tracks.find((t) => t.prop === "y")?.keyframes;
+ expect(JSON.stringify(y(1))).toBe(JSON.stringify(y(1)));
+ expect(JSON.stringify(y(1))).not.toBe(JSON.stringify(y(2)));
+ });
+
+ it("lights the grid through a drifting matte", () => {
+ const nodes = all(make()({ id: "g", kind: "grid" }) as unknown as Node);
+ const lit = nodes.find((n) => n.id === "g-pattern-lit");
+ expect(lit?.matte?.node.id).toBe("g-glow-matte");
+ expect(nodes.find((n) => n.id === "g-pattern")).toBeDefined();
+ const plain = all(
+ make()({ id: "g", kind: "dots", glow: false }) as unknown as Node,
+ );
+ expect(plain.find((n) => n.id === "g-pattern-lit")).toBeUndefined();
+ });
+});
diff --git a/packages/components/src/backdrop/index.ts b/packages/components/src/backdrop/index.ts
new file mode 100644
index 00000000..fd5c168f
--- /dev/null
+++ b/packages/components/src/backdrop/index.ts
@@ -0,0 +1,404 @@
+/**
+ * Backdrop: the surface behind a scene. A drifting mesh gradient, a grid or
+ * a dot field, with a vignette and film grain. Every motion is periodic in
+ * `loop`, so frame f and frame f + loop are the same picture and the
+ * backdrop can sit under any length of scene.
+ *
+ * Keys sit on each motion's extremes with `sine.inOut` (an exact cosine
+ * between extremes), so a loop costs a few keys per axis.
+ *
+ * Coordinates are the frame's: the root covers the video (default
+ * 1920 × 1080 × theme scale, or the given width / height) from 0, 0.
+ */
+import {
+ type KeyframeTuple,
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import { defineComponent } from "../core/contract.js";
+import type { Animatable } from "../core/host.js";
+
+export const BACKDROP_KINDS = ["mesh", "grid", "dots", "solid"] as const;
+export type BackdropKind = (typeof BACKDROP_KINDS)[number];
+
+export interface BackdropCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** The first frame of every loop. */
+ loops: ReadonlyArray<{ frame: number }>;
+}
+
+/** Keys per track stay under the program's 128-per-animation limit. */
+const MAX_KEYS = 120;
+
+export const backdrop = /* @__PURE__ */ defineComponent({
+ name: "Backdrop",
+ props: () => ({
+ kind: z.enum(BACKDROP_KINDS).default("mesh"),
+ /** Blob colours (mesh); the first is the grid / dot colour. */
+ colors: z.array(z.string()).min(1).optional(),
+ background: z.string().optional(),
+ /** Frames of one loop. Default 10 seconds. */
+ loop: z.number().int().min(2).optional(),
+ /** Drift amplitude multiplier (the period stays `loop`). */
+ speed: z.number().min(0).default(1),
+ /** Grid cell / dot pitch. */
+ cell: z.number().positive().optional(),
+ intensity: z.number().min(0).max(2).default(1),
+ /** A soft light drifting over the grid or dots. */
+ glow: z.boolean().optional(),
+ vignette: z.number().min(0).max(1).default(0.45),
+ grain: z.union([z.number().min(0).max(1), z.literal(false)]).default(0.35),
+ }),
+ defaults: { enter: false, exit: false },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ const s = theme.scale;
+ const W = ctx.requested.width ?? 1920 * s;
+ const H = ctx.requested.height ?? 1080 * s;
+ const c = theme.color;
+ const loop = props.loop ?? fps * 10;
+ const colors = props.colors ?? [c.accent, c.accent2, c.highlight];
+ const cell = props.cell ?? 64 * s;
+ // Motion is keyed for the window, or a minute, in whole loops.
+ const span =
+ Math.max(1, Math.ceil((ctx.requested.duration ?? fps * 60) / loop)) *
+ loop;
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const children: LayoutNode[] = [];
+ const add = (name: string, node: Animatable<LayoutNode>) => {
+ parts[name] = node;
+ children.push(node);
+ return node;
+ };
+
+ add(
+ "background",
+ host.box({
+ id: ctx.partId("background"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ background: props.background ?? c.bg,
+ }),
+ );
+
+ if (props.kind === "mesh") {
+ const count = Math.max(3, colors.length + 1);
+ const r = ctx.rng("mesh");
+ for (let i = 0; i < count; i++) {
+ const size = Math.max(W, H) * (0.75 + r.next() * 0.35);
+ const cx = W * (0.15 + 0.7 * ((i + r.next() * 0.6) / count));
+ const cy = H * (0.25 + r.next() * 0.5);
+ const ax = W * 0.16 * props.speed;
+ const ay = H * 0.14 * props.speed;
+ const color = colors[i % colors.length] as string;
+ const blob = host.box({
+ id: ctx.partId(`blob-${i}`),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: size,
+ height: size,
+ background: `radial-gradient(closest-side, ${color} 0%, ${transparent(color)} 100%)`,
+ opacity: Math.min(1, 0.6 * props.intensity),
+ });
+ // y on the blob, x on its carrier: one track each, each under the key limit.
+ blob.animate(
+ LayerAnimation.keys(
+ "y",
+ cosineKeys(
+ cy - size / 2,
+ ay,
+ 2,
+ r.next() * Math.PI * 2,
+ loop,
+ span,
+ ),
+ ),
+ );
+ const carrier = host.box({
+ id: ctx.partId(`blob-${i}-x`),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ children: [blob],
+ });
+ carrier.animate(
+ LayerAnimation.keys(
+ "x",
+ cosineKeys(
+ cx - size / 2,
+ ax * (r.next() < 0.5 ? -1 : 1),
+ 1,
+ r.next() * Math.PI * 2,
+ loop,
+ span,
+ ),
+ ),
+ );
+ parts[`blob-${i}`] = blob;
+ add(`blob-${i}-x`, carrier);
+ }
+ }
+
+ if (props.kind === "grid" || props.kind === "dots") {
+ const color = colors[0] as string;
+ // Dots are bullet glyphs on a lattice: one text node draws hundreds
+ // of them in a few milliseconds (a path of circles takes seconds).
+ const dotSize = Math.max(6, cell * 0.3);
+ const advance = host.measure("•", {
+ fontFamily: theme.font.body,
+ fontSize: dotSize,
+ }).width;
+ const dots = () => {
+ const cols = Math.ceil(W / cell) + 3;
+ const rows = Math.ceil(H / cell) + 3;
+ return Array.from({ length: rows }, () => "•".repeat(cols)).join("\n");
+ };
+ const pattern = (name: string, opacity: number) => {
+ const place = {
+ id: ctx.partId(name),
+ position: "absolute" as const,
+ x: -cell,
+ y: -cell,
+ opacity: Math.min(1, opacity * props.intensity),
+ };
+ const node =
+ props.kind === "grid"
+ ? host.shape("path", {
+ ...place,
+ width: W + cell * 2,
+ height: H + cell * 2,
+ d: gridPath(W, H, cell),
+ fillType: "none",
+ strokeColor: color,
+ strokeWidth: Math.max(1, s),
+ })
+ : host.text(dots(), {
+ ...place,
+ fontFamily: theme.font.body,
+ fontSize: dotSize,
+ fill: color,
+ letterSpacing: cell - advance,
+ lineHeight: cell,
+ });
+ // One cell per loop, diagonally, snapping back on the loop frame.
+ node.animate(
+ LayerAnimation.create()
+ .keys("x", slideKeys(-cell, cell, loop, span))
+ .keys("y", slideKeys(-cell, cell, loop, span)),
+ );
+ return add(name, node);
+ };
+ pattern("pattern", props.kind === "grid" ? 0.1 : 0.16);
+ if (props.glow ?? true) {
+ // A brighter copy of the pattern, seen through a drifting light.
+ const lit = pattern("pattern-lit", 0.5);
+ const size = Math.max(W, H) * 0.7;
+ const r = ctx.rng("glow");
+ const lightKeys = {
+ x: cosineKeys(
+ W / 2 - size / 2,
+ W * 0.3 * props.speed,
+ 1,
+ r.next() * Math.PI * 2,
+ loop,
+ span,
+ ),
+ y: cosineKeys(
+ H / 2 - size / 2,
+ H * 0.25 * props.speed,
+ 1,
+ r.next() * Math.PI * 2,
+ loop,
+ span,
+ ),
+ };
+ const light = host.box({
+ id: ctx.partId("glow-matte"),
+ position: "absolute",
+ x: lightKeys.x[0]?.[1] as number,
+ y: lightKeys.y[0]?.[1] as number,
+ width: size,
+ height: size,
+ background:
+ "radial-gradient(closest-side, #fff 0%, rgba(255,255,255,0) 100%)",
+ });
+ light.animate(
+ LayerAnimation.create().keys("x", lightKeys.x).keys("y", lightKeys.y),
+ );
+ host.matte(lit, light);
+ parts["glow-matte"] = light;
+ // A faint halo of the pattern colour where the light is.
+ const halo = host.box({
+ id: ctx.partId("glow"),
+ position: "absolute",
+ x: lightKeys.x[0]?.[1] as number,
+ y: lightKeys.y[0]?.[1] as number,
+ width: size,
+ height: size,
+ background: `radial-gradient(closest-side, ${color} 0%, ${transparent(color)} 100%)`,
+ opacity: 0.18 * props.intensity,
+ });
+ halo.animate(
+ LayerAnimation.create().keys("x", lightKeys.x).keys("y", lightKeys.y),
+ );
+ add("glow", halo);
+ }
+ }
+
+ if (props.vignette > 0)
+ add(
+ "vignette",
+ host.box({
+ id: ctx.partId("vignette"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ background: `radial-gradient(rgba(0,0,0,0) 45%, rgba(0,0,0,${round(props.vignette)}) 100%)`,
+ }),
+ );
+
+ // Grain is its own soft-light layer over everything else.
+ if (props.grain !== false && props.grain > 0)
+ add(
+ "grain",
+ host.grain({
+ id: ctx.partId("grain"),
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ strength: round(props.grain * 100),
+ }),
+ );
+ const surface = host.box({
+ id: ctx.partId("surface"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ overflow: "hidden",
+ children,
+ });
+ parts.surface = surface;
+
+ return {
+ children: [surface],
+ width: W,
+ height: H,
+ duration: null,
+ origin: [0, 0],
+ cues: {
+ loops: Array.from({ length: span / loop }, (_, k) => ({
+ frame: k * loop,
+ })),
+ } as BackdropCues,
+ parts,
+ };
+ },
+});
+
+const round = (v: number) => Math.round(v * 1000) / 1000;
+
+/** `#rrggbb` / `#rgb` at alpha 0 (same hue, so the fade has no dark fringe). */
+function transparent(color: string): string {
+ const hex = color.trim().replace(/^#/, "");
+ const full =
+ hex.length === 3
+ ? hex
+ .split("")
+ .map((h) => h + h)
+ .join("")
+ : hex.slice(0, 6);
+ if (!/^[0-9a-f]{6}$/i.test(full)) return "rgba(0,0,0,0)";
+ const n = Number.parseInt(full, 16);
+ return `rgba(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255},0)`;
+}
+
+/**
+ * Keys for `centre + amplitude × cos(2π · cycles · f / loop + phase)` over
+ * `span` frames (whole loops): the value at every loop start, and at each
+ * extreme inside the loop. Between extremes `sine.inOut` is the cosine
+ * exactly; the partial pieces at loop starts use `sine.out` / `sine.in`.
+ * Every loop repeats the same keys, so the motion is exactly periodic.
+ */
+export function cosineKeys(
+ centre: number,
+ amplitude: number,
+ cycles: number,
+ phase: number,
+ loop: number,
+ span: number,
+): KeyframeTuple[] {
+ const at = (f: number) =>
+ round(
+ centre + amplitude * Math.cos((2 * Math.PI * cycles * f) / loop + phase),
+ );
+ if (amplitude === 0) return [[0, round(centre)]];
+ // Extremes: 2π·cycles·f/loop + phase = nπ.
+ const extremes: number[] = [];
+ for (let n = -2; n <= cycles * 2 + 2; n++) {
+ const f = Math.round(
+ ((n * Math.PI - phase) * loop) / (2 * Math.PI * cycles),
+ );
+ if (f > 0 && f < loop && !extremes.includes(f)) extremes.push(f);
+ }
+ extremes.sort((a, b) => a - b);
+ const perLoop: KeyframeTuple[] = extremes.map((f, i) => [
+ f,
+ at(f),
+ i === 0 ? "sine.out" : "sine.inOut",
+ ]);
+ const loops = Math.max(
+ 1,
+ Math.min(span / loop, Math.floor(MAX_KEYS / (perLoop.length + 1))),
+ );
+ const keys: KeyframeTuple[] = [];
+ for (let k = 0; k < loops; k++) {
+ keys.push(k === 0 ? [0, at(0)] : [k * loop, at(0), "sine.in"]);
+ for (const [f, v, e] of perLoop)
+ keys.push([k * loop + (f as number), v, e] as KeyframeTuple);
+ }
+ keys.push([loops * loop, at(0), "sine.in"]);
+ return keys;
+}
+
+/** `from` → `from + by` linearly over each loop, snapping back on the loop frame. */
+export function slideKeys(
+ from: number,
+ by: number,
+ loop: number,
+ span: number,
+): KeyframeTuple[] {
+ const loops = Math.max(1, Math.min(span / loop, Math.floor(MAX_KEYS / 2)));
+ const keys: KeyframeTuple[] = [[0, from]];
+ for (let k = 0; k < loops; k++) {
+ keys.push([
+ (k + 1) * loop - 1,
+ round(from + (by * (loop - 1)) / loop),
+ "linear",
+ ]);
+ keys.push([(k + 1) * loop, from, "hold"]);
+ }
+ return keys;
+}
+
+function gridPath(W: number, H: number, cell: number): string {
+ const w = W + cell * 2;
+ const h = H + cell * 2;
+ const parts: string[] = [];
+ for (let x = 0; x <= w + 0.01; x += cell)
+ parts.push(`M${round(x)} 0L${round(x)} ${round(h)}`);
+ for (let y = 0; y <= h + 0.01; y += cell)
+ parts.push(`M0 ${round(y)}L${round(w)} ${round(y)}`);
+ return parts.join("");
+}
diff --git a/packages/components/src/backdrop/meta.ts b/packages/components/src/backdrop/meta.ts
new file mode 100644
index 00000000..3e86ecba
--- /dev/null
+++ b/packages/components/src/backdrop/meta.ts
@@ -0,0 +1,23 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "Backdrop",
+ summary:
+ "The surface behind a scene: a drifting mesh gradient, a grid or a dot field, with vignette and film grain, looping exactly.",
+ tags: ["background", "backdrop", "gradient", "grid", "dots", "grain", "loop"],
+ parts: [
+ "surface",
+ "background",
+ "blob-0",
+ "blob-0-x",
+ "pattern",
+ "pattern-lit",
+ "glow-matte",
+ "glow",
+ "vignette",
+ "grain",
+ ],
+ cues: ["loops"],
+ example: `Backdrop({ kind: "mesh" })`,
+ since: "M7",
+});
diff --git a/packages/components/src/before-after/index.test.ts b/packages/components/src/before-after/index.test.ts
new file mode 100644
index 00000000..dc65c755
--- /dev/null
+++ b/packages/components/src/before-after/index.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { fakeHost } from "../test/fake-host.js";
+import { beforeAfter } from "./index.js";
+
+const make = () => bind(fakeHost(), beforeAfter);
+type Key = { frame: number; value: number };
+type Node = {
+ id?: string;
+ x?: number;
+ width?: number;
+ height?: number;
+ opacity?: number;
+ children?: Node[];
+ animation?: { tracks: Array<{ prop: string; keyframes: Key[] }> };
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+const keys = (n: Node | undefined, prop: string) =>
+ n?.animation?.tracks.find((t) => t.prop === prop)?.keyframes ?? [];
+
+describe("BeforeAfter", () => {
+ it("clips the before side to the divider", () => {
+ const b = make()({
+ id: "b",
+ before: [],
+ after: [],
+ width: 1000,
+ height: 500,
+ split: [
+ [0, 0.2],
+ [30, 0.8, "power2.inOut"],
+ ],
+ });
+ const clip = keys(find(b, "b-before-clip"), "width");
+ const divider = keys(find(b, "b-divider"), "x");
+ expect(clip.map((k) => k.value)).toEqual([200, 800]);
+ // The divider's centre rides the clip's edge.
+ const w = find(b, "b-divider")?.width ?? 0;
+ expect(divider.map((k) => k.value + w / 2)).toEqual([200, 800]);
+ // Both sides are laid out at the full size.
+ expect(find(b, "b-before")?.width).toBe(1000);
+ expect(find(b, "b-after")?.width).toBe(1000);
+ expect(b.cues.settled[0]?.frame).toBe(30);
+ });
+
+ it("fades a label as the divider covers it", () => {
+ const b = make()({
+ id: "b",
+ before: [],
+ after: [],
+ width: 1000,
+ height: 500,
+ split: [
+ [0, 0.5],
+ [30, 0],
+ ],
+ });
+ const label = keys(find(b, "b-label-0"), "opacity");
+ expect(label[0]?.value).toBe(1);
+ expect(label.at(-1)?.value).toBe(0);
+ expect(keys(find(b, "b-label-1"), "opacity").at(-1)?.value).toBe(1);
+ });
+
+ it("splits vertically and holds a static split", () => {
+ const b = make()({
+ id: "b",
+ before: [],
+ after: [],
+ height: 400,
+ direction: "vertical",
+ split: 0.25,
+ });
+ expect(find(b, "b-before-clip")?.height).toBe(100);
+ expect(keys(find(b, "b-before-clip"), "height")).toEqual([]);
+ expect(b.span.end).toBe(Number.POSITIVE_INFINITY);
+ });
+});
diff --git a/packages/components/src/before-after/index.ts b/packages/components/src/before-after/index.ts
new file mode 100644
index 00000000..119cff0e
--- /dev/null
+++ b/packages/components/src/before-after/index.ts
@@ -0,0 +1,335 @@
+/**
+ * BeforeAfter: two versions of one picture split by a moving divider. The
+ * `before` side is clipped to the divider; both sides are laid out at the
+ * full size, so they line up pixel for pixel. Give one clip twice, once
+ * with an effect, to show what the effect does.
+ */
+import {
+ type KeyframeTuple,
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import { bakeSamples } from "../core/bake.js";
+import { defineComponent } from "../core/contract.js";
+import { evaluateEase } from "../core/ease.js";
+import type { Animatable } from "../core/host.js";
+import { scaleFrames } from "../core/timing.js";
+
+export interface BeforeAfterCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** The divider's last move ends. */
+ settled: ReadonlyArray<{ frame: number }>;
+}
+
+const side = () =>
+ z.custom<LayoutNode | LayoutNode[] | string>(
+ (v) =>
+ typeof v === "string" ||
+ Array.isArray(v) ||
+ (typeof v === "object" && v !== null),
+ { message: "Expected layers or a media path for this side" },
+ );
+
+export const beforeAfter = /* @__PURE__ */ defineComponent({
+ name: "BeforeAfter",
+ props: () => ({
+ before: side(),
+ after: side(),
+ /** Divider position 0–1, or keys `[frame, value, ease?]`. Default: a sweep. */
+ split: z
+ .union([
+ z.number().min(0).max(1),
+ z
+ .array(
+ z.union([
+ z.tuple([z.number().int().min(0), z.number().min(0).max(1)]),
+ z.tuple([
+ z.number().int().min(0),
+ z.number().min(0).max(1),
+ z.string(),
+ ]),
+ ]),
+ )
+ .min(1),
+ ])
+ .optional(),
+ direction: z.enum(["horizontal", "vertical"]).default("horizontal"),
+ labels: z
+ .union([z.tuple([z.string(), z.string()]), z.literal(false)])
+ .default(["Before", "After"]),
+ handle: z.boolean().default(true),
+ fit: z.enum(["cover", "contain", "fill"]).default("cover"),
+ color: z.string().default("#ffffff"),
+ }),
+ defaults: { enter: false, exit: false },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ const s = theme.scale;
+ const W = ctx.requested.width ?? 1280 * s;
+ const H = ctx.requested.height ?? 720 * s;
+ const across = props.direction === "horizontal";
+ const L = across ? W : H;
+ const f = (n: number) => scaleFrames(n, fps);
+ const keys: KeyframeTuple[] =
+ typeof props.split === "number"
+ ? [[0, props.split]]
+ : ((props.split as KeyframeTuple[] | undefined) ?? [
+ [0, 0.5],
+ [f(20), 0.5],
+ [f(50), 0.15, "power2.inOut"],
+ [f(100), 0.85, "power2.inOut"],
+ [f(135), 0.5, "power2.inOut"],
+ ]);
+ const sorted = [...keys].sort(
+ (a, b) => (a[0] as number) - (b[0] as number),
+ );
+ const px = (k: KeyframeTuple[], by = 0): KeyframeTuple[] =>
+ k.map(([fr, v, e]) =>
+ e
+ ? [fr, round((v as number) * L + by), e]
+ : [fr, round((v as number) * L + by)],
+ ) as KeyframeTuple[];
+ const settled = sorted[sorted.length - 1]?.[0] as number;
+
+ const fill = (name: string, content: LayoutNode | LayoutNode[] | string) =>
+ typeof content === "string"
+ ? [
+ host.media(content, {
+ id: ctx.partId(`${name}-media`),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ fit: props.fit,
+ }),
+ ]
+ : Array.isArray(content)
+ ? content
+ : [content];
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const add = <T extends Animatable<LayoutNode>>(name: string, node: T) => {
+ parts[name] = node;
+ return node;
+ };
+ const after = add(
+ "after",
+ host.box({
+ id: ctx.partId("after"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ overflow: "hidden",
+ children: fill("after", props.after),
+ }),
+ );
+ const start = (sorted[0]?.[1] as number) * L;
+ const clip = add(
+ "before-clip",
+ host.box({
+ id: ctx.partId("before-clip"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: across ? start : W,
+ height: across ? H : start,
+ overflow: "hidden",
+ children: [
+ add(
+ "before",
+ host.box({
+ id: ctx.partId("before"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ children: fill("before", props.before),
+ }),
+ ),
+ ],
+ }),
+ );
+ if (sorted.length > 1)
+ clip.animate(
+ LayerAnimation.keys(across ? "width" : "height", px(sorted)),
+ );
+ const children: LayoutNode[] = [after, clip];
+
+ // ── Divider and handle ───────────────────────────────────────────
+ const thick = Math.max(2, 3 * s);
+ const line = add(
+ "divider",
+ host.box({
+ id: ctx.partId("divider"),
+ position: "absolute",
+ x: across ? start - thick / 2 : 0,
+ y: across ? 0 : start - thick / 2,
+ width: across ? thick : W,
+ height: across ? H : thick,
+ background: props.color,
+ }),
+ );
+ host.style(line, {
+ dropShadow: {
+ color: "#000000",
+ opacity: 0.35,
+ angle: 90,
+ distance: 0,
+ size: 12 * s,
+ },
+ });
+ if (sorted.length > 1)
+ line.animate(
+ LayerAnimation.keys(across ? "x" : "y", px(sorted, -thick / 2)),
+ );
+ children.push(line);
+ if (props.handle) {
+ const d = 52 * s;
+ const c = d / 2;
+ const a = d * 0.12;
+ const chevrons = across
+ ? `M${c - a * 1.2} ${c - a}L${c - a * 2.2} ${c}L${c - a * 1.2} ${c + a}M${c + a * 1.2} ${c - a}L${c + a * 2.2} ${c}L${c + a * 1.2} ${c + a}`
+ : `M${c - a} ${c - a * 1.2}L${c} ${c - a * 2.2}L${c + a} ${c - a * 1.2}M${c - a} ${c + a * 1.2}L${c} ${c + a * 2.2}L${c + a} ${c + a * 1.2}`;
+ const grip = add(
+ "handle",
+ host.box({
+ id: ctx.partId("handle"),
+ position: "absolute",
+ x: across ? start - c : W / 2 - c,
+ y: across ? H / 2 - c : start - c,
+ width: d,
+ height: d,
+ background: props.color,
+ borderRadius: c,
+ children: [
+ host.shape("path", {
+ id: ctx.partId("handle-arrows"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: d,
+ height: d,
+ d: chevrons,
+ fillType: "none",
+ strokeColor: "#111111",
+ strokeWidth: Math.max(1.5, 2.4 * s),
+ strokeLineCap: "round",
+ strokeLineJoin: "round",
+ }),
+ ],
+ }),
+ );
+ host.style(grip, {
+ dropShadow: {
+ color: "#000000",
+ opacity: 0.4,
+ angle: 90,
+ distance: 3 * s,
+ size: 14 * s,
+ },
+ });
+ if (sorted.length > 1)
+ grip.animate(LayerAnimation.keys(across ? "x" : "y", px(sorted, -c)));
+ children.push(grip);
+ }
+
+ // ── Labels: each fades as the divider covers it ─────────────────
+ if (props.labels) {
+ const fs = 22 * s;
+ const pad = 14 * s;
+ const margin = 24 * s;
+ const length = Math.max(1, settled);
+ const splitAt = (fr: number) => valueAt(sorted, fr) * L;
+ props.labels.forEach((text, i) => {
+ const m = host.measure(text, {
+ fontFamily: theme.font.body,
+ fontSize: fs,
+ fontWeight: 600,
+ });
+ const w = m.width + pad * 2;
+ const h = m.height + pad * 0.9;
+ const x = across ? (i === 0 ? margin : W - margin - w) : margin;
+ const y = across ? margin : i === 0 ? margin : H - margin - h;
+ // How far the label's far edge is inside its own side.
+ const visible = (fr: number) => {
+ const at = splitAt(fr);
+ const edge = across ? (i === 0 ? x + w : x) : i === 0 ? y + h : y;
+ const inside = i === 0 ? at - edge : edge - at;
+ return Math.max(0, Math.min(1, inside / (24 * s) + 1));
+ };
+ const pill = add(
+ `label-${i}`,
+ host.box({
+ id: ctx.partId(`label-${i}`),
+ position: "absolute",
+ x,
+ y,
+ width: w,
+ height: h,
+ background: "rgba(0,0,0,0.55)",
+ borderRadius: h / 2,
+ opacity: visible(0),
+ children: [
+ host.text(text, {
+ id: ctx.partId(`label-${i}-text`),
+ position: "absolute",
+ x: pad,
+ y: pad * 0.45,
+ fontFamily: theme.font.body,
+ fontSize: fs,
+ fontWeight: 600,
+ fill: "#ffffff",
+ }),
+ ],
+ }),
+ );
+ if (sorted.length > 1)
+ pill.animate(
+ LayerAnimation.keys(
+ "opacity",
+ bakeSamples(
+ Array.from({ length: length + 1 }, (_, fr) => visible(fr)),
+ 0,
+ { tolerance: 0.02 },
+ ),
+ ),
+ );
+ children.push(pill);
+ });
+ }
+
+ return {
+ children,
+ width: W,
+ height: H,
+ duration: null,
+ cues: { settled: [{ frame: settled }] } as BeforeAfterCues,
+ parts,
+ };
+ },
+});
+
+const round = (v: number) => Math.round(v * 1000) / 1000;
+
+/** The split keys' value at frame `f` (each segment eased by its end key). */
+function valueAt(keys: readonly KeyframeTuple[], f: number): number {
+ const first = keys[0] as KeyframeTuple;
+ if (f <= (first[0] as number)) return first[1] as number;
+ for (let i = 0; i < keys.length - 1; i++) {
+ const [f0, v0] = keys[i] as KeyframeTuple;
+ const [f1, v1, e] = keys[i + 1] as KeyframeTuple;
+ if (f >= (f0 as number) && f <= (f1 as number)) {
+ const t = evaluateEase(
+ e as string | undefined,
+ (f - (f0 as number)) / Math.max(1, (f1 as number) - (f0 as number)),
+ );
+ return (v0 as number) + ((v1 as number) - (v0 as number)) * t;
+ }
+ }
+ return keys[keys.length - 1]?.[1] as number;
+}
diff --git a/packages/components/src/before-after/meta.ts b/packages/components/src/before-after/meta.ts
new file mode 100644
index 00000000..085fbe86
--- /dev/null
+++ b/packages/components/src/before-after/meta.ts
@@ -0,0 +1,20 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "BeforeAfter",
+ summary:
+ "Two versions of one picture split by a moving divider with a grip and labels: a clip with and without an effect, a redesign, a cleanup.",
+ tags: ["before after", "comparison", "split", "wipe", "slider", "effects"],
+ parts: [
+ "after",
+ "before",
+ "before-clip",
+ "divider",
+ "handle",
+ "label-0",
+ "label-1",
+ ],
+ cues: ["settled"],
+ example: `BeforeAfter({ before: "assets/raw.mp4", after: graded })`,
+ since: "M8",
+});
diff --git a/packages/components/src/captions/index.test.ts b/packages/components/src/captions/index.test.ts
index 81996936..72f4166a 100644
--- a/packages/components/src/captions/index.test.ts
+++ b/packages/components/src/captions/index.test.ts
@@ -56,6 +56,31 @@ describe("Captions", () => {
);
});
+ it("pulses the active word with the voice level", () => {
+ // Level = frame / 100: easy to read back.
+ const level = Array.from({ length: 200 }, (_, f) => f / 100);
+ const pulse = { fps: 30, frames: 200, bands: [], level, beats: [] };
+ const c = make()({ id: "c", words, pulse, pulseAmount: 0.2 });
+ const animator = find(c, "c-phrase-0")?.animators?.find(
+ (a) => a.name === "pulse",
+ );
+ expect(animator?.props.scale).toBeCloseTo(1.2, 6);
+ const expr = animator?.selectors[0]?.expression ?? "";
+ const phraseStart = c.cues.phrases[0]?.frame ?? 0;
+ const word = c.cues.words[1] as { frame: number };
+ const local = word.frame - phraseStart + 2;
+ // The active word reads the level of its component frame; others are 0.
+ expect(
+ evaluateGlyphExpression(expr, { frame: local, wordIndex: 1 }),
+ ).toBeCloseTo((word.frame + 2) / 100, 6);
+ expect(evaluateGlyphExpression(expr, { frame: local, wordIndex: 3 })).toBe(
+ 0,
+ );
+ expect(() => make()({ words, pulse, fps: 24 })).toThrow(
+ /analysed at 30 fps/,
+ );
+ });
+
it("keeps every line inside the safe area at the auto-fitted size", () => {
const long =
"a fairly long caption sentence that keeps going on and on for several lines of text"
diff --git a/packages/components/src/captions/index.ts b/packages/components/src/captions/index.ts
index a08c755e..83177d42 100644
--- a/packages/components/src/captions/index.ts
+++ b/packages/components/src/captions/index.ts
@@ -14,6 +14,7 @@ import {
type TextNode,
} from "@framefields/compositions/program";
import { z } from "zod";
+import { audioLevelsSchema } from "../core/audio.js";
import { defineComponent } from "../core/contract.js";
import type { Rect } from "../core/draw.js";
import {
@@ -110,6 +111,10 @@ export const captions = /* @__PURE__ */ defineComponent({
/** SRT, WebVTT, or word-level JSON (`[{ word | text, start, end }]`). */
transcript: z.string().optional(),
style: z.enum(CAPTION_STYLES).default("karaoke"),
+ /** The voice's levels (`analyzeAudio`): the active word swells with it. Frame 0 = the component's first frame. */
+ pulse: z.union([audioLevelsSchema(), z.literal(false)]).default(false),
+ /** Scale added at full level. */
+ pulseAmount: z.number().min(0).default(0.12),
group: z
.object({
maxChars: z.number().int().positive().optional(),
@@ -227,6 +232,10 @@ export const captions = /* @__PURE__ */ defineComponent({
const anchor =
props.placement.anchor ?? (style === "bold" ? "center" : "bottom");
const frameOf = (seconds: number) => Math.round(seconds * fps);
+ if (props.pulse && Math.abs(props.pulse.fps - fps) > 1e-6)
+ throw new Error(
+ `Captions: \`pulse\` was analysed at ${props.pulse.fps} fps but the component runs at ${fps}. Analyse with { fps: ${fps} }.`,
+ );
const fast = themeFrames(theme, "fast", fps);
const children: LayoutNode[] = [];
const parts: Record<string, Animatable<LayoutNode>> = {};
@@ -448,6 +457,15 @@ export const captions = /* @__PURE__ */ defineComponent({
),
);
+ if (props.pulse) {
+ // The phrase's slice of the voice level, indexed by its local frame.
+ const level = props.pulse.level.slice(start, end);
+ animators.push(
+ glyphAnimator("pulse", pulseExpression(wStart, wEnd, level), {
+ scale: 1 + props.pulseAmount,
+ }),
+ );
+ }
if (animators.length > 0) node.animators = animators as never;
const text = host.text(layout.text, node);
// A heavy outline around the glyphs, never over them.
@@ -624,3 +642,14 @@ function stripUndefined<T extends object>(o: T): Partial<T> {
Object.entries(o).filter(([, v]) => v !== undefined),
) as Partial<T>;
}
+
+/** The active word's weight is the voice level on that frame (0 elsewhere). */
+function pulseExpression(
+ starts: readonly number[],
+ ends: readonly number[],
+ level: readonly number[],
+): string {
+ const list = (v: readonly number[]) =>
+ `[${v.map((x) => Math.round(x * 1000) / 1000).join(",")}]`;
+ return `((S,E,L)=>{const s=S[wordIndex];if(s===undefined||frame<s||frame>=E[wordIndex])return 0;return L[floor(frame)]??0;})(${list(starts)},${list(ends)},${list(level)})`;
+}
diff --git a/packages/components/src/card-stack/index.test.ts b/packages/components/src/card-stack/index.test.ts
new file mode 100644
index 00000000..11dcd6ba
--- /dev/null
+++ b/packages/components/src/card-stack/index.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { fakeHost } from "../test/fake-host.js";
+import { cardStack, SHRINK } from "./index.js";
+
+const make = () => bind(fakeHost(), cardStack);
+type Key = { frame: number; value: number };
+type Node = {
+ id?: string;
+ y?: number;
+ children?: Node[];
+ animation?: { tracks: Array<{ prop: string; keyframes: Key[] }> };
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+const valueAt = (n: Node | undefined, prop: string, f: number) => {
+ const keys =
+ n?.animation?.tracks.find((t) => t.prop === prop)?.keyframes ?? [];
+ return [...keys].reverse().find((k) => k.frame <= f)?.value ?? keys[0]?.value;
+};
+const cards = ["a", "b", "c", "d"].map((title) => ({ title }));
+
+describe("CardStack", () => {
+ it("rests with the front card last, unscaled, and the rest stepped back", () => {
+ const st = make()({ id: "s", cards, tilt: false });
+ const stage = (st.children as Node[])[0] as Node;
+ expect(stage.children?.at(-1)?.id).toBe("s-card-0");
+ expect(valueAt(find(st, "s-card-0"), "scale", 0)).toBe(1);
+ const y0 = valueAt(find(st, "s-card-0"), "y", 0) as number;
+ for (const k of [1, 2]) {
+ expect(valueAt(find(st, `s-card-${k}`), "scale", 0)).toBeCloseTo(
+ 1 - SHRINK * k,
+ 6,
+ );
+ expect(
+ y0 - (valueAt(find(st, `s-card-${k}`), "y", 0) as number),
+ ).toBeCloseTo(26 * k, 6);
+ }
+ // A card behind shows only the strip above the card in front.
+ const clip = valueAt(find(st, "s-card-1-clip"), "height", 0) as number;
+ expect(clip).toBeCloseTo(26 / (1 - SHRINK), 3);
+ });
+
+ it("returns to the starting order after a full cycle", () => {
+ const st = make()({ id: "s", cards, every: 40 });
+ const end = st.span.duration;
+ expect(Number.isFinite(end)).toBe(false); // open-ended
+ const settle = (st.cues.changes.at(-1)?.frame ?? 0) + 60;
+ for (const [c] of cards.entries())
+ for (const prop of ["y", "scale"])
+ expect(valueAt(find(st, `s-card-${c}`), prop, settle)).toBeCloseTo(
+ valueAt(find(st, `s-card-${c}`), prop, 0) as number,
+ 6,
+ );
+ expect(st.cues.changes.map((c) => c.index)).toEqual([1, 2, 3, 0]);
+ });
+
+ it("deals cards on top, in order", () => {
+ const st = make()({ id: "s", cards, mode: "deal", every: 30, tilt: false });
+ const stage = (st.children as Node[])[0] as Node;
+ expect(stage.children?.at(-1)?.id).toBe("s-card-3");
+ expect(valueAt(find(st, "s-card-3"), "opacity", 10)).toBe(0);
+ expect(valueAt(find(st, "s-card-3"), "scale", 200)).toBe(1);
+ expect(valueAt(find(st, "s-card-0"), "scale", 200)).toBeCloseTo(
+ 1 - SHRINK * 3,
+ 6,
+ );
+ expect(st.cues.changes.map((c) => c.index)).toEqual([1, 2, 3]);
+ });
+});
diff --git a/packages/components/src/card-stack/index.ts b/packages/components/src/card-stack/index.ts
new file mode 100644
index 00000000..f9c8f30b
--- /dev/null
+++ b/packages/components/src/card-stack/index.ts
@@ -0,0 +1,380 @@
+/**
+ * CardStack: cards in a depth stack that shuffle. In `cycle` the front card
+ * flies off and returns to the back while the rest step forward; in `deal`
+ * cards land one at a time on top of the pile.
+ *
+ * Draw order is fixed by the tree (the renderer has no animated z-order), so
+ * in `cycle` every card sits in a clip that shows only the strip peeking out
+ * above the card in front of it: whichever card is drawn later, a card
+ * behind can never paint over one in front. The leaving card flies sideways,
+ * clear of the stack, before it slots in at the back.
+ */
+import {
+ type KeyframeTuple,
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import { defineComponent } from "../core/contract.js";
+import type { Animatable } from "../core/host.js";
+import { themeFrames } from "../core/theme.js";
+
+export interface CardStackCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** A move starts; `index` is the card coming to the front. */
+ changes: ReadonlyArray<{ frame: number; index: number }>;
+}
+
+const SIMPLE = z
+ .object({
+ title: z.string(),
+ body: z.string().optional(),
+ image: z.string().optional(),
+ accent: z.string().optional(),
+ })
+ .strict();
+type SimpleCard = z.infer<typeof SIMPLE>;
+
+/** Slot geometry: card k behind the front is this much smaller and higher. */
+export const SHRINK = 0.06;
+
+export const cardStack = /* @__PURE__ */ defineComponent({
+ name: "CardStack",
+ props: () => ({
+ cards: z
+ .array(
+ z.union([
+ SIMPLE,
+ z.custom<LayoutNode>(
+ (v) => typeof v === "object" && v !== null && "kind" in v,
+ { message: "Expected a layer or { title, body?, image? }" },
+ ),
+ ]),
+ )
+ .min(2),
+ mode: z.enum(["cycle", "deal"]).default("cycle"),
+ /** Frames between moves. Default 1.5 seconds. */
+ every: z.number().int().positive().optional(),
+ cycles: z.number().int().positive().default(1),
+ /** Cards shown behind the front one. */
+ visible: z.number().int().min(0).max(8).default(3),
+ flyTo: z.enum(["up", "left", "right"]).default("left"),
+ cardWidth: z.number().positive().optional(),
+ cardHeight: z.number().positive().optional(),
+ tilt: z
+ .union([
+ z.literal(false),
+ z
+ .object({
+ rotateX: z.number().default(12),
+ rotateY: z.number().default(0),
+ })
+ .strict(),
+ ])
+ .default({ rotateX: 12, rotateY: 0 }),
+ }),
+ defaults: { enter: false, exit: false, hold: 30 },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ const s = theme.scale;
+ const cw = props.cardWidth ?? 640 * s;
+ const ch = props.cardHeight ?? 400 * s;
+ const n = props.cards.length;
+ const every = props.every ?? Math.round(fps * 1.5);
+ const base = themeFrames(theme, "base", fps);
+ const tr = Math.min(every - 1, Math.round(base * 1.8));
+ const ease = theme.motion.ease.move;
+ const step = 26 * s;
+ const depth = Math.min(props.visible, n - 1);
+ const W = ctx.requested.width ?? cw * 1.5;
+ const H = ctx.requested.height ?? ch + step * depth + ch * 0.4;
+ const front = { x: (W - cw) / 2, y: H - ch - ch * 0.2 };
+ const pose = (k: number) => {
+ const shown = Math.min(k, depth);
+ return {
+ y: front.y - shown * step,
+ scale: 1 - SHRINK * shown,
+ opacity: k <= depth ? 1 : 0,
+ dim: Math.min(0.6, 0.14 * shown),
+ // Local height of the strip that peeks above the card in front.
+ clip: k === 0 ? ch : step / (1 - SHRINK * shown),
+ };
+ };
+
+ // ── Timeline: each card's slot at each move ──────────────────────
+ const cycle = props.mode === "cycle";
+ const moves = cycle ? n * props.cycles : n - 1;
+ const changes = Array.from({ length: moves }, (_, m) => ({
+ frame: (m + 1) * every,
+ index: cycle ? (m + 1) % n : m + 1,
+ }));
+ const fly =
+ props.flyTo === "up"
+ ? { x: 0, y: -ch * 1.3, rotation: -4 }
+ : {
+ x: (props.flyTo === "left" ? -1 : 1) * cw * 1.1,
+ y: -ch * 0.15,
+ rotation: props.flyTo === "left" ? -10 : 10,
+ };
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const nodes: LayoutNode[] = [];
+ props.cards.forEach((card, c) => {
+ const tracks = {
+ x: [] as KeyframeTuple[],
+ y: [] as KeyframeTuple[],
+ scale: [] as KeyframeTuple[],
+ rotation: [] as KeyframeTuple[],
+ opacity: [] as KeyframeTuple[],
+ dim: [] as KeyframeTuple[],
+ clip: [] as KeyframeTuple[],
+ };
+ const put = (
+ f: number,
+ k: number,
+ e?: string,
+ also?: Partial<Record<keyof typeof tracks, number>>,
+ ) => {
+ const p = pose(k);
+ const v = {
+ x: front.x,
+ y: p.y,
+ scale: p.scale,
+ rotation: 0,
+ opacity: p.opacity,
+ dim: p.dim,
+ clip: p.clip,
+ ...also,
+ };
+ for (const key of Object.keys(tracks) as Array<keyof typeof tracks>)
+ tracks[key].push(e ? [f, round(v[key]), e] : [f, round(v[key])]);
+ };
+ if (cycle) {
+ put(0, c);
+ changes.forEach(({ frame: t }, m) => {
+ const k = (((c - m) % n) + n) % n;
+ if (k === 0) {
+ // Leaves: flies clear, then slots in at the back unseen and fades up.
+ const away = t + Math.round(tr * 0.55);
+ put(t, 0);
+ put(away, 0, "power2.in", {
+ x: front.x + fly.x,
+ y: front.y + fly.y,
+ rotation: fly.rotation,
+ opacity: 0,
+ });
+ put(away + 1, n - 1, "hold", { opacity: 0 });
+ put(t + tr, n - 1, "power2.out");
+ } else {
+ // Steps forward once the leaving card is half way out.
+ put(t + Math.round(tr * 0.3), k);
+ put(t + tr, k - 1, ease);
+ }
+ });
+ } else {
+ // Deal: card c lands on top at move c (card 0 is already down).
+ const landAt = c === 0 ? 0 : (changes[c - 1]?.frame as number);
+ if (c > 0) {
+ put(0, 0, undefined, {
+ y: front.y - ch * 1.4,
+ rotation: 9,
+ opacity: 0,
+ });
+ put(landAt, 0, "hold", {
+ y: front.y - ch * 1.4,
+ rotation: 9,
+ opacity: 0,
+ });
+ put(landAt + tr, 0, theme.motion.ease.enter);
+ } else put(0, 0);
+ // Pushed back one slot by every later card.
+ changes.slice(c).forEach(({ frame: t }, j) => {
+ put(t, j);
+ put(t + tr, j + 1, ease);
+ });
+ }
+
+ const content = isSimple(card) ? simpleCard(ctx, card, c, cw, ch) : card;
+ const dim = host.box({
+ id: ctx.partId(`card-${c}-dim`),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: cw,
+ height: ch,
+ background: "#000000",
+ borderRadius: theme.radius.lg,
+ opacity: 0,
+ });
+ dim.animate(LayerAnimation.keys("opacity", ascending(tracks.dim)));
+ const clip = host.box({
+ id: ctx.partId(`card-${c}-clip`),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: cw,
+ height: ch,
+ overflow: "hidden",
+ borderRadius: theme.radius.lg,
+ children: [content, dim],
+ });
+ if (cycle)
+ clip.animate(LayerAnimation.keys("height", ascending(tracks.clip)));
+ const node = host.box({
+ id: ctx.partId(`card-${c}`),
+ position: "absolute",
+ x: front.x,
+ y: pose(c).y,
+ width: cw,
+ height: ch,
+ anchorX: 0.5,
+ anchorY: 0,
+ children: [clip],
+ });
+ const anim = LayerAnimation.create()
+ .keys("y", ascending(tracks.y))
+ .keys("scale", ascending(tracks.scale))
+ .keys("opacity", ascending(tracks.opacity));
+ if (tracks.x.some((k) => k[1] !== front.x))
+ anim.keys("x", ascending(tracks.x));
+ if (tracks.rotation.some((k) => k[1] !== 0))
+ anim.keys("rotation", ascending(tracks.rotation));
+ node.animate(anim);
+ host.style(node, {
+ dropShadow: {
+ color: "#000000",
+ opacity: 0.35,
+ angle: 90,
+ distance: 12 * s,
+ size: 34 * s,
+ },
+ });
+ parts[`card-${c}`] = node;
+ parts[`card-${c}-clip`] = clip;
+ nodes.push(node);
+ });
+ // Front-most last: cycle starts with card 0 in front, deal ends with the last on top.
+ const ordered = cycle ? [...nodes].reverse() : nodes;
+ const children = props.tilt
+ ? [
+ host.box({
+ id: ctx.partId("tilt"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ perspective: 1600 * s,
+ rotateX: props.tilt.rotateX,
+ rotateY: props.tilt.rotateY,
+ children: ordered,
+ }),
+ ]
+ : ordered;
+ if (props.tilt) parts.tilt = children[0] as Animatable<LayoutNode>;
+
+ return {
+ children,
+ width: W,
+ height: H,
+ duration: (changes.at(-1)?.frame ?? 0) + tr,
+ openEnded: true,
+ cues: { changes } as CardStackCues,
+ parts,
+ };
+ },
+});
+
+const round = (v: number) => Math.round(v * 1000) / 1000;
+
+const isSimple = (card: unknown): card is SimpleCard =>
+ typeof card === "object" &&
+ card !== null &&
+ "title" in card &&
+ !("kind" in card);
+
+/** Later keys on a shared frame win; frames ascend. */
+function ascending(keys: KeyframeTuple[]): KeyframeTuple[] {
+ const byFrame = new Map<number, KeyframeTuple>();
+ for (const k of keys) byFrame.set(k[0] as number, k);
+ return [...byFrame.values()].sort(
+ (a, b) => (a[0] as number) - (b[0] as number),
+ );
+}
+
+/** A card drawn from the theme: optional image on top, title, body, accent bar. */
+function simpleCard(
+ ctx: Parameters<(typeof cardStack)["build"]>[0],
+ card: SimpleCard,
+ c: number,
+ w: number,
+ h: number,
+): LayoutNode {
+ const { host, theme } = ctx;
+ const s = theme.scale;
+ const pad = 36 * s;
+ const imageH = card.image ? h * 0.48 : 0;
+ const kids: LayoutNode[] = [];
+ if (card.image)
+ kids.push(
+ host.media(card.image, {
+ id: ctx.partId(`card-${c}-image`),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: w,
+ height: imageH,
+ fit: "cover",
+ }),
+ );
+ kids.push(
+ host.box({
+ id: ctx.partId(`card-${c}-accent`),
+ position: "absolute",
+ x: pad,
+ y: imageH + pad,
+ width: 44 * s,
+ height: 5 * s,
+ background: card.accent ?? theme.color.accent,
+ borderRadius: 3 * s,
+ }),
+ host.text(card.title, {
+ id: ctx.partId(`card-${c}-title`),
+ position: "absolute",
+ x: pad,
+ y: imageH + pad + 22 * s,
+ width: w - pad * 2,
+ fontFamily: theme.font.display,
+ fontSize: 40 * s,
+ fontWeight: 700,
+ fill: theme.color.ink,
+ }),
+ );
+ if (card.body)
+ kids.push(
+ host.text(card.body, {
+ id: ctx.partId(`card-${c}-body`),
+ position: "absolute",
+ x: pad,
+ y: imageH + pad + 80 * s,
+ width: w - pad * 2,
+ fontFamily: theme.font.body,
+ fontSize: 24 * s,
+ fill: theme.color.muted,
+ }),
+ );
+ return host.box({
+ id: ctx.partId(`card-${c}-face`),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: w,
+ height: h,
+ background: theme.color.raised,
+ borderRadius: theme.radius.lg,
+ borderColor: theme.color.line,
+ borderWidth: Math.max(1, s),
+ strokeAlign: "inside",
+ children: kids,
+ });
+}
diff --git a/packages/components/src/card-stack/meta.ts b/packages/components/src/card-stack/meta.ts
new file mode 100644
index 00000000..33e1b106
--- /dev/null
+++ b/packages/components/src/card-stack/meta.ts
@@ -0,0 +1,20 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "CardStack",
+ summary:
+ "Cards in a depth stack that shuffle: the front card flies off and returns to the back, or cards are dealt onto the pile.",
+ tags: [
+ "cards",
+ "stack",
+ "deck",
+ "carousel",
+ "testimonials",
+ "features",
+ "3d",
+ ],
+ parts: ["card-0", "card-0-clip", "tilt"],
+ cues: ["changes"],
+ example: `CardStack({ cards: [{ title: "Fast" }, { title: "Typed" }, { title: "Yours" }] })`,
+ since: "M8",
+});
diff --git a/packages/components/src/core/audio.test.ts b/packages/components/src/core/audio.test.ts
new file mode 100644
index 00000000..db710760
--- /dev/null
+++ b/packages/components/src/core/audio.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import {
+ analyzeChannels,
+ bandEdges,
+ resampleBands,
+ smoothRelease,
+} from "./audio.js";
+
+const SR = 44100;
+
+function tone(seconds: number, hz: number, amp = 0.5): Float32Array {
+ return Float32Array.from(
+ { length: Math.round(seconds * SR) },
+ (_, i) => amp * Math.sin((2 * Math.PI * hz * i) / SR),
+ );
+}
+
+/** 100 Hz kicks (fast decay) every `every` seconds, starting at `first`. */
+function kicks(seconds: number, first: number, every: number): Float32Array {
+ const out = new Float32Array(Math.round(seconds * SR));
+ for (let t = first; t < seconds; t += every) {
+ const s = Math.round(t * SR);
+ for (let i = 0; i < SR * 0.12 && s + i < out.length; i++)
+ out[s + i] =
+ 0.8 *
+ Math.exp(-i / (SR * 0.03)) *
+ Math.sin((2 * Math.PI * 100 * i) / SR);
+ }
+ return out;
+}
+
+describe("analyzeChannels", () => {
+ it("puts a tone in the band that holds its frequency", () => {
+ const levels = analyzeChannels([tone(2, 440)], SR, { fps: 30, bands: 32 });
+ const edges = bandEdges(32, 50, 12000);
+ const band = edges.findIndex(
+ (e, i) => e <= 440 && (edges[i + 1] ?? 0) > 440,
+ );
+ expect(levels.frames).toBe(60);
+ const mid = levels.bands.map((b) => b[30] ?? 0);
+ expect(mid[band]).toBeGreaterThan(0.9);
+ // Far bands stay dark.
+ expect(mid[0]).toBeLessThan(0.2);
+ expect(mid[31]).toBeLessThan(0.2);
+ expect(levels.level[30]).toBeGreaterThan(0.9);
+ });
+
+ it("finds kick onsets within one frame", () => {
+ const levels = analyzeChannels([kicks(4, 0.5, 0.5)], SR, { fps: 30 });
+ const expected = [0.5, 1, 1.5, 2, 2.5, 3, 3.5].map((t) => t * 30);
+ expect(levels.beats.length).toBe(expected.length);
+ levels.beats.forEach((b, i) => {
+ expect(Math.abs(b - (expected[i] as number))).toBeLessThanOrEqual(1);
+ });
+ });
+
+ it("is deterministic and silent where the audio is", () => {
+ const a = analyzeChannels([kicks(2, 0.5, 0.5)], SR);
+ const b = analyzeChannels([kicks(2, 0.5, 0.5)], SR);
+ expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+ const silent = analyzeChannels([new Float32Array(SR)], SR);
+ expect(Math.max(...silent.level)).toBe(0);
+ });
+});
+
+describe("band helpers", () => {
+ it("resamples bands by averaging", () => {
+ const out = resampleBands([[0], [1], [0.5], [0.5]], 2);
+ expect(out).toEqual([[0.5], [0.5]]);
+ expect(resampleBands([[0.2], [0.8]], 4).map((b) => b[0])).toEqual([
+ 0.2, 0.2, 0.8, 0.8,
+ ]);
+ });
+
+ it("releases slowly and attacks at once", () => {
+ const out = smoothRelease([0, 1, 0, 0], 1);
+ expect(out[1]).toBe(1);
+ expect(out[2]).toBe(0.5);
+ expect(out[3]).toBe(0.25);
+ });
+});
diff --git a/packages/components/src/core/audio.ts b/packages/components/src/core/audio.ts
new file mode 100644
index 00000000..458445a0
--- /dev/null
+++ b/packages/components/src/core/audio.ts
@@ -0,0 +1,256 @@
+/**
+ * Audio analysis, offline and deterministic: decoded samples in, plain
+ * per-frame data out (`AudioLevels`). Components bind it to props as
+ * signals or bake it into glyph tables, so the result seeks exactly and
+ * serialises as JSON.
+ */
+import { z } from "zod";
+
+/** A track's spectrum and loudness per frame, every value 0–1. */
+export interface AudioLevels {
+ fps: number;
+ /** Length in frames. */
+ frames: number;
+ /** `[band][frame]`, low → high frequencies. */
+ bands: number[][];
+ /** Loudness envelope, `[frame]`. */
+ level: number[];
+ /** Onset frames (kicks, plosives), from low-band flux. */
+ beats: number[];
+}
+
+export interface AnalyzeOptions {
+ /** Frame rate of the composition. Default 30. */
+ fps?: number;
+ /** Log-spaced bands. Default 32. */
+ bands?: number;
+ /** Lowest band edge, Hz. Default 50. */
+ minHz?: number;
+ /** Highest band edge, Hz. Default 12 000 (or Nyquist). */
+ maxHz?: number;
+}
+
+const FFT_SIZE = 2048;
+/** dB below a band's reference that reads as 0. */
+const BAND_RANGE = 42;
+/** A band's reference never sits more than this under the loudest band's. */
+const BAND_FLOOR = 30;
+const LEVEL_RANGE = 48;
+/** References never sit below this (dBFS): silence stays 0, not normalised up. */
+const SILENCE = -60;
+
+/** In-place radix-2 FFT over `re` / `im` (length a power of two). */
+function fft(re: Float64Array, im: Float64Array): void {
+ const n = re.length;
+ for (let i = 1, j = 0; i < n; i++) {
+ let bit = n >> 1;
+ for (; j & bit; bit >>= 1) j ^= bit;
+ j ^= bit;
+ if (i < j) {
+ [re[i], re[j]] = [re[j] as number, re[i] as number];
+ [im[i], im[j]] = [im[j] as number, im[i] as number];
+ }
+ }
+ for (let len = 2; len <= n; len <<= 1) {
+ const ang = (-2 * Math.PI) / len;
+ const wr = Math.cos(ang);
+ const wi = Math.sin(ang);
+ for (let i = 0; i < n; i += len) {
+ let cr = 1;
+ let ci = 0;
+ for (let k = 0; k < len / 2; k++) {
+ const a = i + k;
+ const b = a + len / 2;
+ const xr = (re[b] as number) * cr - (im[b] as number) * ci;
+ const xi = (re[b] as number) * ci + (im[b] as number) * cr;
+ re[b] = (re[a] as number) - xr;
+ im[b] = (im[a] as number) - xi;
+ re[a] = (re[a] as number) + xr;
+ im[a] = (im[a] as number) + xi;
+ const t = cr * wr - ci * wi;
+ ci = cr * wi + ci * wr;
+ cr = t;
+ }
+ }
+ }
+}
+
+function percentile(values: readonly number[], p: number): number {
+ if (values.length === 0) return 0;
+ const sorted = [...values].sort((a, b) => a - b);
+ return sorted[
+ Math.min(sorted.length - 1, Math.floor(p * sorted.length))
+ ] as number;
+}
+
+const db = (v: number) => 20 * Math.log10(v + 1e-9);
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+const round = (v: number) => Math.round(v * 1000) / 1000;
+
+/** Band edges in Hz, log-spaced. */
+export function bandEdges(
+ count: number,
+ minHz: number,
+ maxHz: number,
+): number[] {
+ return Array.from(
+ { length: count + 1 },
+ (_, i) => minHz * (maxHz / minHz) ** (i / count),
+ );
+}
+
+/**
+ * Analyse decoded audio: a Hann-windowed FFT per frame into log-spaced
+ * bands, each normalised to its own 98th percentile (floored 30 dB under the
+ * loudest band's, so a quiet band is not stretched into noise), an RMS level
+ * envelope, and onsets from low-band spectral flux.
+ */
+export function analyzeChannels(
+ channels: readonly Float32Array[],
+ sampleRate: number,
+ options: AnalyzeOptions = {},
+): AudioLevels {
+ const fps = options.fps ?? 30;
+ const count = options.bands ?? 32;
+ const minHz = options.minHz ?? 50;
+ const maxHz = Math.min(options.maxHz ?? 12000, sampleRate / 2);
+ const length = Math.max(0, ...channels.map((c) => c.length));
+ const mono = new Float32Array(length);
+ for (const c of channels)
+ for (let i = 0; i < c.length; i++)
+ mono[i] = (mono[i] as number) + (c[i] as number) / channels.length;
+
+ const frames = Math.ceil((length / sampleRate) * fps);
+ const hop = sampleRate / fps;
+ const hann = Float64Array.from(
+ { length: FFT_SIZE },
+ (_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / (FFT_SIZE - 1)),
+ );
+ const edges = bandEdges(count, minHz, maxHz);
+ const binHz = sampleRate / FFT_SIZE;
+ const ranges = edges.slice(0, -1).map((lo, b) => {
+ const from = Math.max(1, Math.floor(lo / binHz));
+ const to = Math.max(from + 1, Math.ceil((edges[b + 1] as number) / binHz));
+ return [from, Math.min(FFT_SIZE / 2, to)] as const;
+ });
+ const lowBands = edges.filter((e) => e < 150).length;
+
+ const raw = Array.from({ length: count }, () => new Array<number>(frames));
+ const rms = new Array<number>(frames);
+ const flux = new Array<number>(frames).fill(0);
+ let previousLow: number[] | null = null;
+ const re = new Float64Array(FFT_SIZE);
+ const im = new Float64Array(FFT_SIZE);
+ for (let f = 0; f < frames; f++) {
+ const centre = Math.round((f + 0.5) * hop);
+ const from = centre - FFT_SIZE / 2;
+ for (let i = 0; i < FFT_SIZE; i++) {
+ const s = mono[from + i];
+ re[i] = (s ?? 0) * (hann[i] as number);
+ im[i] = 0;
+ }
+ fft(re, im);
+ const low: number[] = [];
+ ranges.forEach(([a, b], band) => {
+ let sum = 0;
+ for (let k = a; k < b; k++)
+ sum += Math.hypot(re[k] as number, im[k] as number);
+ const mag = (sum / (b - a)) * (4 / FFT_SIZE);
+ (raw[band] as number[])[f] = mag;
+ if (band < Math.max(1, lowBands)) low.push(mag);
+ });
+ if (previousLow)
+ flux[f] = low.reduce(
+ (acc, v, i) =>
+ acc + Math.max(0, v - ((previousLow as number[])[i] ?? 0)),
+ 0,
+ );
+ previousLow = low;
+ // Loudness of this frame's own stretch of samples.
+ const s0 = Math.round(f * hop);
+ const s1 = Math.min(length, Math.round((f + 1) * hop));
+ let e = 0;
+ for (let i = s0; i < s1; i++) e += (mono[i] as number) ** 2;
+ rms[f] = Math.sqrt(e / Math.max(1, s1 - s0));
+ }
+
+ const refs = raw.map((band) => percentile(band.map(db), 0.98));
+ const loudest = Math.max(...refs);
+ const bands = raw.map((band, b) => {
+ const ref = Math.max(refs[b] as number, loudest - BAND_FLOOR, SILENCE - 20);
+ return band.map((v) => round(clamp01(1 - (ref - db(v)) / BAND_RANGE)));
+ });
+ const levelRef = Math.max(SILENCE, percentile(rms.map(db), 0.98));
+ const level = rms.map((v) =>
+ round(clamp01(1 - (levelRef - db(v)) / LEVEL_RANGE)),
+ );
+ return { fps, frames, bands, level, beats: pickOnsets(flux, fps) };
+}
+
+/** Local maxima of `flux` well above its neighbourhood, at least 0.15 s apart. */
+function pickOnsets(flux: readonly number[], fps: number): number[] {
+ const reach = Math.max(2, Math.round(fps * 0.5));
+ const gap = Math.max(1, Math.round(fps * 0.15));
+ const peak = Math.max(0, ...flux);
+ const beats: number[] = [];
+ for (let f = 1; f < flux.length; f++) {
+ const v = flux[f] as number;
+ if (v <= peak * 0.08) continue;
+ if (v < (flux[f - 1] as number) || v < (flux[f + 1] ?? 0)) continue;
+ const near = flux.slice(Math.max(0, f - reach), f + reach + 1);
+ const mean = near.reduce((a, b) => a + b, 0) / near.length;
+ const sd = Math.sqrt(
+ near.reduce((a, b) => a + (b - mean) ** 2, 0) / near.length,
+ );
+ if (v < mean + 1.5 * sd) continue;
+ const last = beats[beats.length - 1];
+ if (last !== undefined && f - last < gap) continue;
+ beats.push(f);
+ }
+ return beats;
+}
+
+/** Average adjacent bands down (or repeat them up) to `count` bands. */
+export function resampleBands(
+ bands: readonly (readonly number[])[],
+ count: number,
+): number[][] {
+ const n = bands.length;
+ if (n === 0) return [];
+ const frames = bands[0]?.length ?? 0;
+ return Array.from({ length: count }, (_, i) => {
+ const a = Math.floor((i * n) / count);
+ const b = Math.max(a + 1, Math.floor(((i + 1) * n) / count));
+ return Array.from({ length: frames }, (_, f) => {
+ let sum = 0;
+ for (let k = a; k < b; k++)
+ sum += (bands[k] as readonly number[])[f] ?? 0;
+ return round(sum / (b - a));
+ });
+ });
+}
+
+/** Each value falls no faster than `release` frames from its peak (attack is instant). */
+export function smoothRelease(
+ values: readonly number[],
+ release: number,
+): number[] {
+ if (release <= 0) return [...values];
+ const k = 1 / (release + 1);
+ let prev = 0;
+ return values.map((v) => {
+ prev = v >= prev ? v : prev + (v - prev) * k;
+ return round(prev);
+ });
+}
+
+/** The schema for `AudioLevels` props (Waveform, Captions `pulse`). */
+export function audioLevelsSchema(): z.ZodType<AudioLevels> {
+ return z.object({
+ fps: z.number().positive(),
+ frames: z.number().int().min(0),
+ bands: z.array(z.array(z.number())),
+ level: z.array(z.number()),
+ beats: z.array(z.number().int()),
+ });
+}
diff --git a/packages/components/src/core/contract.ts b/packages/components/src/core/contract.ts
index f434bbf3..c7887d75 100644
--- a/packages/components/src/core/contract.ts
+++ b/packages/components/src/core/contract.ts
@@ -181,8 +181,18 @@ export interface BuildContext {
partId(part: string): string;
/** A seeded stream for `key`, stable across unrelated prop changes. */
rng(key: string | number): Rng;
- /** The size the user asked for (base `width` / `height`), if any. */
- requested: { width?: number; height?: number };
+ /**
+ * What the user asked for: size, window, `at`, and the root's own `x` /
+ * `y` (3D nodes ignore their 2D parents' offsets, so they add these).
+ */
+ requested: {
+ width?: number;
+ height?: number;
+ duration?: number;
+ at: number;
+ x: number;
+ y: number;
+ };
/** Frames the finished state holds (base `hold`, or the component's default). */
hold: number;
}
@@ -341,7 +351,14 @@ function assemble<S extends z.ZodRawShape, C extends Cues, E extends object>(
id,
partId: (part) => `${id}-${part}`,
rng: (key) => hashRng(seed, key),
- requested: { width: props.width, height: props.height },
+ requested: {
+ width: props.width,
+ height: props.height,
+ duration: props.duration,
+ at: props.at ?? 0,
+ x: props.x ?? 0,
+ y: props.y ?? 0,
+ },
hold,
};
diff --git a/packages/components/src/core/host.ts b/packages/components/src/core/host.ts
index d372555f..3a88346f 100644
--- a/packages/components/src/core/host.ts
+++ b/packages/components/src/core/host.ts
@@ -78,7 +78,7 @@ export interface Host {
fonts(): readonly string[];
/** A default id: stable per run (a counter per prefix), like `Layer.*` ids. */
autoId(prefix: string): string;
- /** A video or image layer, by file extension. */
+ /** A video, image or SVG layer, by file extension. */
media(source: string, options: MediaOptions): Animatable<LayoutNode>;
/** Attach layer styles (shadow, glow, stroke) to `node`; returns it. */
style<T extends Animatable<LayoutNode>>(node: T, config: LayerStyleConfig): T;
@@ -100,6 +100,50 @@ export interface Host {
cutout(source: string, options: CutoutOptions): Animatable<LayoutNode>;
/** A GPU particle system layer. */
particles(options: ParticleOptions): Animatable<LayoutNode>;
+ /**
+ * A per-frame signal from values (framefields' `Signal.fromArray`), for
+ * `LayerAnimation.signal`. Signals read the composition's frame: value
+ * `k` drives composition frame `k`.
+ */
+ signal(values: readonly number[], fps: number): object;
+ /**
+ * An animated film-grain layer to put over other layers: neutral grey
+ * carrying framefields' `FilmGrain`, soft-light blended. (Effects only
+ * attach to media layers, so grain can't go on a box.)
+ */
+ grain(options: GrainOptions): Animatable<LayoutNode>;
+ /** Solid extruded 3D text (framefields' `Layer3D.extrudedText`), centred on x, y. */
+ extrudedText(options: ExtrudedTextOptions): Animatable<LayoutNode>;
+}
+
+export interface GrainOptions {
+ id?: string;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ /** 0–100, the engine's scale. */
+ strength: number;
+ size?: number;
+}
+
+export interface ExtrudedTextOptions {
+ id?: string;
+ text: string;
+ /** Centre of the text. */
+ x: number;
+ y: number;
+ depth: number;
+ fontFamily?: string;
+ fontSize: number;
+ fontWeight?: number;
+ fill?: string;
+ bevelColor?: string;
+ material?: "lit" | "glass";
+ metallic?: number;
+ roughness?: number;
+ shininess?: number;
+ opacity?: number;
}
/** A GPU particle system (framefields' `Layer.particles`), as plain data. */
diff --git a/packages/components/src/core/path.ts b/packages/components/src/core/path.ts
index 2453ce0e..ecc0801e 100644
--- a/packages/components/src/core/path.ts
+++ b/packages/components/src/core/path.ts
@@ -114,8 +114,9 @@ export function toPathData(points: readonly Vec2[], closed = false): string {
}
/**
- * Scale and offset absolute SVG path data (M, L, H, V, C, S, Q, T, Z):
- * `x' = x × scale + dx`. Used to size glyphs designed on a small grid.
+ * Scale and offset SVG path data: `x' = x × scale + dx`. Absolute commands
+ * move by the offset; relative ones (and arc radii) only scale. Used to
+ * size glyphs designed on a small grid, and logo marks in their viewBox.
*/
export function transformPathData(
d: string,
@@ -124,32 +125,37 @@ export function transformPathData(
dy = 0,
): string {
const r = (n: number) => Math.round(n * 1000) / 1000;
- const tokens = d.match(/[a-zA-Z]|-?\d*\.?\d+(?:e[-+]?\d+)?/g) ?? [];
+ const tokens =
+ d.match(/[a-zA-Z]|[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi) ?? [];
const out: string[] = [];
let command = "";
let axis = 0;
for (const token of tokens) {
- if (/[a-zA-Z]/.test(token)) {
- if (token !== token.toUpperCase() && token.toLowerCase() !== "z") {
- throw new Error(
- `transformPathData: relative command "${token}" is not supported`,
- );
- }
- if (token.toUpperCase() === "A") {
- throw new Error("transformPathData: arcs are not supported");
- }
- command = token.toUpperCase();
+ if (/^[a-zA-Z]$/.test(token)) {
+ command = token;
axis = 0;
out.push(command);
continue;
}
const n = Number(token);
- if (command === "H") out.push(String(r(n * scale + dx)));
- else if (command === "V") out.push(String(r(n * scale + dy)));
+ const upper = command.toUpperCase();
+ const relative = command !== upper;
+ if (upper === "A") {
+ // rx ry rotation large-arc sweep x y: flags and rotation stay.
+ const k = axis % 7;
+ axis++;
+ if (k === 2 || k === 3 || k === 4) out.push(String(n));
+ else if (k < 2 || relative) out.push(String(r(n * scale)));
+ else out.push(String(r(n * scale + (k === 5 ? dx : dy))));
+ continue;
+ }
+ if (relative) out.push(String(r(n * scale)));
+ else if (upper === "H") out.push(String(r(n * scale + dx)));
+ else if (upper === "V") out.push(String(r(n * scale + dy)));
else {
out.push(String(r(n * scale + (axis % 2 === 0 ? dx : dy))));
axis++;
}
}
- return out.join(" ").replace(/ ?([A-Z]) ?/g, "$1");
+ return out.join(" ").replace(/ ?([a-zA-Z]) ?/g, "$1");
}
diff --git a/packages/components/src/core/targets.ts b/packages/components/src/core/targets.ts
index 43980688..2f5fbb8a 100644
--- a/packages/components/src/core/targets.ts
+++ b/packages/components/src/core/targets.ts
@@ -193,10 +193,22 @@ function nodeRect(node: TargetNode): Rect | null {
return { x, y, width, height };
}
-function textRects(
+/** A text target's string, measured glyphs and range, and where the node sits. */
+export interface TextLayout {
+ content: string;
+ metrics: ReturnType<MeasureFn>;
+ options: MeasureOptions;
+ range: [number, number];
+ /** The node's x / y: add to measured glyph positions. */
+ x: number;
+ y: number;
+}
+
+/** Measure a text target the way the renderer lays it out. */
+export function textLayout(
target: Extract<Target, { text: TargetNode }>,
ctx: TargetContext,
-): Rect[] {
+): TextLayout {
const node = target.text;
const content =
typeof node.text === "string"
@@ -240,11 +252,25 @@ function textRects(
`Text target: "${String(target.match)}" not found in "${content}".`,
);
}
- const metrics = ctx.measure(content, options);
- const rects = rangeRects(metrics, range[0], range[1], options);
+ return {
+ content,
+ metrics: ctx.measure(content, options),
+ options,
+ range: [range[0], range[1]],
+ x,
+ y,
+ };
+}
+
+function textRects(
+ target: Extract<Target, { text: TargetNode }>,
+ ctx: TargetContext,
+): Rect[] {
+ const t = textLayout(target, ctx);
+ const rects = rangeRects(t.metrics, t.range[0], t.range[1], t.options);
if (rects.length === 0)
throw new Error("Text target range covers no glyphs.");
- return rects.map((r) => ({ ...r, x: r.x + x, y: r.y + y }));
+ return rects.map((r) => ({ ...r, x: r.x + t.x, y: r.y + t.y }));
}
/** Text node alignment (start / center / end, or left / right) as measure reads it. */
diff --git a/packages/components/src/device-frame/index.test.ts b/packages/components/src/device-frame/index.test.ts
new file mode 100644
index 00000000..0415e81c
--- /dev/null
+++ b/packages/components/src/device-frame/index.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { fakeHost } from "../test/fake-host.js";
+import { deviceFrame } from "./index.js";
+
+const make = () => bind(fakeHost(), deviceFrame);
+type Node = {
+ id?: string;
+ x?: number;
+ y?: number;
+ width?: number;
+ height?: number;
+ scale?: number;
+ rotateY?: number;
+ children?: Node[];
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+
+describe("DeviceFrame", () => {
+ for (const [device, orientation] of [
+ ["phone", "portrait"],
+ ["phone", "landscape"],
+ ["tablet", "portrait"],
+ ["laptop", "portrait"],
+ ] as const)
+ it(`${device} ${orientation}: at() spans the screen`, () => {
+ const d = make()({ id: "d", device, orientation, x: 100, y: 50 });
+ const r = d.screenRect;
+ const pts =
+ device === "phone"
+ ? orientation === "portrait"
+ ? [393, 852]
+ : [852, 393]
+ : device === "tablet"
+ ? [820, 1180]
+ : [1440, 900];
+ expect(d.at(0, 0)).toEqual([r.x, r.y]);
+ const [x, y] = d.at(pts[0] as number, pts[1] as number);
+ expect(x).toBeCloseTo(r.x + r.width, 6);
+ expect(y).toBeCloseTo(r.y + r.height, 6);
+ // The screen sits inside the device.
+ expect(r.x).toBeGreaterThan(100);
+ expect(r.x + r.width).toBeLessThan(100 + (d.width as number));
+ // Content is laid out in points and scaled to the screen.
+ const content = find(d, "d-content");
+ expect(content?.width).toBe(pts[0]);
+ expect((content?.width ?? 0) * (content?.scale ?? 0)).toBeCloseTo(
+ r.width,
+ 6,
+ );
+ });
+
+ it("sizes from height (handhelds) or width (laptops)", () => {
+ expect(make()({ device: "phone", height: 800 }).height).toBe(800);
+ expect(make()({ device: "laptop", width: 1000 }).width).toBe(1000);
+ });
+
+ it("fills, tilts and draws the island and status bar", () => {
+ const d = make()({ id: "d", tilt: { rotateY: -20 } });
+ d.fill({ kind: "box", id: "ui" } as never);
+ expect(find(d, "d-content")?.children?.map((c) => c.id)).toEqual(["ui"]);
+ expect(find(d, "d-tilt")?.rotateY).toBe(-20);
+ expect(find(d, "d-island")).toBeDefined();
+ expect(find(d, "d-status-time")).toBeDefined();
+ const bare = make()({ id: "b", device: "laptop" });
+ expect(find(bare, "b-island")).toBeUndefined();
+ expect(find(bare, "b-status")).toBeUndefined();
+ expect(find(bare, "b-base")).toBeDefined();
+ });
+});
diff --git a/packages/components/src/device-frame/index.ts b/packages/components/src/device-frame/index.ts
new file mode 100644
index 00000000..8d42e3f9
--- /dev/null
+++ b/packages/components/src/device-frame/index.ts
@@ -0,0 +1,516 @@
+/**
+ * DeviceFrame: a phone, tablet or laptop around a screen. Content is
+ * authored in the device's own points (a phone screen is 393 × 852) and
+ * scaled into the screen, so a mock UI made at device size drops in
+ * unchanged; `at(x, y)` maps those points to the parent's coordinates.
+ */
+import type { BoxNode, LayoutNode } from "@framefields/compositions/program";
+import { z } from "zod";
+import { defineComponent } from "../core/contract.js";
+import type { Animatable, Host } from "../core/host.js";
+import type { Vec2 } from "../core/path.js";
+
+export const DEVICES = ["phone", "tablet", "laptop"] as const;
+export type Device = (typeof DEVICES)[number];
+
+export interface DeviceFrameApi {
+ /** The screen in the parent's coordinates. */
+ readonly screenRect: { x: number; y: number; width: number; height: number };
+ /** Screen points → the parent's coordinates (ignores `tilt`). */
+ at(x: number, y: number): Vec2;
+ /** Add layers (in screen points) to the screen. */
+ fill(...nodes: LayoutNode[]): DeviceFrameApi;
+}
+
+export interface DeviceFrameCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+}
+
+const POINTS: Record<Device, [number, number]> = {
+ phone: [393, 852],
+ tablet: [820, 1180],
+ laptop: [1440, 900],
+};
+
+const FINISHES = {
+ graphite: { body: "#2c2e33", edge: "#55585f", button: "#3a3d43" },
+ silver: { body: "#d8dade", edge: "#f2f3f5", button: "#c4c7cd" },
+ midnight: { body: "#1b2130", edge: "#424a5c", button: "#262d3d" },
+} as const;
+
+export const deviceFrame = /* @__PURE__ */ defineComponent({
+ name: "DeviceFrame",
+ props: () => ({
+ device: z.enum(DEVICES).default("phone"),
+ orientation: z.enum(["portrait", "landscape"]).default("portrait"),
+ /** Layers in screen points, or a media path that fills the screen. */
+ content: z
+ .custom<LayoutNode | LayoutNode[] | string>(
+ (v) =>
+ typeof v === "string" ||
+ Array.isArray(v) ||
+ (typeof v === "object" && v !== null),
+ { message: "Expected layers or a media path" },
+ )
+ .optional(),
+ fit: z.enum(["cover", "contain", "fill"]).default("cover"),
+ /** Screen size content is authored in. */
+ points: z.tuple([z.number().positive(), z.number().positive()]).optional(),
+ finish: z
+ .union([z.enum(["graphite", "silver", "midnight"]), z.string()])
+ .default("graphite"),
+ island: z.boolean().default(true),
+ statusBar: z
+ .union([
+ z.boolean(),
+ z
+ .object({
+ time: z.string().optional(),
+ /** Dark icons, for light screens. */
+ dark: z.boolean().optional(),
+ })
+ .strict(),
+ ])
+ .default(true),
+ screen: z.string().default("#000000"),
+ tilt: z
+ .union([
+ z.literal(false),
+ z
+ .object({
+ rotateX: z.number().default(10),
+ rotateY: z.number().default(-18),
+ })
+ .strict(),
+ ])
+ .default(false),
+ elevation: z.number().int().min(0).max(3).default(2),
+ }),
+ defaults: { enter: "rise" },
+ build(ctx, props) {
+ const { host, theme } = ctx;
+ const s = theme.scale;
+ const device = props.device;
+ const laptop = device === "laptop";
+ const landscape = !laptop && props.orientation === "landscape";
+ const native = POINTS[device];
+ const [pw, ph] =
+ props.points ?? (landscape ? [native[1], native[0]] : native);
+
+ // ── Proportions, in points ──────────────────────────────────────
+ const short = Math.min(pw, ph);
+ const bezel =
+ device === "phone"
+ ? short * 0.045
+ : device === "tablet"
+ ? short * 0.04
+ : pw * 0.018;
+ const rim = device === "laptop" ? pw * 0.004 : short * 0.012;
+ const top = laptop ? bezel * 1.6 : bezel;
+ const bodyWp = pw + bezel * 2 + rim * 2;
+ const bodyHp = ph + top + bezel + rim * 2;
+ const baseWp = laptop ? bodyWp * 1.14 : 0;
+ const baseHp = laptop ? pw * 0.032 : 0;
+ const buttonP = laptop ? 0 : short * 0.011;
+ const totalWp = laptop ? baseWp : bodyWp + buttonP * 2;
+ const totalHp = bodyHp + baseHp;
+
+ // Points → px: from the size asked for (height for handhelds, width for laptops).
+ const k = laptop
+ ? (ctx.requested.width ?? 1280 * s) / totalWp
+ : (ctx.requested.height ?? 860 * s) / totalHp;
+ const W = ctx.requested.width ?? totalWp * k;
+ const H = ctx.requested.height ?? totalHp * k;
+ const px = (v: number) => v * k;
+ const bodyX = (W - bodyWp * k) / 2;
+ const bodyY = 0;
+ const screenX = bodyX + px(rim + bezel);
+ const screenY = bodyY + px(rim + top);
+ const screenW = px(pw);
+ const screenH = px(ph);
+
+ const named = FINISHES[props.finish as keyof typeof FINISHES];
+ const finish = named ?? {
+ body: props.finish,
+ edge: props.finish,
+ button: props.finish,
+ };
+ const bodyR = laptop
+ ? px(pw * 0.022)
+ : px(short * (device === "phone" ? 0.14 : 0.075));
+ const screenR = laptop
+ ? px(pw * 0.006)
+ : Math.max(0, bodyR - px(rim + bezel));
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const kids: LayoutNode[] = [];
+ const box = (name: string, o: Partial<BoxNode>) => {
+ const node = host.box({
+ id: ctx.partId(name),
+ position: "absolute",
+ ...o,
+ });
+ parts[name] = node;
+ return node;
+ };
+
+ // ── Shadow, buttons, body ───────────────────────────────────────
+ if (props.elevation > 0) {
+ const e = props.elevation;
+ const plate = box("shadow", {
+ x: bodyX,
+ y: bodyY,
+ width: px(bodyWp),
+ height: px(bodyHp + baseHp),
+ background: finish.body,
+ borderRadius: bodyR,
+ });
+ host.style(plate, {
+ dropShadow: {
+ color: "#000000",
+ opacity: [0, 0.3, 0.45, 0.6][e],
+ angle: 90,
+ distance: [0, 10, 26, 46][e] * s,
+ size: [0, 26, 56, 90][e] * s,
+ spread: 0,
+ },
+ });
+ kids.push(plate);
+ }
+ if (!laptop) {
+ // Side buttons stand just proud of the body.
+ const bw = px(buttonP * 1.6);
+ const along = landscape ? px(bodyWp) : px(bodyHp);
+ const spec: Array<[side: -1 | 1, from: number, len: number]> =
+ device === "phone"
+ ? [
+ [-1, 0.17, 0.04],
+ [-1, 0.24, 0.07],
+ [-1, 0.33, 0.07],
+ [1, 0.26, 0.11],
+ ]
+ : [
+ [1, 0.08, 0.05],
+ [1, 0.15, 0.05],
+ ];
+ const buttons = spec.map(([side, from, len], i) =>
+ landscape
+ ? host.box({
+ id: ctx.partId(`button-${i}`),
+ position: "absolute",
+ x: bodyX + from * along,
+ y: side < 0 ? bodyY - bw / 2 : bodyY + px(bodyHp) - bw / 2,
+ width: len * along,
+ height: bw,
+ background: finish.button,
+ borderRadius: bw / 2,
+ })
+ : host.box({
+ id: ctx.partId(`button-${i}`),
+ position: "absolute",
+ x: side < 0 ? bodyX - bw / 2 : bodyX + px(bodyWp) - bw / 2,
+ y: bodyY + from * along,
+ width: bw,
+ height: len * along,
+ background: finish.button,
+ borderRadius: bw / 2,
+ }),
+ );
+ const group = box("buttons", {
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ children: buttons,
+ });
+ kids.push(group);
+ }
+ kids.push(
+ box("body", {
+ x: bodyX,
+ y: bodyY,
+ width: px(bodyWp),
+ height: px(bodyHp),
+ background: finish.body,
+ borderRadius: bodyR,
+ borderColor: finish.edge,
+ borderWidth: Math.max(1, px(rim * 0.35)),
+ strokeAlign: "inside",
+ }),
+ box("bezel", {
+ x: bodyX + px(rim),
+ y: bodyY + px(rim),
+ width: px(bodyWp - rim * 2),
+ height: px(bodyHp - rim * 2),
+ background: "#050506",
+ borderRadius: Math.max(0, bodyR - px(rim)),
+ }),
+ );
+
+ // ── Screen: content in points, scaled in ────────────────────────
+ const content: Animatable<LayoutNode> & { children?: LayoutNode[] } = box(
+ "content",
+ {
+ x: 0,
+ y: 0,
+ width: pw,
+ height: ph,
+ scale: k,
+ anchorX: 0,
+ anchorY: 0,
+ children:
+ props.content === undefined
+ ? []
+ : typeof props.content === "string"
+ ? [
+ host.media(props.content, {
+ id: ctx.partId("media"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: pw,
+ height: ph,
+ fit: props.fit,
+ }),
+ ]
+ : Array.isArray(props.content)
+ ? props.content
+ : [props.content],
+ },
+ );
+ const overlay: LayoutNode[] = [];
+ const phone = device === "phone";
+ if (phone && props.island && !landscape)
+ overlay.push(
+ box("island", {
+ x: (pw - 124) / 2,
+ y: 11,
+ width: 124,
+ height: 36,
+ background: "#000000",
+ borderRadius: 18,
+ }),
+ );
+ if (props.statusBar !== false && !laptop) {
+ const opts = typeof props.statusBar === "object" ? props.statusBar : {};
+ overlay.push(
+ statusBar(ctx, {
+ width: pw,
+ height: phone && !landscape ? 54 : 30,
+ time: opts.time ?? "9:41",
+ color: opts.dark ? "#000000" : "#ffffff",
+ compact: !phone || landscape,
+ font: theme.font.body,
+ }),
+ );
+ }
+ const status = overlay.length
+ ? box("overlay", {
+ x: 0,
+ y: 0,
+ width: pw,
+ height: ph,
+ scale: k,
+ anchorX: 0,
+ anchorY: 0,
+ children: overlay,
+ })
+ : undefined;
+ kids.push(
+ box("screen", {
+ x: screenX,
+ y: screenY,
+ width: screenW,
+ height: screenH,
+ background: props.screen,
+ borderRadius: screenR,
+ overflow: "hidden",
+ children: status ? [content, status] : [content],
+ }),
+ );
+ if (laptop) {
+ kids.push(
+ box("base", {
+ x: (W - px(baseWp)) / 2,
+ y: bodyY + px(bodyHp) - px(baseHp * 0.1),
+ width: px(baseWp),
+ height: px(baseHp),
+ background: finish.button,
+ borderRadius: px(baseHp * 0.5),
+ borderColor: finish.edge,
+ borderWidth: Math.max(1, px(rim * 0.3)),
+ strokeAlign: "inside",
+ children: [
+ host.box({
+ id: ctx.partId("groove"),
+ position: "absolute",
+ x: px(baseWp * 0.42),
+ y: 0,
+ width: px(baseWp * 0.16),
+ height: px(baseHp * 0.32),
+ background: finish.body,
+ borderRadius: px(baseHp * 0.16),
+ }),
+ ],
+ }),
+ );
+ }
+
+ const tilted = props.tilt !== false;
+ const stack = tilted
+ ? [
+ box("tilt", {
+ x: 0,
+ y: 0,
+ width: W,
+ height: H,
+ perspective: 1800 * s,
+ rotateX: (props.tilt as { rotateX: number }).rotateX,
+ rotateY: (props.tilt as { rotateY: number }).rotateY,
+ children: kids,
+ }),
+ ]
+ : kids;
+ return {
+ children: stack,
+ width: W,
+ height: H,
+ duration: null,
+ cues: {} as DeviceFrameCues,
+ parts,
+ api: (placement): DeviceFrameApi => {
+ const rect = {
+ x: placement.x + screenX,
+ y: placement.y + screenY,
+ width: screenW,
+ height: screenH,
+ };
+ const api: DeviceFrameApi = {
+ screenRect: rect,
+ at: (x, y) => [rect.x + x * k, rect.y + y * k],
+ fill: (...nodes) => {
+ content.children = [...(content.children ?? []), ...nodes];
+ return api;
+ },
+ };
+ return api;
+ },
+ };
+ },
+});
+
+/** Time, signal, Wi-Fi and battery, drawn from boxes and paths (no icon font). */
+function statusBar(
+ ctx: { host: Host; partId(p: string): string },
+ o: {
+ width: number;
+ height: number;
+ time: string;
+ color: string;
+ compact: boolean;
+ font: string;
+ },
+): LayoutNode {
+ const { host } = ctx;
+ const mid = o.height / 2 + (o.compact ? 0 : 3);
+ const kids: LayoutNode[] = [
+ host.text(o.time, {
+ id: ctx.partId("status-time"),
+ position: "absolute",
+ x: o.compact ? 20 : 48,
+ y: mid - 10,
+ fontFamily: o.font,
+ fontSize: 16,
+ fontWeight: 600,
+ fill: o.color,
+ }),
+ ];
+ // From the right edge: battery, Wi-Fi, signal.
+ const right = o.width - (o.compact ? 20 : 30);
+ const bx = right - 27;
+ kids.push(
+ host.box({
+ id: ctx.partId("status-battery"),
+ position: "absolute",
+ x: bx,
+ y: mid - 6.5,
+ width: 25,
+ height: 13,
+ borderRadius: 4,
+ borderColor: o.color,
+ borderWidth: 1.2,
+ opacity: 0.95,
+ children: [
+ host.box({
+ id: ctx.partId("status-charge"),
+ position: "absolute",
+ x: 2,
+ y: 2,
+ width: 18,
+ height: 9,
+ background: o.color,
+ borderRadius: 2,
+ }),
+ ],
+ }),
+ host.box({
+ id: ctx.partId("status-nub"),
+ position: "absolute",
+ x: bx + 26,
+ y: mid - 2.5,
+ width: 1.6,
+ height: 5,
+ background: o.color,
+ borderRadius: 1,
+ opacity: 0.6,
+ }),
+ );
+ // Wi-Fi: three arcs and a dot, as one stroked path.
+ const wx = bx - 13;
+ const wy = mid + 5;
+ // A quarter arc as one quadratic: the control point sits r·√2 out.
+ const arc = (r: number) => {
+ const c = r * Math.SQRT1_2;
+ const f = (v: number) => v.toFixed(2);
+ return `M${f(wx - c)} ${f(wy - c)}Q${f(wx)} ${f(wy - r * Math.SQRT2)} ${f(wx + c)} ${f(wy - c)}`;
+ };
+ kids.push(
+ host.shape("path", {
+ id: ctx.partId("status-wifi"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: o.width,
+ height: o.height,
+ d: `${arc(11)}${arc(7)}${arc(3)}`,
+ fillType: "none",
+ strokeColor: o.color,
+ strokeWidth: 2,
+ strokeLineCap: "round",
+ }),
+ );
+ // Signal: four rising bars.
+ const sx = wx - 40;
+ for (let i = 0; i < 4; i++)
+ kids.push(
+ host.box({
+ id: ctx.partId(`status-signal-${i}`),
+ position: "absolute",
+ x: sx + i * 5,
+ y: mid + 5 - (4 + i * 2.6),
+ width: 3.4,
+ height: 4 + i * 2.6,
+ background: o.color,
+ borderRadius: 1,
+ }),
+ );
+ return host.box({
+ id: ctx.partId("status"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: o.width,
+ height: o.height,
+ children: kids,
+ });
+}
diff --git a/packages/components/src/device-frame/meta.ts b/packages/components/src/device-frame/meta.ts
new file mode 100644
index 00000000..bf597740
--- /dev/null
+++ b/packages/components/src/device-frame/meta.ts
@@ -0,0 +1,32 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "DeviceFrame",
+ summary:
+ "A phone, tablet or laptop around a screen; content is authored in device points and `at(x, y)` maps them for pointers and touches.",
+ tags: [
+ "device",
+ "phone",
+ "mobile",
+ "tablet",
+ "laptop",
+ "mockup",
+ "screen",
+ "app",
+ ],
+ parts: [
+ "body",
+ "bezel",
+ "screen",
+ "content",
+ "island",
+ "status",
+ "buttons",
+ "base",
+ "shadow",
+ "tilt",
+ ],
+ cues: [],
+ example: `DeviceFrame({ device: "phone", content: "assets/app.mp4" })`,
+ since: "M8",
+});
diff --git a/packages/components/src/ids.test.ts b/packages/components/src/ids.test.ts
index 1456b2c4..48782001 100644
--- a/packages/components/src/ids.test.ts
+++ b/packages/components/src/ids.test.ts
@@ -1,23 +1,32 @@
import { describe, expect, it } from "vitest";
import { annotate } from "./annotate/index.js";
import { appFrame } from "./app-frame/index.js";
+import { backdrop } from "./backdrop/index.js";
+import { beforeAfter } from "./before-after/index.js";
import { callout } from "./callout/index.js";
import { captions } from "./captions/index.js";
+import { cardStack } from "./card-stack/index.js";
import { chatThread } from "./chat-thread/index.js";
import { codeBlock } from "./code-block/index.js";
import { confetti } from "./confetti/index.js";
import { bind } from "./core/contract.js";
import { counter } from "./counter/index.js";
+import { deviceFrame } from "./device-frame/index.js";
import { focusZoom } from "./focus-zoom/index.js";
+import { logoReveal } from "./logo-reveal/index.js";
import { lowerThird } from "./lower-third/index.js";
import { meter } from "./meter/index.js";
import { mousePointer } from "./mouse-pointer/index.js";
+import { selection } from "./selection/index.js";
import { spotlight } from "./spotlight/index.js";
import { terminal } from "./terminal/index.js";
import { fakeHost } from "./test/fake-host.js";
import { textReveal } from "./text-reveal/index.js";
import { titleCard } from "./title-card/index.js";
import { toasts } from "./toasts/index.js";
+import { touchPoint } from "./touch-point/index.js";
+import { waveform } from "./waveform/index.js";
+import { wordCycle } from "./word-cycle/index.js";
/**
* The renderer keys layout and motion by node id: two nodes with one id
@@ -275,6 +284,133 @@ const cases: Array<[string, () => unknown]> = [
],
}),
],
+ ...(["slide", "pop", "draw", "rise"] as const).map(
+ (style) =>
+ [
+ `LogoReveal ${style}`,
+ () =>
+ bind(
+ fakeHost(),
+ logoReveal,
+ )({
+ mark: { d: "M0 0L1 1Z", viewBox: [1, 1] },
+ name: "ab",
+ tagline: "t",
+ style,
+ }),
+ ] as [string, () => unknown],
+ ),
+ ...(["mesh", "grid", "dots", "solid"] as const).map(
+ (kind) =>
+ [`Backdrop ${kind}`, () => bind(fakeHost(), backdrop)({ kind })] as [
+ string,
+ () => unknown,
+ ],
+ ),
+ ...(["bars", "mirror", "dots", "radial"] as const).map(
+ (kind) =>
+ [
+ `Waveform ${kind}`,
+ () =>
+ bind(
+ fakeHost(),
+ waveform,
+ )({
+ audio: {
+ fps: 30,
+ frames: 2,
+ bands: [
+ [0, 1],
+ [1, 0],
+ ],
+ level: [0, 1],
+ beats: [],
+ },
+ kind,
+ bars: 4,
+ }),
+ ] as [string, () => unknown],
+ ),
+ ...(["roll", "fade", "slide", "type"] as const).map(
+ (transition) =>
+ [
+ `WordCycle ${transition}`,
+ () =>
+ bind(
+ fakeHost(),
+ wordCycle,
+ )({
+ text: "a {} b",
+ words: ["x", "yy", "zzz"],
+ transition,
+ slot: "pill",
+ }),
+ ] as [string, () => unknown],
+ ),
+ ...(["phone", "tablet", "laptop"] as const).map(
+ (device) =>
+ [
+ `DeviceFrame ${device}`,
+ () =>
+ bind(fakeHost(), deviceFrame)({ device, content: "a.mp4", tilt: {} }),
+ ] as [string, () => unknown],
+ ),
+ [
+ "TouchPoint",
+ () =>
+ bind(
+ fakeHost(),
+ touchPoint,
+ )({
+ touches: [
+ { to: [10, 10], tap: 2 },
+ { to: [20, 20], press: 20 },
+ { to: [30, 30], swipe: [30, 300] },
+ ],
+ }),
+ ],
+ [
+ "BeforeAfter",
+ () => bind(fakeHost(), beforeAfter)({ before: "a.mp4", after: "b.mp4" }),
+ ],
+ [
+ "Selection text",
+ () =>
+ bind(
+ fakeHost(),
+ selection,
+ )({ target: { text }, drag: { frame: 0, end: 10 } }),
+ ],
+ [
+ "Selection marquee",
+ () =>
+ bind(
+ fakeHost(),
+ selection,
+ )({
+ kind: "marquee",
+ drag: { frame: 0, end: 10 },
+ items: [[5, 5], { x: 0, y: 0, width: 9, height: 9 }],
+ }),
+ ],
+ ...(["cycle", "deal"] as const).map(
+ (mode) =>
+ [
+ `CardStack ${mode}`,
+ () =>
+ bind(
+ fakeHost(),
+ cardStack,
+ )({
+ cards: [
+ { title: "a", body: "b", image: "i.png" },
+ { title: "c" },
+ { title: "d" },
+ ],
+ mode,
+ }),
+ ] as [string, () => unknown],
+ ),
];
describe("node ids", () => {
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index 7715d21e..f72e2a9d 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -16,6 +16,18 @@ export {
type AppFrameKind,
appFrame,
} from "./app-frame/index.js";
+export {
+ BACKDROP_KINDS,
+ type BackdropCues,
+ type BackdropKind,
+ backdrop,
+ cosineKeys,
+ slideKeys,
+} from "./backdrop/index.js";
+export {
+ type BeforeAfterCues,
+ beforeAfter,
+} from "./before-after/index.js";
export {
CALLOUT_SIDES,
type CalloutCues,
@@ -29,6 +41,10 @@ export {
captions,
type Word,
} from "./captions/index.js";
+export {
+ type CardStackCues,
+ cardStack,
+} from "./card-stack/index.js";
export { type ChatThreadCues, chatThread } from "./chat-thread/index.js";
export {
CODE_LANGS,
@@ -40,6 +56,15 @@ export {
} from "./code-block/index.js";
export { tokenize } from "./code-block/tokenize.js";
export { type ConfettiCues, confetti } from "./confetti/index.js";
+export {
+ type AnalyzeOptions,
+ type AudioLevels,
+ analyzeChannels,
+ audioLevelsSchema,
+ bandEdges,
+ resampleBands,
+ smoothRelease,
+} from "./core/audio.js";
export {
type BakedKey,
type BakeOptions,
@@ -100,6 +125,8 @@ export type {
Animatable,
AnimatableMethods,
CutoutOptions,
+ ExtrudedTextOptions,
+ GrainOptions,
Host,
LayerStyleConfig,
MediaOptions,
@@ -135,7 +162,10 @@ export {
resolveTarget,
type Target,
type TargetContext,
+ type TargetNode,
+ type TextLayout,
targetPoint,
+ textLayout,
} from "./core/targets.js";
export {
findRange,
@@ -177,12 +207,27 @@ export {
type CounterFormat,
counter,
} from "./counter/index.js";
+export {
+ DEVICES,
+ type Device,
+ type DeviceFrameApi,
+ type DeviceFrameCues,
+ deviceFrame,
+} from "./device-frame/index.js";
export {
type FocusZoomApi,
type FocusZoomCues,
type Followable,
focusZoom,
} from "./focus-zoom/index.js";
+export {
+ LOGO_LAYOUTS,
+ LOGO_STYLES,
+ type LogoLayout,
+ type LogoRevealCues,
+ type LogoStyle,
+ logoReveal,
+} from "./logo-reveal/index.js";
export {
LOWER_THIRD_LAYOUTS,
type LowerThirdCues,
@@ -203,6 +248,11 @@ export {
mousePointer,
type Waypoint,
} from "./mouse-pointer/index.js";
+export {
+ type SelectionCues,
+ type SelectionPointer,
+ selection,
+} from "./selection/index.js";
export { type SpotlightCues, spotlight } from "./spotlight/index.js";
export {
type TerminalCues,
@@ -233,3 +283,23 @@ export {
type ToastsCues,
toasts,
} from "./toasts/index.js";
+export {
+ type PlannedTouch,
+ planTouches,
+ type TouchPointCues,
+ touchPoint,
+} from "./touch-point/index.js";
+export {
+ WAVEFORM_KINDS,
+ type WaveformCues,
+ type WaveformKind,
+ waveform,
+} from "./waveform/index.js";
+export {
+ WORD_SLOTS,
+ WORD_TRANSITIONS,
+ type WordCycleCues,
+ type WordSlot,
+ type WordTransition,
+ wordCycle,
+} from "./word-cycle/index.js";
diff --git a/packages/components/src/logo-reveal/index.test.ts b/packages/components/src/logo-reveal/index.test.ts
new file mode 100644
index 00000000..e1d60a52
--- /dev/null
+++ b/packages/components/src/logo-reveal/index.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { transformPathData } from "../core/path.js";
+import { fakeHost } from "../test/fake-host.js";
+import { logoReveal } from "./index.js";
+
+const make = () => bind(fakeHost(), logoReveal);
+type Node = {
+ id?: string;
+ kind?: string;
+ x?: number;
+ y?: number;
+ width?: number;
+ height?: number;
+ startFrame?: number;
+ d?: string;
+ children?: Node[];
+ animation?: {
+ tracks: Array<{
+ prop: string;
+ keyframes: Array<{ frame: number; value: unknown }>;
+ }>;
+ };
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+const last = (n: Node | undefined, prop: string) => {
+ const keys = n?.animation?.tracks.find((t) => t.prop === prop)?.keyframes;
+ return keys?.[keys.length - 1]?.value as number | undefined;
+};
+const MARK = {
+ d: "M0 0 L10 0 L10 10 Z",
+ viewBox: [10, 10] as [number, number],
+};
+
+describe("LogoReveal", () => {
+ it("centres the lockup in its box, in both layouts", () => {
+ // Fake measure: 0.5 em per glyph → "abcd" at 120 px is 240 wide.
+ const row = make()({ id: "l", mark: MARK, name: "abcd" });
+ const gap = 120 * 0.32;
+ expect(row.width).toBeCloseTo(150 + gap + 240, 5);
+ expect(find(row, "l-name-clip")?.x).toBeCloseTo(150 + gap, 5);
+ // The mark settles at the left edge, vertically centred.
+ const mark = find(row, "l-mark");
+ expect(last(mark, "x")).toBe(0);
+ expect(mark?.y).toBeCloseTo(((row.height as number) - 150) / 2, 5);
+
+ const stack = make()({
+ id: "s",
+ mark: MARK,
+ name: "abcd",
+ layout: "stack",
+ });
+ expect(stack.width).toBe(240);
+ expect(last(find(stack, "s-mark"), "y")).toBe(0);
+ expect(find(stack, "s-mark")?.x).toBeCloseTo((240 - 150) / 2, 5);
+ expect(find(stack, "s-name-clip")?.x).toBeCloseTo(0, 5);
+ });
+
+ it("slide: the name waits for the glide, behind the mark", () => {
+ const l = make()({ id: "l", mark: MARK, name: "abcd" });
+ const name = find(l, "l-name");
+ const glideStart = find(l, "l-mark")
+ ?.animation?.tracks.find((t) => t.prop === "x")
+ ?.keyframes.find((k) => k.frame > 0)?.frame;
+ expect(name?.startFrame).toBe(glideStart);
+ // Starts left of its clip (hidden), lands at 0.
+ expect(name?.x).toBeLessThan(0);
+ expect(last(name, "x")).toBe(0);
+ // The mark is drawn last, over the name.
+ const stage = (l.children as Node[])[0] as Node;
+ expect(stage.children?.[stage.children.length - 1]?.id).toBe("l-mark");
+ });
+
+ it("orders its cues and stays after the glint", () => {
+ const l = make()({ mark: MARK, name: "abcd", tagline: "tag" });
+ const hit = l.cues.hit[0]?.frame ?? 0;
+ const revealed = l.cues.revealed[0]?.frame ?? 0;
+ const glint = l.cues.glint[0]?.frame ?? 0;
+ expect(hit).toBeLessThanOrEqual(revealed);
+ expect(glint).toBeGreaterThan(revealed);
+ expect(l.span.end).toBe(Number.POSITIVE_INFINITY);
+ expect(make()({ name: "abcd", glint: false }).cues.glint).toEqual([]);
+ });
+
+ it("draws a path mark in, settling where pop does", () => {
+ const draw = make()({ id: "a", mark: MARK, name: "ab", style: "draw" });
+ const pop = make()({ id: "a", mark: MARK, name: "ab", style: "pop" });
+ const outline = find(draw, "a-mark-outline");
+ expect(last(outline, "trimEnd")).toBe(1);
+ expect(last(outline, "opacity")).toBe(0);
+ expect(find(draw, "a-mark-fill")?.d).toBe(find(pop, "a-mark-fill")?.d);
+ expect(find(draw, "a-mark")?.x).toBe(find(pop, "a-mark")?.x);
+ // An image mark can't draw on: it pops.
+ const image = make()({ id: "i", mark: "logo.png", style: "draw" });
+ expect(find(image, "i-mark-outline")).toBeUndefined();
+ expect(find(image, "i-mark-image")).toBeDefined();
+ });
+
+ it("extrudes the name when given depth", () => {
+ const l = make()({ id: "l", name: "abcd", depth: 40, material: "chrome" });
+ const name = find(l, "l-name") as Node & {
+ depth?: number;
+ metallic?: number;
+ };
+ expect(name.kind).toBe("model");
+ expect(name.depth).toBe(40);
+ expect(name.metallic).toBe(1);
+ expect(last(name, "rotateY")).toBe(0);
+ expect(l.cues.glint).toEqual([]);
+ });
+
+ it("needs a mark or a name", () => {
+ expect(() => make()({})).toThrow(/mark.*name/);
+ });
+});
+
+describe("transformPathData", () => {
+ it("scales relative commands and arcs without offsetting them", () => {
+ expect(transformPathData("M1 1 l2 0 h1 v-1 z", 2, 10, 20)).toBe(
+ "M12 22l4 0h2v-2z",
+ );
+ expect(
+ transformPathData("M0 0 A5 5 30 0 1 10 10 a1 2 0 1 0 3 4", 2, 1, 1),
+ ).toBe("M1 1A10 10 30 0 1 21 21a2 4 0 1 0 6 8");
+ });
+});
diff --git a/packages/components/src/logo-reveal/index.ts b/packages/components/src/logo-reveal/index.ts
new file mode 100644
index 00000000..9a8da4b4
--- /dev/null
+++ b/packages/components/src/logo-reveal/index.ts
@@ -0,0 +1,482 @@
+/**
+ * LogoReveal: the end-card lockup. A mark (image, SVG or path data) and a
+ * wordmark arrive as one move, then a light sweeps across the name. Path
+ * marks can draw themselves on; names can be extruded in 3D.
+ */
+import {
+ type KeyframeTuple,
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import { springKeys } from "../core/bake.js";
+import { defineComponent } from "../core/contract.js";
+import { drawOnKeys } from "../core/draw.js";
+import {
+ glyphAnimator,
+ rendererChars,
+ scheduleExpression,
+} from "../core/glyphs.js";
+import type { Animatable } from "../core/host.js";
+import { transformPathData } from "../core/path.js";
+import { themeFrames } from "../core/theme.js";
+
+export const LOGO_STYLES = ["slide", "pop", "draw", "rise"] as const;
+export type LogoStyle = (typeof LOGO_STYLES)[number];
+export const LOGO_LAYOUTS = ["row", "stack"] as const;
+export type LogoLayout = (typeof LOGO_LAYOUTS)[number];
+
+export interface LogoRevealCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** The mark lands. */
+ hit: ReadonlyArray<{ frame: number }>;
+ /** The lockup is complete. */
+ revealed: ReadonlyArray<{ frame: number }>;
+ /** The glint starts (empty without `glint`). */
+ glint: ReadonlyArray<{ frame: number }>;
+}
+
+const POP = { stiffness: 260, damping: 14 };
+const SWING = { stiffness: 120, damping: 14 };
+
+export const logoReveal = /* @__PURE__ */ defineComponent({
+ name: "LogoReveal",
+ props: () => ({
+ /** An image / SVG file, or path data in its own viewBox. */
+ mark: z
+ .union([
+ z.string().min(1),
+ z
+ .object({
+ d: z.string().min(1),
+ viewBox: z.tuple([z.number().positive(), z.number().positive()]),
+ color: z.string().optional(),
+ })
+ .strict(),
+ ])
+ .optional(),
+ name: z.string().min(1).optional(),
+ tagline: z.string().min(1).optional(),
+ layout: z.enum(LOGO_LAYOUTS).default("row"),
+ style: z.enum(LOGO_STYLES).default("slide"),
+ glint: z.boolean().default(true),
+ /** Above 0, the name is extruded text this deep (px). */
+ depth: z.number().min(0).default(0),
+ material: z.enum(["lit", "chrome", "glass"]).default("lit"),
+ markSize: z.number().positive().optional(),
+ nameSize: z.number().positive().optional(),
+ gap: z.number().min(0).optional(),
+ color: z.string().optional(),
+ accent: z.string().optional(),
+ fontFamily: z.string().optional(),
+ fontWeight: z.number().int().min(100).max(900).default(800),
+ }),
+ defaults: { enter: false, exit: false, hold: 60 },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ if (!props.mark && !props.name)
+ throw new Error("LogoReveal: give a `mark`, a `name`, or both.");
+ const s = theme.scale;
+ const base = themeFrames(theme, "base", fps);
+ const ease = theme.motion.ease.move;
+ const accent = props.accent ?? theme.color.accent;
+ const ink = props.color ?? theme.color.ink;
+ const fontFamily = props.fontFamily ?? theme.font.display;
+ const ns = props.nameSize ?? 120 * s;
+ const m = props.mark ? (props.markSize ?? 150 * s) : 0;
+ const gap = props.mark && props.name ? (props.gap ?? ns * 0.32) : 0;
+ const stack = props.layout === "stack";
+ const solid = props.depth > 0;
+ const pathMark = typeof props.mark === "object" ? props.mark : null;
+ // Image marks can't draw on: they pop.
+ const style: LogoStyle =
+ props.style === "draw" && !pathMark ? "pop" : props.style;
+
+ // ── Geometry ─────────────────────────────────────────────────────
+ const nameM = props.name
+ ? host.measure(props.name, {
+ fontFamily,
+ fontSize: ns,
+ fontWeight: props.fontWeight,
+ })
+ : { width: 0, height: 0 };
+ const tagSize = Math.max(18 * s, ns * 0.26);
+ const tagM = props.tagline
+ ? host.measure(props.tagline, {
+ fontFamily: theme.font.body,
+ fontSize: tagSize,
+ })
+ : { width: 0, height: 0 };
+ const tagGap = props.tagline ? ns * 0.12 : 0;
+ const textW = Math.max(nameM.width, tagM.width);
+ const textH = nameM.height + tagGap + tagM.height;
+ const W = stack ? Math.max(m, textW) : m + gap + textW;
+ const H = stack ? m + gap + textH : Math.max(m, textH);
+ const markAt = stack ? { x: (W - m) / 2, y: 0 } : { x: 0, y: (H - m) / 2 };
+ const nameAt = stack
+ ? { x: (W - nameM.width) / 2, y: m + gap }
+ : { x: m + gap, y: (H - textH) / 2 };
+ const tagAt = stack
+ ? { x: (W - tagM.width) / 2, y: nameAt.y + nameM.height + tagGap }
+ : { x: nameAt.x, y: nameAt.y + nameM.height + tagGap };
+
+ // ── Timeline ─────────────────────────────────────────────────────
+ const drawFrames = Math.round(base * 2.2);
+ const glide = Math.round(base * 1.5);
+ const glideAt = style === "slide" ? Math.round(base * 1.1) : 0;
+ const hit = !props.mark
+ ? 0
+ : style === "draw"
+ ? drawFrames
+ : style === "rise"
+ ? base
+ : Math.round(base * 0.75);
+ const nameStart = !props.mark
+ ? 0
+ : style === "slide"
+ ? glideAt
+ : style === "draw"
+ ? Math.round(drawFrames * 0.6)
+ : style === "rise"
+ ? Math.round(base * 0.35)
+ : Math.round(base * 0.55);
+ const chars = props.name?.length ?? 0;
+ const stagger = Math.max(1, Math.round(fps / 30) * 1.5);
+ const letters = style === "pop" || style === "draw";
+ const nameDone = !props.name
+ ? hit
+ : solid
+ ? nameStart + base * 2
+ : style === "slide"
+ ? glideAt + glide
+ : letters
+ ? nameStart + Math.round(stagger * Math.max(0, chars - 1)) + base
+ : nameStart + base;
+ const tagStart = Math.max(nameStart, nameDone - Math.round(base * 0.4));
+ const revealed = Math.max(
+ hit,
+ nameDone,
+ props.tagline ? tagStart + base : 0,
+ );
+ const glintAt = revealed + Math.round(base * 0.3);
+ const glintFrames = Math.round(base * 1.8);
+ const glints = props.glint && props.name && !solid;
+ const end = glints ? glintAt + glintFrames : revealed;
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const children: LayoutNode[] = [];
+ // Drawn last: the name wipes out from behind it.
+ let markNode: LayoutNode | undefined;
+
+ // ── Mark ─────────────────────────────────────────────────────────
+ if (props.mark) {
+ const markColor = pathMark?.color ?? accent;
+ const markKids: LayoutNode[] = [];
+ if (pathMark) {
+ const [vw, vh] = pathMark.viewBox;
+ const k = m / Math.max(vw, vh);
+ const d = transformPathData(
+ pathMark.d,
+ k,
+ (m - vw * k) / 2,
+ (m - vh * k) / 2,
+ );
+ const fill = host.shape("path", {
+ id: ctx.partId("mark-fill"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: m,
+ height: m,
+ d,
+ fillType: "solid",
+ fillColor: markColor,
+ });
+ parts["mark-fill"] = fill;
+ if (style === "draw") {
+ const outline = host.shape("path", {
+ id: ctx.partId("mark-outline"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: m,
+ height: m,
+ d,
+ fillType: "none",
+ strokeColor: markColor,
+ strokeWidth: Math.max(2, 3 * s),
+ strokeLineCap: "round",
+ strokeLineJoin: "round",
+ });
+ outline.animate(
+ LayerAnimation.create()
+ .keys("trimEnd", drawOnKeys(0, drawFrames, "power2.inOut"))
+ .keys("opacity", [
+ [drawFrames, 1],
+ [drawFrames + base, 0, "power2.out"],
+ ]),
+ );
+ fill.animate(
+ LayerAnimation.keys("opacity", [
+ [Math.round(drawFrames * 0.7), 0],
+ [drawFrames, 1, "power2.out"],
+ ]),
+ );
+ markKids.push(fill, outline);
+ parts["mark-outline"] = outline;
+ } else markKids.push(fill);
+ } else {
+ const image = host.media(props.mark as string, {
+ id: ctx.partId("mark-image"),
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: m,
+ height: m,
+ fit: "contain",
+ });
+ markKids.push(image);
+ parts["mark-image"] = image;
+ }
+ const centred = stack
+ ? { x: markAt.x, y: (H - m) / 2 }
+ : { x: (W - m) / 2, y: markAt.y };
+ const slide = style === "slide" && !!props.name;
+ const mark = host.box({
+ id: ctx.partId("mark"),
+ position: "absolute",
+ x: slide ? centred.x : markAt.x,
+ y: slide ? centred.y : markAt.y,
+ width: m,
+ height: m,
+ children: markKids,
+ });
+ const anim = LayerAnimation.create();
+ const scale: KeyframeTuple[] = [];
+ if (style === "slide" || style === "pop")
+ scale.push(...(springKeys(0, 0, 1, fps, POP) as KeyframeTuple[]));
+ if (glints) {
+ // A small bump as the light passes.
+ if (scale.length === 0) scale.push([0, 1]);
+ scale.push(
+ [glintAt, 1],
+ [glintAt + Math.round(base * 0.4), 1.06, "power2.out"],
+ [glintAt + Math.round(base * 1.2), 1, "power2.inOut"],
+ );
+ }
+ if (scale.length > 0) anim.keys("scale", scale);
+ if (slide) {
+ anim.keys(stack ? "y" : "x", [
+ [glideAt, stack ? centred.y : centred.x],
+ [glideAt + glide, stack ? markAt.y : markAt.x, ease],
+ ]);
+ }
+ if (style === "rise") {
+ anim.keys("opacity", [
+ [0, 0],
+ [Math.round(base * 0.6), 1, "power2.out"],
+ ]);
+ }
+ mark.animate(anim);
+ parts.mark = mark;
+ if (style === "rise") {
+ // Rises through its own clip.
+ mark.y = m;
+ mark.x = 0;
+ mark.animate(
+ LayerAnimation.keys("y", [
+ [0, m],
+ [base, 0, theme.motion.ease.enter],
+ ]),
+ );
+ const clip = host.box({
+ id: ctx.partId("mark-clip"),
+ position: "absolute",
+ x: markAt.x,
+ y: markAt.y,
+ width: m,
+ height: m,
+ overflow: "hidden",
+ children: [mark],
+ });
+ parts["mark-clip"] = clip;
+ markNode = clip;
+ } else markNode = mark;
+ }
+
+ // ── Name ─────────────────────────────────────────────────────────
+ if (props.name) {
+ if (solid) {
+ const chrome = props.material === "chrome";
+ const name = host.extrudedText({
+ id: ctx.partId("name"),
+ text: props.name,
+ // 3D nodes ignore 2D parents' offsets: place it in the root's parent.
+ x: ctx.requested.x + nameAt.x + nameM.width / 2,
+ y: ctx.requested.y + nameAt.y + nameM.height / 2,
+ depth: props.depth,
+ fontFamily,
+ fontSize: ns,
+ fontWeight: props.fontWeight,
+ fill: chrome ? "#e8ecf2" : ink,
+ bevelColor: chrome ? "#9aa3ad" : accent,
+ material: props.material === "glass" ? "glass" : "lit",
+ ...(chrome && { metallic: 1, roughness: 0.18, shininess: 96 }),
+ });
+ name.animate(
+ LayerAnimation.create()
+ .keys(
+ "rotateY",
+ springKeys(nameStart, -70, 0, fps, SWING) as KeyframeTuple[],
+ )
+ .keys("opacity", [
+ [nameStart, 0],
+ [nameStart + Math.round(base * 0.5), 1, "power2.out"],
+ ]),
+ );
+ parts.name = name;
+ children.push(name);
+ } else {
+ const animators =
+ letters || glints
+ ? [
+ ...(letters
+ ? [
+ glyphAnimator(
+ "rise",
+ scheduleExpression(
+ "char",
+ {
+ starts: rendererChars(
+ props.name,
+ Array.from({ length: chars }, (_, i) =>
+ Math.round(i * stagger),
+ ),
+ ),
+ duration: base,
+ ease: theme.motion.ease.enter,
+ },
+ "enter",
+ ),
+ { y: ns * 0.35, opacity: 0 },
+ ),
+ ]
+ : []),
+ ...(glints
+ ? [
+ glyphAnimator(
+ "glint",
+ glintExpression(
+ props.name,
+ glintAt - nameStart,
+ glintFrames,
+ ),
+ { fillColor: "#ffffff" },
+ ),
+ ]
+ : []),
+ ]
+ : undefined;
+ const wipe = style === "slide" && !!props.mark;
+ const text = host.text(props.name, {
+ id: ctx.partId("name"),
+ position: "absolute",
+ x: wipe ? (stack ? 0 : -nameM.width - gap) : 0,
+ y: wipe && stack ? -nameM.height : 0,
+ fontFamily,
+ fontSize: ns,
+ fontWeight: props.fontWeight,
+ fill: ink,
+ ...(animators && { animators: animators as never }),
+ startFrame: nameStart,
+ });
+ if (wipe)
+ text.animate(
+ LayerAnimation.keys(stack ? "y" : "x", [
+ [0, stack ? -nameM.height : -nameM.width - gap],
+ [glide, 0, ease],
+ ]),
+ );
+ else if (style === "rise" || (!props.mark && style === "slide"))
+ text.animate(
+ LayerAnimation.keys("y", [
+ [0, nameM.height],
+ [base, 0, theme.motion.ease.enter],
+ ]),
+ );
+ // The name sits in a clip: it wipes out from behind the mark or rises.
+ const clip = host.box({
+ id: ctx.partId("name-clip"),
+ position: "absolute",
+ x: nameAt.x,
+ y: nameAt.y,
+ width: nameM.width,
+ height: nameM.height,
+ ...(!letters && { overflow: "hidden" as const }),
+ children: [text],
+ });
+ parts.name = text;
+ parts["name-clip"] = clip;
+ children.push(clip);
+ }
+ }
+
+ // ── Tagline ──────────────────────────────────────────────────────
+ if (props.tagline) {
+ const tag = host.text(props.tagline, {
+ id: ctx.partId("tagline"),
+ position: "absolute",
+ x: tagAt.x,
+ y: tagAt.y,
+ fontFamily: theme.font.body,
+ fontSize: tagSize,
+ fill: theme.color.muted,
+ });
+ tag.animate(
+ LayerAnimation.create()
+ .keys("opacity", [
+ [tagStart, 0],
+ [tagStart + base, 1, "power2.out"],
+ ])
+ .keys("y", [
+ [tagStart, tagAt.y + 12 * s],
+ [tagStart + base, tagAt.y, theme.motion.ease.enter],
+ ]),
+ );
+ parts.tagline = tag;
+ children.push(tag);
+ }
+ if (markNode) children.push(markNode);
+
+ return {
+ children,
+ width: W,
+ height: H,
+ duration: end,
+ openEnded: true,
+ cues: {
+ hit: props.mark ? [{ frame: hit }] : [],
+ revealed: [{ frame: revealed }],
+ glint: glints ? [{ frame: glintAt }] : [],
+ } as LogoRevealCues,
+ parts,
+ };
+ },
+});
+
+/**
+ * A soft band of light crossing the name left to right: each character
+ * peaks as the band passes its position (frame is the name's local frame).
+ */
+function glintExpression(text: string, start: number, frames: number): string {
+ const n = Math.max(1, text.length - 1);
+ const peaks = rendererChars(
+ text,
+ Array.from(
+ { length: text.length },
+ (_, i) => Math.round((start + (i / n) * frames * 0.7) * 100) / 100,
+ ),
+ );
+ const width = Math.max(2, frames * 0.18);
+ return `((P)=>{const d=abs(frame-(P[textIndex]??-999));return d<${width}?(1-d/${width})*0.85:0;})([${peaks.join(",")}])`;
+}
diff --git a/packages/components/src/logo-reveal/meta.ts b/packages/components/src/logo-reveal/meta.ts
new file mode 100644
index 00000000..55ded0c4
--- /dev/null
+++ b/packages/components/src/logo-reveal/meta.ts
@@ -0,0 +1,21 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "LogoReveal",
+ summary:
+ "The end-card lockup: a mark and a wordmark arriving as one move, drawn on, popped or wiped, with a glint across the name; names can be extruded in 3D.",
+ tags: ["logo", "brand", "lockup", "end card", "outro", "wordmark", "3d"],
+ parts: [
+ "mark",
+ "mark-clip",
+ "mark-image",
+ "mark-fill",
+ "mark-outline",
+ "name",
+ "name-clip",
+ "tagline",
+ ],
+ cues: ["hit", "revealed", "glint"],
+ example: `LogoReveal({ mark: "assets/logo.svg", name: "framefields", tagline: "Motion in code" })`,
+ since: "M7",
+});
diff --git a/packages/components/src/selection/index.test.ts b/packages/components/src/selection/index.test.ts
new file mode 100644
index 00000000..3b98d81d
--- /dev/null
+++ b/packages/components/src/selection/index.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { rangeRects } from "../core/text.js";
+import { fakeHost, fakeMeasure } from "../test/fake-host.js";
+import { selection } from "./index.js";
+
+const make = () => bind(fakeHost(), selection);
+type Key = { frame: number; value: number };
+type Node = {
+ id?: string;
+ x?: number;
+ y?: number;
+ width?: number;
+ children?: Node[];
+ animation?: { tracks: Array<{ prop: string; keyframes: Key[] }> };
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+const track = (n: Node | undefined, prop: string) =>
+ n?.animation?.tracks.find((t) => t.prop === prop)?.keyframes ?? [];
+const valueAt = (keys: Key[], f: number) =>
+ [...keys].reverse().find((k) => k.frame <= f)?.value ?? 0;
+
+// Fake measure: 20 px glyphs at 40 px; lines 48 px tall.
+const text = {
+ kind: "text",
+ id: "t",
+ text: "select these words now",
+ x: 100,
+ y: 200,
+ fontSize: 40,
+ fontFamily: "Inter",
+ width: 260,
+};
+
+describe("Selection", () => {
+ it("ends on the glyph boundary nearest the pointer", () => {
+ // The pointer sweeps from the start of the text, 15 px a frame, on line 0.
+ const pointer = {
+ positionAt: (f: number): [number, number] => [100 + (f - 10) * 15, 220],
+ cues: { drags: [{ frame: 10, end: 30 }] },
+ };
+ const sel = make()({
+ id: "s",
+ target: { text, match: "select these" },
+ pointer,
+ });
+ const line = find(sel, "s-line-0");
+ expect(line?.x).toBe(100);
+ // Frame 17: pointer at 205 px → 5.25 glyphs in → boundary 5.
+ expect(valueAt(track(line, "width"), 17)).toBe(100);
+ // Frame 30: pointer at 400, past the line's end (340) → its whole width.
+ expect(valueAt(track(line, "width"), 30)).toBe(240);
+ expect(sel.cues.selected[0]?.frame).toBe(30);
+ });
+
+ it("draws one rect per line, matching rangeRects", () => {
+ const sel = make()({
+ id: "s",
+ target: { text },
+ drag: { frame: 0, end: 20 },
+ });
+ const options = { fontFamily: "Inter", fontSize: 40, width: 260 };
+ const rects = rangeRects(
+ fakeMeasure(text.text, options),
+ 0,
+ text.text.length,
+ options,
+ );
+ expect(rects.length).toBeGreaterThan(1);
+ rects.forEach((r, i) => {
+ const line = find(sel, `s-line-${i}`);
+ expect(line?.x).toBe(100 + r.x);
+ expect(track(line, "width").at(-1)?.value).toBeCloseTo(r.width, 6);
+ });
+ });
+
+ it("marquee: lights items as the box covers them", () => {
+ const sel = make()({
+ id: "s",
+ kind: "marquee",
+ from: [0, 0],
+ to: [400, 400],
+ drag: { frame: 0, end: 40 },
+ items: [
+ { x: 50, y: 50, width: 20, height: 20 },
+ { x: 350, y: 350, width: 20, height: 20 },
+ { x: 900, y: 900, width: 20, height: 20 },
+ ],
+ });
+ expect(sel.cues.items.map((c) => c.index)).toEqual([0, 1]);
+ const [a, b] = sel.cues.items.map((c) => c.frame) as [number, number];
+ expect(a).toBeLessThan(b);
+ expect(track(find(sel, "s-item-2"), "opacity").at(-1)?.value ?? 0).toBe(0);
+ expect(track(find(sel, "s-marquee"), "opacity").at(-1)?.value).toBe(0);
+ });
+
+ it("needs a drag", () => {
+ expect(() => make()({ target: { text } })).toThrow(/drag/);
+ });
+});
diff --git a/packages/components/src/selection/index.ts b/packages/components/src/selection/index.ts
new file mode 100644
index 00000000..5e39c988
--- /dev/null
+++ b/packages/components/src/selection/index.ts
@@ -0,0 +1,342 @@
+/**
+ * Selection: a text selection or a marquee, the way an editor draws them,
+ * driven by a `MousePointer` drag. Text selections follow the pointer glyph
+ * by glyph; a marquee follows it corner by corner and lights up the items it
+ * covers.
+ *
+ * Coordinates are the frame's: the root covers the video (default
+ * 1920 × 1080 × theme scale, or the given width / height) from 0, 0.
+ */
+import {
+ type KeyframeTuple,
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import { bakeSamples } from "../core/bake.js";
+import { defineComponent } from "../core/contract.js";
+import type { Rect } from "../core/draw.js";
+import { evaluateEase } from "../core/ease.js";
+import type { Animatable } from "../core/host.js";
+import type { Vec2 } from "../core/path.js";
+import { targetSchema } from "../core/schemas.js";
+import {
+ boundsOf,
+ resolveTarget,
+ type Target,
+ type TargetNode,
+ textLayout,
+} from "../core/targets.js";
+import { lineShift, rangeRects } from "../core/text.js";
+import { scaleFrames } from "../core/timing.js";
+
+export interface SelectionCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** The selection is complete (the drag ends). */
+ selected: ReadonlyArray<{ frame: number }>;
+ /** Marquee items, as each is first covered. */
+ items: ReadonlyArray<{ frame: number; index: number }>;
+}
+
+/** What Selection reads from a pointer: `MousePointer` satisfies it. */
+export interface SelectionPointer {
+ positionAt(frame: number): Vec2;
+ cues?: { drags?: ReadonlyArray<{ frame: number; end: number }> };
+}
+
+export const selection = /* @__PURE__ */ defineComponent({
+ name: "Selection",
+ props: () => ({
+ kind: z.enum(["text", "marquee"]).default("text"),
+ /** Text to select: `{ text, match? | range? }`. */
+ target: z
+ .custom<{
+ text: object;
+ match?: string | RegExp;
+ range?: [number, number];
+ nth?: number;
+ }>((v) => typeof v === "object" && v !== null && "text" in v, {
+ message: "Expected a text target `{ text, match? | range? }`",
+ })
+ .optional(),
+ /** A MousePointer to follow during the drag. */
+ pointer: z
+ .custom<SelectionPointer>(
+ (v) =>
+ typeof v === "object" &&
+ v !== null &&
+ typeof (v as SelectionPointer).positionAt === "function",
+ { message: "Expected a MousePointer (anything with positionAt)" },
+ )
+ .optional(),
+ /** Drag frames (parent timeline). Default: the pointer's first drag. */
+ drag: z
+ .object({ frame: z.number().int().min(0), end: z.number().int().min(0) })
+ .passthrough()
+ .optional(),
+ /** Marquee corners (parent coordinates). Default: the pointer's. */
+ from: z.tuple([z.number(), z.number()]).optional(),
+ to: z.tuple([z.number(), z.number()]).optional(),
+ /** Marquee: these light up once covered. */
+ items: z.array(targetSchema()).default([]),
+ /** Frame (parent timeline) the selection disappears. */
+ clear: z.number().int().min(0).optional(),
+ color: z.string().optional(),
+ }),
+ defaults: { enter: false, exit: false },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ const s = theme.scale;
+ const W = ctx.requested.width ?? 1920 * s;
+ const H = ctx.requested.height ?? 1080 * s;
+ const color = props.color ?? theme.color.accent;
+ const at0 = ctx.requested.at;
+ const drag = props.drag ?? props.pointer?.cues?.drags?.[0];
+ if (!drag)
+ throw new Error(
+ "Selection: give `drag: { frame, end }`, or a `pointer` that drags.",
+ );
+ // Local frames: the component's own timeline.
+ const start = drag.frame - at0;
+ const end = Math.max(start + 1, drag.end - at0);
+ const progress = (f: number) =>
+ evaluateEase(
+ "power2.inOut",
+ Math.max(0, Math.min(1, (f - start) / (end - start))),
+ );
+ const pointerAt = (f: number) => props.pointer?.positionAt(f + at0);
+ const fade = scaleFrames(8, fps);
+ const clear = props.clear !== undefined ? props.clear - at0 : undefined;
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const children: LayoutNode[] = [];
+ const cues: SelectionCues = {
+ selected: [{ frame: end }],
+ items: [] as Array<{ frame: number; index: number }>,
+ };
+ if (props.kind === "text") {
+ if (!props.target)
+ throw new Error("Selection: a text selection needs a `target`.");
+ const t = textLayout(
+ props.target as Extract<Target, { text: TargetNode }>,
+ { measure: host.measure, fps },
+ );
+ const [r0, r1] = t.range;
+ const glyphs = t.metrics.glyphs.filter(
+ (g) => g.index >= r0 && g.index < r1,
+ );
+ // The selection's end (a string index) on frame f.
+ const endIndex = (f: number): number => {
+ if (f <= start) return r0;
+ const p = pointerAt(Math.min(f, end));
+ if (!p) return r0 + Math.round(progress(f) * (r1 - r0));
+ // The line under the pointer, then the glyph boundary nearest it.
+ const lh = t.metrics.lineHeight;
+ const lines = [...new Set(glyphs.map((g) => g.line))];
+ const want = Math.floor((p[1] - t.y) / lh);
+ const line = Math.max(
+ lines[0] as number,
+ Math.min(lines[lines.length - 1] as number, want),
+ );
+ const shift = lineShift(t.metrics, line, t.options);
+ let best = r0;
+ let bestD = Number.POSITIVE_INFINITY;
+ for (const g of glyphs) {
+ if (g.line !== line) continue;
+ for (const [edge, idx] of [
+ [g.x, g.index],
+ [g.x + g.width, g.index + 1],
+ ] as const) {
+ const d = Math.abs(t.x + shift + edge - p[0]);
+ if (d < bestD) {
+ bestD = d;
+ best = idx;
+ }
+ }
+ }
+ // Below the range's lines selects to the end; above, to the start.
+ if (want > (lines[lines.length - 1] as number)) return r1;
+ if (want < (lines[0] as number)) return r0;
+ return Math.max(r0, Math.min(r1, best));
+ };
+ const full = rangeRects(t.metrics, r0, r1, t.options);
+ const lineOf = (rect: Rect) => Math.round(rect.y / t.metrics.lineHeight);
+ full.forEach((rect, i) => {
+ const line = lineOf(rect);
+ const widthAt = (f: number) => {
+ const part = rangeRects(t.metrics, r0, endIndex(f), t.options).find(
+ (r) => lineOf(r) === line,
+ );
+ return part ? round(part.x + part.width - rect.x) : 0;
+ };
+ const keys: KeyframeTuple[] = [[0, 0]];
+ let last = 0;
+ for (let f = start; f <= end; f++) {
+ const w = widthAt(f);
+ if (w !== last) {
+ keys.push([f, w, "hold"]);
+ last = w;
+ }
+ }
+ const pad = Math.max(1, 2 * s);
+ const box = host.box({
+ id: ctx.partId(`line-${i}`),
+ position: "absolute",
+ x: t.x + rect.x,
+ y: t.y + rect.y + pad,
+ width: 0,
+ height: rect.height - pad * 2,
+ background: withAlpha(color, 0.32),
+ borderRadius: Math.max(1, 3 * s),
+ });
+ const anim = LayerAnimation.create().keys("width", thin(keys));
+ if (clear !== undefined)
+ anim.keys("opacity", [
+ [clear, 1],
+ [clear + fade, 0, "power2.out"],
+ ]);
+ box.animate(anim);
+ parts[`line-${i}`] = box;
+ children.push(box);
+ });
+ } else {
+ const from: Vec2 = props.from ?? pointerAt(start) ?? [W * 0.3, H * 0.3];
+ const to: Vec2 = props.to ?? pointerAt(end) ?? [W * 0.7, H * 0.7];
+ const corner = (f: number): Vec2 => {
+ const p = props.to ? undefined : pointerAt(Math.min(f, end));
+ if (p) return p;
+ const k = progress(f);
+ return [
+ from[0] + (to[0] - from[0]) * k,
+ from[1] + (to[1] - from[1]) * k,
+ ];
+ };
+ const rectAt = (f: number): Rect => {
+ const c = corner(f);
+ return {
+ x: Math.min(from[0], c[0]),
+ y: Math.min(from[1], c[1]),
+ width: Math.abs(c[0] - from[0]),
+ height: Math.abs(c[1] - from[1]),
+ };
+ };
+ const frames = Array.from({ length: end - start + 1 }, (_, k) =>
+ rectAt(start + k),
+ );
+ const track = (k: keyof Rect) =>
+ bakeSamples(
+ frames.map((r) => r[k]),
+ start,
+ { tolerance: 0.3 },
+ );
+ const box = host.box({
+ id: ctx.partId("marquee"),
+ position: "absolute",
+ x: from[0],
+ y: from[1],
+ width: 0,
+ height: 0,
+ background: withAlpha(color, 0.16),
+ borderColor: color,
+ borderWidth: Math.max(1, 1.5 * s),
+ opacity: 0,
+ });
+ box.animate(
+ LayerAnimation.create()
+ .keys("x", track("x"))
+ .keys("y", track("y"))
+ .keys("width", track("width"))
+ .keys("height", track("height"))
+ // The marquee goes on release; what it selected stays.
+ .keys("opacity", [
+ [start, 1, "hold"],
+ [end, 1],
+ [end + fade, 0, "power2.out"],
+ ]),
+ );
+ parts.marquee = box;
+
+ props.items.forEach((item, index) => {
+ const r = boundsOf(
+ (() => {
+ const res = resolveTarget(item, { measure: host.measure, fps });
+ return res.kind === "static" ? res.rects : [res.at(end)];
+ })(),
+ );
+ const hits = (m: Rect) =>
+ m.x < r.x + r.width &&
+ m.x + m.width > r.x &&
+ m.y < r.y + r.height &&
+ m.y + m.height > r.y;
+ const keys: KeyframeTuple[] = [[0, 0]];
+ let on = false;
+ frames.forEach((m, k) => {
+ const now = m.width > 0 && m.height > 0 && hits(m);
+ if (now !== on) {
+ keys.push([start + k, now ? 1 : 0, "hold"]);
+ if (now && !cues.items.some((c) => c.index === index))
+ (cues.items as Array<{ frame: number; index: number }>).push({
+ frame: start + k,
+ index,
+ });
+ on = now;
+ }
+ });
+ if (on && clear !== undefined)
+ keys.push([clear, 1], [clear + fade, 0, "power2.out"]);
+ const pad = 4 * s;
+ const glow = host.box({
+ id: ctx.partId(`item-${index}`),
+ position: "absolute",
+ x: r.x - pad,
+ y: r.y - pad,
+ width: r.width + pad * 2,
+ height: r.height + pad * 2,
+ background: withAlpha(color, 0.18),
+ borderColor: color,
+ borderWidth: Math.max(1.5, 2 * s),
+ borderRadius: theme.radius.sm + pad,
+ opacity: 0,
+ });
+ glow.animate(LayerAnimation.keys("opacity", keys));
+ parts[`item-${index}`] = glow;
+ children.push(glow);
+ });
+ children.push(box);
+ }
+
+ const settle = props.kind === "marquee" ? end + fade : end;
+ return {
+ children,
+ width: W,
+ height: H,
+ duration: clear !== undefined ? clear + fade : settle,
+ openEnded: clear === undefined,
+ origin: [0, 0],
+ cues,
+ parts,
+ };
+ },
+});
+
+const round = (v: number) => Math.round(v * 100) / 100;
+
+/** Drop repeated hold keys past the program's per-track key budget, keeping the last. */
+function thin(keys: KeyframeTuple[]): KeyframeTuple[] {
+ if (keys.length <= 120) return keys;
+ const step = Math.ceil(keys.length / 119);
+ return [
+ ...keys.filter((_, i) => i % step === 0),
+ keys[keys.length - 1] as KeyframeTuple,
+ ];
+}
+
+/** `#rrggbb` / `#rgb` at alpha `a`; other colours pass through. */
+function withAlpha(color: string, a: number): string {
+ const hex = color.trim().replace(/^#/, "");
+ const full =
+ hex.length === 3 ? hex.replace(/./g, (x) => x + x) : hex.slice(0, 6);
+ if (!/^[0-9a-f]{6}$/i.test(full)) return color;
+ const n = Number.parseInt(full, 16);
+ return `rgba(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255},${a})`;
+}
diff --git a/packages/components/src/selection/meta.ts b/packages/components/src/selection/meta.ts
new file mode 100644
index 00000000..71cff562
--- /dev/null
+++ b/packages/components/src/selection/meta.ts
@@ -0,0 +1,20 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "Selection",
+ summary:
+ "A text selection or a marquee driven by a MousePointer drag: it follows the pointer glyph by glyph, and lights up covered items.",
+ tags: [
+ "selection",
+ "highlight",
+ "marquee",
+ "drag",
+ "editor",
+ "ui",
+ "pointer",
+ ],
+ parts: ["line-0", "marquee", "item-0"],
+ cues: ["selected", "items"],
+ example: `Selection({ target: { text: paragraph, match: "the key line" }, pointer })`,
+ since: "M8",
+});
diff --git a/packages/components/src/test/fake-host.ts b/packages/components/src/test/fake-host.ts
index daf95f3c..1380a356 100644
--- a/packages/components/src/test/fake-host.ts
+++ b/packages/components/src/test/fake-host.ts
@@ -125,6 +125,10 @@ export function fakeHost(): Host & { created: LayoutNode[] } {
}) as never,
particles: (o) =>
make({ kind: "particles", ...o, id: o.id ?? "particles" }) as never,
+ signal: (values, fps) => ({ kind: "signal", values: [...values], fps }),
+ grain: (o) => make({ kind: "grain", ...o, id: o.id ?? "grain" }) as never,
+ extrudedText: (o) =>
+ make({ kind: "model", ...o, id: o.id ?? "extruded" }) as never,
matte: (node, matte, mode = "alpha") => {
(node as unknown as { matte?: unknown }).matte = { node: matte, mode };
return node;
diff --git a/packages/components/src/touch-point/index.test.ts b/packages/components/src/touch-point/index.test.ts
new file mode 100644
index 00000000..a2c19324
--- /dev/null
+++ b/packages/components/src/touch-point/index.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { fakeHost } from "../test/fake-host.js";
+import { touchPoint } from "./index.js";
+
+const make = () => bind(fakeHost(), touchPoint);
+type Key = { frame: number; value: number };
+type Node = {
+ id?: string;
+ children?: Node[];
+ animation?: { tracks: Array<{ prop: string; keyframes: Key[] }> };
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+const track = (n: Node | undefined, prop: string) =>
+ n?.animation?.tracks.find((t) => t.prop === prop)?.keyframes ?? [];
+const valueAt = (keys: Key[], f: number) =>
+ [...keys].reverse().find((k) => k.frame <= f)?.value ?? keys[0]?.value;
+
+describe("TouchPoint", () => {
+ it("cues taps, presses and swipes in order", () => {
+ const t = make()({
+ touches: [
+ { to: [100, 100], tap: 2 },
+ { to: [200, 200], press: 30 },
+ { to: [300, 600], swipe: [300, 200] },
+ ],
+ });
+ expect(t.cues.taps.length).toBe(2);
+ expect(t.cues.presses.length).toBe(1);
+ expect(t.cues.swipes.length).toBe(1);
+ expect(t.cues.touches.length).toBe(4);
+ const frames = t.cues.touches.map((c) => c.frame);
+ expect([...frames].sort((a, b) => a - b)).toEqual(frames);
+ const press = t.cues.presses[0] as { frame: number; end: number };
+ expect(press.end - press.frame).toBe(30);
+ });
+
+ it("a swipe's disc is at `from` on the cue frame and `to` at its end", () => {
+ const t = make()({
+ id: "t",
+ size: 40,
+ touches: [{ to: [300, 600], swipe: [300, 200] }],
+ });
+ const sw = t.cues.swipes[0] as { frame: number; end: number };
+ const disc = find(t, "t-touch-0");
+ expect(valueAt(track(disc, "y"), sw.frame)).toBe(600 - 20);
+ expect(valueAt(track(disc, "y"), sw.end)).toBe(200 - 20);
+ expect(find(t, "t-touch-0-trail-0")).toBeDefined();
+ });
+
+ it("is invisible before the lead-in and after the lift", () => {
+ const t = make()({ id: "t", touches: [{ to: [100, 100], at: 30 }] });
+ const o = track(find(t, "t-touch-0"), "opacity");
+ expect(valueAt(o, 20)).toBe(0);
+ expect(valueAt(o, 30)).toBeGreaterThan(0);
+ expect(o.at(-1)?.value).toBe(0);
+ expect(t.cues.taps[0]?.frame).toBe(30);
+ });
+
+ it("waits after each touch when `at` is omitted", () => {
+ const t = make()({ touches: [{ to: [0, 0] }, { to: [10, 10] }] });
+ const [a, b] = t.cues.taps.map((c) => c.frame);
+ expect((b as number) - (a as number)).toBeGreaterThan(20);
+ });
+});
diff --git a/packages/components/src/touch-point/index.ts b/packages/components/src/touch-point/index.ts
new file mode 100644
index 00000000..f5cd3217
--- /dev/null
+++ b/packages/components/src/touch-point/index.ts
@@ -0,0 +1,356 @@
+/**
+ * TouchPoint: fingers on glass, drawn the way screen recordings show
+ * touches: a soft disc that lands, presses and lifts, with a ripple. Taps,
+ * double taps, long presses and swipes. Between touches the finger is
+ * lifted, so nothing travels: each touch is its own disc.
+ *
+ * Coordinates are the frame's: the root covers the video (default
+ * 1920 × 1080 × theme scale, or the given width / height) from 0, 0.
+ */
+import {
+ type KeyframeTuple,
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import { defineComponent } from "../core/contract.js";
+import type { Animatable } from "../core/host.js";
+import { dist, type Vec2 } from "../core/path.js";
+import { targetSchema } from "../core/schemas.js";
+import { resolveTarget, type Target, targetPoint } from "../core/targets.js";
+import { scaleFrames } from "../core/timing.js";
+
+export interface TouchPointCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** Each tap's touch-down. */
+ taps: ReadonlyArray<{ frame: number; point: Vec2 }>;
+ /** Long presses, down to lift. */
+ presses: ReadonlyArray<{ frame: number; end: number; point: Vec2 }>;
+ /** Swipes, from the start of the move to its end. */
+ swipes: ReadonlyArray<{ frame: number; end: number; from: Vec2; to: Vec2 }>;
+ /** Every touch-down. */
+ touches: ReadonlyArray<{ frame: number; point: Vec2 }>;
+}
+
+/** One planned touch, in local frames. */
+export interface PlannedTouch {
+ point: Vec2;
+ /** Disc starts landing. */
+ lead: number;
+ /** Taps: down frames; presses and swipes: one. */
+ downs: number[];
+ /** Swipe: move window and destination. */
+ swipe?: { start: number; end: number; to: Vec2 };
+ /** Finger leaves the glass. */
+ lift: number;
+ kind: "tap" | "press" | "swipe";
+ pressEnd?: number;
+}
+
+export const touchPoint = /* @__PURE__ */ defineComponent({
+ name: "TouchPoint",
+ props: () => ({
+ touches: z
+ .array(
+ z
+ .object({
+ to: targetSchema(),
+ /** Touch-down frame. Default: after the previous touch. */
+ at: z.number().int().min(0).optional(),
+ /** Tap count. */
+ tap: z.number().int().positive().optional(),
+ /** Long press: frames held. */
+ press: z.number().int().positive().optional(),
+ /** Drag to here and lift. */
+ swipe: targetSchema().optional(),
+ /** Frames to wait after this touch. */
+ dwell: z.number().int().min(0).optional(),
+ })
+ .strict(),
+ )
+ .min(1),
+ size: z.number().positive().optional(),
+ color: z.string().default("#ffffff"),
+ opacity: z.number().min(0).max(1).default(0.55),
+ ripple: z.boolean().default(true),
+ trail: z.boolean().default(true),
+ }),
+ defaults: { enter: false, exit: false },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ const s = theme.scale;
+ const W = ctx.requested.width ?? 1920 * s;
+ const H = ctx.requested.height ?? 1080 * s;
+ const size = props.size ?? 64 * s;
+ const f = (n: number) => scaleFrames(n, fps);
+ const pointOf = (t: Target, at: number) =>
+ targetPoint(resolveTarget(t, { measure: host.measure, fps }), at);
+
+ const plan = planTouches(
+ props.touches.map((t) => ({
+ at: t.at,
+ tap: t.tap,
+ press: t.press,
+ dwell: t.dwell,
+ point: (frame: number) => pointOf(t.to, frame),
+ swipe: t.swipe
+ ? (frame: number) => pointOf(t.swipe as Target, frame)
+ : undefined,
+ })),
+ fps,
+ );
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const children: LayoutNode[] = [];
+ const ringFrames = f(16);
+ const lead = f(4);
+ plan.forEach((touch, i) => {
+ const press: KeyframeTuple[] = [
+ [touch.lead, 1.25],
+ [touch.lead + lead, 1, "power2.out"],
+ ];
+ for (const d of touch.downs.slice(1)) {
+ // Between taps the finger lifts a little and comes back down.
+ press.push([d - f(3), 1.1, "power2.out"], [d, 1, "power2.in"]);
+ }
+ if (touch.kind === "press" && touch.pressEnd !== undefined)
+ press.push([touch.pressEnd, 0.88, "sine.inOut"]);
+ press.push(
+ [touch.lift, touch.kind === "press" ? 0.88 : 1],
+ [touch.lift + f(6), 1.2, "power2.out"],
+ );
+ const anim = LayerAnimation.create()
+ .keys("opacity", [
+ [touch.lead, 0],
+ [touch.lead + lead, props.opacity, "power2.out"],
+ [touch.lift, props.opacity],
+ [touch.lift + f(6), 0, "power2.in"],
+ ])
+ .keys("scale", ascending(press));
+ if (touch.swipe) {
+ const { start, end, to } = touch.swipe;
+ anim
+ .keys("x", [
+ [start, touch.point[0] - size / 2],
+ [end, to[0] - size / 2, "power2.inOut"],
+ ])
+ .keys("y", [
+ [start, touch.point[1] - size / 2],
+ [end, to[1] - size / 2, "power2.inOut"],
+ ]);
+ }
+ const disc = host.box({
+ id: ctx.partId(`touch-${i}`),
+ position: "absolute",
+ x: touch.point[0] - size / 2,
+ y: touch.point[1] - size / 2,
+ width: size,
+ height: size,
+ background: `radial-gradient(closest-side, ${props.color} 0%, ${props.color} 72%, rgba(255,255,255,0) 100%)`,
+ borderRadius: size / 2,
+ borderColor: props.color,
+ borderWidth: Math.max(1, 1.5 * s),
+ opacity: 0,
+ });
+ disc.animate(anim);
+ host.style(disc, {
+ dropShadow: {
+ color: "#000000",
+ opacity: 0.25,
+ angle: 90,
+ distance: 2 * s,
+ size: 10 * s,
+ },
+ });
+
+ // Ghosts that lag behind a swipe: a short fading streak.
+ if (touch.swipe && props.trail) {
+ const { start, end, to } = touch.swipe;
+ [2, 4, 6].forEach((lag, g) => {
+ const ghost = host.box({
+ id: ctx.partId(`touch-${i}-trail-${g}`),
+ position: "absolute",
+ x: touch.point[0] - size / 2,
+ y: touch.point[1] - size / 2,
+ width: size,
+ height: size,
+ background: props.color,
+ borderRadius: size / 2,
+ opacity: 0,
+ scale: 0.85 - g * 0.15,
+ });
+ const o = props.opacity * (0.35 - g * 0.1);
+ ghost.animate(
+ LayerAnimation.create()
+ .keys("x", [
+ [start + f(lag), touch.point[0] - size / 2],
+ [end + f(lag), to[0] - size / 2, "power2.inOut"],
+ ])
+ .keys("y", [
+ [start + f(lag), touch.point[1] - size / 2],
+ [end + f(lag), to[1] - size / 2, "power2.inOut"],
+ ])
+ .keys("opacity", [
+ [start, 0],
+ [start + f(lag), o],
+ [end + f(lag), 0, "power2.in"],
+ ]),
+ );
+ parts[`touch-${i}-trail-${g}`] = ghost;
+ children.push(ghost);
+ });
+ }
+
+ if (props.ripple && touch.kind !== "swipe") {
+ const rings =
+ touch.kind === "press" ? [touch.downs[0] as number] : touch.downs;
+ rings.forEach((d, r) => {
+ const ring = host.box({
+ id: ctx.partId(`touch-${i}-ripple-${r}`),
+ position: "absolute",
+ x: touch.point[0] - size / 2,
+ y: touch.point[1] - size / 2,
+ width: size,
+ height: size,
+ borderRadius: size / 2,
+ borderColor: props.color,
+ borderWidth: Math.max(1.5, 2.5 * s),
+ opacity: 0,
+ });
+ const span =
+ touch.kind === "press"
+ ? Math.max(ringFrames, (touch.pressEnd ?? d) - d)
+ : ringFrames;
+ ring.animate(
+ LayerAnimation.create()
+ .keys("scale", [
+ [d, 0.6],
+ [d + span, 2.2, "power2.out"],
+ ])
+ .keys("opacity", [
+ [0, 0],
+ [d, 0.7, "hold"],
+ [d + span, 0, "power1.out"],
+ ]),
+ );
+ parts[`touch-${i}-ripple-${r}`] = ring;
+ children.push(ring);
+ });
+ }
+ parts[`touch-${i}`] = disc;
+ children.push(disc);
+ });
+
+ const last = Math.max(
+ ...plan.map((t) => t.lift + f(6)),
+ ...plan.map((t) => (t.downs.at(-1) ?? 0) + ringFrames),
+ );
+ return {
+ children,
+ width: W,
+ height: H,
+ duration: last,
+ origin: [0, 0],
+ cues: {
+ taps: plan.flatMap((t) =>
+ t.kind === "tap"
+ ? t.downs.map((frame) => ({ frame, point: t.point }))
+ : [],
+ ),
+ presses: plan
+ .filter((t) => t.kind === "press")
+ .map((t) => ({
+ frame: t.downs[0] as number,
+ end: t.lift,
+ point: t.point,
+ })),
+ swipes: plan.flatMap((t) =>
+ t.swipe
+ ? [
+ {
+ frame: t.swipe.start,
+ end: t.swipe.end,
+ from: t.point,
+ to: t.swipe.to,
+ },
+ ]
+ : [],
+ ),
+ touches: plan.flatMap((t) =>
+ t.downs.map((frame) => ({ frame, point: t.point })),
+ ),
+ } as TouchPointCues,
+ parts,
+ };
+ },
+});
+
+interface TouchInput {
+ at?: number;
+ tap?: number;
+ press?: number;
+ dwell?: number;
+ point: (frame: number) => Vec2;
+ swipe?: (frame: number) => Vec2;
+}
+
+/** Touch timing: lead-in, downs, presses, swipe moves and lifts. Pure. */
+export function planTouches(
+ touches: readonly TouchInput[],
+ fps: number,
+): PlannedTouch[] {
+ const f = (n: number) => scaleFrames(n, fps);
+ const lead = f(4);
+ let free = lead;
+ return touches.map((t) => {
+ const down = t.at ?? free;
+ const point = t.point(down);
+ let lift: number;
+ let out: PlannedTouch;
+ if (t.swipe) {
+ const start = down + f(3);
+ const to0 = t.swipe(start);
+ const d = dist(point, to0);
+ const move = Math.max(
+ f(6),
+ Math.round((0.16 + 0.1 * Math.log2(1 + d / 40)) * fps),
+ );
+ const end = start + move;
+ lift = end + f(2);
+ out = {
+ point,
+ lead: Math.max(0, down - lead),
+ downs: [down],
+ swipe: { start, end, to: t.swipe(end) },
+ lift,
+ kind: "swipe",
+ };
+ } else if (t.press) {
+ lift = down + t.press;
+ out = {
+ point,
+ lead: Math.max(0, down - lead),
+ downs: [down],
+ lift,
+ kind: "press",
+ pressEnd: down + Math.min(t.press, f(8)),
+ };
+ } else {
+ const n = t.tap ?? 1;
+ const downs = Array.from({ length: n }, (_, k) => down + k * f(9));
+ lift = (downs.at(-1) as number) + f(4);
+ out = { point, lead: Math.max(0, down - lead), downs, lift, kind: "tap" };
+ }
+ free = lift + f(6) + (t.dwell ?? f(14)) + lead;
+ return out;
+ });
+}
+
+/** Later keys on a shared frame win; frames ascend. */
+function ascending(keys: KeyframeTuple[]): KeyframeTuple[] {
+ const byFrame = new Map<number, KeyframeTuple>();
+ for (const k of keys) byFrame.set(k[0] as number, k);
+ return [...byFrame.values()].sort(
+ (a, b) => (a[0] as number) - (b[0] as number),
+ );
+}
diff --git a/packages/components/src/touch-point/meta.ts b/packages/components/src/touch-point/meta.ts
new file mode 100644
index 00000000..bd128c17
--- /dev/null
+++ b/packages/components/src/touch-point/meta.ts
@@ -0,0 +1,12 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "TouchPoint",
+ summary:
+ "Fingers on glass: taps, double taps, long presses and swipes as soft discs with ripples, for mobile demos in a DeviceFrame.",
+ tags: ["touch", "tap", "swipe", "mobile", "gesture", "demo", "phone"],
+ parts: ["touch-0", "touch-0-ripple-0", "touch-0-trail-0"],
+ cues: ["taps", "presses", "swipes", "touches"],
+ example: `TouchPoint({ touches: [{ to: phone.at(196, 700) }, { to: phone.at(196, 600), swipe: phone.at(196, 200) }] })`,
+ since: "M8",
+});
diff --git a/packages/components/src/waveform/index.test.ts b/packages/components/src/waveform/index.test.ts
new file mode 100644
index 00000000..d1818e4a
--- /dev/null
+++ b/packages/components/src/waveform/index.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import type { AudioLevels } from "../core/audio.js";
+import { bind } from "../core/contract.js";
+import { fakeHost } from "../test/fake-host.js";
+import { waveform } from "./index.js";
+
+const make = () => bind(fakeHost(), waveform);
+type Signal = { kind: "signal"; values: number[]; fps: number };
+type Node = {
+ id?: string;
+ x?: number;
+ height?: number;
+ rotation?: number;
+ children?: Node[];
+ animation?: {
+ tracks: Array<{ prop: string; source?: { inputHandleId: string } }>;
+ };
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+
+/** Four bands over 10 frames: band b is (b + 1) / 4 on frame 5, 0 elsewhere. */
+const audio: AudioLevels = {
+ fps: 30,
+ frames: 10,
+ bands: [0, 1, 2, 3].map((b) =>
+ Array.from({ length: 10 }, (_, f) => (f === 5 ? (b + 1) / 4 : 0)),
+ ),
+ level: new Array(10).fill(0),
+ beats: [5],
+};
+
+/** The signal objects a host built, in order. */
+function signalsOf(host: ReturnType<typeof fakeHost>) {
+ const out: Signal[] = [];
+ const signal = host.signal;
+ host.signal = (values, fps) => {
+ const s = signal(values, fps) as Signal;
+ out.push(s);
+ return s;
+ };
+ return out;
+}
+
+describe("Waveform", () => {
+ it("needs audio analysed at its own fps", () => {
+ expect(() => make()({ audio, fps: 24 })).toThrow(/analysed at 30 fps/);
+ });
+
+ it("binds bar heights to their band, offset to the track's start", () => {
+ const host = fakeHost();
+ const signals = signalsOf(host);
+ const w = bind(
+ host,
+ waveform,
+ )({
+ id: "w",
+ audio,
+ kind: "bars",
+ floor: 0,
+ smoothing: 0,
+ height: 100,
+ audioStart: 20,
+ });
+ expect(w.span.duration).toBe(10);
+ expect(w.cues.beats.map((c) => c.frame)).toEqual([25]);
+ // Band 3's height signal: 20 frames of floor, then the levels.
+ const heights = signals.filter((_, i) => i % 2 === 0);
+ expect(heights.length).toBe(4);
+ const top = heights[3] as Signal;
+ expect(top.values.length).toBe(20 + 10 + 1);
+ expect(top.values[25]).toBe(100);
+ expect(top.values[24]).toBe(0);
+ expect(heights[0]?.values[25]).toBe(25);
+ const bar = find(w, "w-bar-3");
+ expect(bar?.animation?.tracks.map((t) => t.prop)).toEqual(["height", "y"]);
+ });
+
+ it("defaults the track's start to the component's", () => {
+ const host = fakeHost();
+ const signals = signalsOf(host);
+ bind(host, waveform)({ audio, at: 12 });
+ expect(signals[0]?.values.length).toBe(12 + 10 + 1);
+ });
+
+ it("mirrors bands out from the middle", () => {
+ const host = fakeHost();
+ const signals = signalsOf(host);
+ const w = bind(host, waveform)({ id: "w", audio, bars: 6 });
+ // 3 bands, each shown twice; lowest in the middle.
+ expect(signals.length).toBe(3 * 2);
+ const handle = (i: number) =>
+ find(w, `w-bar-${i}`)?.animation?.tracks[0]?.source?.inputHandleId;
+ expect(handle(2)).toBe(handle(3));
+ expect(handle(0)).toBe(handle(5));
+ expect(handle(0)).not.toBe(handle(2));
+ });
+
+ it("arranges a ring of spokes", () => {
+ const w = make()({ id: "w", audio, kind: "radial", bars: 8 });
+ expect(find(w, "w-spoke-2")?.rotation).toBe(90);
+ expect(find(w, "w-spoke-2")?.children?.[0]?.id).toBe("w-bar-2");
+ });
+});
diff --git a/packages/components/src/waveform/index.ts b/packages/components/src/waveform/index.ts
new file mode 100644
index 00000000..7abfcc31
--- /dev/null
+++ b/packages/components/src/waveform/index.ts
@@ -0,0 +1,245 @@
+/**
+ * Waveform: an audiogram. Bars, mirrored bars, dots or a ring that move
+ * with a track's spectrum. The audio is analysed offline into `AudioLevels`
+ * (plain data); each bar is bound to its band as a signal, so a minute of
+ * audio costs no keyframes and every frame seeks exactly.
+ */
+import {
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import {
+ audioLevelsSchema,
+ resampleBands,
+ smoothRelease,
+} from "../core/audio.js";
+import { defineComponent } from "../core/contract.js";
+import type { Animatable } from "../core/host.js";
+
+export const WAVEFORM_KINDS = ["bars", "mirror", "dots", "radial"] as const;
+export type WaveformKind = (typeof WAVEFORM_KINDS)[number];
+
+export interface WaveformCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** Onsets in the audio (kicks, plosives). */
+ beats: ReadonlyArray<{ frame: number }>;
+}
+
+export const waveform = /* @__PURE__ */ defineComponent({
+ name: "Waveform",
+ props: () => ({
+ /** From `analyzeAudio(source, { fps })`. */
+ audio: audioLevelsSchema(),
+ /** Composition frame the track starts on. Default: the component's `at`. */
+ audioStart: z.number().int().min(0).optional(),
+ kind: z.enum(WAVEFORM_KINDS).default("mirror"),
+ /** Bars shown. Default: one per band. */
+ bars: z.number().int().min(1).max(256).optional(),
+ /** Space between bars, as a fraction of a bar's pitch. */
+ gap: z.number().min(0).max(0.95).default(0.45),
+ /** Bar corner radius. Default: round. */
+ radius: z.number().min(0).optional(),
+ /** Smallest bar, as a fraction of full height. */
+ floor: z.number().min(0).max(1).default(0.06),
+ gain: z.number().positive().default(1),
+ /** Frames a bar takes to fall from a peak. */
+ smoothing: z.number().int().min(0).default(2),
+ /** One colour, or a pair graded across the bars. */
+ color: z.union([z.string(), z.tuple([z.string(), z.string()])]).optional(),
+ }),
+ defaults: { enter: false, exit: false },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ const s = theme.scale;
+ const audio = props.audio;
+ if (Math.abs(audio.fps - fps) > 1e-6)
+ throw new Error(
+ `Waveform: the audio was analysed at ${audio.fps} fps but the component runs at ${fps}. Analyse with { fps: ${fps} }.`,
+ );
+ const kind = props.kind;
+ const radial = kind === "radial";
+ const W = ctx.requested.width ?? (radial ? 420 : 800) * s;
+ const H = ctx.requested.height ?? (radial ? 420 : 200) * s;
+ const start = props.audioStart ?? ctx.requested.at;
+ const count = props.bars ?? audio.bands.length;
+ const mirror = kind === "mirror";
+ // Mirrored bars show each band twice, lowest in the middle.
+ const bands = resampleBands(
+ audio.bands,
+ mirror ? Math.ceil(count / 2) : count,
+ );
+ const floor = props.floor;
+ const level = (band: number) =>
+ smoothRelease(
+ (bands[band] ?? []).map((v) => Math.min(1, v * props.gain)),
+ props.smoothing,
+ ).map((v) => Math.round((floor + (1 - floor) * v) * 1000) / 1000);
+ // Signals read the composition's frame: the floor before the track and after it.
+ const levels = bands.map((_, b) => [
+ ...new Array<number>(start).fill(floor),
+ ...level(b),
+ floor,
+ ]);
+ const signals = new Map<string, object>();
+ /** One signal per band and mapping (`v` is the level, floor..1), shared by bars. */
+ const bound = (band: number, key: string, map: (v: number) => number) => {
+ const id = `${band}:${key}`;
+ let signal = signals.get(id);
+ if (!signal) {
+ signal = host.signal(
+ (levels[band] as number[]).map((v) => Math.round(map(v) * 100) / 100),
+ fps,
+ );
+ signals.set(id, signal);
+ }
+ return signal;
+ };
+ const colorOf = (i: number) => {
+ const c = props.color ?? theme.color.accent;
+ return typeof c === "string"
+ ? c
+ : mix(c[0], c[1], count > 1 ? i / (count - 1) : 0);
+ };
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const children: LayoutNode[] = [];
+ const pitch = (radial ? 0 : W) / count;
+ const bw = Math.max(1, pitch * (1 - props.gap));
+ for (let i = 0; i < count; i++) {
+ const band = mirror
+ ? Math.min(bands.length - 1, Math.floor(Math.abs(i - (count - 1) / 2)))
+ : i;
+ const color = colorOf(i);
+ if (radial) {
+ const D = Math.min(W, H);
+ const inner = D * 0.26;
+ const len = D / 2 - inner;
+ const thick = Math.max(
+ 2 * s,
+ ((2 * Math.PI * inner) / count) * (1 - props.gap),
+ );
+ // Grows outward from the ring: its bottom edge stays on the ring.
+ const bottom = D / 2 - inner;
+ const bar = host.box({
+ id: ctx.partId(`bar-${i}`),
+ position: "absolute",
+ x: D / 2 - thick / 2,
+ y: bottom - len * floor,
+ width: thick,
+ height: len * floor,
+ background: color,
+ borderRadius: props.radius ?? thick / 2,
+ });
+ bar.animate(
+ LayerAnimation.create()
+ .signal(
+ "height",
+ bound(band, "radial-h", (v) => len * v),
+ )
+ .signal(
+ "y",
+ bound(band, "radial-y", (v) => bottom - len * v),
+ ),
+ );
+ const spoke = host.box({
+ id: ctx.partId(`spoke-${i}`),
+ position: "absolute",
+ x: (W - D) / 2,
+ y: (H - D) / 2,
+ width: D,
+ height: D,
+ rotation: (360 * i) / count,
+ children: [bar],
+ });
+ parts[`bar-${i}`] = bar;
+ parts[`spoke-${i}`] = spoke;
+ children.push(spoke);
+ continue;
+ }
+ if (kind === "dots") {
+ const size = Math.min(bw, H);
+ const dot = host.box({
+ id: ctx.partId(`bar-${i}`),
+ position: "absolute",
+ x: i * pitch + (pitch - size) / 2,
+ y: (H - size) / 2,
+ width: size,
+ height: size,
+ background: color,
+ borderRadius: props.radius ?? size / 2,
+ scale: floor,
+ });
+ dot.animate(
+ LayerAnimation.create().signal(
+ "scale",
+ bound(band, "dot", (v) => v),
+ ),
+ );
+ parts[`bar-${i}`] = dot;
+ children.push(dot);
+ continue;
+ }
+ const up = kind === "bars";
+ const bar = host.box({
+ id: ctx.partId(`bar-${i}`),
+ position: "absolute",
+ x: i * pitch + (pitch - bw) / 2,
+ y: up ? H * (1 - floor) : (H * (1 - floor)) / 2,
+ width: bw,
+ height: H * floor,
+ background: color,
+ borderRadius: props.radius ?? bw / 2,
+ });
+ bar.animate(
+ LayerAnimation.create()
+ .signal(
+ "height",
+ bound(band, "h", (v) => H * v),
+ )
+ .signal(
+ "y",
+ bound(band, up ? "y-up" : "y-mid", (v) =>
+ up ? H * (1 - v) : (H * (1 - v)) / 2,
+ ),
+ ),
+ );
+ parts[`bar-${i}`] = bar;
+ children.push(bar);
+ }
+
+ return {
+ children,
+ width: W,
+ height: H,
+ duration: Math.max(1, audio.frames),
+ cues: {
+ beats: audio.beats.map((frame) => ({
+ frame: frame + start - ctx.requested.at,
+ })),
+ } as WaveformCues,
+ parts,
+ };
+ },
+});
+
+/** Mix two `#rrggbb` colours (`t` 0 → a, 1 → b); other formats: `a`. */
+function mix(a: string, b: string, t: number): string {
+ const rgb = (c: string) => {
+ const h = c.replace(/^#/, "");
+ const full = h.length === 3 ? h.replace(/./g, (x) => x + x) : h.slice(0, 6);
+ return /^[0-9a-f]{6}$/i.test(full)
+ ? [0, 2, 4].map((k) => Number.parseInt(full.slice(k, k + 2), 16))
+ : null;
+ };
+ const x = rgb(a);
+ const y = rgb(b);
+ if (!x || !y) return a;
+ return `#${x
+ .map((v, k) =>
+ Math.round(v + ((y[k] as number) - v) * t)
+ .toString(16)
+ .padStart(2, "0"),
+ )
+ .join("")}`;
+}
diff --git a/packages/components/src/waveform/meta.ts b/packages/components/src/waveform/meta.ts
new file mode 100644
index 00000000..6ee75158
--- /dev/null
+++ b/packages/components/src/waveform/meta.ts
@@ -0,0 +1,20 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "Waveform",
+ summary:
+ "An audiogram: bars, mirrored bars, dots or a ring that move with a track's spectrum, analysed offline and bound as signals.",
+ tags: [
+ "audio",
+ "waveform",
+ "audiogram",
+ "spectrum",
+ "podcast",
+ "music",
+ "visualizer",
+ ],
+ parts: ["bar-0", "spoke-0"],
+ cues: ["beats"],
+ example: `Waveform({ audio: await analyzeAudio("voice.wav", { fps: 30 }), kind: "mirror" })`,
+ since: "M7",
+});
diff --git a/packages/components/src/word-cycle/index.test.ts b/packages/components/src/word-cycle/index.test.ts
new file mode 100644
index 00000000..6865d6af
--- /dev/null
+++ b/packages/components/src/word-cycle/index.test.ts
@@ -0,0 +1,124 @@
+import type { KeyframeTuple } from "@framefields/compositions/program";
+import { describe, expect, it } from "vitest";
+import { bind } from "../core/contract.js";
+import { fakeHost } from "../test/fake-host.js";
+import { wordCycle } from "./index.js";
+
+const make = () => bind(fakeHost(), wordCycle);
+type Node = {
+ id?: string;
+ x?: number;
+ width?: number;
+ opacity?: number;
+ children?: Node[];
+ animation?: {
+ tracks: Array<{
+ prop: string;
+ keyframes: Array<{ frame: number; value: number }>;
+ }>;
+ };
+};
+const find = (n: unknown, id: string): Node | undefined => {
+ const node = n as Node;
+ if (node.id === id) return node;
+ for (const c of node.children ?? []) {
+ const hit = find(c, id);
+ if (hit) return hit;
+ }
+ return undefined;
+};
+const keys = (n: Node | undefined, prop: string) =>
+ (n?.animation?.tracks.find((t) => t.prop === prop)?.keyframes ?? []).map(
+ (k) => [k.frame, k.value] as KeyframeTuple,
+ );
+const at = (k: KeyframeTuple[], f: number) =>
+ [...k].reverse().find((key) => (key[0] as number) <= f)?.[1] as number;
+
+// Fake measure: 0.5 em per glyph at 96 px → 48 px a glyph, a space is 48.
+const G = 48;
+
+describe("WordCycle", () => {
+ it("keeps one space between the slot and the text after it, at rest", () => {
+ const w = make()({
+ id: "w",
+ text: "Make {} today",
+ words: ["it", "videos", "a"],
+ every: 60,
+ });
+ const slot = find(w, "w-slot");
+ const after = find(w, "w-after");
+ for (const [i, len] of [2, 6, 1].entries()) {
+ // Settled frames: just before the next change, and after the last.
+ const f = i < 2 ? (i + 1) * 60 - 1 : 400;
+ const slotRight = at(keys(slot, "x"), f) + at(keys(slot, "width"), f);
+ expect(at(keys(slot, "width"), f)).toBeCloseTo(len * G, 5);
+ expect(at(keys(after, "x"), f) - slotRight).toBeCloseTo(G, 5);
+ }
+ // The root fits the longest line: "Make" + space + "videos" + space + "today".
+ expect(w.width).toBeCloseTo((4 + 1 + 6 + 1 + 5) * G, 5);
+ });
+
+ it("re-centres the line for centred text", () => {
+ const w = make()({
+ id: "w",
+ text: "Make {} today",
+ words: ["it", "videos"],
+ align: "center",
+ });
+ const before = find(w, "w-before");
+ // Word 0 is 4 glyphs shorter than the longest: the line starts 2 in.
+ expect(before?.x).toBeCloseTo(2 * G, 5);
+ expect(keys(before, "x").at(-1)?.[1]).toBeCloseTo(0, 5);
+ });
+
+ it("shows one word at rest and cues every change", () => {
+ const w = make()({
+ id: "w",
+ text: "{} works",
+ words: ["it", "this", "that"],
+ every: 40,
+ cycles: 2,
+ });
+ expect(w.cues.changes.map((c) => c.frame)).toEqual([40, 80, 120, 160, 200]);
+ expect(w.cues.changes.map((c) => c.word)).toEqual([
+ "this",
+ "that",
+ "it",
+ "this",
+ "that",
+ ]);
+ const visible = (f: number) =>
+ [0, 1, 2].filter((i) => {
+ const n = find(w, `w-word-${i}`);
+ const o = keys(n, "opacity");
+ return (
+ (o.length ? at(o, f) : (n?.opacity ?? 1)) > 0 &&
+ at(keys(n, "y"), f) === 0
+ );
+ });
+ expect(visible(20)).toEqual([0]);
+ expect(visible(70)).toEqual([1]);
+ expect(visible(300)).toEqual([2]);
+ expect(w.span.end).toBe(Number.POSITIVE_INFINITY);
+ });
+
+ it("types: deletes, then types the next word", () => {
+ const w = make()({
+ id: "w",
+ text: "{}",
+ words: ["ab", "xyz"],
+ transition: "type",
+ every: 60,
+ });
+ const reveal = keys(find(w, "w-word-1"), "text");
+ expect(reveal.at(-1)?.[1]).toBe(1);
+ const slotW = keys(find(w, "w-slot"), "width");
+ expect(slotW.at(-1)?.[1]).toBeCloseTo(3 * G, 5);
+ });
+
+ it("rejects a line without one slot", () => {
+ expect(() => make()({ text: "no slot", words: ["a", "b"] })).toThrow(
+ /slot/,
+ );
+ });
+});
diff --git a/packages/components/src/word-cycle/index.ts b/packages/components/src/word-cycle/index.ts
new file mode 100644
index 00000000..77a8a456
--- /dev/null
+++ b/packages/components/src/word-cycle/index.ts
@@ -0,0 +1,374 @@
+/**
+ * WordCycle: one slot in a line cycles through words. The slot resizes to
+ * each word's measured width and the rest of the line glides to fit, so
+ * the sentence always reads as set type, never as a gap.
+ */
+import {
+ type KeyframeTuple,
+ LayerAnimation,
+ type LayoutNode,
+} from "@framefields/compositions/program";
+import { z } from "zod";
+import { defineComponent } from "../core/contract.js";
+import type { Animatable } from "../core/host.js";
+import { themeFrames } from "../core/theme.js";
+
+export const WORD_TRANSITIONS = ["roll", "fade", "slide", "type"] as const;
+export type WordTransition = (typeof WORD_TRANSITIONS)[number];
+export const WORD_SLOTS = ["plain", "pill", "underline"] as const;
+export type WordSlot = (typeof WORD_SLOTS)[number];
+
+export interface WordCycleCues {
+ [name: string]: ReadonlyArray<{ frame: number }>;
+ /** Each new word starts arriving. */
+ changes: ReadonlyArray<{ frame: number; index: number; word: string }>;
+}
+
+/** Keys per node stay under the program's 128-per-animation limit. */
+const MAX_KEYS = 120;
+
+export const wordCycle = /* @__PURE__ */ defineComponent({
+ name: "WordCycle",
+ props: () => ({
+ /** One line with one `{}` marking the slot. */
+ text: z
+ .string()
+ .refine((t) => t.split("{}").length === 2 && !t.includes("\n"), {
+ message: 'Expected one line with exactly one "{}" slot',
+ }),
+ words: z.array(z.string().min(1)).min(2),
+ /** Frames each word stays. Default 1.6 seconds. */
+ every: z.number().int().positive().optional(),
+ /** Passes through `words`; the last word stays. */
+ cycles: z.number().int().positive().default(1),
+ transition: z.enum(WORD_TRANSITIONS).default("roll"),
+ align: z.enum(["left", "center", "right"]).default("left"),
+ slot: z.enum(WORD_SLOTS).default("plain"),
+ color: z.string().optional(),
+ slotColor: z.string().optional(),
+ fontSize: z.number().positive().optional(),
+ fontFamily: z.string().optional(),
+ fontWeight: z.number().int().min(100).max(900).default(800),
+ }),
+ defaults: { enter: false, exit: false, hold: 30 },
+ build(ctx, props) {
+ const { host, theme, fps } = ctx;
+ const s = theme.scale;
+ const fs = props.fontSize ?? 96 * s;
+ const fontFamily = props.fontFamily ?? theme.font.display;
+ const ink = props.color ?? theme.color.ink;
+ const accent = props.slotColor ?? theme.color.accent;
+ const every = props.every ?? Math.round(fps * 1.6);
+ const base = themeFrames(theme, "base", fps);
+ const ease = theme.motion.ease.move;
+ const pill = props.slot === "pill";
+
+ // ── Measure ──────────────────────────────────────────────────────
+ const font = { fontFamily, fontSize: fs, fontWeight: props.fontWeight };
+ const measure = (t: string) => host.measure(t, font);
+ const [rawBefore = "", rawAfter = ""] = props.text.split("{}");
+ const before = rawBefore.trimEnd();
+ const after = rawAfter.trimStart();
+ // Spaces at the slot are measured, never trusted to a trailing space.
+ const space = measure("a a").width - measure("aa").width;
+ const lineH = measure("Ag").height;
+ const gapB = rawBefore !== before && before ? space : 0;
+ const gapA = rawAfter !== after && after ? space : 0;
+ const wB = before ? measure(before).width : 0;
+ const wA = after ? measure(after).width : 0;
+ const pad = pill ? fs * 0.24 : 0;
+ const widths = props.words.map((w) => measure(w).width);
+ const slotW = (i: number) => (widths[i] as number) + pad * 2;
+ const lineW = (i: number) => wB + gapB + slotW(i) + gapA + wA;
+ const W = Math.max(...props.words.map((_, i) => lineW(i)));
+ const H = lineH + (props.slot === "underline" ? fs * 0.14 : 0);
+ const offset = (i: number) =>
+ props.align === "left"
+ ? 0
+ : props.align === "center"
+ ? (W - lineW(i)) / 2
+ : W - lineW(i);
+
+ // ── Timeline ─────────────────────────────────────────────────────
+ const n = props.words.length;
+ const shown = Array.from({ length: n * props.cycles }, (_, k) => k % n);
+ const tr = Math.min(every - 1, props.transition === "type" ? 0 : base);
+ // For `type`: each word deletes, then types (frames per character).
+ const del = Math.max(1, Math.round(fps / 30));
+ const typ = Math.max(1, Math.round((fps / 30) * 2));
+ const changes = shown.slice(1).map((index, k) => ({
+ frame: (k + 1) * every,
+ index,
+ word: props.words[index] as string,
+ }));
+ const lastChange = changes[changes.length - 1]?.frame ?? 0;
+ const lastIndex = shown[shown.length - 1] as number;
+ const settle =
+ props.transition === "type"
+ ? lastChange +
+ (props.words[shown[shown.length - 2] as number] as string).length *
+ del +
+ (props.words[lastIndex] as string).length * typ
+ : lastChange + tr;
+
+ // Slot geometry over time: [frame, slot width] steps, eased (or per char for `type`).
+ const slotKeys: KeyframeTuple[] = [[0, slotW(0)]];
+ const lineKeys: KeyframeTuple[] = [[0, offset(0)]];
+ if (props.transition === "type") {
+ let prev = 0;
+ for (const c of changes) {
+ const out = props.words[prev] as string;
+ const inc = props.words[c.index] as string;
+ const mo = measure(out);
+ const mi = measure(inc);
+ for (let k = 1; k <= out.length; k++) {
+ const f = c.frame + k * del;
+ const w = mo.caretX(out.length - k) + pad * 2;
+ slotKeys.push([f, w, "hold"]);
+ }
+ const typeAt = c.frame + out.length * del;
+ for (let k = 1; k <= inc.length; k++) {
+ slotKeys.push([typeAt + k * typ, mi.caretX(k) + pad * 2, "hold"]);
+ }
+ // The line re-centres once, as the new word lands.
+ lineKeys.push(
+ [typeAt, offset(prev)],
+ [typeAt + inc.length * typ, offset(c.index), ease],
+ );
+ prev = c.index;
+ }
+ } else {
+ let prev = 0;
+ for (const c of changes) {
+ slotKeys.push(
+ [c.frame, slotW(prev)],
+ [c.frame + tr, slotW(c.index), ease],
+ );
+ lineKeys.push(
+ [c.frame, offset(prev)],
+ [c.frame + tr, offset(c.index), ease],
+ );
+ prev = c.index;
+ }
+ }
+ if (slotKeys.length > MAX_KEYS)
+ throw new Error(
+ `WordCycle: ${slotKeys.length} width keys exceed the ${MAX_KEYS}-key limit of one track. Use fewer \`cycles\` or shorter words.`,
+ );
+ const add = (keys: KeyframeTuple[], by: number): KeyframeTuple[] =>
+ keys.map(([f, v, e]) =>
+ e ? [f, round((v as number) + by), e] : [f, round((v as number) + by)],
+ ) as KeyframeTuple[];
+ const sum = (a: KeyframeTuple[], b: KeyframeTuple[], by = 0) => {
+ // After-text x = line offset + slot width (+ constants): key both tracks' frames.
+ const frames = [...new Set([...a, ...b].map((k) => k[0] as number))].sort(
+ (x, y) => x - y,
+ );
+ const at = (keys: KeyframeTuple[], f: number) => valueAt(keys, f);
+ return frames.map((f) => {
+ const k = [...a, ...b].find((key) => key[0] === f && key[2]);
+ const v = round(at(a, f) + at(b, f) + by);
+ return k ? ([f, v, k[2]] as KeyframeTuple) : ([f, v] as KeyframeTuple);
+ });
+ };
+
+ const parts: Record<string, Animatable<LayoutNode>> = {};
+ const children: LayoutNode[] = [];
+ const text = (name: string, content: string, x: number, fill: string) =>
+ host.text(content, {
+ id: ctx.partId(name),
+ position: "absolute",
+ x,
+ y: 0,
+ ...font,
+ fill,
+ });
+ const moving = props.align !== "left";
+
+ if (before) {
+ const node = text("before", before, offset(0), ink);
+ if (moving) node.animate(LayerAnimation.keys("x", lineKeys));
+ parts.before = node;
+ children.push(node);
+ }
+
+ // Slot decoration: a pill behind, or an underline under, sized like the slot.
+ const slotX = wB + gapB;
+ if (props.slot !== "plain") {
+ const deco = host.box({
+ id: ctx.partId(pill ? "pill" : "underline"),
+ position: "absolute",
+ x: offset(0) + slotX,
+ y: pill ? lineH * 0.06 : lineH + fs * 0.02,
+ width: slotW(0),
+ height: pill ? lineH * 0.9 : Math.max(3, fs * 0.07),
+ background: accent,
+ borderRadius: pill ? lineH * 0.45 : fs * 0.035,
+ });
+ deco.animate(
+ LayerAnimation.create()
+ .keys("x", add(lineKeys, slotX))
+ .keys("width", slotKeys),
+ );
+ parts[pill ? "pill" : "underline"] = deco;
+ children.push(deco);
+ }
+
+ // Words sit in a clip as wide as the slot, so a roll never shows outside it.
+ const wordFill = pill ? theme.color.bg : accent;
+ const wordNodes = props.words.map((word, i) => {
+ const node = text(`word-${i}`, word, pad, wordFill);
+ if (i !== 0) node.opacity = 0;
+ const anim = LayerAnimation.create();
+ const y: KeyframeTuple[] = [];
+ const x: KeyframeTuple[] = [];
+ const opacity: KeyframeTuple[] = [];
+ const reveal: KeyframeTuple[] = [];
+ const park = props.transition === "roll" ? lineH : 0;
+ const visibleAt0 = i === 0;
+ y.push([0, visibleAt0 ? 0 : park]);
+ opacity.push([0, visibleAt0 ? 1 : 0]);
+ if (props.transition === "type") reveal.push([0, visibleAt0 ? 1 : 0]);
+ let prev = 0;
+ for (const c of changes) {
+ const f = c.frame;
+ if (c.index === i) {
+ // Arrives.
+ if (props.transition === "roll") {
+ y.push(
+ [f - 1, park, "hold"],
+ [f, park, "hold"],
+ [f + tr, 0, theme.motion.ease.enter],
+ );
+ opacity.push([f, 1, "hold"]);
+ } else if (props.transition === "fade") {
+ y.push(
+ [f, fs * 0.12, "hold"],
+ [f + tr, 0, theme.motion.ease.enter],
+ );
+ opacity.push([f, 0, "hold"], [f + tr, 1, "power2.out"]);
+ } else if (props.transition === "slide") {
+ x.push(
+ [f, pad + slotW(c.index), "hold"],
+ [f + tr, pad, theme.motion.ease.enter],
+ );
+ opacity.push([f, 1, "hold"]);
+ } else {
+ const out = props.words[prev] as string;
+ const typeAt = f + out.length * del;
+ opacity.push([typeAt, 1, "hold"]);
+ for (let k = 1; k <= word.length; k++)
+ reveal.push([typeAt + k * typ, k / word.length, "hold"]);
+ }
+ } else if (prev === i) {
+ // Leaves.
+ if (props.transition === "roll") {
+ y.push(
+ [f, 0],
+ [f + tr, -lineH, theme.motion.ease.exit],
+ [f + tr + 1, park, "hold"],
+ );
+ opacity.push([f + tr, 1], [f + tr + 1, 0, "hold"]);
+ } else if (props.transition === "fade") {
+ y.push([f, 0], [f + tr, -fs * 0.12, theme.motion.ease.exit]);
+ opacity.push([f, 1], [f + tr, 0, "power2.in"]);
+ } else if (props.transition === "slide") {
+ x.push(
+ [f, pad],
+ [
+ f + tr,
+ pad - (widths[i] as number) - pad * 2,
+ theme.motion.ease.exit,
+ ],
+ );
+ opacity.push([f + tr, 1], [f + tr + 1, 0, "hold"]);
+ } else {
+ for (let k = 1; k <= word.length; k++)
+ reveal.push([
+ f + k * del,
+ (word.length - k) / word.length,
+ "hold",
+ ]);
+ opacity.push([f + word.length * del, 0, "hold"]);
+ }
+ }
+ prev = c.index;
+ }
+ if (y.length > 1) anim.keys("y", ascending(y));
+ if (x.length > 0) anim.keys("x", ascending([[0, pad], ...x]));
+ if (opacity.length > 1) anim.keys("opacity", ascending(opacity));
+ if (reveal.length > 1) anim.keys("text", ascending(reveal));
+ node.animate(anim);
+ parts[`word-${i}`] = node;
+ return node;
+ });
+ const clip = host.box({
+ id: ctx.partId("slot"),
+ position: "absolute",
+ x: offset(0) + slotX,
+ y: 0,
+ width: slotW(0),
+ height: H,
+ overflow: "hidden",
+ children: wordNodes,
+ });
+ clip.animate(
+ LayerAnimation.create()
+ .keys("x", add(lineKeys, slotX))
+ .keys("width", slotKeys),
+ );
+ parts.slot = clip;
+ children.push(clip);
+
+ if (after) {
+ const node = text(
+ "after",
+ after,
+ offset(0) + slotX + slotW(0) + gapA,
+ ink,
+ );
+ node.animate(
+ LayerAnimation.keys("x", sum(lineKeys, slotKeys, slotX + gapA)),
+ );
+ parts.after = node;
+ children.push(node);
+ }
+
+ return {
+ children,
+ width: W,
+ height: H,
+ duration: Math.max(1, settle),
+ openEnded: true,
+ cues: { changes } as WordCycleCues,
+ parts,
+ };
+ },
+});
+
+const round = (v: number) => Math.round(v * 1000) / 1000;
+
+/** Later keys on a shared frame win; frames ascend. */
+function ascending(keys: KeyframeTuple[]): KeyframeTuple[] {
+ const byFrame = new Map<number, KeyframeTuple>();
+ for (const k of keys) byFrame.set(k[0] as number, k);
+ return [...byFrame.values()].sort(
+ (a, b) => (a[0] as number) - (b[0] as number),
+ );
+}
+
+/** A keyed track's value at `f` (linear between keys, `hold` steps). */
+function valueAt(keys: readonly KeyframeTuple[], f: number): number {
+ const first = keys[0] as KeyframeTuple;
+ if (f <= (first[0] as number)) return first[1] as number;
+ for (let i = 0; i < keys.length - 1; i++) {
+ const [f0, v0] = keys[i] as KeyframeTuple;
+ const [f1, v1, e] = keys[i + 1] as KeyframeTuple;
+ if (f >= (f0 as number) && f <= (f1 as number)) {
+ if (e === "hold") return f === f1 ? (v1 as number) : (v0 as number);
+ const t = (f - (f0 as number)) / ((f1 as number) - (f0 as number));
+ return (v0 as number) + ((v1 as number) - (v0 as number)) * t;
+ }
+ }
+ return keys[keys.length - 1]?.[1] as number;
+}
diff --git a/packages/components/src/word-cycle/meta.ts b/packages/components/src/word-cycle/meta.ts
new file mode 100644
index 00000000..99755b2f
--- /dev/null
+++ b/packages/components/src/word-cycle/meta.ts
@@ -0,0 +1,19 @@
+import { defineMeta } from "../core/meta.js";
+
+export default defineMeta({
+ name: "WordCycle",
+ summary:
+ "One slot in a line cycles through words: rolled, faded, slid or retyped, while the slot resizes to each word and the line glides to fit.",
+ tags: [
+ "text",
+ "headline",
+ "rotating word",
+ "kinetic type",
+ "launch",
+ "typography",
+ ],
+ parts: ["before", "slot", "word-0", "after", "pill", "underline"],
+ cues: ["changes"],
+ example: `WordCycle({ text: "Make videos {}", words: ["faster", "together", "in code"] })`,
+ since: "M7",
+});
diff --git a/packages/framefields/scripts/check-components-treeshake.mjs b/packages/framefields/scripts/check-components-treeshake.mjs
index 18bfdcff..9bd775b4 100644
--- a/packages/framefields/scripts/check-components-treeshake.mjs
+++ b/packages/framefields/scripts/check-components-treeshake.mjs
@@ -34,10 +34,19 @@ const TOAST = "bottom-center";
const CALLOUT = "leader-2";
const SPOT = "radial-gradient(closest-side, #ffffff ";
const CONFETTI = "sparkles-";
+const LOGO = "LogoReveal: give a `mark`";
+const BACKDROP = "radial-gradient(rgba(0,0,0,0) 45%";
+const WAVE = "Waveform: the audio was analysed";
+const WORDS = "width keys exceed the";
+const DEVICE = "status-battery";
+const TOUCH = "-ripple-";
+const SPLIT = "before-clip";
+const SELECT = "Selection: give";
+const CARDS = "Expected a layer or { title";
/** Each component: a string only its module has, and what it may compose. */
const COMPONENTS = {
- MousePointer: { own: POINTER, uses: [], budget: 60_000 },
+ MousePointer: { own: POINTER, uses: [], budget: 62_000 },
AppFrame: { own: FRAME, uses: [], budget: 45_000 },
FocusZoom: { own: CAMERA, uses: [], budget: 40_000 },
TextReveal: { own: REVEAL, uses: [GLYPHS], budget: 55_000 },
@@ -54,6 +63,15 @@ const COMPONENTS = {
Callout: { own: CALLOUT, uses: [], budget: 50_000 },
Spotlight: { own: SPOT, uses: [], budget: 45_000 },
Confetti: { own: CONFETTI, uses: [], budget: 45_000 },
+ LogoReveal: { own: LOGO, uses: [GLYPHS], budget: 55_000 },
+ Backdrop: { own: BACKDROP, uses: [], budget: 45_000 },
+ Waveform: { own: WAVE, uses: [], budget: 50_000 },
+ WordCycle: { own: WORDS, uses: [], budget: 45_000 },
+ DeviceFrame: { own: DEVICE, uses: [], budget: 45_000 },
+ TouchPoint: { own: TOUCH, uses: [], budget: 45_000 },
+ BeforeAfter: { own: SPLIT, uses: [], budget: 40_000 },
+ Selection: { own: SELECT, uses: [], budget: 45_000 },
+ CardStack: { own: CARDS, uses: [], budget: 40_000 },
};
const OWN = Object.values(COMPONENTS).map((c) => c.own);
diff --git a/packages/framefields/src/components/audio.ts b/packages/framefields/src/components/audio.ts
new file mode 100644
index 00000000..d5c81b92
--- /dev/null
+++ b/packages/framefields/src/components/audio.ts
@@ -0,0 +1,21 @@
+/**
+ * `analyzeAudio`: decode a track and analyse it into `AudioLevels`, plain
+ * per-frame data for `Waveform` and `Captions` `pulse`. Offline and
+ * deterministic: the same file always gives the same levels.
+ */
+import {
+ type AnalyzeOptions,
+ type AudioLevels,
+ analyzeChannels,
+} from "@framefields/components";
+import { decodeAudioSource } from "@framefields/compositions";
+
+export async function analyzeAudio(
+ source: string,
+ options: AnalyzeOptions = {},
+): Promise<AudioLevels> {
+ const decoded = await decodeAudioSource(source);
+ if (!decoded || decoded.channels.length === 0)
+ throw new Error(`analyzeAudio: could not decode audio from ${source}`);
+ return analyzeChannels(decoded.channels, decoded.sampleRate, options);
+}
diff --git a/packages/framefields/src/components/host.ts b/packages/framefields/src/components/host.ts
index 4c50d26a..85d45e8a 100644
--- a/packages/framefields/src/components/host.ts
+++ b/packages/framefields/src/components/host.ts
@@ -4,12 +4,15 @@
* each call, never at module load, so importing this file has no effects.
*/
import type { Host, LayerStyleConfig } from "@framefields/components";
-import { LayerStyle } from "../effects/index.js";
+import { frameArraySignal } from "@framefields/core";
+import { FilmGrain, LayerStyle } from "../effects/index.js";
import { FontManager } from "../fonts/index.js";
import { autoId } from "../ids.js";
import { type AnimatableNode, Layer } from "../index.js";
+import { Layer3D } from "../shapes3d.js";
const IMAGE = /\.(png|jpe?g|webp|gif|avif|tiff?|bmp)(\?.*)?$/i;
+const SVG = /\.svg(\?.*)?$/i;
/** Every style the config names is switched on. */
function layerStyle(config: LayerStyleConfig): LayerStyle {
@@ -23,6 +26,15 @@ function layerStyle(config: LayerStyleConfig): LayerStyle {
} as ConstructorParameters<typeof LayerStyle>[0]);
}
+/** A mid-grey SVG as a data URL: neutral under soft-light, so only its grain shows. */
+function greySvg(width: number, height: number): string {
+ const w = Math.max(16, Math.round(width));
+ const h = Math.max(16, Math.round(height));
+ return `data:image/svg+xml;utf8,${encodeURIComponent(
+ `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}"><rect width="${w}" height="${h}" fill="#808080"/></svg>`,
+ )}`;
+}
+
export const host: Host = {
box: (options) => Layer.box(options),
flex: (options) => Layer.flex(options),
@@ -32,9 +44,11 @@ export const host: Host = {
fonts: () => FontManager.getAll().map((f) => f.family),
autoId,
media: (source, options) =>
- IMAGE.test(source)
- ? Layer.image(source, options)
- : Layer.video(source, { muted: true, ...options }),
+ SVG.test(source)
+ ? Layer.svg(source, options)
+ : IMAGE.test(source)
+ ? Layer.image(source, options)
+ : Layer.video(source, { muted: true, ...options }),
style: (node, config) => {
(node as unknown as AnimatableNode).withEffect(layerStyle(config));
return node;
@@ -55,6 +69,34 @@ export const host: Host = {
keyBackground: true,
}),
particles: (options) => Layer.particles(options),
+ // `Signal.fromArray` itself; the `Signal` namespace would pull every builder.
+ signal: (values, fps) => frameArraySignal([...values], fps),
+ grain: ({ id, x, y, width, height, strength, size }) =>
+ Layer.svg(greySvg(width, height), {
+ id,
+ position: "absolute",
+ x,
+ y,
+ width,
+ height,
+ fit: "fill",
+ blendMode: "soft-light",
+ }).withEffect(
+ new FilmGrain({
+ strength,
+ ...(size !== undefined && { size }),
+ shadows: 1,
+ midtones: 1,
+ highlights: 1,
+ }),
+ ),
+ extrudedText: ({ fontWeight, ...options }) =>
+ Layer3D.extrudedText({
+ ...options,
+ ...(fontWeight !== undefined && { fontWeight: String(fontWeight) }),
+ align: "center",
+ verticalAlign: "middle",
+ } as Parameters<typeof Layer3D.extrudedText>[0]),
matte: (node, matte, mode = "alpha") => {
(node as unknown as AnimatableNode).withMatte(matte, mode);
return node;
diff --git a/packages/framefields/src/components/index.ts b/packages/framefields/src/components/index.ts
index f4463c41..fcda7f2a 100644
--- a/packages/framefields/src/components/index.ts
+++ b/packages/framefields/src/components/index.ts
@@ -12,25 +12,34 @@ import {
annotate,
appFrame,
type BaseProps,
+ backdrop,
+ beforeAfter,
bind,
type ComponentDefinition,
type ComponentExtras,
type Cues,
callout,
captions,
+ cardStack,
chatThread,
codeBlock,
confetti,
counter,
+ deviceFrame,
focusZoom,
+ logoReveal,
lowerThird,
meter,
mousePointer,
+ selection,
spotlight,
terminal,
textReveal,
titleCard,
toasts,
+ touchPoint,
+ waveform,
+ wordCycle,
} from "@framefields/components";
import type { BoxNode } from "@framefields/compositions/program";
import type { z } from "zod";
@@ -106,7 +115,20 @@ export const Spotlight = /* @__PURE__ */ bindComponent(spotlight);
/** GPU confetti bursts: paper, ribbons and sparkles that fall and can settle. */
export const Confetti = /* @__PURE__ */ bindComponent(confetti);
+/** The end-card lockup: mark and wordmark in one move, drawn, popped or wiped, with a glint. */
+export const LogoReveal = /* @__PURE__ */ bindComponent(logoReveal);
+
+/** A drifting mesh gradient, grid or dot field with vignette and grain, looping exactly. */
+export const Backdrop = /* @__PURE__ */ bindComponent(backdrop);
+
+/** An audiogram: bars, mirrored bars, dots or a ring bound to a track's analysed spectrum. */
+export const Waveform = /* @__PURE__ */ bindComponent(waveform);
+
+/** One slot in a line cycles through words; the line glides to fit each one. */
+export const WordCycle = /* @__PURE__ */ bindComponent(wordCycle);
+
export {
+ type AnalyzeOptions,
type Anchor,
type AnnotateCues,
type AppFrameApi,
@@ -115,16 +137,24 @@ export {
type ArcPath,
type ArrowCurve,
type ArrowGeometry,
+ type AudioLevels,
+ analyzeChannels,
anchorPoint,
arcPath,
arrowPaths,
+ audioLevelsSchema,
+ BACKDROP_KINDS,
+ type BackdropCues,
+ type BackdropKind,
type BakedKey,
type BakeOptions,
type BaseProps,
+ type BeforeAfterCues,
type BuildContext,
type BuildResult,
bakeFunction,
bakeSamples,
+ bandEdges,
basePropsSchema,
beats,
boilKeys,
@@ -136,6 +166,7 @@ export {
type CalloutSide,
type CaptionStyle,
type CaptionsCues,
+ type CardStackCues,
type ChatThreadCues,
CODE_LANGS,
type CodeBlockCues,
@@ -157,7 +188,12 @@ export {
chain,
constantExpression,
contrastRatio,
+ cosineKeys,
cover,
+ DEVICES,
+ type Device,
+ type DeviceFrameApi,
+ type DeviceFrameCues,
defineComponent,
defineMeta,
defineTheme,
@@ -166,6 +202,7 @@ export {
type EaseFn,
EXIT_STYLES,
type ExitStyle,
+ type ExtrudedTextOptions,
ease,
ellipsePath,
enterAnimation,
@@ -181,11 +218,17 @@ export {
type GlyphAnimator,
type GlyphProps,
type GlyphUnit,
+ type GrainOptions,
glyphAnimator,
type HandOptions,
hashRng,
hashString,
+ LOGO_LAYOUTS,
+ LOGO_STYLES,
LOWER_THIRD_LAYOUTS,
+ type LogoLayout,
+ type LogoRevealCues,
+ type LogoStyle,
type LowerThirdCues,
type LowerThirdLayout,
lerp2,
@@ -208,8 +251,10 @@ export {
offsetCues,
type ParticleOptions,
type Placement,
+ type PlannedTouch,
type PropsOf,
type PulseOptions,
+ planTouches,
pulseKeys,
quantize,
REVEAL_STYLES,
@@ -219,13 +264,18 @@ export {
type RevealStyle,
type Rng,
rangeRects,
+ resampleBands,
resolveMotion,
resolveTarget,
rng,
+ type SelectionCues,
+ type SelectionPointer,
type SpotlightCues,
type StaggerOrder,
scaleFrames,
scheduleExpression,
+ slideKeys,
+ smoothRelease,
springAt,
springKeys,
springSettleFrames,
@@ -238,6 +288,7 @@ export {
type TargetContext,
type TerminalCues,
type TerminalStep,
+ type TextLayout,
type TextRevealApi,
type TextRevealCues,
type Theme,
@@ -253,7 +304,9 @@ export {
type ToastsCues,
type Token,
type TokenKind,
+ type TouchPointCues,
targetPoint,
+ textLayout,
themeFrames,
themes,
toFrames,
@@ -263,11 +316,35 @@ export {
typingFrames,
type UnitSchedule,
type Vec2,
+ WAVEFORM_KINDS,
+ type WaveformCues,
+ type WaveformKind,
type Waypoint,
+ WORD_SLOTS,
+ WORD_TRANSITIONS,
type Word,
+ type WordCycleCues,
type WordRange,
+ type WordSlot,
+ type WordTransition,
windowExpression,
within,
wobblePoints,
wordRanges,
} from "@framefields/components";
+/** A phone, tablet or laptop around a screen; content in device points, `at(x, y)` for touches. */
+export const DeviceFrame = /* @__PURE__ */ bindComponent(deviceFrame);
+
+/** Taps, long presses and swipes as soft discs with ripples, for mobile demos. */
+export const TouchPoint = /* @__PURE__ */ bindComponent(touchPoint);
+
+/** Two versions of one picture split by a moving divider, with a grip and labels. */
+export const BeforeAfter = /* @__PURE__ */ bindComponent(beforeAfter);
+
+/** A text selection or marquee that follows a MousePointer drag. */
+export const Selection = /* @__PURE__ */ bindComponent(selection);
+
+/** Cards in a depth stack that shuffle forward or are dealt onto the pile. */
+export const CardStack = /* @__PURE__ */ bindComponent(cardStack);
+
+export { analyzeAudio } from "./audio.js";
diff --git a/packages/framefields/src/components/m7.render.test.ts b/packages/framefields/src/components/m7.render.test.ts
new file mode 100644
index 00000000..c3cdafc7
--- /dev/null
+++ b/packages/framefields/src/components/m7.render.test.ts
@@ -0,0 +1,232 @@
+import type { AudioLevels } from "@framefields/components";
+import { beforeAll, describe, expect, it } from "vitest";
+import { FontManager } from "../fonts/index.js";
+import { Composition } from "../index.js";
+import { computeMse, decodePngPixels, getPixel } from "../test-utils/pixels.js";
+import {
+ Backdrop,
+ Captions,
+ LogoReveal,
+ Waveform,
+ WordCycle,
+} from "./index.js";
+
+/**
+ * Render tests for the M7 components: the lockup's name waits behind the
+ * mark, draw and pop settle on the same frame, backdrops loop exactly, bars
+ * follow their band on the composition's clock, a word roll stays inside
+ * its slot, and the voice pulse only moves the active word.
+ */
+beforeAll(async () => {
+ await FontManager.register("assets/fonts/Inter.ttf");
+});
+function comp(nodes: Parameters<Composition["add"]>[0], durationMs = 12000) {
+ const c = new Composition({
+ width: 960,
+ height: 540,
+ fps: 30,
+ durationMs,
+ backgroundColor: "#0d0e11",
+ });
+ c.add(nodes);
+ return c;
+}
+const frame = async (c: Composition, n: number) =>
+ decodePngPixels(await c.renderFrame({ frame: n }));
+type Image = Awaited<ReturnType<typeof frame>>;
+
+/** Pixels in a rect brighter than the background. */
+function lit(img: Image, x0: number, y0: number, x1: number, y1: number) {
+ let n = 0;
+ for (let y = Math.round(y0); y < y1; y += 2)
+ for (let x = Math.round(x0); x < x1; x += 2) {
+ const p = getPixel(img, x, y);
+ if (p.r + p.g + p.b > 120) n++;
+ }
+ return n;
+}
+
+const MARK = {
+ d: "M0 0L100 0L100 100L0 100Z",
+ viewBox: [100, 100] as [number, number],
+ color: "#ffffff",
+};
+
+describe("LogoReveal (render)", () => {
+ it("slide: the name stays hidden until the mark glides", async () => {
+ const logo = LogoReveal({
+ x: 100,
+ y: 200,
+ mark: MARK,
+ name: "frames",
+ markSize: 80,
+ nameSize: 80,
+ glint: false,
+ });
+ const c = comp(logo);
+ const W = logo.width as number;
+ // Right of the centred mark, inside the name's final box.
+ const region = [100 + (W + 80) / 2 + 4, 200, 100 + W, 200 + 100] as const;
+ const before = await frame(c, 10);
+ expect(lit(before, ...region)).toBe(0);
+ const after = await frame(c, (logo.cues.revealed[0]?.frame ?? 0) + 5);
+ expect(lit(after, ...region)).toBeGreaterThan(20);
+ });
+
+ it("a path mark settles identically drawn or popped", async () => {
+ const at = (style: "draw" | "pop") =>
+ frame(
+ comp(LogoReveal({ x: 200, y: 180, mark: MARK, name: "frames", style })),
+ 300,
+ );
+ const draw = await at("draw");
+ const pop = await at("pop");
+ expect(computeMse(draw.pixels, pop.pixels)).toBeLessThan(0.5);
+ });
+
+ it("extrudes the name in 3D", async () => {
+ const logo = LogoReveal({
+ x: 180,
+ y: 200,
+ name: "frames",
+ depth: 30,
+ nameSize: 100,
+ });
+ const img = await frame(comp(logo), 200);
+ expect(
+ lit(img, 180, 200, 180 + (logo.width as number), 320),
+ ).toBeGreaterThan(20);
+ });
+});
+
+describe("Backdrop (render)", () => {
+ for (const kind of ["mesh", "grid", "dots"] as const)
+ it(`${kind}: frame f equals frame f + loop`, async () => {
+ const c = comp(
+ Backdrop({ kind, loop: 60, grain: false, width: 960, height: 540 }),
+ );
+ for (const f of [7, 33]) {
+ const a = await frame(c, f);
+ const b = await frame(c, f + 60);
+ expect(computeMse(a.pixels, b.pixels)).toBe(0);
+ }
+ });
+
+ it("grains the surface", async () => {
+ const at = (grain: number | false) =>
+ frame(
+ comp(Backdrop({ kind: "solid", grain, width: 960, height: 540 })),
+ 5,
+ );
+ const clean = await at(false);
+ expect(computeMse((await at(0.6)).pixels, clean.pixels)).toBeGreaterThan(0);
+ });
+
+ it("seeds the mesh", async () => {
+ const at = (seed: number) =>
+ frame(
+ comp(Backdrop({ seed, grain: false, width: 960, height: 540 })),
+ 20,
+ );
+ const one = await at(1);
+ expect(computeMse(one.pixels, (await at(1)).pixels)).toBe(0);
+ expect(computeMse(one.pixels, (await at(2)).pixels)).toBeGreaterThan(0);
+ });
+});
+
+describe("Waveform (render)", () => {
+ // One band: full on audio frame 10, silent on 20.
+ const audio: AudioLevels = {
+ fps: 30,
+ frames: 40,
+ bands: [Array.from({ length: 40 }, (_, f) => (f === 10 ? 1 : 0))],
+ level: new Array(40).fill(0),
+ beats: [],
+ };
+ const bar = (at: number) =>
+ Waveform({
+ at,
+ x: 400,
+ y: 100,
+ width: 100,
+ height: 300,
+ audio,
+ kind: "bars",
+ floor: 0,
+ smoothing: 0,
+ color: "#ffffff",
+ });
+
+ it("a bar's height follows its band on the composition's clock", async () => {
+ for (const at of [0, 15]) {
+ const c = comp(bar(at));
+ const top = await frame(c, at + 10);
+ expect(lit(top, 420, 110, 480, 140)).toBeGreaterThan(10);
+ const quiet = await frame(c, at + 20);
+ expect(lit(quiet, 400, 100, 500, 400)).toBe(0);
+ }
+ });
+});
+
+describe("WordCycle (render)", () => {
+ const cycle = (words: string[], transition: "roll" | "fade" = "roll") =>
+ WordCycle({
+ x: 100,
+ y: 200,
+ text: "Make it {} now",
+ words,
+ every: 40,
+ fontSize: 64,
+ transition,
+ });
+
+ it("shows only the current word at rest", async () => {
+ const a = await frame(comp(cycle(["fast", "beta"])), 20);
+ const b = await frame(comp(cycle(["fast", "zeta"])), 20);
+ expect(computeMse(a.pixels, b.pixels)).toBe(0);
+ });
+
+ it("a roll never shows a word outside the slot", async () => {
+ const node = cycle(["fast", "together"]);
+ const c = comp(node);
+ const mid = await frame(c, 40 + 4);
+ const H = node.height as number;
+ // Above and below the line, across its whole width.
+ expect(lit(mid, 100, 120, 100 + (node.width as number), 198)).toBe(0);
+ expect(lit(mid, 100, 200 + H + 2, 100 + (node.width as number), 400)).toBe(
+ 0,
+ );
+ // And the incoming word is on its way inside it.
+ expect(
+ lit(mid, 100, 200, 100 + (node.width as number), 200 + H),
+ ).toBeGreaterThan(0);
+ });
+});
+
+describe("Captions pulse (render)", () => {
+ const words = "one two three"
+ .split(" ")
+ .map((text, i) => ({ text, start: i * 0.5, end: i * 0.5 + 0.45 }));
+ const levels = (v: number): AudioLevels => ({
+ fps: 30,
+ frames: 60,
+ bands: [],
+ level: new Array(60).fill(v),
+ beats: [],
+ });
+ const at = (pulse: AudioLevels | false) =>
+ frame(
+ comp(
+ Captions({ words, pulse, style: "karaoke", width: 960, height: 540 }),
+ ),
+ 20,
+ );
+
+ it("moves the active word only with the voice", async () => {
+ const none = await at(false);
+ expect(computeMse((await at(levels(0))).pixels, none.pixels)).toBe(0);
+ expect(
+ computeMse((await at(levels(1))).pixels, none.pixels),
+ ).toBeGreaterThan(0);
+ });
+});
diff --git a/packages/framefields/src/components/m8.render.test.ts b/packages/framefields/src/components/m8.render.test.ts
new file mode 100644
index 00000000..cafc98b3
--- /dev/null
+++ b/packages/framefields/src/components/m8.render.test.ts
@@ -0,0 +1,175 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { FontManager } from "../fonts/index.js";
+import { Composition, Layer } from "../index.js";
+import { computeMse, decodePngPixels, getPixel } from "../test-utils/pixels.js";
+import {
+ BeforeAfter,
+ CardStack,
+ DeviceFrame,
+ Selection,
+ TouchPoint,
+} from "./index.js";
+
+/**
+ * Render tests for the M8 components: device content fills exactly the
+ * screen, touches leave nothing behind, the split shows each side on its
+ * own side of the divider, a selection draws, and a full card cycle comes
+ * back to the frame it started on.
+ */
+beforeAll(async () => {
+ await FontManager.register("assets/fonts/Inter.ttf");
+});
+function comp(nodes: Parameters<Composition["add"]>[0]) {
+ const c = new Composition({
+ width: 960,
+ height: 540,
+ fps: 30,
+ durationMs: 12000,
+ backgroundColor: "#0d0e11",
+ });
+ c.add(nodes);
+ return c;
+}
+const frame = async (c: Composition, n: number) =>
+ decodePngPixels(await c.renderFrame({ frame: n }));
+const red = (p: { r: number; g: number; b: number }) =>
+ p.r > 200 && p.g < 60 && p.b < 60;
+
+describe("DeviceFrame (render)", () => {
+ it("content authored in points fills the screen, and nothing else", async () => {
+ const phone = DeviceFrame({
+ x: 380,
+ y: 20,
+ height: 500,
+ enter: false,
+ elevation: 0,
+ statusBar: false,
+ island: false,
+ content: Layer.box({
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 393,
+ height: 852,
+ background: "#ff0000",
+ }),
+ });
+ const r = phone.screenRect;
+ const img = await frame(comp(phone), 0);
+ const cx = r.x + r.width / 2;
+ const cy = r.y + r.height / 2;
+ expect(red(getPixel(img, Math.round(cx), Math.round(cy)))).toBe(true);
+ // Just inside each edge (mid-side, clear of the rounded corners).
+ expect(red(getPixel(img, Math.round(r.x + 2), Math.round(cy)))).toBe(true);
+ expect(
+ red(getPixel(img, Math.round(r.x + r.width - 3), Math.round(cy))),
+ ).toBe(true);
+ expect(red(getPixel(img, Math.round(cx), Math.round(r.y + 2)))).toBe(true);
+ // Just outside: bezel, not content.
+ expect(red(getPixel(img, Math.round(r.x - 3), Math.round(cy)))).toBe(false);
+ expect(
+ red(getPixel(img, Math.round(cx), Math.round(r.y + r.height + 3))),
+ ).toBe(false);
+ });
+});
+
+describe("TouchPoint (render)", () => {
+ it("draws only while a finger is down", async () => {
+ const t = TouchPoint({
+ width: 960,
+ height: 540,
+ touches: [{ to: [480, 270], at: 30 }],
+ });
+ const c = comp(t);
+ const empty = await frame(comp([]), 0);
+ expect(computeMse((await frame(c, 10)).pixels, empty.pixels)).toBe(0);
+ expect(
+ computeMse((await frame(c, 31)).pixels, empty.pixels),
+ ).toBeGreaterThan(0);
+ expect(
+ computeMse((await frame(c, t.span.duration + 2)).pixels, empty.pixels),
+ ).toBe(0);
+ });
+});
+
+describe("BeforeAfter (render)", () => {
+ const side = (color: string) =>
+ Layer.box({
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 960,
+ height: 540,
+ background: color,
+ });
+
+ it("shows before left of the divider and after right of it", async () => {
+ const ba = BeforeAfter({
+ width: 960,
+ height: 540,
+ before: side("#ff0000"),
+ after: side("#0000ff"),
+ split: [
+ [0, 0.3],
+ [30, 0.7, "power2.inOut"],
+ ],
+ handle: false,
+ labels: false,
+ });
+ const c = comp(ba);
+ for (const [f, at] of [
+ [0, 0.3],
+ [30, 0.7],
+ ] as const) {
+ const img = await frame(c, f);
+ const x = 960 * at;
+ expect(red(getPixel(img, Math.round(x - 8), 270))).toBe(true);
+ const right = getPixel(img, Math.round(x + 8), 270);
+ expect(right.b > 200 && right.r < 60).toBe(true);
+ }
+ });
+});
+
+describe("Selection (render)", () => {
+ it("highlights the selected text", async () => {
+ const text = Layer.text("select these words", {
+ position: "absolute",
+ x: 100,
+ y: 200,
+ fontFamily: "Inter",
+ fontSize: 48,
+ fill: "#ffffff",
+ });
+ const sel = Selection({
+ width: 960,
+ height: 540,
+ target: { text, match: "these" },
+ drag: { frame: 0, end: 20 },
+ color: "#3b82f6",
+ });
+ const plain = await frame(comp(text), 30);
+ const lit = await frame(comp([sel, text]), 30);
+ expect(computeMse(plain.pixels, lit.pixels)).toBeGreaterThan(0);
+ const before = await frame(comp([sel, text]), 0);
+ expect(computeMse(plain.pixels, before.pixels)).toBe(0);
+ });
+});
+
+describe("CardStack (render)", () => {
+ it("a full cycle comes back to the starting frame", async () => {
+ const stack = CardStack({
+ x: 160,
+ y: 0,
+ cards: [{ title: "One" }, { title: "Two" }, { title: "Three" }],
+ every: 40,
+ cardWidth: 420,
+ cardHeight: 260,
+ });
+ const c = comp(stack);
+ const first = await frame(c, 0);
+ const back = await frame(c, (stack.cues.changes.at(-1)?.frame ?? 0) + 80);
+ expect(computeMse(first.pixels, back.pixels)).toBeLessThan(0.5);
+ const mid = await frame(c, 40 + 10);
+ expect(computeMse(first.pixels, mid.pixels)).toBeGreaterThan(0);
+ });
+});
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index 08914347..b8a9ef68 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -3403,6 +3403,13 @@ export {
type AppFrameApi,
type AppFrameCues,
type AppFrameKind,
+ type AudioLevels,
+ analyzeAudio,
+ Backdrop,
+ type BackdropCues,
+ type BackdropKind,
+ BeforeAfter,
+ type BeforeAfterCues,
bindComponent,
CAPTION_STYLES,
Callout,
@@ -3410,6 +3417,8 @@ export {
type CaptionStyle,
Captions,
type CaptionsCues,
+ CardStack,
+ type CardStackCues,
ChatThread,
type ChatThreadCues,
CodeBlock,
@@ -3423,10 +3432,15 @@ export {
type CounterFormat,
CURSOR_STYLES,
type CursorStyle,
+ DeviceFrame,
+ type DeviceFrameApi,
FocusZoom,
type FocusZoomApi,
type FocusZoomCues,
type Followable,
+ LogoReveal,
+ type LogoRevealCues,
+ type LogoStyle,
LowerThird,
type LowerThirdCues,
type LowerThirdLayout,
@@ -3437,6 +3451,8 @@ export {
type MousePointerApi,
type MousePointerCues,
type RevealStyle,
+ Selection,
+ type SelectionCues,
Spotlight,
type SpotlightCues,
Terminal,
@@ -3450,5 +3466,13 @@ export {
type TitleLayout,
Toasts,
type ToastsCues,
+ TouchPoint,
+ type TouchPointCues,
+ Waveform,
+ type WaveformCues,
+ type WaveformKind,
type Waypoint,
+ WordCycle,
+ type WordCycleCues,
+ type WordTransition,
} from "./components/index.js";
diff --git a/packages/framefields/src/overflow-clip.test.ts b/packages/framefields/src/overflow-clip.test.ts
index e81f6e9f..1f51ecf0 100644
--- a/packages/framefields/src/overflow-clip.test.ts
+++ b/packages/framefields/src/overflow-clip.test.ts
@@ -15,7 +15,13 @@ async function pixel(png: Buffer, x: number, y: number) {
}
function clipped(radius: number, animated: boolean) {
- const comp = new Composition({ width: 400, height: 400, fps: 30, durationFrames: 30, backgroundColor: "#000000" });
+ const comp = new Composition({
+ width: 400,
+ height: 400,
+ fps: 30,
+ durationFrames: 30,
+ backgroundColor: "#000000",
+ });
const box = Layer.box({
id: "clip",
position: "absolute",
@@ -25,9 +31,28 @@ function clipped(radius: number, animated: boolean) {
height: 200,
overflow: "hidden",
borderRadius: animated ? 0 : radius,
- children: [Layer.box({ id: "fill", position: "absolute", x: 0, y: 0, width: 200, height: 200, background: "#ffffff" })],
+ children: [
+ Layer.box({
+ id: "fill",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 200,
+ height: 200,
+ background: "#ffffff",
+ }),
+ ],
});
- comp.add(animated ? box.animate(LayerAnimation.create().fromTo("borderRadius", 0, radius, { start: 0, end: 10 })) : box);
+ comp.add(
+ animated
+ ? box.animate(
+ LayerAnimation.create().fromTo("borderRadius", 0, radius, {
+ start: 0,
+ end: 10,
+ }),
+ )
+ : box,
+ );
return comp;
}
@@ -40,7 +65,56 @@ describe("overflow clipping", () => {
it("clips children to an animated border radius", async () => {
const comp = clipped(100, true);
- expect(await pixel(await comp.renderFrame({ frame: 0 }), 104, 104)).toEqual([255, 255, 255]);
- expect(await pixel(await comp.renderFrame({ frame: 20 }), 104, 104)).toEqual([0, 0, 0]);
+ expect(await pixel(await comp.renderFrame({ frame: 0 }), 104, 104)).toEqual(
+ [255, 255, 255],
+ );
+ expect(
+ await pixel(await comp.renderFrame({ frame: 20 }), 104, 104),
+ ).toEqual([0, 0, 0]);
+ });
+
+ it("clips grandchildren to an outer container, not just children", async () => {
+ const comp = new Composition({
+ width: 400,
+ height: 200,
+ fps: 30,
+ durationFrames: 10,
+ backgroundColor: "#000000",
+ });
+ comp.add(
+ Layer.box({
+ id: "outer",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 100,
+ height: 200,
+ overflow: "hidden",
+ children: [
+ Layer.box({
+ id: "inner",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 400,
+ height: 200,
+ children: [
+ Layer.box({
+ id: "fill",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 400,
+ height: 200,
+ background: "#ffffff",
+ }),
+ ],
+ }),
+ ],
+ }),
+ );
+ const png = await comp.renderFrame({ frame: 0 });
+ expect(await pixel(png, 50, 100)).toEqual([255, 255, 255]);
+ expect(await pixel(png, 300, 100)).toEqual([0, 0, 0]);
});
});
diff --git a/packages/webgpu-renderers/src/renderer2d/index.ts b/packages/webgpu-renderers/src/renderer2d/index.ts
index 7c291323..944c9b9a 100644
--- a/packages/webgpu-renderers/src/renderer2d/index.ts
+++ b/packages/webgpu-renderers/src/renderer2d/index.ts
@@ -477,6 +477,31 @@ export class Renderer2D {
this.clipStack.pushScissor(rect, this.surfaceWidth, this.surfaceHeight);
}
+ /**
+ * Push `rect` (surface px) intersected with the current scissor, so a
+ * nested container never draws outside an outer one's clip.
+ */
+ pushScissorIntersect(rect: Rect): void {
+ const current = this.clipStack.getCurrentScissor(
+ this.surfaceWidth,
+ this.surfaceHeight,
+ );
+ if (!current) {
+ this.pushScissor(rect);
+ return;
+ }
+ const x = Math.max(rect.x, current.x);
+ const y = Math.max(rect.y, current.y);
+ const x2 = Math.min(rect.x + rect.width, current.x + current.width);
+ const y2 = Math.min(rect.y + rect.height, current.y + current.height);
+ this.pushScissor({
+ x,
+ y,
+ width: Math.max(0, x2 - x),
+ height: Math.max(0, y2 - y),
+ });
+ }
+
pushScissorLocal(rect: Rect): void {
const m = this.transformStack.getCurrent();
const points = [