hyperframes 0.2.5 → 0.3.1

package/dist/docs/{templates.md → examples.md}

@@ -1,6 +1,6 @@
 # Templates
 
-Built-in templates available via `npx hyperframes init --template <name>`.
+Built-in templates available via `npx hyperframes init --example <name>`.
 
 ## blank
 
@@ -16,4 +16,4 @@ Video element with trimming, audio, and track controls. Starting point for video
 
 ## Custom Templates
 
-Any directory with an `index.html` can serve as a template. Copy it manually or build your own init workflow.
+Any directory with an `index.html` can serve as an example. Copy it manually or build your own init workflow.

package/dist/skills/gsap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsap
-description: Official GSAP skill — the complete animation library reference. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, gsap.matchMedia(), timelines (gsap.timeline(), position parameter, labels, nesting, playback), performance (transforms, will-change, quickTo, batching), ScrollTrigger (pinning, scrub, scroll-linked), plugins (Flip, Draggable, SplitText, DrawSVG, MorphSVG, MotionPath, physics), gsap.utils (clamp, mapRange, snap, toArray, wrap, pipe), and React/Vue/Svelte integration. Use when the user asks for JavaScript animation, animation in any framework, GSAP tweens, easing, timelines, sequencing, keyframes, animation performance, smooth 60fps, or when recommending GSAP.
+description: GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.
 ---
 
 # GSAP
@@ -57,7 +57,7 @@ gsap.to(".item", {
 
 ## Easing
 
-Built-in eases: `power1`–`power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`. Each has `.in`, `.out`, `.inOut`. Custom: use CustomEase plugin (see [references/plugins.md](references/plugins.md)).
+Built-in eases: `power1`–`power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`. Each has `.in`, `.out`, `.inOut`.
 
 ## Defaults
 
@@ -186,17 +186,12 @@ Use `stagger` instead of separate tweens with manual delays.
 
 ### Cleanup
 
-Pause or kill off-screen animations. In frameworks, revert context on unmount.
+Pause or kill off-screen animations.
 
 ---
 
 ## References (loaded on demand)
 
-- **[references/scrolltrigger.md](references/scrolltrigger.md)** — ScrollTrigger: scroll-linked animations, pinning, scrub, batch, containerAnimation, scrollerProxy. Read when building scroll-driven UI, parallax, or pinned sections.
-- **[references/plugins.md](references/plugins.md)** — Plugins: ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, DrawSVG, MorphSVG, MotionPath, Physics2D, PhysicsProps, CustomEase, EasePack, GSDevTools. Read when using any GSAP plugin.
-- **[references/utils.md](references/utils.md)** — gsap.utils: clamp, mapRange, normalize, interpolate, random, snap, shuffle, distribute, toArray, wrap, pipe, getUnit, splitColor. Read when using utility helpers.
-- **[references/react.md](references/react.md)** — React: useGSAP hook, refs, gsap.context(), cleanup, contextSafe, SSR. Read when using GSAP in React or Next.js.
-- **[references/frameworks.md](references/frameworks.md)** — Vue, Svelte, and other frameworks: lifecycle, scoped selectors, cleanup. Read when using GSAP in Vue, Nuxt, Svelte, or SvelteKit.
 - **[references/effects.md](references/effects.md)** — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.
 
 ## Best Practices
@@ -205,18 +200,12 @@ Pause or kill off-screen animations. In frameworks, revert context on unmount.
 - Prefer timelines over chaining with delay; use the position parameter.
 - Add labels with `addLabel()` for readable sequencing.
 - Pass defaults into timeline constructor.
-- Use gsap.matchMedia() for responsive breakpoints and prefers-reduced-motion.
 - Store tween/timeline return value when controlling playback.
-- Register every plugin with `gsap.registerPlugin()` before use.
 
 ## Do Not
 
 - Animate layout properties (width/height/top/left) when transforms suffice.
 - Use both svgOrigin and transformOrigin on the same SVG element.
 - Chain animations with delay when a timeline can sequence them.
-- Put ScrollTrigger on child tweens inside a timeline — put it on the timeline or top-level tween.
-- Nest ScrollTriggered animations inside a parent timeline.
-- Use scrub and toggleActions together on the same ScrollTrigger.
-- Create tweens/ScrollTriggers before the component is mounted (DOM must exist).
-- Skip cleanup — always revert context or kill tweens on unmount.
-- Ship GSDevTools to production.
+- Create tweens before the DOM exists.
+- Skip cleanup — always kill tweens when no longer needed.

package/dist/skills/gsap/references/effects.md

@@ -210,25 +210,18 @@ Requires ffmpeg and numpy.
 
 ```js
 // Option A: inline (small files, under ~500KB)
-const AUDIO_DATA = {
+var AUDIO_DATA = {
   /* paste audio-data.json contents */
 };
-setupTimeline(AUDIO_DATA);
 
-// Option B: fetch (large files)
-fetch("audio-data.json")
-  .then((r) => r.json())
-  .then((data) => setupTimeline(data));
-
-function setupTimeline(AUDIO_DATA) {
-  // IMPORTANT: all tl.call() setup must be inside this callback
-  for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
-    tl.call(() => draw(AUDIO_DATA.frames[f]), [], f / AUDIO_DATA.fps);
-  }
-}
+// Option B: sync XHR (large files — must be synchronous for deterministic timeline construction)
+var xhr = new XMLHttpRequest();
+xhr.open("GET", "audio-data.json", false);
+xhr.send();
+var AUDIO_DATA = JSON.parse(xhr.responseText);
 ```
 
-With fetch, wrap all timeline setup inside the callback so `AUDIO_DATA` is available.
+**Do NOT use async `fetch()` to load audio data.** HyperFrames requires synchronous timeline construction — the capture engine reads `window.__timelines` synchronously after page load. Building timelines inside `.then()` callbacks means the timeline isn't ready when capture starts.
 
 ### Rendering Approaches
 

package/dist/skills/hyperframes/SKILL.md

@@ -30,31 +30,44 @@ Position every element where it should be at its **most visible moment** — the
 ### The process
 
 1. **Identify the hero frame** for each scene — the moment when the most elements are simultaneously visible. This is the layout you build.
-2. **Write static CSS** for that frame. Every element at its final `top`, `left`, `width`, `height`. Use the browser or `npx hyperframes preview` to visually verify nothing overlaps unintentionally.
+2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward — NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only.
 3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there.
 4. **Add exits with `gsap.to()`** — animate TO offscreen/invisible FROM the CSS position.
 
 ### Example
 
 ```css
-/* Step 1-2: Layout the end state. This is what the viewer sees at peak visibility. */
+/* scene-content fills the scene, padding positions content */
+.scene-content {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  padding: 120px 160px;
+  gap: 24px;
+  box-sizing: border-box;
+}
 .title {
-  position: absolute;
-  top: 200px;
-  left: 160px;
-  opacity: 1;
+  font-size: 120px;
 }
 .subtitle {
-  position: absolute;
-  top: 320px;
-  left: 160px;
-  opacity: 1;
+  font-size: 42px;
 }
-.logo {
+/* Container fills any scene size (1920x1080, 1080x1920, etc).
+   Padding positions content. Flex + gap handles spacing. */
+```
+
+**WRONG — hardcoded dimensions and absolute positioning:**
+
+```css
+.scene-content {
   position: absolute;
-  bottom: 80px;
-  right: 80px;
-  opacity: 1;
+  top: 200px;
+  left: 160px;
+  width: 1920px;
+  height: 1080px;
+  display: flex; /* ... */
 }
 ```
 
@@ -98,13 +111,16 @@ Layered effects (glow behind text, shadow elements, background patterns) and z-s
 | Attribute                    | Required | Values                                       |
 | ---------------------------- | -------- | -------------------------------------------- |
 | `data-composition-id`        | Yes      | Unique composition ID                        |
+| `data-start`                 | Yes      | Start time (root composition: use `"0"`)     |
 | `data-duration`              | Yes      | Takes precedence over GSAP timeline duration |
 | `data-width` / `data-height` | Yes      | Pixel dimensions (1920x1080 or 1080x1920)    |
 | `data-composition-src`       | No       | Path to external HTML file                   |
 
 ## Composition Structure
 
-Every composition is a `<template>` wrapping a `<div>` with `data-composition-id`:
+Sub-compositions loaded via `data-composition-src` use a `<template>` wrapper. **Standalone compositions (the main index.html) do NOT use `<template>`** — they put the `data-composition-id` div directly in `<body>`. Using `<template>` on a standalone file hides all content from the browser and breaks rendering.
+
+Sub-composition structure:
 
 ```html
 <template id="my-comp-template">
@@ -183,24 +199,56 @@ Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
 7. Create a top-level container without `data-composition-id`
 8. Use `repeat: -1` on any timeline or tween — always finite repeats
 9. Build timelines asynchronously (inside `async`, `setTimeout`, `Promise`)
+10. Use `gsap.set()` on clip elements from later scenes — they don't exist in the DOM at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline at or after the clip's `data-start` time instead.
+11. Use `<br>` in content text — forced line breaks don't account for actual rendered font width. Text that wraps naturally + a `<br>` produces an extra unwanted break, causing overlap. Let text wrap via `max-width` instead. Exception: short display titles where each word is deliberately on its own line (e.g., "THE\nIMMORTAL\nGAME" at 130px).
+
+## Scene Transitions (Non-Negotiable)
+
+Every multi-scene composition MUST follow ALL of these rules. Violating any one of them is a broken composition.
+
+1. **ALWAYS use transitions between scenes.** No jump cuts. No exceptions.
+2. **ALWAYS use entrance animations on every scene.** Every element animates IN via `gsap.from()`. No element may appear fully-formed. If a scene has 5 elements, it needs 5 entrance tweens.
+3. **NEVER use exit animations** except on the final scene. This means: NO `gsap.to()` that animates opacity to 0, y offscreen, scale to 0, or any other "out" animation before a transition fires. The transition IS the exit. The outgoing scene's content MUST be fully visible at the moment the transition starts.
+4. **Final scene only:** The last scene may fade elements out (e.g., fade to black). This is the ONLY scene where `gsap.to(..., { opacity: 0 })` is allowed.
+
+**WRONG — exit animation before transition:**
+
+```js
+// BANNED — this empties the scene before the transition can use it
+tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
+tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
+// transition fires on empty frame
+```
+
+**RIGHT — entrance only, transition handles exit:**
+
+```js
+// Scene 1 entrance animations
+tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
+tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
+// NO exit tweens — transition at 7.2s handles the scene change
+// Scene 2 entrance animations
+tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
+```
+
+## Animation Guardrails
+
+- Offset first animation 0.1-0.3s (not t=0)
+- Vary eases across entrance tweens — use at least 3 different eases per scene
+- Don't repeat an entrance pattern within a scene
+- Avoid full-screen linear gradients on dark backgrounds (H.264 banding — use radial or solid + localized glow)
+- 60px+ headlines, 20px+ body, 16px+ data labels for rendered video
+- `font-variant-numeric: tabular-nums` on number columns
+
+When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults.
 
 ## Typography and Assets
 
-- **Fonts:** Just write the `font-family` you want in CSS — the compiler embeds supported fonts automatically via `@font-face` with inline data URIs. No `<link>` tags or `@import` needed. If a font isn't in the supported set, the compiler warns and you should add it to `deterministicFonts.ts`.
+- **Fonts:** Just write the `font-family` you want in CSS — the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns.
 - Add `crossorigin="anonymous"` to external media
-- **Minimum font sizes for rendered video (1080p at DPR 1):**
-  - Body/label text: 20px minimum (landscape), 18px minimum (portrait)
-  - Data labels, axis labels, footnotes: 16px minimum — anything smaller becomes illegible after encoding
-  - Headlines: 36px+ recommended
-  - Avoid sub-14px text entirely — it will be unreadable in the final MP4
-- For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` — returns `{ fontSize, fits }`
+- For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`
 - All files live at the project root alongside `index.html`; sub-compositions use `../`
 
-### Backgrounds and Color
-
-- **Avoid full-screen linear gradients on dark backgrounds** — H.264 encoding creates visible color banding. Prefer: solid colors, radial gradients with limited range, or subtle noise/texture overlays to break up banding.
-- For dark themes, use solid `#000` or `#0A0A0A` with localized radial glows rather than a linear gradient spanning the full viewport.
-
 ## Editing Existing Compositions
 
 - Read the full composition first — match existing fonts, colors, animation patterns
@@ -209,18 +257,52 @@ Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
 
 ## Output Checklist
 
-- [ ] Every top-level container has `data-composition-id`, `data-width`, `data-height`, `data-duration`
-- [ ] Compositions in own HTML files, loaded via `data-composition-src`
-- [ ] `<template>` wrapper on sub-compositions
-- [ ] `window.__timelines` registered for every composition
-- [ ] Timeline construction is synchronous (no async/await wrapping timeline code)
-- [ ] No `repeat: -1` on any tween or nested timeline
-- [ ] No text below 16px (data labels, footnotes) or 20px (body text)
-- [ ] No full-screen linear dark gradients (use radial or solid + localized glow)
-- [ ] Font families declared in CSS (compiler embeds them automatically)
-- [ ] 100% deterministic
-- [ ] Each composition includes GSAP script tag
 - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass
+- [ ] Contrast warnings addressed (see Quality Checks below)
+- [ ] Animation choreography verified (see Quality Checks below)
+
+## Quality Checks
+
+### Contrast
+
+`hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings:
+
+```
+⚠ WCAG AA contrast warnings (3):
+  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)
+```
+
+If warnings appear:
+
+- On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold)
+- On light backgrounds: darken it
+- Stay within the palette family — don't invent a new color, adjust the existing one
+- Re-run `hyperframes validate` until clean
+
+Use `--no-contrast` to skip if iterating rapidly and you'll check later.
+
+### Animation Map
+
+After authoring animations, run the animation map to verify choreography:
+
+```bash
+node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
+  --out <composition-dir>/.hyperframes/anim-map
+```
+
+Outputs a single `animation-map.json` with:
+
+- **Per-tween summaries**: `"#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"`
+- **ASCII timeline**: Gantt chart of all tweens across the composition duration
+- **Stagger detection**: reports actual intervals (`"3 elements stagger at 120ms"`)
+- **Dead zones**: periods over 1s with no animation — intentional hold or missing entrance?
+- **Element lifecycles**: first/last animation time, final visibility
+- **Scene snapshots**: visible element state at 5 key timestamps
+- **Flags**: `offscreen`, `collision`, `invisible`, `paced-fast` (under 0.2s), `paced-slow` (over 2s)
+
+Read the JSON. Scan summaries for anything unexpected. Check every flag — fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.
+
+Skip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.
 
 ---
 
@@ -229,8 +311,8 @@ Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
 - **[references/captions.md](references/captions.md)** — Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing.
 - **[references/tts.md](references/tts.md)** — Text-to-speech with Kokoro-82M. Voice selection, speed tuning, TTS+captions workflow. Read when generating narration or voiceover.
 - **[references/audio-reactive.md](references/audio-reactive.md)** — Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound.
-- **[references/marker-highlight.md](references/marker-highlight.md)** — Animated text highlighting via canvas overlays: marker pen, circle, burst, scribble, sketchout. Read when adding visual emphasis to text.
-- **[references/fonts.md](references/fonts.md)** — Typography: typographic tension and contrast principles, font pairing theory, case studies from SSENSE/Acne/Stripe/Fly.io/Collins, failure modes, runtime font discovery. Read when picking and pairing typefaces.
+- **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.
+- **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text.
 - **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations.
 - **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no style is specified.
 - **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns.
@@ -238,9 +320,8 @@ Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
 - **[references/transcript-guide.md](references/transcript-guide.md)** — Transcription commands, whisper models, external APIs, troubleshooting.
 - **[references/dynamic-techniques.md](references/dynamic-techniques.md)** — Dynamic caption animation techniques (karaoke, clip-path, slam, scatter, elastic, 3D).
 
-- **[references/transitions.md](references/transitions.md)** — Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, narrative position, CSS vs WebGL guidance. Read when a composition has multiple scenes that need visual handoffs.
+- **[references/transitions.md](references/transitions.md)** — Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, CSS vs WebGL guidance. **Always read for multi-scene compositions** — scenes without transitions feel like jump cuts.
   - [transitions/catalog.md](references/transitions/catalog.md) — Hard rules, scene template, and routing to per-type implementation code.
-  - [transitions/shader-setup.md](references/transitions/shader-setup.md) — WebGL boilerplate for shader transitions.
-  - [transitions/shader-transitions.md](references/transitions/shader-transitions.md) — 14 fragment shaders.
+  - Shader transitions are in `@hyperframes/shader-transitions` (`packages/shader-transitions/`) — read package source, not skill files.
 
 GSAP patterns and effects are in the `/gsap` skill.

package/dist/skills/hyperframes/house-style.md

@@ -1,119 +1,60 @@
 # House Style
 
-Defaults when no `visual-style.md` or animation direction is provided. These raise the floor — not a brand identity, just professional quality.
+Creative direction for compositions when no `visual-style.md` is provided. These are starting points — override anything that doesn't serve the content.
 
 ## Before Writing HTML
 
-1. **Interpret the prompt.** Generate real content for the topic — don't use the prompt text as body copy. A recipe lists real ingredients. A stats dashboard shows the actual numbers given. A product showcase names real features and specs. A sci-fi HUD has actual crosshairs and readouts, not a heading that says "sci-fi HUD."
-2. **Pick a palette.** First decide: does this content call for a light or dark canvas? Then load the file most appropriate for the theme and pick one palette at random from the file. Declare your bg, fg, and accent colors before writing any code.
-3. **Pick a typeface.** Don't reach for Sora, Space Grotesk, Outfit, Playfair Display, Cormorant Garamond, or Bodoni Moda — they're overused. Read [references/fonts.md](references/fonts.md) and pick a font that matches the content mood. Serif for editorial, mono for technical, display for impact, handwritten for personal. Just write the `font-family` in CSS — the compiler embeds supported fonts automatically.
-4. **Pick a layout approach.** Don't default to the same structure every time.
-5. **Pick your entrance patterns.** Plan how elements enter — never use the same entrance pattern twice in a composition.
+1. **Interpret the prompt.** Generate real content. A recipe lists real ingredients. A HUD has real readouts.
+2. **Pick a palette.** Light or dark? Declare bg, fg, accent before writing code.
+3. **Pick typefaces.** Run the font discovery script in [references/typography.md](references/typography.md) — or pick a font you already know that fits the theme. The script broadens your options; it's not the only source.
 
-## Motion
-
-### Easing
-
-Vary your eases. Don't use the same ease on more than 2 tweens in a composition. Pick from the full GSAP vocabulary:
-
-`power1-4.in/out/inOut`, `back.out(1.4-2.5)`, `elastic.out(1, 0.3-0.5)`, `circ.out`, `expo.out`, `sine.inOut`, `steps(n)`
-
-A few principles:
-
-- Opacity fades should be gentle (`power1` or `none`) — don't draw attention to the fade itself
-- Overshoot on scale or position feels alive — `back.out` or `elastic.out`
-- Snappy moves want `expo.out` or `power4.out` — fast departure, hard stop
-- Smooth arcs want `sine.inOut` or `circ.inOut` — no hard edges
+## Lazy Defaults to Question
 
-### Timing
+These patterns are AI design tells — the first thing every LLM reaches for. If you're about to use one, pause and ask: is this a deliberate choice for THIS content, or am I defaulting?
 
-- **0.3–0.6s** for most moves. Shorter than you think.
-- **Exits 2x faster** than entrances.
-- **Nothing starts at t=0** — offset first animation 0.1–0.3s.
-- **Overlap entries** — next element starts before previous finishes. Use GSAP position parameter: `tl.to(el, {...}, "-=0.15")`
-- **Stagger with easing**, not uniform: `stagger: { each: 0.08, ease: "power2.in" }`
+- Gradient text (`background-clip: text` + gradient)
+- Left-edge accent stripes on cards/callouts
+- Cyan-on-dark / purple-to-blue gradients / neon accents
+- Pure `#000` or `#fff` (tint toward your accent hue instead)
+- Identical card grids (same-size cards repeated)
+- Everything centered with equal weight (lead the eye somewhere)
+- Banned fonts (see [references/typography.md](references/typography.md) for full list)
 
-### Entrance Patterns
+If the content genuinely calls for one of these — centered layout for a solemn closing, cards for a real product UI mockup, a banned font because it's the perfect thematic match — use it. The goal is intentionality, not avoidance.
 
-Never fade-in alone. Combine opacity with at least one transform. Never repeat the same entrance in a composition. Invent your own combinations — mix properties creatively:
+## Color
 
-- **Position** — x, y, or both (diagonal). Vary the axis and distance per element.
-- **Scale** — from smaller or larger. Pair with overshoot easing.
-- **Rotation** — small angles (3-12deg) feel intentional. Large angles (45-180deg) feel dramatic.
-- **Clip path** — `inset()`, `circle()`, `polygon()`. Direction matters: left, right, top, center outward.
-- **Blur + opacity** — `filter: blur(8px)` combined with opacity creates a focus-pull effect.
-- **Letter spacing / word spacing** — for text, animate tracking from wide to tight or vice versa.
-- **Skew** — `skewX` or `skewY` gives a motion-blur feeling without actual blur.
-- **3D transforms** — `rotationX`, `rotationY` with `transformPerspective` for depth.
+- Match light/dark to content: food, wellness, kids → light. Tech, cinema, finance → dark.
+- One accent hue. Same background across all scenes.
+- Tint neutrals toward your accent (even subtle warmth/coolness beats dead gray).
+- **Contrast:** enforced by `hyperframes validate` (WCAG AA). Text must be readable with decoratives removed.
+- Declare palette up front. Don't invent colors per-element.
 
-Don't copy the same combination across compositions. Each composition should feel like it has its own motion personality.
+## Background Layer
 
-### Choreography
+Every scene needs visual depth — persistent decorative elements that stay visible while content animates in. Without these, scenes feel empty during entrance staggering.
 
-- **Combined transforms** — animate 2–3 properties together (position + scale, rotation + opacity), not one at a time.
-- **Coordinated entry** — when a new element enters, existing elements react. Anchor moves, follower tracks.
-- **Ambient motion** — keep the composition alive during holds. Don't default to zoom-in every time. Pick one per composition:
-  - Slow pan (x or y drift on a container)
-  - Subtle rotation (0.5–2deg over several seconds)
-  - Scale push or pull (zoom in OR out — both work)
-  - Parallax layers (background moves slower than foreground)
-  - Color/opacity shift on an accent element
-  - No ambient motion at all — stillness can be powerful
-- **End with intention** — don't always zoom at the end. Options: snap to black, fade to stillness, final element snaps into place, a hard cut. Vary this across compositions.
+Ideas (mix and match, 2-5 per scene):
 
-### Scene Pacing
+- Radial glows (accent-tinted, low opacity, breathing scale)
+- Ghost text (theme words at 3-8% opacity, very large, slow drift)
+- Accent lines (hairline rules, subtle pulse)
+- Grain/noise overlay, geometric shapes, grid patterns
+- Thematic decoratives (orbit rings for space, vinyl grooves for music, grid lines for data)
 
-Structure compositions in three phases — don't front-load everything:
+All decoratives should have slow ambient GSAP animation — breathing, drift, pulse. Static decoratives feel dead.
 
-- **Build (0–30%)** — elements enter. Stagger arrivals so there's a sequence, not a simultaneous dump.
-- **Breathe (30–70%)** — content is visible. Keep it alive with subtle motion: slow camera push, gentle drift, a color shift, a pulsing accent. Static holds feel dead.
-- **Resolve (70–100%)** — elements exit or the composition punctuates. Exits are faster than entrances. End with intention — a final zoom, a fade to black, a snap to stillness.
-
-Don't crowd the build phase. If you have 6 elements, let 2-3 enter, breathe, then bring in the rest. Layers of reveals beat a single wave.
-
-## Sizing
-
-- **Text scale contrast** — headings at 3–5x body size, not 1.5x. Big contrast reads as cinematic.
-- **Element fill** — hero elements fill 60–80% of the frame. Don't leave them floating at 30%.
-- **Travel distance** — entrance moves should cover 80–200px. Under 20px looks like a glitch.
-- **Overshoot** — 5–10% overshoot reads as energy. Under 2% reads as a bug.
-
-## Visual Depth
+## Motion
 
-Flat single-color backgrounds look digital. Avoid pure solid backgrounds — add some visual layer to break the flatness. Options include gradients, subtle background shapes, texture, shadows on cards, or border accents. Pick what fits the content — not every composition needs the same treatment. A luxury product wants subtle gradients. A children's show wants bold shapes. A news graphic wants clean borders.
+See [references/motion-principles.md](references/motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries.
 
 ## Typography
 
-Beyond choosing a typeface:
-
-- **Weight contrast** — pair a heavy weight (700-900) headline with a light weight (300-400) body. Always use at least two explicit font-weight values — even with display fonts that look bold by default, set labels or secondary text to a lighter weight.
-- **Case deliberately** — ALL CAPS for labels and short text (under 5 words). Sentence case for longer text. Don't uppercase paragraphs.
-- **Tracking** — tight tracking (-0.02em) on large headlines. Normal or wide tracking on small labels.
-- **One typeface, two weights** — don't mix typefaces unless you have a reason. One family at two weights creates more hierarchy than two families at one weight each.
-
-## Anti-Defaults
-
-Things the LLM reaches for that look generic. Do the opposite.
-
-| Default                           | Instead                                                                                                                                                                                                                                          |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Inter / Roboto / system font      | Pick a typeface with character — commit to it                                                                                                                                                                                                    |
-| `#f5f5f5` / `#333` / mid-gray     | Go high contrast. Near-black or near-white, not the middle                                                                                                                                                                                       |
-| Blue accent `#3b82f6`             | No blue unless the user asks for blue                                                                                                                                                                                                            |
-| Everything centered, equal weight | One focal point per frame. Lead the eye somewhere                                                                                                                                                                                                |
-| Uniform spacing                   | Tight clusters and open gaps. Vary deliberately                                                                                                                                                                                                  |
-| Same entrance on every element    | Never repeat an entrance pattern in a composition                                                                                                                                                                                                |
-| 1s duration on everything         | 0.3–0.6s. Shorter than you think                                                                                                                                                                                                                 |
-| `power2.out` on everything        | Vary eases — no more than 2 independent tweens with the same ease (staggers are exempt)                                                                                                                                                          |
-| Always dark background            | Match the content: food, weddings, kids, wellness, education → light palette                                                                                                                                                                     |
-| Inventing colors per-element      | Declare palette up front. Every element references it                                                                                                                                                                                            |
-| Content in cards/containers       | Place content directly on the canvas — separate with space and alignment, not box boundaries. Cards are a web pattern. Exception: dashboards, lower thirds, captions over footage                                                                |
-| Hand-drawn SVG illustrations      | Don't attempt to draw real-world objects (faces, buildings, food, animals) with SVG paths — they look crude. Use geometric shapes, lines, and abstract forms only. If the composition needs imagery, use text and typography to evoke it instead |
-| Overlapping elements              | Every element needs its own clear space. Check that positioned elements don't collide — stagger positions vertically with enough margin. Overlapping text is always ugly                                                                         |
+See [references/typography.md](references/typography.md) for full rules. Quick: 700-900 headlines / 300-400 body, serif + sans (not two sans), 60px+ headlines / 20px+ body.
 
 ## Palettes
 
-Before writing any HTML, declare your palette: one background, one foreground, one accent. Pick from a category below — don't invent colors. **Match palette to content** — don't default to dark. Children's content, food, weddings, wellness, education, and lifestyle content should typically use light or warm palettes.
+Declare one background, one foreground, one accent before writing HTML.
 
 | Category          | Use for                                       | File                                                       |
 | ----------------- | --------------------------------------------- | ---------------------------------------------------------- |
@@ -127,4 +68,4 @@ Before writing any HTML, declare your palette: one background, one foreground, o
 | Jewel / Rich      | Luxury, events, sophisticated                 | [palettes/jewel-rich.md](palettes/jewel-rich.md)           |
 | Monochrome        | Dramatic, typography-focused                  | [palettes/monochrome.md](palettes/monochrome.md)           |
 
-**Escape hatch:** If no category fits, derive from the color wheel — pick a base hue, take its complement or triadic, pull a dark from OKLCH lightness 15% and a light from 90%.
+Or derive from OKLCH — pick a hue, build bg/fg/accent at different lightnesses, tint everything toward that hue.

package/dist/skills/hyperframes/references/captions.md

@@ -44,7 +44,7 @@ Scan for words deserving distinct treatment:
 - **Numbers/statistics** — bold weight, accent color
 - **Emotional keywords** — exaggerated animation (overshoot, bounce)
 - **Call-to-action** — highlight, underline, color pop
-- **Marker highlight** — for beyond-color emphasis, see [marker-highlight.md](marker-highlight.md)
+- **Marker highlight** — for beyond-color emphasis, see [css-patterns.md](css-patterns.md)
 
 ## Script-to-Style Mapping
 
@@ -121,7 +121,7 @@ tl.seek(0);
 
 - [dynamic-techniques.md](dynamic-techniques.md) — karaoke, clip-path reveals, slam words, scatter exits, elastic, 3D rotation
 - [transcript-guide.md](transcript-guide.md) — transcription commands, whisper models, external APIs
-- [marker-highlight.md](marker-highlight.md) — animated text emphasis paired with per-word styling
+- [css-patterns.md](css-patterns.md) — CSS+GSAP marker highlighting (deterministic, fully seekable)
 
 ## Constraints