hyperframes

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\nsurface, soft side light, slow camera push-in, restrained motion, no\ntext overlays.\n"}

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.

OpenDesign integration (load-bearing for this surface)

When this skill runs inside OpenDesign (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 Open Design's deterministic 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.

# 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). Open Design writes these files itself; it does
#    not run `hyperframes init`, consult an npx cache, or install global skills.
"$OD_NODE_BIN" "$OD_BIN" media scaffold \
  --project "$OD_PROJECT_ID" \
  --composition-dir "$COMP_REL"

# 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 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):

• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" lint "$COMP" — validate composition before dispatch
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" transcribe <audio> — generate captions
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" tts <text> — generate narration

Reserve the daemon dispatch for render/inspect/preview (anything Chrome-bound). After authoring the composition under .hyperframes-cache/, render it by calling "$OD_NODE_BIN" "$OD_BIN" media generate --surface video --model hyperframes-html --composition-dir <rel>. The daemon runs the Chrome-bound HyperFrames render outside your shell sandbox and streams progress back to you. Do not run HyperFrames render yourself.

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

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 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.

For motion defaults, sizing, entrance patterns, and easing — follow 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

/* 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:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// 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:

<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>