hyperframes-core

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，处理同轨重叠 / 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/script-format.md	编写可选的 SCRIPT.md 固定旁白
references/subagent-dispatch.md	将子 Agent 调度动词（并行扇出 / 后台运行 / 等待）映射到你的运行环境
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> 放在 <template> 内部。 ⚠ 宿主 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，内容便会堆在左上角。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