HyperFrames 动效合成 Builder 契约全解布局、时间线与确定性渲染的强制规则【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes本指南详解 HyperFrames 中 motion-graphics 动效合成的Builder 契约skills/motion-graphics/references/builder-contract.md——它是构建阶段Builder把shot-plan.json落成可渲染compositions/index.html时不可协商的组成规则。读完本文你将掌握如何正确给根舞台定尺寸、如何按先静态布局、后动画的顺序搭建 Hero Frame、如何用一条 paused 的 GSAP 时间线驱动全部运动、如何保证 seek 安全与输出确定性并通过hyperframes check、proof snapshot 等验证闭环交付一段可被引擎逐帧驱动渲染的 HTML 合成。一、契约的定位Builder 背后的详细规则在 motion-graphics 技能的工作流中build阶段由 Builder 子代理将 shot-plan.json 中的块选择、布局、运动规划转换为一份单文件合成 compositions/index.html。其中 agents/builder.md 定义的是高层职责复用优先、HF 契约不可协商、IR→合成映射、GSAP/seek 正确性、交接验证而本契约文件则是这些职责背后的逐条细节包括根节点尺寸、布局顺序、时间线注册、确定性约束与配色纪律。核心前提HTML 是唯一事实来源source of truth一条 paused 的 GSAP 时间线承载全部运动渲染引擎按帧 seek 它。这意味着合成代码必须满足引擎随时可以把时间线拨到任意时刻并得到正确画面这一根本要求——下文所有规则都围绕这一目标展开。二、根节点必须显式定尺寸契约第一条根舞台#stage带data-composition-id的元素必须写明#stage { position: relative; width: 1920px; height: 1080px; }为什么必须定高如果没有解析出的高度flex 子元素会塌缩到约 0内容会全部堆叠到左上角。注意引擎对根节点的宽高读取是有据可查的——data-width/data-height属性会被运行时读取为合成尺寸packages/core/src/runtime/timeline.ts 的测试同时验证了默认 1920×1080 的回退与从根节点显式读取如 3840×2160两条路径见 packages/core/src/runtime/timeline.test.ts。契约特别提醒自动化的 gate 可能漏检这一点所以必须人工检查 proof snapshot验证阶段的证据截图肉眼确认内容没有挤在左上角。参考官方空白模板的根节点写法packages/cli/src/templates/blank/index.htmldiv idroot >.scene-content { display: flex; flex-direction: column; justify-content: center; width: 100%; height: 100%; padding: 120px 160px; gap: 24px; box-sizing: border-box; }要点内容容器永远不要用position: absolute; top: Npx来定位——它会溢出画布position: absolute只留给装饰性元素decoratives内边距保持 ≥ 80pxtitle-safe margin标题安全边距上面的 120px/160px 即为合规示例。四、入场与退场from 与 fromTo 的边界入场Entrancesgsap.from()只允许用于从 t0 就活跃的、非 clip 的元素在.clip内部、子组合sub-compositions中、以及任何延迟入场的元素都必须使用显式的fromTo()。原因在于from()依赖引擎从首帧就开始推进补间而 clip 内部或延迟元素在时间线被 seek 到起点之前其初始状态不可靠。显式fromTo()才具备 seek 安全性。退场Exits只有最后一个场景final scene会做元素退场动画场景与场景之间转场本身就是退场——不需要单独为每个场景写 exit。这条规则大幅简化了时间线中间场景的动画只需要进 停在 Hero Frame只有结尾需要出。五、时间线与 clip 契约一条 paused 时间线注册到 window.__timelines全合成恰好一条gsap.timeline({ paused: true })注册到window.__timelines[id]id 对应data-composition-id构建结束调用tl.seek(0)归零渲染关键运动永远不要tl.play()——引擎是 seek 驱动的play 会引入墙钟wall-clock不确定性。window.__timelines是 HyperFrames 运行时的既定全局契约见 packages/core/src/inline-scripts/runtimeContract.ts 中HYPERFRAME_RUNTIME_GLOBALS.timelines __timelines的定义CLI 文档 packages/cli/src/docs/gsap.md 给出了最小示例script srchttps://cdn.jsdelivr.net/npm/gsap3/dist/gsap.min.js/script script const tl gsap.timeline({ paused: true }); tl.to(#title, { opacity: 1, duration: 0.5 }, 0); window.__timelines window.__timelines || {}; window.__timelines[root] tl; /script时间线注册表同时被运行时读取用于推导合成时长——timeline.test.ts 验证了引擎可从__timelines注册的duration()取组合成/场景时长也可通过getChildren()内省 GSAP tween 的目标元素、起止时间来反推场景元素的时间范围。因此时间线的结构与注册名必须准确它不仅是动画数据也是运行时元数据的来源。定时元素classclip 时间属性 稳定 id需要按时间出现的元素必须带classclip带data-start/data-duration/data-track-index属性有一个稳定且唯一的id。各属性的语义见 packages/cli/src/docs/data-attributes.md属性含义data-start开始时间秒data-duration持续时长秒data-track-indexStudio 时间线轨道序号仅用于显示渲染不读取它也不控制绘制顺序绘制顺序用 CSSz-indexdata-composition-id组合包裹元素的唯一 ID必需data-width/data-height合成宽高像素在一个覆盖全时长的 clip 内部由时间线驱动的各个子元素不需要各自携带 timing 属性——clip 提供生命周期子元素的时间完全由 GSAP 时间线决定。六、确定性禁止时间与随机源契约规定合成代码只能确定性运行禁止Date.now()、Math.random()、网络请求数字滚动count-up必须 tween 一个代理对象proxy并通过onUpdate渲染绝不能用墙钟计数器。计数器的 seek 安全实现模式const proxy { value: 0 }; tl.to(proxy, { value: 100, duration: 2, ease: power2.out, onUpdate: () { el.textContent Math.round(proxy.value).toLocaleString(); }, });契约同时记录了一个重要的引擎行为Eval findingcount-up 只在宿主以事件启用events enabled的方式推进时间线时才渲染——即通过tl.time()或非 suppressed 的 seek。裸调用seek(t, true)会把计数冻结在 0因此 HyperFrames 的渲染宿主必须以事件开启方式 seek。这是合成作者需要知悉的运行时细节避免误判计数器坏了。七、正确性细则Seek-safe 的延迟元素揭示对于非 clip 元素、或 clip 内部的包装元素若要实现延迟到某时刻才显示使用已注册时间线中的一条fromTo()起点显式{ autoAlpha: 0 }终点{ autoAlpha: 1, ... }不要在页面加载时用gsap.set()去设置后续.clip永远不要直接操作.clip的可见性——clip 的生命周期由框架拥有。钳制 tween 边界把值钳制在 tween 边界内不要让 spring 之类的弹性补间越过停留值产生 overshoot——否则在 seek 到保持帧时画面会出现多余位移。允许的缓动ease白名单power1–power4、back、bounce、circ、elastic、expo、sine均可使用.in/.out/.inOut变体。白名单之外的自定义缓动不被契约保证。每场景一个视觉母题motif每个 scene 只做一个核心视觉母题避免视觉焦点竞争。完成后运行hyperframes check对于有意为之的溢出动画如元素出画用data-layout-allow-overflowtrue显式标记。该属性在布局审计实现中有明确处理packages/cli/src/commands/layout-audit.browser.js 通过element.closest([data-layout-allow-overflow])判断元素或其祖先是否声明了允许溢出命中则跳过对应的溢出告警文本溢出、子元素越界、偏移定位越界等场景的提示文案中均包含该属性。未标记的溢出会被check判定为缺陷。调色板纪律Palette discipline所有颜色集中在唯一的palette对象 / CSS 自定义属性中定义严禁在标记里散落 inline hex对于asset-fusion类别用 eyedropper 从素材asset中吸取调色板而不是凭空编色。这样既保证全片色调统一也让品牌色、素材色的后续替换只需改一处。八、验证闭环把契约落成可渲染结果Builder 完成自检后将合成交回编排器进入验证阶段skills/motion-graphics/SKILL.md Step 5(cd $PROJECT_DIR npx hyperframes lint .) (cd $PROJECT_DIR npx hyperframes check .) (cd $PROJECT_DIR npx hyperframes snapshot --at proof-times)proof 时刻要覆盖开场状态、标志性运动、最终保持帧三处检查 contact sheet / snapshot 后再继续若 lint / check / snapshot 失败交给 repair 子代理做一轮就地修复后重跑失败的 gate修复过程中绝不修改固定的data-duration来掩盖缺陷。九、速查清单主题规则根节点#stage需position: relative 显式width/height高未解析则 flex 子元素塌缩布局先静态搭 Hero Frame再写动画内容容器用 flex ≥80px paddingabsolute 只给装饰入场非 clip 且 t0 活跃的元素可用from()clip 内、子组合、延迟入场一律fromTo()退场仅最终场景做退场场景间转场即退场时间线唯一 paused timeline注册window.__timelines[id]tl.seek(0)禁止play()定时元素classclipdata-start/data-duration/data-track-index 稳定 idclip 内子元素免 timing 属性确定性禁Date.now()/Math.random()/网络count-up 用 proxy onUpdate揭示延迟元素用注册时间线fromTo({autoAlpha:0},{autoAlpha:1})不碰.clip可见性边界钳制在 tween 边界缓动限于power1–4/back/bounce/circ/elastic/expo/sine母题每场景一个有意溢出标记data-layout-allow-overflowtrue调色颜色集中在 palette 对象/CSS 变量asset-fusion从素材取色验证lint check proof snapshot修复不改固定data-duration本文规则同时是对 agents/builder.md 中非协商 HF 契约的落地展开。遵循这套契约写出的合成可被 HyperFrames 引擎确定性逐帧驱动最终通过npx hyperframes render输出 MP4透明叠加层则用--format webm或mov。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考