HyperFrames 合成规范——构建一个可渲染的项目。用于合成结构、`data-*` 时间属性、`class="clip"`、轨道、子合成、变量、框架拥有的媒体播放、确定性渲染规则和验证。在编写合成 HTML 之前请先阅读。
HyperFrames Core
HyperFrames 从 HTML 渲染视频。合成是一个 HTML 文件，其 DOM 使用 data-* 属性声明时间，其动画运行时是可搜索的，并且媒体播放由框架拥有。
本技能是技术规范——如何构建一个 hyperframes 项目。以下正文是构建指南；每个主题的详细信息位于 references/ 中（索引见下文），按需阅读。其他问题位于兄弟领域技能中——hyperframes-animation、hyperframes-creative、hyperframes-media、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力图说明了每个技能涵盖的内容。
参考
| 文件 | 阅读目的… |
|---|---|
references/minimal-composition.md |
从最小的可渲染合成骨架开始 |
references/composition-patterns.md |
选择整体式与模块化；构建模块化 index.html；选择子合成原型 |
references/data-attributes.md |
查找任何 data-*（根/剪辑/子合成宿主/遗留别名）；使用 class="clip" |
references/tracks-and-clips.md |
选择 data-track-index，处理同轨道重叠/层级，使一个剪辑相对于另一个剪辑定时 |
references/sub-compositions.md |
连接子合成（宿主属性、<template>、实例变量）并在其内部制作动画 |
references/variables-and-media.md |
声明变量；放置 <video>/<audio>，设置音量，裁剪 |
references/determinism-rules.md |
构建可搜索的时间线；确定性禁止项；可动画属性白名单；布局/文本适配 |
references/full-screen-motion.md |
使用共享背景创作全帧运动 |
references/storyboard-format.md |
创作 STORYBOARD.md 计划（以及解析后的清单） |
references/script-format.md |
创作可选的 SCRIPT.md 锁定旁白 |
references/subagent-dispatch.md |
将子代理调度动词（并行扇出/后台/等待）映射到你的工具集 |
references/tailwind.md |
在 Tailwind v4 项目中工作（init --tailwind；运行时合约与 Studio 的 v3 不同） |
有关动画运行时的具体信息（GSAP API、Lottie、Three.js 等），请参阅 hyperframes-animation → 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 以像素为单位），并且每个祖先直到 height:100% 元素都必须有已解析的高度——否则 flex/100% 子元素会折叠到约 0，内容堆叠到左上角。lint/validate/inspect 不会捕获此问题。骨架 → references/minimal-composition.md。
一个暂停的时间线
每个合成在 window.__timelines["<id>"] 处注册恰好一个 gsap.timeline({ paused: true })（键 = 根 data-composition-id），在页面加载时同步构建。渲染时长 = 根 data-duration，而不是时间线长度。不要手动将子时间线嵌套到宿主中。完整合约（包括非 GSAP 运行时）→ references/determinism-rules.md + hyperframes-animation/adapters/。
不可协商的规则（lint/validate/inspect 不会捕获的静默错误）
在此列出；完整理由见链接参考。不得违反：
- 无渲染时时钟/未播种的
Math.random/网络/输入状态；无repeat: -1（使用有限次数）。→determinism-rules.md - 仅动画化视觉属性白名单；从不使用
display/visibility；不在后期场景剪辑上使用gsap.set。→determinism-rules.md - 正文文本中无
<br>；变换后的元素必须是块级且带尺寸；脉动绝对定位装饰元素需要峰值间隙。→determinism-rules.md <video>/<audio>必须是宿主根的直接子元素（绝不能放在子合成<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。
验证
使用 hyperframes-cli 获取命令详细信息
- [ ]
npx hyperframes lint通过（0 错误） - [ ]
npx hyperframes validate通过（0 控制台错误） - [ ]
npx hyperframes inspect通过（0 错误） - [ ] 包含子合成的项目：
npx hyperframes snapshot --at <midpoints>并目视检查每一帧 - [ ] 使用
npx hyperframes preview进行审查（用户可以在 Studio 的时间线中编辑任何内容） - [ ] 仅在用户批准后执行
npx hyperframes render
