hyperframes-core
The 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. Read before writing composition HTML.
vakovalskii · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add vakovalskii/nd-video-studio --skill hyperframes-coreAbout this skill
name: hyperframes-core
description: The 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. Read before writing composition HTML.
Plugin installs: Before setup or freshness commands, follow plugin execution rules when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
HyperFrames Core
Agent pitfalls (read first):
- Center with flex/
inset, not CSStransform: translate(-50%,-50%)on a node you then GSAPx/y. Lint:gsap_css_transform_conflict. UsefromToorxPercent/yPercent. - Do not add a scene-exit
tl.set(..., {visibility:"hidden"}). The runtime already hides timed clips. Opacity fades on inner nodes (oropacityon.clip) are enough. Caption hard-kills are a different rule. window.__timelines["id"]must match the rootdata-composition-id.- After
render, read the summary's second line:beginframevsscreenshot, GPU mode, stage timings.screenshot+software gpuon Linux is the slow path.
HyperFrames renders video from HTML. A composition is an HTML file whose DOM declares timing with data-* attributes, whose animation runtime is seekable, and whose media playback is owned by the framework.
This skill is the technical contract — how to build one hyperframes project. The body below is the build guide; per-topic detail lives in references/ (index next), read on demand. Process docs (brief, storyboard, review, production, dispatch, frame-worker) live in /hyperframes → references/. Other concerns live in the sibling domain skills — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. The capability map in /hyperframes says what each one covers.
References
| File | Read it to… |
|---|---|
references/minimal-composition.md | start from the smallest renderable composition skeleton |
references/composition-patterns.md | choose monolithic vs modular; structure a modular index.html; pick a sub-comp archetype |
references/data-attributes.md | look up any data-* (root / clip / sub-comp host / legacy aliases); use class="clip" |
references/tracks-and-clips.md | understand what data-track-index does (and does not) control, z-index, time a clip relative to another; list every track and clip with npx hyperframes timeline |
references/creator-editing-recipes.md | copy truthful cut/trim/reorder/retime/freeze/camera/mask/crossfade/audio editing recipes and their limits |
references/sub-compositions.md | wire a sub-composition (host attrs, <template>, per-instance vars) and animate inside it |
references/variables-and-media.md | declare variables; place <video>/<audio>, set volume, trim |
references/determinism-rules.md | build a seekable timeline; determinism bans; layout / text fit |
references/full-screen-motion.md | author full-frame motion with shared backgrounds |
references/tailwind.md | work in a Tailwind v4 project (init --tailwind; runtime contract differs from Studio's v3) |
For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to hyperframes-animation → adapters/<runtime>.md.
Building a composition
Two root forms (not interchangeable)
- Standalone (top-level
index.html): root<div data-composition-id="…">sits directly in<body>, no<template>wrapper. Wrapping a standalone root hides all content andlintrejects it (standalone_composition_wrapped_in_template, error). - Sub-composition (loaded via
data-composition-src): wrap the root in<template>. This is the shape to write: the loader also accepts a plain full document and falls back to its<body>, but the templated form is what the examples and tooling assume.
⚠ Transport rule: for a templated sub-composition the assembler drops the file's own
<head><style>/<script>(packages/core/src/compiler/compositionAssembly.ts, thehasTemplategate), so put<style>/<script>inside the template.<link>is hoisted either way. ⚠ Host-id convention: give the host slot, the inner template, and thewindow.__timelines["<id>"]key the same id. A different local id is supported (the assembler falls back to the first root in the file) but the mismatch is silent, so match them unless you have a reason not to.
File shape, host wiring, and the pre-render checklist → references/sub-compositions.md.
Root must be sized (silent layout bug)
The standalone root authors width/`heigh