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.tsindex 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.mdindex 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 3Specified 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 astandalone 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 (bodyweight 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 theflutter 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 = [