HyperFrames 核心
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 | 将子代理调度动词(并行扇出/后台/等待)映射到你的工具链 |
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 且内容堆叠到左上角。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