HyperFrames 核心
HyperFrames 从 HTML 渲染视频。合成是一个 HTML 文件，其 DOM 通过 data-* 属性声明时序，动画运行时是可搜寻的，媒体播放由框架拥有。
这是合成契约——如何构建一个 HyperFrames 项目。以下内容为构建指南；每个主题的详细信息位于 references/（索引见下），按需阅读。其他关注点位于同一技能的兄弟章节——../cli（开发循环）和 ../registry（安装块/组件）——以及兄弟设计技能 /hyperframes-motion（动画配方）和 /hyperframes-design（调色板、排版、帧预设）。../SKILL.md 中的能力映射说明了每个部分涵盖的内容。
参考
| 文件 | 阅读它以… |
|---|---|
references/minimal-composition.md | 从最小的可渲染合成骨架开始 |
references/composition-patterns.md | 选择单体 vs 模块化；构建模块化 index.html；选择子合成原型 |
references/data-attributes.md | 查找任何 data-*（根/剪辑/子合成宿主/遗留别名）；使用 class="clip" |
references/tracks-and-clips.md | 选择 data-track-index，处理同轨道重叠/z 索引，将一个剪辑相对于另一个剪辑计时 |
references/sub-compositions.md | 连接子合成（宿主属性、<template>、实例变量）并在其中制作动画 |
references/variables-and-media.md | 声明变量；放置 <video> 以实现纯视觉播放 |
references/determinism-rules.md | 构建可搜寻的时间轴；确定性禁止；可动画属性允许列表；布局/文本适配 |
references/full-screen-motion.md | 使用共享背景创作全帧动画 |
references/storyboard-format.md | 创作 STORYBOARD.md 计划（加上解析的清单） |
references/subagent-dispatch.md | 将子代理调度动词（并行扇出/后台/等待）映射到你的工具链 |
references/tailwind.md | 在 Tailwind v4 项目中工作（init --tailwind；运行时契约与 Studio 的 v3 不同） |
关于动画运行时的具体内容（GSAP API、Lottie、Three.js 等）请参见 /hyperframes-motion → adapters/<runtime>.md。
构建合成
两种根形式（不可互换）
- 独立（顶层
index.html）——根<div data-composition-id="…">直接位于<body>中，没有<template>包装器（包装它会隐藏所有内容并破坏渲染）。 - 子合成（通过
data-composition-src加载）——根必须包装在<template>中。
⚠ 传输规则：运行时仅克隆
<template>内容；外部所有内容（包括<head>中的样式/脚本）都会被丢弃——将<style>/<script>放在模板内部。 ⚠ 宿主 ID 规则：宿主插槽的data-composition-id必须完全等于内部模板的data-composition-id并且window.__timelines["<id>"]键——没有-mount/-slot/-host后缀。
文件形状、宿主连接和预渲染检查清单 → references/sub-compositions.md。
根必须有尺寸（静默布局错误）
独立根需要一个显式尺寸框（width/height 以 px 为单位），并且每个祖先元素直到 height:100% 的元素都必须有解析的高度——否则 flex/100% 的子元素会折叠成约 0，内容挤到左上角。lint/validate/inspect 并不捕获这个。骨架 → references/minimal-composition.md。
一个暂停的时间轴
每个合成在 window.__timelines["<id>"]（键 = 根 data-composition-id）处注册恰好一个 gsap.timeline({ paused: true })，在页面加载时同步构建。渲染持续时间为根 data-duration，而不是时间轴长度。不要手动将子时间轴嵌套到宿主中。完整契约（包括非 GSAP 运行时）→ references/determinism-rules.md + /hyperframes-motion/adapters/。
不可协商的规则（lint/validate/inspect 不会捕获的静默错误）
这里列出；完整理由在链接的参考中。不要违反：
- 无运行时时钟/未播种的
Math.random/网络/输入状态；无repeat: -1（使用有限次数）。→determinism-rules.md - 仅对视觉属性允许列表进行动画；永远不要使用
display/visibility；后续场景剪辑不要使用gsap.set。→determinism-rules.md - 正文文本中无
<br>；变换后的元素必须是块级+有尺寸；脉冲绝对装饰元素需要峰清除。→determinism-rules.md <video>必须是宿主的直接子元素（永远不要在子合成<template>/包装器内部）；框架拥有播放控制。→variables-and-media.md- 每个
id在组装后的页面中必须唯一；在子合成内部，用合成 ID 前缀 id（#<id>-hero）。重复的<video>/<img>id 渲染为空白——生产者通过getElementById注入帧，跨文件重复会绕过lint。→composition-patterns.md - 全屏场景填充放在满出血子元素上（
position:absolute; inset:0），永远不要放在合成根自身——生产者的帧合成可能会丢弃根元素自身的background（帧渲染为黑色），即使预览/snapshot显示正常。→composition-patterns.md
编辑现有合成
- 先阅读文件。保留不相关的时序、轨道、ID、变量、媒体路径。
- 匹配现有合成 ID 和时间轴键。
- 添加剪辑：选择一个不重叠的
data-track-index或有意调整周围时序。 - 添加子合成：在连接宿主之前验证其内部
data-composition-id。
验证
运行 CLI 步骤（参见 ../cli/SKILL.md → 工作流程 + 最低完成门，了解规范的 lint/validate/inspect/snapshot/preview/render 检查清单，包括子合成项目所需的视觉冒烟测试）。