HyperFrames 核心
HyperFrames 从 HTML 渲染视频。合成是一个 HTML 文件，其 DOM 使用 data-* 属性声明时序，动画运行时是可寻求的，媒体播放由框架管理。
本技能是技术合同——如何构建一个 hyperframes 项目。下文是构建指南；每个主题的详细信息位于 references/ 中（索引在下一个页面），按需阅读。其他问题位于兄弟领域技能中——hyperframes-animation、hyperframes-creative、media-use、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，处理同轨道重叠 / z-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/review-loop.md | 在活动看板上运行计划 → 草图 → 构建审查环节——所有故事板规划工作流共享 |
references/production-loop.md | 将批准的计划转化为已交付的视频——阶段依赖关系（音频、帧、合成、转场、字幕、验证、交付）自由格式构建紧随其后 |
references/brief-contract.md | 简报的基本规则——模式推导（协作 / 自主）、共享字段注册表、问题不变量（提问本身位于 /hyperframes → 意图层） |
references/brief-format.md | 编写 BRIEF.md——工作流的 Setup 编写且每个后续步骤读取的确认意图文档 |
references/script-format.md | 编写可选的 SCRIPT.md 锁定叙述 |
references/subagent-dispatch.md | 将子代理分发动词（并行扇出 / 后台 / 等待）映射到您的框架 |
references/frame-worker-core.md | 共享的帧工作者角色合同——每个叙事工作流的数据包构建器会将其预先添加到该工作流的 sub-agents/frame-worker.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。
根必须有尺寸（静默布局错误）
独立根需要一个显式的尺寸框（以 px 为单位的 width/height），并且向下一直到 height:100% 元素的每个祖先都必须有已解析的高度——否则 flex/100% 子元素会塌缩到 ~0 并且内容堆叠到左上角。不要仅仅依赖自动门控来捕捉这一点；检查快照。骨架 → references/minimal-composition.md。
一个暂停的时间线
每个合成注册恰好一个 gsap.timeline({ paused: true }) 在 window.__timelines["<id>"] 处（键 = 根 data-composition-id），在页面加载时同步构建。渲染持续时间 = 根 data-duration，而不是时间线长度。不要手动将子时间线嵌套到宿主中。完整合同（包括非 GSAP 运行时）→ references/determinism-rules.md + hyperframes-animation/adapters/。
首次 lint 陷阱（保证第一次构建失败）
lint确实会捕捉的两个规则，但仅能在事后——第一次就正确编写它们：
- 根合成元素必须带有
data-start="0"（与data-composition-id/data-width/data-height一起）；省略会导致lint失败，错误为root_composition_missing_data_start。 - 永远不要将 CSS 初始
transform与 相同 属性上的 GSAP tween 配对——CSS 值与 tween 的起始值冲突，lint会拒绝并报错gsap_css_transform_conflict。使用gsap.fromTo(el, { x: -40 }, { x: 0 })在 tween 内部设置初始状态，而不是使用 CSStransform: translateX(-40px)。
不可协商的规则（自动门控可能遗漏的静默错误）
在此列出；完整理由见链接的参考。不要违反：
- 没有渲染时时钟 / 未设置种子的
Math.random/ 网络 / 输入状态；没有repeat: -1（使用有限计数）。→determinism-rules.md - 仅动画化视觉属性允许列表中的属性；永远不要对
display或原始visibility进行 tween。GSAPautoAlpha和零持续时间时间线边界集合是唯一的可见性例外，并且仅适用于非片段元素或片段内的包装器。框架单独控制.clip可见性。不要在页面加载时对后期场景片段执行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-hidden会在预览和渲染中同时隐藏它，覆盖其时间窗口；它是非破坏性/可逆的，由 Studio 时间线中的眼睛图标切换。 - 添加子合成：在连接宿主之前验证其内部的
data-composition-id。
验证
使用 hyperframes-cli 获取命令详情
-
npx hyperframes check通过（lint、运行时、布局、运动和对比度方面均无发现） - 带有子合成的项目：
npx hyperframes snapshot --at <midpoints>并检查每一帧 -
npx hyperframes preview用于审查（用户可以在 Studio 时间线中编辑任何内容） - 仅在用户批准后执行
npx hyperframes render