topcheer/ggcode

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	Brief 的基本规则——模式推导（协作 / 自主）、共享字段注册表、问题不变量（提问本身位于 /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。

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

独立式根需要一个显式的尺寸盒子（width/height 以 px 为单位），并且每个祖先元素直到 height:100% 元素都必须具有已解析的高度——否则 flex / 100% 的子元素会收缩到约 0，内容堆积在左上角。不要仅依赖自动门控来捕捉此问题；检查快照。骨架 → references/minimal-composition.md。

一个暂停的时间线

每个合成在 window.__timelines["<id>"] 处注册恰好一个 gsap.timeline({ paused: true })（键 = 根 data-composition-id），在页面加载时同步构建。渲染时长 = 根 data-duration，而非时间线长度。不要手动将子时间线嵌套到宿主中。完整合约（包括非 GSAP 运行时）→ references/determinism-rules.md + hyperframes-animation/adapters/。

不可协商的规则（自动门控可能遗漏的静默错误）

此处列出；完整理由请参考相关链接。不得违反：

• 禁止运行时时钟 / 未播种的 Math.random / 网络 / 输入状态；禁止 repeat: -1（使用有限次数）。→ determinism-rules.md
• 仅动画化视觉属性允许列表；切勿补间 display 或原始 visibility。GSAP autoAlpha 和零时长时间线边界设置是唯一的可见性例外，且仅适用于非剪辑元素或剪辑内的包装器。框架独自控制 .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、运行时、布局、动画和对比度方面的 0 项发现）
• 带有子合成的项目：npx hyperframes snapshot --at <midpoints> 并目视检查每一帧
• npx hyperframes preview 用于审查（用户可以在 Studio 的时间线中编辑任何内容）
• 仅在用户批准后使用 npx hyperframes render