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. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.
1How It Works & Mechanism
This skill serves as the "technical contract" for HyperFrames: the complete rulebook for authoring HTML into renderable video—a single paused timeline, `data-*` timing attributes, `class="clip"`, sub-compositions, and deterministic rendering prohibitions. The main text of SKILL.md functions as the build guide, with granular details offloaded on demand across 19 cards in references/.
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.
Core model: composition = HTML file, DOM declares timing via `data-*` attributes, each composition registers exactly one `gsap.timeline({ paused: true })` to `window.__timelines["<id>"]`, and render length is determined by the root `data-duration` (not the timeline duration).
Each composition registers **exactly one** `gsap.timeline({ paused: true })` at `window.__timelines["<id>"]` (key = root `data-composition-id`).
Capabilities cover actual lint rulesets: SKILL.md enumerates lint-catchable pitfalls item-by-item (such as gsap_css_transform_conflict, media_crossorigin_breaks_preview, video_nested_in_timed_element, media_missing_id), warning that lint errors will simultaneously disable layout/contrast audits.
Never put `crossorigin` on `<video>`/`<audio>`. `lint` rejects it unconditionally with `media_crossorigin_breaks_preview` (error), including for canvas/WebGL/WebAudio readback. There is no suppression.
Deterministic rendering is a strict rule (not a recommendation): no runtime clocks, unseeded Math.random, network calls, or input state; no `repeat: -1`; no tweening display or raw visibility on clip elements; no `<br>` inside body text.
No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count).
The sub-composition assembly contract is strictly defined down to file structure: standalone roots must not be wrapped in `<template>` (lint error standalone_composition_wrapped_in_template), whereas sub-compositions must be wrapped in `<template>` with style/script placed inside the template (the hasTemplate gate strips header style/script), and the host, inner, and timeline keys must share the identical ID.
for a **templated** sub-composition the assembler drops the file's own `<head>` `<style>`/`<script>` (`packages/core/src/compiler/compositionAssembly.ts`, the `hasTemplate` gate), so put `<style>`/`<script>` **inside** the template.
The validation loop is real, structured, and tiered: `npx hyperframes check` runs five audit classes at once (lint, runtime, layout, motion, contrast), snapshot extracts frames for visual inspection, `preview --background` serves human review, and render requires explicit user approval before execution.
- [ ] `npx hyperframes check` passes (0 findings across lint, runtime, layout, motion, and contrast) - [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame
2Core Capabilities
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI（check/snapshot/preview/render；命令细节在 /hyperframes-cli） |
| network | GSAP 经 CDN 进 composition（示例/骨架引 jsdelivr gsap；渲染时在 headless 浏览器加载——产物运行依赖，非 skill 自身外发） |
| package | @hyperframes/core / engine（同仓 packages/，真实校验/装配/渲染实现） |
4Recommended Governance & Evidence
- scripts/: Executes local scripts or commands: npx hyperframes check / snapshot / preview --background / render (local CLI: lin
- 网络端点: Declares external network access: During rendering and preview, compositions fetch runtime libraries like gsap from CDNs (jsdelivr; artifact-level dependencies that can be vendored to prevent network requests) as authored
- 本地工作目录: File read/write and artifact output: Author output: index.html / compositions/*.html / STORYBOARD.md / SCRIPT.md / frame.m
5Second-Pass Verification
- [ok] lint 规则名与真实校验器对应 — SKILL.md 引用的编译器路径 packages/core/src/compiler/compositionAssembly.ts 在仓库 packages/core 下实测存在（仓库级 glob 复核）；规则命名风格与 .oxlintrc/engine 校验一致。
- [discrepancy] 『document.fonts.ready 内构建可接受』与『禁 async 构建』是否矛盾 — 首轮将两条规则并置易误读：SKILL.md 正文允许在 async callback（fonts.ready）里构建但『register only after the build completes』；animation SKILL.md 的『no timeline construction inside async/setTimeout』指不能把注册放进未完成的异步流。两条实质一致（注册须在构建完成后同步完成），已在 how_it_works 注明而非判定矛盾。
- [ok] preview 进程存活行为 — SKILL.md 'the server survives the invoking command' 复核一致——preview 是常驻本地服务，属预期行为已列入 file_writes 描述。
- [ok] 有无隐藏脚本/网络（纯文档声称） — find 实测 skills/hyperframes-core 含 1 个共享 lib（scripts/lib/frame-packets-core.mjs，packet 数据组装，无 IO 外发）；无网络代码。
- [ok] 与其它 skill 的契约引用一致性 — music-to-video frame-worker.md、hyperframes 路由、hyperframes-audio SKILL 均引用 core 的 determinism/sub-composition 契约且无互相矛盾的定义。
6Verdict & Scenarios
74bec24a87c21ea7…