@w3kits-com/plugin-opendesign 0.1.8 → 0.1.10

package/dist/__w3kits/assets/design-templates/html-ppt-zhangzara-vellum/template.json

@@ -0,0 +1,50 @@
+{
+  "slug": "zhangzara-vellum",
+  "name": "Vellum",
+  "tagline": "Deep navy canvas with warm-yellow italic Cormorant serifs and a single dusty teal accent. A quiet, scholarly aesthetic.",
+  "mood": [
+    "scholarly",
+    "literary",
+    "considered",
+    "quiet",
+    "intellectual"
+  ],
+  "occasion": [
+    "research findings",
+    "white paper or longform report",
+    "academic or university deck",
+    "advisory deliverable",
+    "literary or editorial pitch",
+    "founder reflection / vision deck",
+    "bilingual EN/CN deck"
+  ],
+  "tone": [
+    "literary",
+    "considered",
+    "patient",
+    "intelligent"
+  ],
+  "formality": "high",
+  "density": "low",
+  "palette": {
+    "bg": "#2a3870",
+    "bg_alt": "#343f80",
+    "fg": "#E8D85C",
+    "accent": "#3a7878",
+    "description": "deep periwinkle navy canvas with warm yellow italic-serif type and one dusty-teal accent for quote marks; a single coherent palette across every slide, no inverted theme"
+  },
+  "typography": {
+    "display": "Cormorant Garamond Italic",
+    "body": "DM Sans",
+    "mono": "Courier Prime",
+    "serif_cn": "Noto Serif SC",
+    "sans_cn": "Noto Sans SC",
+    "style": "italic transitional serif as the structural display face, paired with clean DM Sans body and Courier Prime mono for attributions and labels; bilingual EN/CN support"
+  },
+  "scheme": "dark",
+  "best_for": "Anything that should feel scholarly, literary, and quietly intelligent: research synthesis, white papers, academic and policy briefs, advisory deliverables, longform editorial pieces, founder reflections. Equally strong for any deck — including tech, business, or creator work — that wants a calm, considered atmosphere instead of energetic visuals.",
+  "avoid_for": "Contexts that need visual heat or pop — the navy + warm-yellow italic-Cormorant aesthetic is intentionally low-tempo.",
+  "slide_count": 9,
+  "navigation": "inline keyboard handler",
+  "source": "https://github.com/zarazhangrui/beautiful-html-templates/tree/main/templates/vellum"
+}

package/dist/__w3kits/assets/design-templates/hyperframes/SKILL.md

@@ -0,0 +1,500 @@
+---
+name: hyperframes
+description: Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.
+triggers:
+  - "hyperframes"
+  - "html video"
+  - "video composition"
+  - "interactive video"
+  - "captions"
+  - "tts video"
+  - "kinetic typography"
+  - "html in canvas"
+  - "drawElementImage"
+  - "html shader"
+  - "vfx-iphone-device"
+  - "vfx-liquid-glass"
+  - "vfx-portal"
+od:
+  mode: video
+  surface: video
+  scenario: video
+  preview:
+    type: html
+  design_system:
+    requires: false
+  example_prompt: |
+    A 5-second product reveal: a minimal high-end product on a clean cream
+    surface, soft side light, slow camera push-in, restrained motion, no
+    text overlays.
+---
+
+# HyperFrames
+
+HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync.
+
+## Open Design integration (load-bearing for this surface)
+
+When this skill runs inside Open Design (i.e. `$OD_PROJECT_DIR` is set), the
+output flow is fixed: only the rendered `.mp4` should land in the project
+root. Composition source files (`hyperframes.json`, `meta.json`,
+`index.html`, assets) belong inside a hidden cache directory so they don't
+clutter the user's FileViewer or the chat's "produced files" chips.
+
+**Render workflow inside OD — fast path**:
+
+For most OD requests ("test video", "5s product reveal", "demo clip"),
+do NOT write the composition HTML from scratch. Use HyperFrames'
+built-in scaffold and edit only what the prompt actually changes. The
+"author from scratch" path costs minutes of model output and silent
+chat-tool time; the scaffold path costs seconds.
+
+```bash
+# 1. Pick a hidden cache slot. Dotfile prefix → OD's project file
+#    listing skips it, so the source files never clutter the chat.
+COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
+COMP="$OD_PROJECT_DIR/$COMP_REL"
+
+# 2. Get an immediately-renderable scaffold (hyperframes.json,
+#    meta.json, index.html with GSAP CDN + window.__timelines.main
+#    already registered). This runs in your shell — pure file copy,
+#    no Chrome, no network beyond the npx cache.
+npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
+
+# 3. Edit ONLY $COMP/index.html — change `data-duration` on the root
+#    if you need a non-default length, swap the placeholder palette
+#    in <style>, add 1–3 clip <div>s for text/imagery, and append the
+#    matching GSAP tweens inside the existing
+#    `window.__timelines["main"] = gsap.timeline({paused:true})` block.
+#    Keep edits minimal; the scaffold is already valid HF.
+
+# 4. Dispatch render through the OD daemon. Do NOT run `npx hyperframes
+#    render` from this shell — the daemon runs it for you in an
+#    unsandboxed process. (Many agent CLIs, Claude Code in particular,
+#    wrap Bash in macOS sandbox-exec under which puppeteer's Chrome
+#    subprocess hangs partway through frame capture. The daemon process
+#    is unsandboxed, so renders complete reliably.)
+#
+#    The dispatcher returns within ~1s with a {taskId}; drive the
+#    render to completion by looping `"$OD_NODE_BIN" "$OD_BIN" media wait <taskId>` calls.
+#    Each call long-polls up to 25s (well under your shell tool's
+#    default 30s cap) and exits 0/2/5 to signal done/running/failed.
+out=$("$OD_NODE_BIN" "$OD_BIN" media generate \
+  --project "$OD_PROJECT_ID" \
+  --surface video \
+  --model hyperframes-html \
+  --output "<descriptive-name>.mp4" \
+  --composition-dir "$COMP_REL")
+ec=$?
+task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
+since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
+while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
+  out=$("$OD_NODE_BIN" "$OD_BIN" media wait "$task_id" --since "$since")
+  ec=$?
+  since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
+done
+[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
+```
+
+Each `generate` and each `wait` call lasts at most ~25s, so the agent
+shell tool's default ~30s cap never fires. Progress lines from HF
+(`Capturing frame N/M`) stream to stderr live throughout the loop.
+When the render finishes, the last stdout line is
+`{"file": { "name": "<output>", "size": …, "kind": "video", … }}` —
+quote `file.name` in your reply so the user knows what was produced.
+
+**Skip the Visual Identity Gate inside OD.** The HARD-GATE section
+below (under "Approach") tells you to read DESIGN.md / visual-style.md
+or stop and ask 3 mood questions before writing any composition. That
+gate is for standalone HF projects. **OD projects already have their
+own design-system layer** — the user picked their visual direction at
+project creation time. For an OD test render, default to: dark canvas
+(#0b0b0f), one warm accent (#ffb76b), one cool accent (#7da4ff),
+restrained motion. Only ask for stylistic input if the user's prompt
+is too vague to even pick a subject (very rare).
+
+When to skip the scaffold and write from scratch: only when the user
+explicitly asks for something the blank template clearly can't host
+(e.g. multi-composition timelines, audio-reactive overlays, captions
+synced to a TTS track they've already generated). For everything else,
+init + edit is the default path.
+
+The lighter HF subcommands you CAN still run from your own shell
+(they don't need to spawn Chrome):
+
+- `npx hyperframes lint "$COMP"` — validate composition before dispatch
+- `npx hyperframes transcribe <audio>` — generate captions
+- `npx hyperframes tts <text>` — generate narration
+
+Reserve the daemon dispatch for `render`/`inspect`/`preview` (anything
+Chrome-bound).
+
+**Do NOT** call `"$OD_NODE_BIN" "$OD_BIN" media generate --model hyperframes-html` — that
+dispatcher path returns a 400 (`AGENT_RENDERED`) on purpose. HyperFrames
+is rendered by you directly via npx.
+
+**Do NOT** drop `hyperframes.json` / `meta.json` / `index.html` in the
+project root; OD's file listing scans recursively and the user would see
+three unrelated files appear in the chat.
+
+For CLI options beyond `render` (lint, preview, transcribe, tts, inspect,
+benchmark) call them directly from your shell tool when the task warrants
+it (e.g., generate TTS audio into the cache before referencing it from
+the composition).
+
+## Approach
+
+Before writing HTML, think at a high level:
+
+1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.
+2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).
+3. **Timing** — which clips drive the duration, where do transitions land, what's the pacing.
+4. **Layout** — build the end-state first. See "Layout Before Animation" below.
+5. **Animate** — then add motion using the rules below.
+
+For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
+
+### Visual Identity Gate
+
+<HARD-GATE>
+Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors.
+
+Check in this order:
+
+1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints.
+2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.)
+3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns).
+4. **None of the above?** → Ask 3 questions before writing any HTML:
+   - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm)
+   - Light or dark canvas?
+   - Any specific brand colors, fonts, or visual references?
+     Then generate a minimal DESIGN.md from the answers.
+
+Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step.
+</HARD-GATE>
+
+For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like.
+
+## Layout Before Animation
+
+Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet.
+
+**Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion.
+
+### 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. 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
+/* 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 {
+  font-size: 120px;
+}
+.subtitle {
+  font-size: 42px;
+}
+/* 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;
+  top: 200px;
+  left: 160px;
+  width: 1920px;
+  height: 1080px;
+  display: flex; /* ... */
+}
+```
+
+```js
+// Step 3: Animate INTO those positions
+tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
+tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
+tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
+
+// Step 4: Animate OUT from those positions
+tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
+tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
+tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
+```
+
+### When elements share space across time
+
+If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist — but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error.
+
+### What counts as intentional overlap
+
+Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap — two headlines landing on top of each other, a stat covering a label, content bleeding off-frame.
+
+## Data Attributes
+
+### All Clips
+
+| Attribute          | Required                          | Values                                                 |
+| ------------------ | --------------------------------- | ------------------------------------------------------ |
+| `id`               | Yes                               | Unique identifier                                      |
+| `data-start`       | Yes                               | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) |
+| `data-duration`    | Required for img/div/compositions | Seconds. Video/audio defaults to media duration.       |
+| `data-track-index` | Yes                               | Integer. Same-track clips cannot overlap.              |
+| `data-media-start` | No                                | Trim offset into source (seconds)                      |
+| `data-volume`      | No                                | 0-1 (default 1)                                        |
+
+`data-track-index` does **not** affect visual layering — use CSS `z-index`.
+
+### Composition Clips
+
+| 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
+
+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">
+  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
+    <!-- content -->
+    <style>
+      [data-composition-id="my-comp"] {
+        /* scoped styles */
+      }
+    </style>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      // tweens...
+      window.__timelines["my-comp"] = tl;
+    </script>
+  </div>
+</template>
+```
+
+Load in root: `<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>`
+
+## Video and Audio
+
+Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
+
+```html
+<video
+  id="el-v"
+  data-start="0"
+  data-duration="30"
+  data-track-index="0"
+  src="video.mp4"
+  muted
+  playsinline
+></video>
+<audio
+  id="el-a"
+  data-start="0"
+  data-duration="30"
+  data-track-index="2"
+  src="video.mp4"
+  data-volume="1"
+></audio>
+```
+
+## Timeline Contract
+
+- All timelines start `{ paused: true }` — the player controls playback
+- Register every timeline: `window.__timelines["<composition-id>"] = tl`
+- Framework auto-nests sub-timelines — do NOT manually add them
+- Duration comes from `data-duration`, not from GSAP timeline length
+- Never create empty tweens to set duration
+
+## Rules (Non-Negotiable)
+
+**Deterministic:** No `Math.random()`, `Date.now()`, or time-based logic. Use a seeded PRNG if you need pseudo-random values (e.g. mulberry32).
+
+**GSAP:** Only animate visual properties (`opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms). Do NOT animate `visibility`, `display`, or call `video.play()`/`audio.play()`.
+
+**Animation conflicts:** Never animate the same property on the same element from multiple timelines simultaneously.
+
+**No `repeat: -1`:** Infinite-repeat timelines break the capture engine. Calculate the exact repeat count from composition duration: `repeat: Math.ceil(duration / cycleDuration) - 1`.
+
+**Synchronous timeline construction:** Never build timelines inside `async`/`await`, `setTimeout`, or Promises. The capture engine reads `window.__timelines` synchronously after page load. Fonts are embedded by the compiler, so they're available immediately — no need to wait for font loading.
+
+**Never do:**
+
+1. Forget `window.__timelines` registration
+2. Use video for audio — always muted video + separate `<audio>`
+3. Nest video inside a timed div — use a non-timed wrapper
+4. Use `data-layer` (use `data-track-index`) or `data-end` (use `data-duration`)
+5. Animate video element dimensions — animate a wrapper div
+6. Call play/pause/seek on media — framework owns playback
+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. If a font isn't supported, the compiler warns.
+- Add `crossorigin="anonymous"` to external media
+- 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 `../`
+
+## Editing Existing Compositions
+
+- Read the full composition first — match existing fonts, colors, animation patterns
+- Only change what was requested
+- Preserve timing of unrelated clips
+
+## Output Checklist
+
+- [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass
+- [ ] `npx hyperframes inspect` passes, or every reported overflow is intentionally marked
+- [ ] Contrast warnings addressed (see Quality Checks below)
+- [ ] Layout issues addressed (see Quality Checks below)
+- [ ] Animation choreography verified (see Quality Checks below)
+
+## Quality Checks
+
+### Visual Inspect
+
+`hyperframes inspect` runs the composition in headless Chrome, seeks through the timeline, and maps visual layout issues with timestamps, selectors, bounding boxes, and fix hints. Run it after `lint` and `validate`:
+
+```bash
+npx hyperframes inspect
+npx hyperframes inspect --json
+```
+
+Failures usually mean text is spilling out of a bubble/card, a fixed-size label is clipping dynamic copy, or text has moved off the canvas. Fix by increasing container size or padding, reducing font size or letter spacing, adding a real `max-width` so text wraps inside the container, or using `window.__hyperframes.fitTextFontSize(...)` for dynamic copy.
+
+Use `--samples 15` for dense videos and `--at 1.5,4,7.25` for specific hero frames. Repeated static issues are collapsed by default to avoid flooding agent context. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.
+
+`hyperframes layout` is the compatibility alias for the same check.
+
+### 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.
+
+---
+
+## References (loaded on demand)
+
+- **[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/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.
+- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md.
+- **[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.
+- **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns.
+- **[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, 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.
+  - Shader transitions are in `@hyperframes/shader-transitions` (`packages/shader-transitions/`) — read package source, not skill files.
+- **[references/html-in-canvas.md](references/html-in-canvas.md)** — HTML-in-Canvas (`drawElementImage`) for rendering live DOM as WebGL textures: 3D device mockups, shader-warped UIs, liquid glass, portals. Read when the user asks for `vfx-iphone-device`, `vfx-liquid-glass`, `vfx-portal`, or any "HTML mapped onto 3D / shader" effect. The render path auto-enables the Chrome flag, but the texture must be re-captured every frame for animated content — that's the most common cause of "the screen renders dead" output.
+
+GSAP patterns and effects are in the `/gsap` skill.

package/dist/__w3kits/assets/design-templates/hyperframes/data-in-motion.md

@@ -0,0 +1,19 @@
+# Data in Motion
+
+Light guidance for data and stats in video compositions. The [house style](./house-style.md) handles aesthetics — this just addresses data-specific pitfalls.
+
+## Visual Continuity
+
+When successive stats belong to the same concept (Q1 → Q2 → Q3 → Q4, or three metrics for the same product), keep them in the same visual space with the same aesthetic. Only the VALUE changes. An aesthetic change should signal a new concept, not just a new number.
+
+## Numbers Need Visual Weight
+
+A number on its own floats in empty space. Pair every metric with a visual element that gives it presence — a proportional fill bar, a background color shift, a shape that represents the value, a progress ring. The visual doesn't need to be a chart — it just needs to fill the frame and make the data feel tangible rather than just text on a background.
+
+## Avoid Web Patterns
+
+- **No pie charts** — hard to compare, looks like PowerPoint
+- **No multi-axis charts** — viewer can't study intersections in a 3-second window
+- **No 6-panel dashboards** — 2-3 related metrics side-by-side is fine, 6+ is a web pattern
+- **No gridlines, tick marks, or legends** — visual noise that adds nothing in motion
+- **No chart library output** — build with GSAP + SVG/CSS, not D3 or Chart.js

package/dist/__w3kits/assets/design-templates/hyperframes/house-style.md

@@ -0,0 +1,71 @@
+# House Style
+
+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. 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.
+
+## Lazy Defaults to Question
+
+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?
+
+- 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)
+
+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.
+
+## Color
+
+- 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.
+
+## Background Layer
+
+Every scene needs visual depth — persistent decorative elements that stay visible while content animates in. Without these, scenes feel empty during entrance staggering.
+
+Ideas (mix and match, 2-5 per scene):
+
+- 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)
+
+All decoratives should have slow ambient GSAP animation — breathing, drift, pulse. Static decoratives feel dead.
+
+## Motion
+
+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
+
+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
+
+Declare one background, one foreground, one accent before writing HTML.
+
+| Category          | Use for                                       | File                                                       |
+| ----------------- | --------------------------------------------- | ---------------------------------------------------------- |
+| Bold / Energetic  | Product launches, social media, announcements | [palettes/bold-energetic.md](palettes/bold-energetic.md)   |
+| Warm / Editorial  | Storytelling, documentaries, case studies     | [palettes/warm-editorial.md](palettes/warm-editorial.md)   |
+| Dark / Premium    | Tech, finance, luxury, cinematic              | [palettes/dark-premium.md](palettes/dark-premium.md)       |
+| Clean / Corporate | Explainers, tutorials, presentations          | [palettes/clean-corporate.md](palettes/clean-corporate.md) |
+| Nature / Earth    | Sustainability, outdoor, organic              | [palettes/nature-earth.md](palettes/nature-earth.md)       |
+| Neon / Electric   | Gaming, tech, nightlife                       | [palettes/neon-electric.md](palettes/neon-electric.md)     |
+| Pastel / Soft     | Fashion, beauty, lifestyle, wellness          | [palettes/pastel-soft.md](palettes/pastel-soft.md)         |
+| Jewel / Rich      | Luxury, events, sophisticated                 | [palettes/jewel-rich.md](palettes/jewel-rich.md)           |
+| Monochrome        | Dramatic, typography-focused                  | [palettes/monochrome.md](palettes/monochrome.md)           |
+
+Or derive from OKLCH — pick a hue, build bg/fg/accent at different lightnesses, tint everything toward that hue.

package/dist/__w3kits/assets/design-templates/hyperframes/palettes/bold-energetic.md

@@ -0,0 +1,14 @@
+# Bold / Energetic
+
+Product launches, social media, announcements, high-energy content.
+
+```
+#FFBE0B #FB5607 #FF006E #8338EC #3A86FF
+#F72585 #7209B7 #3A0CA3 #4361EE #4CC9F0
+#EF476F #FFD166 #06D6A0 #118AB2 #073B4C
+#FF595E #FFCA3A #8AC926 #1982C4 #6A4C93
+#9B5DE5 #F15BB5 #FEE440 #00BBF9 #00F5D4
+#390099 #9E0059 #FF0054 #FF5400 #FFBD00
+#3D348B #7678ED #F7B801 #F18701 #F35B04
+#FFBC42 #D81159 #8F2D56 #218380 #73D2DE
+```