用途:HyperFrames 从 HTML 渲染视频。一个合成就是一个 HTML 文件,DOM 通过 data-* 属性声明时间信息,动画运行时必须可定位(seekable),媒体播放由框架统一管理。本技能即“合成契约”,规定如何构建一个 HyperFrames 项目;细节按需查阅 references/ 目录索引,开发循环见 ../cli,安装块与组件见 ../registry,动画配方见 /hyperframes-motion,配色、排版与画框预设见 /hyperframes-design。
主要能力与结构:两种根形式不可互换——独立合成(顶层 index.html,根 div 的 data-composition-id 直接位于 body,不能包 template,否则内容被隐藏、渲染失败);子合成(通过 data-composition-src 加载,根必须包在 template 中)。transport 只克隆 template 内容,head 里的样式与脚本会被丢弃,需放进 template。宿主槽的 data-composition-id 必须与内层 template 及 window.__timelines["<id>"] 键完全一致,不能加后缀。独立根必须显式设置 px 宽高,且到 height:100% 元素的每个祖先都需有确定高度,否则 flex/100% 子元素会塌陷。
必要用法:每个合成在 window.__timelines["<id>"] 注册恰好一个 gsap.timeline({ paused: true }),在页面加载时同步构建;渲染时长取根 data-duration,而非时间轴长度;不要手动把子时间轴嵌入宿主。
限制(lint/validate/inspect 无法捕获的静默错误):禁止渲染期时钟、未播种 Math.random、网络与输入状态,禁止 repeat: -1;仅允许对白名单视觉属性做动画,禁止 display/visibility,禁止对后续场景剪辑做 gsap.set;正文禁用 <br>;被 transform 的元素须为块级并有尺寸;video 必须是宿主根的直系子元素;所有 id 全页唯一,子合成内加前缀;全屏场景填充放在全出血子元素上,不放合成根;修改既有合成时先读文件并保留无关时序、轨道、ID、变量和媒体路径。校验请运行 CLI 门禁(lint / validate / inspect / snapshot / preview / render,子合成项目需视觉冒烟测试)。
适用场景:构建或修改 HyperFrames 视频合成项目、组织模块化与非模块化结构、编排轨道与剪辑、接入子合成与变量、排查渲染为黑屏或布局塌陷等问题。