hyperframes-core

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	选择整体式与模块式；构建模块化的 index.html；选择子合成原型
references/data-attributes.md	查找任何 data-*（根/剪辑/子合成宿主/遗留别名）；使用 class="clip"
references/tracks-and-clips.md	选择 data-track-index，处理同轨道重叠/z-index，将剪辑相对于另一个剪辑定时
references/creator-editing-recipes.md	复制真实的剪切/修剪/重排序/重定时/冻结/相机/遮罩/交叉淡入淡出/音频编辑配方及其限制
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 为单位），并且每个祖先直到 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 }) 在补间内部设置初始状态，而不是使用 CSS transform: translateX(-40px)。

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

在此列出；完整理由请参阅链接的参考文献。请勿违反：

• 无渲染时时钟/无种子化的 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 --background 用于评审（用户可以在 Studio 的时间线中编辑任何内容，并且服务器在调用命令后仍可运行）
• 仅在用户批准后使用 npx hyperframes render