hyperframes-core

**插件安装：**在设置或检查更新之前，如果此技能位于 HyperFrames 插件中，请遵循插件执行规则。独立安装请保留以下更新说明。

HyperFrames Core

Agent 常见问题（请先阅读）：

• 使用 flex/inset 居中，不要在之后会通过 GSAP 设置 x/y 的节点上使用 CSS transform: translate(-50%,-50%)。Lint：gsap_css_transform_conflict。请使用 fromTo 或 xPercent/yPercent。
• 不要添加场景退出时的 tl.set(..., {visibility:"hidden"})。运行时已经会隐藏定时片段。对内部节点进行透明度淡出（或设置 .clip 的 opacity）即可。字幕的强制隐藏是另一条规则。
• window.__timelines["id"] 必须与根节点的 data-composition-id 匹配。
• render 后，请读取摘要的第二行：beginframe 与 screenshot、GPU 模式、阶段耗时。在 Linux 上，screenshot + software gpu 是较慢的路径。

HyperFrames 从 HTML 渲染视频。合成内容是一个 HTML 文件，其 DOM 使用 data-* 属性声明时间，动画运行时可进行定位播放，媒体播放则由框架负责。

此技能是技术规范——说明如何构建一个 hyperframes 项目。下文是构建指南；各主题的详细信息位于 references/（索引见下一节），请按需阅读。流程文档（简报、故事板、评审、制作、派发、frame-worker）位于 /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-*（根元素 / clip / 子合成宿主 / 旧版别名）；使用 class="clip"
references/tracks-and-clips.md	了解 data-track-index 会（和不会）控制什么、z-index，以及相对于另一个 clip 设置 clip 时间；使用 npx hyperframes timeline 列出每条轨道和每个 clip
references/creator-editing-recipes.md	复制真实可靠的剪切 / 修剪 / 重排 / 调速 / 定格 / 摄像机 / 遮罩 / 交叉淡化 / 音频编辑方案及其限制
references/sub-compositions.md	接入子合成（宿主属性、<template>、每个实例的变量），并在其中进行动画处理
references/variables-and-media.md	声明变量；放置 <video>/<audio>，设置音量和修剪
references/determinism-rules.md	构建可定位时间轴；确定性禁用项；布局 / 文本适配
references/full-screen-motion.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> 包装。包装独立合成的根元素会隐藏所有内容，且 lint 会拒绝它（standalone_composition_wrapped_in_template，错误）。
• 子合成（通过 data-composition-src 加载）：将根元素包装在 <template> 中。应采用这种形式：加载器也接受普通完整文档，并回退到其 <body>，但示例和工具默认使用带模板的形式。

⚠ 传输规则：对于带模板的子合成，装配器会丢弃文件自身 <head> 中的 <style>/<script>（packages/core/src/compiler/compositionAssembly.ts 中的 hasTemplate 检查），因此请将 <style>/<script> 放在模板内部。无论哪种形式，<link> 都会被提升。 ⚠ 宿主 ID 约定：宿主插槽、内部模板以及 window.__timelines["<id>"] 键使用相同的 ID。支持使用不同的本地 ID（装配器会回退到文件中的第一个根元素），但这种不匹配不会提示，因此除非有特殊原因，否则请保持一致。

文件结构、宿主接线和预渲染检查清单 → references/sub-compositions.md。

根元素必须设置尺寸（静默布局错误）

独立根元素使用 width/height: 100%。画布尺寸由 data-width/data-height 指定。运行时会将这些像素值写入合成根元素。不要在 #root 上硬编码 1920px/1080px。骨架 → references/minimal-composition.md。

一个暂停的时间轴

每个合成恰好注册一个 gsap.timeline({ paused: true })，并存放在 window.__timelines["<id>"] 中（键 = 根元素的 data-composition-id）。在异步回调（document.fonts.ready）中构建它也受支持；关键是仅在构建完成后注册。渲染时长由根元素的 data-duration 指定，而不是时间轴的时长：超出该时长的时间轴会被截断，提前结束的时间轴则会停留在最后一帧。省略根元素的 data-duration 时，时长会改为推断（根据时间轴、媒体窗口或适配器）。你不需要设置 window.__timelines = window.__timelines || {}：运行时会在内联脚本运行前创建注册表，而且 lint 已不再要求设置它。不要手动将子时间轴嵌套到宿主中；运行时会自动嵌套已注册的子时间轴。完整规范（包括非 GSAP 运行时）→ references/determinism-rules.md + hyperframes-animation/adapters/。

首轮 lint 易错点（必定导致首次构建失败）

以下问题是 lint 会检测到的，但只能在事后发现。请一开始就写对：

• 绝不要在同一属性上同时使用 CSS 初始 transform 和 GSAP 补间动画——CSS 值会与补间动画的起始值冲突，lint 会以 gsap_css_transform_conflict 拒绝。请改为在补间动画中设置初始状态，例如使用 gsap.fromTo(el, { x: -40 }, { x: 0 })，而不是 CSS transform: translateX(-40px)。
• 绝不要在 <video>/<audio> 上使用 crossorigin。lint 会无条件以 media_crossorigin_breaks_preview（错误）拒绝，包括用于 canvas/WebGL/WebAudio 读取的情况。没有例外。
• 绝不要让带有 data-start 的 <video> 的祖先元素也带有 data-start。lint 会以 video_nested_in_timed_element（错误）拒绝。只对外层元素或视频设置时间，不要同时设置。
• 每个 <audio> 都需要有 id。否则 lint 会以 media_missing_id 拒绝；而且没有 id 的 <audio> 永远不会被混音器拾取，因此渲染结果会静音。
• 绝不要对 .clip 使用 autoAlpha 或 visibility 补间动画——lint 会以 gsap_animates_clip_element 拒绝。请改为对其子元素设置动画。
• 命名的 CSS font-family 需要在文件内使用 @font-face 指向已随项目提供的本地文件，否则 lint 会触发 font_family_without_font_face。
• 子合成的 #root 使用 width/height: 100%（或 inset: 0），不要硬编码 1920px/1080px。画布尺寸由 data-width/data-height 指定。

出现 lint 错误也会关闭布局和对比度审计：此时 check 会报告 0 sample(s) 和 0/0 text checks，看起来像是文件没有问题，但实际上什么都没运行。请先清除 lint 错误，再相信这些数字。

不可妥协的规则（自动检查可能遗漏的隐蔽错误）

此处列出；完整原因见链接的参考文档。请勿违反：

• 不要在渲染时使用时钟／未设种子的 Math.random／网络／输入状态；repeat: -1 只能用于具有有限根 data-duration 的情况（导出片段时将其作为时长上限——否则请使用有限次数）。→ determinism-rules.md
• 绝不要在 .clip 元素上对 display、visibility 或 autoAlpha 执行动画。框架负责控制片段可见性，且 lint 会拒绝这种做法（gsap_animates_clip_element）。请改为对其子元素执行动画。→ determinism-rules.md
• 正文中不要使用 <br>；变换后的元素必须是块级元素且具有尺寸；脉冲式绝对定位装饰元素必须留有足够的峰值空间。→ determinism-rules.md
• <video>／<audio> 通过扁平的文档查询查找，因此框架会在任意嵌套深度（包括子合成 <template> 或包装元素内部）对其进行定位和解码。只有一项硬性限制：如果 <video data-start> 位于另一个也带有 data-start 的普通元素内部，lint 会报错；这会导致实际故障（源帧错误，随后片段在时段中途消失），因此请将时间设置在包装元素或视频上，绝不要两者都设置。子合成宿主不受此限制：子合成内部的媒体可以正确渲染。另一项注意事项涉及时间轴，而非放置位置：子合成时间轴无法对宿主根元素执行动画。→ variables-and-media.md
• 确保组装后的页面中每个 id 都唯一（为子合成 ID 添加合成 ID 前缀，例如 #<id>-hero），这样你自己的 #id CSS 和 getElementById 调用才能正确解析。帧注入不再依赖此规则：编译器会为每个 video[src]／audio[src]／img[src] 添加文档级唯一的 data-hf-render-id。使用 <source> 子元素而非 src 属性的媒体不会添加此标记，因此此类媒体仍需要唯一 ID。→ composition-patterns.md
• 在普通渲染中，合成根元素上的全屏填充没有问题。只有在分层合成路径中（HDR 内容，或使用着色器转场的合成），该填充才会被移除；此时引擎会强制所有合成根元素透明，让下方图层显示出来。如果合成使用着色器转场或 HDR 媒体，请将填充放在全出血的子元素上（position:absolute; inset:0）。→ composition-patterns.md

编辑现有合成

• 先阅读文件。保留无关的时间设置、轨道、ID、变量和媒体路径。
• 若要了解项目时间轴上的内容（轨道、片段、起止时间、播放内容），请运行 npx hyperframes timeline [--json]，而不是逐一阅读 index.html 和每个子合成文件。
• 匹配现有合成 ID 和时间轴键。
• 添加片段时：根据周围的片段，有意设置其 data-start／data-duration。data-track-index 是 Studio 的显示轨道，并非时间约束，因此无需空闲。
• 如果片段结束时间超过根元素的 data-duration，片段会被截断：请在同一次编辑中将根元素的 data-duration 延长至片段结束时间（lint 会发出 clip_ends_past_root_duration 警告）。
• 嵌套在另一个定时元素中的片段，其 data-start 从合成起始时间计算，而非从该元素起始时间计算；且仅在该元素显示时显示。timeline 会将其列在父元素之下，并在两个时间窗口错开时发出 never visible 警告（lint 会报告 nested_clip_never_visible）。
• 对任何合成元素设置 data-hidden，都会使其在预览和渲染中同时隐藏，并覆盖其时间窗口；此操作可逆，不会破坏内容，可通过 Studio 时间轴上的眼睛图标切换。
• 添加子合成时：在连接宿主之前，先确认其内部的 data-composition-id。

验证

使用 hyperframes-cli 查看命令详情

• npx hyperframes check 通过（lint、运行时、布局、动画和对比度检查均无发现）
• 包含子合成的项目：运行 npx hyperframes snapshot --at <midpoints>，并目视检查每一帧
• 使用 npx hyperframes preview --background 进行审查（用户可以在 Studio 的时间轴中编辑任何内容，且服务器会在调用命令结束后继续运行）
• 仅在用户批准后运行 npx hyperframes render