Diogenesoftoronto/keating / video/keating-surface-tour/.agents/skills/hyperframes-core
hyperframes-core
VerifiedThe HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.3 KB |
| references/brief-contract.md | markdown | 11.8 KB |
| references/brief-format.md | markdown | 7.0 KB |
| references/composition-patterns.md | markdown | 13.5 KB |
| references/data-attributes.md | markdown | 13.1 KB |
| references/determinism-rules.md | markdown | 8.1 KB |
| references/frame-worker-core.md | markdown | 16.4 KB |
| references/full-screen-motion.md | markdown | 2.9 KB |
| references/minimal-composition.md | markdown | 2.0 KB |
| references/production-loop.md | markdown | 7.1 KB |
| references/review-loop.md | markdown | 6.8 KB |
| references/script-format.md | markdown | 2.8 KB |
| references/storyboard-format.md | markdown | 7.6 KB |
| references/sub-compositions.md | markdown | 11.0 KB |
| references/subagent-dispatch.md | markdown | 3.6 KB |
| references/tailwind.md | markdown | 4.9 KB |
| references/tracks-and-clips.md | markdown | 3.6 KB |
| references/variables-and-media.md | markdown | 6.8 KB |
| scripts/lib/frame-packets-core.mjs | script | 7.1 KB |
references/tracks-and-clips.md
View on GitHub# Tracks and Clips
Clips are timed children of the composition root. Tracks are a temporal-overlap concept, not a visual-stacking concept.
## What is a Clip
A clip is any DOM element with `data-start`, `data-duration` (where required), and `data-track-index`. Common kinds:
- **Visual `<div>` clips** — scenes, cards, overlays. Always require `data-duration`.
- **Sub-composition hosts** — `<div>` with `data-composition-src`. Always require `data-duration`.
- **Video clips** — `<video>` with `muted` and `playsinline`. Duration can default to media length.
- **Audio clips** — `<audio>`. Duration can default to media length.
- **Image clips** — `<img>`. Always require `data-duration`.
Add `class="clip"` to authored visual clips so tooling and examples can find them.
## Tracks Are Temporal, Not Visual
`data-track-index` controls **temporal overlap**, not paint order:
- **Two clips on the same `data-track-index`** must NOT overlap in time. `hyperframes lint` flags this.
- **Visual layering (front/back)** is controlled by CSS `z-index`, not by track index.
A clip on track `5` is not "above" a clip on track `1` — it's just on a different audio/visual lane in time. Use CSS for layering, tracks for sequencing.
## Picking a Track Index
There's no fixed convention, but common patterns:
- **Track 0** — base video (e.g. an A-roll).
- **Track 1+** — visual scenes, overlays, captions.
- **Higher tracks (e.g. 10+)** — audio clips, separated from visual tracks to keep linting clear.
When adding a new clip to an existing composition:
1. Find an existing track that has no overlap with your new clip's `[data-start, data-start + data-duration)` range.
2. Or pick a fresh track index.
3. Never overlap two clips on the same track — the linter will fail and the render is undefined.
## Clip Time Inside the Composition
`data-start` is in seconds, measured from the start of the _composition_. For sub-compositions, the sub-composition's internal timeline (its own `data-duration` and child clips) runs from `data-start` to `data-start + data-duration` of the host.
`data-media-start` (on `<video>`/`<audio>`) is an offset _into the source media_. Use it to skip the first few seconds of a media file without trimming the file itself.
## Relative Timing
`data-start` accepts a clip ID instead of a number, meaning "start when that clip ends". Add `+ N` / `- N` to offset; negative produces overlap (useful for crossfades).
```html
<video id="intro" data-start="0" data-duration="10" data-track-index="0" src="..."></video>
<video id="main" data-start="intro" data-duration="20" data-track-index="0" src="..."></video>
<video
id="scene-a"
data-start="intro + 2"
data-duration="20"
data-track-index="0"
src="..."
></video>
<video
id="scene-b"
data-start="intro - 0.5"
data-duration="20"
data-track-index="1"
src="..."
></video>
```
Rules:
- References resolve **inside the same composition only** — cannot reach into a parent or sibling sub-composition.
- The referenced clip must have a **known duration** (explicit `data-duration` or inferred from media). Otherwise the reference cannot resolve.
- **No circular references** — `A → B → A` is rejected. Cycles are detected and error out.
- A value that parses as a number is always treated as absolute seconds. Otherwise the resolver expects `<id>`, `<id> + <number>`, or `<id> - <number>` (whitespace optional).
- References can chain (`A → B → C`). Keep chains under 3-4 levels for readability.
- Negative offsets create overlap; overlapping clips must be on **different tracks**, same-track overlap is rejected.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |