HyperFrames Core
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 | 选择整体式 vs 模块化;构建模块化 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。
一个暂停的时间线
每个合成在 window.__timelines["<id>"](键 = 根元素的 data-composition-id)处注册恰好一个 gsap.timeline({ paused: true }),在页面加载时同步构建。渲染时长 = 根元素的 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 对同一属性的补间配对——CSS 值和补间的起始值冲突,lint会以gsap_css_transform_conflict拒绝它。请使用gsap.fromTo(el, { x: -40 }, { x: 0 })在补间内设置初始状态,而不是使用 CSStransform: translateX(-40px)。
不可协商的规则(自动化门控可能遗漏的静默错误)
在此列出;完整理由见链接的参考文献。不得违反:
- 禁止运行时时钟 / 未播种的
Math.random/ 网络 / 输入状态;禁止repeat: -1(使用有限计数)。→determinism-rules.md - 仅对视觉属性允许列表进行动画;永远不要对
display或原始visibility进行补间。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