hyperframes-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HyperFrames Core

HyperFrames 核心

HyperFrames renders video from HTML. A composition is an HTML file whose DOM declares timing with

data-*

attributes, whose animation runtime is seekable, and whose media playback is owned by the framework.

This skill is the technical contract. Other concerns live in sibling skills:

```
hyperframes-animation
```
— atomic motion rules + scene blueprints + per-runtime adapters (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)
```
hyperframes-creative
```
— palettes, typography, narration, beat planning, audio-reactive
```
hyperframes-media
```
— TTS, Whisper transcribe, background removal, captions
```
hyperframes-registry
```
— install blocks and components (
```
hyperframes add
```
)
```
hyperframes-cli
```
— dev loop commands (lint / validate / preview / render)

For Tailwind v4 projects (

hyperframes init --tailwind

), see

references/tailwind.md

— the browser-runtime contract is distinct from Studio's Tailwind v3 setup.

HyperFrames 基于 HTML 渲染视频。合成文件是一个 HTML 文件，其 DOM 通过

data-*

属性声明时序，动画运行时支持跳转，媒体播放由框架托管。

本技能是技术契约。其他相关内容在同级技能中：

```
hyperframes-animation
```
— 原子运动规则 + 场景蓝图 + 各运行时适配器（GSAP、Lottie、Three、Anime.js、CSS、WAAPI、TypeGPU）
```
hyperframes-creative
```
— 调色板、排版、旁白、节拍规划、音频响应
```
hyperframes-media
```
— TTS、Whisper 转写、背景移除、字幕
```
hyperframes-registry
```
— 安装块与组件（
```
hyperframes add
```
）
```
hyperframes-cli
```
— 开发循环命令（lint / 验证 / 预览 / 渲染）

针对Tailwind v4 项目（

hyperframes init --tailwind

），请查看

references/tailwind.md

—— 浏览器运行时契约与 Studio 的 Tailwind v3 配置不同。

Routing

Want to…	Read
See a minimal renderable composition	`references/minimal-composition.md`
Decide between monolithic single-file and modular sub-comp architecture	`references/composition-patterns.md`
Structure a modular `index.html` (orchestrator + slots + root audio)	`references/composition-patterns.md`
Pick a sub-comp archetype (content / driver-only / multi-scene merge / audio-reactive)	`references/composition-patterns.md`
Look up a `data-*` attribute (root, clip, sub-comp host, legacy aliases)	`references/data-attributes.md`
Use `class="clip"` correctly	`references/data-attributes.md`
Pick a `data-track-index` ; same-track overlap; track-index vs CSS `z-index`	`references/tracks-and-clips.md`
Time a clip relative to another ( `data-start="intro + 2"` , crossfade overlap, chains)	`references/tracks-and-clips.md`
Wire a sub-composition (host attributes, `<template>` wrapper, per-instance variables)	`references/sub-compositions.md`
Animate inside a sub-composition ( `gsap.fromTo` over `gsap.from` , seek-back behavior)	`references/sub-compositions.md`
Declare variables (types, extra options, defaults, `--strict-variables` in CI)	`references/variables-and-media.md`
Place `<video>` / `<audio>` , set volume, trim with `data-media-start`	`references/variables-and-media.md`
Build a seekable timeline (paused, sync construction, `gsap.set` later-scene trap)	`references/determinism-rules.md`
Avoid non-deterministic state (clocks, `Math.random` , `repeat: -1` , finite repeat formula)	`references/determinism-rules.md`
Know what can / cannot be animated (visual-property allowlist; not `display` / `visibility` )	`references/determinism-rules.md`
Fit text and prevent overflow ( `fitTextFontSize` signature, `<br>` rule, layout contract)	`references/determinism-rules.md`
Author full-frame motion with shared backgrounds	`references/full-screen-motion.md`
Work in a Tailwind v4 project ( `init --tailwind` )	`references/tailwind.md`

For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to

hyperframes-animation

→

adapters/<runtime>.md

想要…	阅读文档
查看最小可渲染合成示例	`references/minimal-composition.md`
在单体单文件和模块化子合成架构间做选择	`references/composition-patterns.md`
构建模块化 `index.html` （编排器 + 插槽 + 根音频）	`references/composition-patterns.md`
选择子合成原型（内容型 / 仅驱动型 / 多场景合并 / 音频响应型）	`references/composition-patterns.md`
查询 `data-*` 属性（根、片段、子合成宿主、旧版别名）	`references/data-attributes.md`
正确使用 `class="clip"`	`references/data-attributes.md`
选择 `data-track-index` ；同轨道重叠；track-index 与 CSS `z-index` 的对比	`references/tracks-and-clips.md`
相对于其他片段设置时序（ `data-start="intro + 2"` 、交叉淡入重叠、链式时序）	`references/tracks-and-clips.md`
连接子合成（宿主属性、 `<template>` 包装器、实例变量）	`references/sub-compositions.md`
在子合成内制作动画（优先 `gsap.fromTo` 而非 `gsap.from` 、回退跳转行为）	`references/sub-compositions.md`
声明变量（类型、额外选项、默认值、CI 中的 `--strict-variables` ）	`references/variables-and-media.md`
放置 `<video>` / `<audio>` 、设置音量、用 `data-media-start` 裁剪媒体	`references/variables-and-media.md`
构建可跳转的时间轴（暂停、同步构建、 `gsap.set` 后期场景陷阱）	`references/determinism-rules.md`
避免非确定性状态（时钟、 `Math.random` 、 `repeat: -1` 、有限重复公式）	`references/determinism-rules.md`
了解可/不可动画的属性（视觉属性白名单；不可动画 `display` / `visibility` ）	`references/determinism-rules.md`
适配文本并防止溢出（ `fitTextFontSize` 签名、 `<br>` 规则、布局契约）	`references/determinism-rules.md`
制作带共享背景的全屏动画	`references/full-screen-motion.md`
在 Tailwind v4 项目中开发（ `init --tailwind` ）	`references/tailwind.md`

如需了解动画运行时细节（GSAP API、Lottie、Three.js 等），请前往

hyperframes-animation

→

adapters/<runtime>.md

。

Composition Structure

合成结构

Two root forms; they are not interchangeable.

Standalone (the top-level
```
index.html
```
) — root
```
<div data-composition-id="…">
```
sits directly in
```
<body>
```
. No
<template>
wrapper. Wrapping a standalone root in
```
<template>
```
hides all content from the browser and breaks rendering.
Sub-composition (a file loaded via
```
data-composition-src
```
) — root
```
<div data-composition-id="…">
```
must be wrapped in
```
<template>
```
. Without the wrapper the runtime cannot extract and mount it.

⚠ Sub-composition transport rule: the runtime only clones
<template>
contents into the live DOM. Everything outside the template — including
<head>
and any
<style>
/
<script>
/
<link>
that lives in
<head>
— is discarded. Put
<style>
and
<script>
blocks inside
<template>
, not in
<head>
.
⚠ Host-id rule: in the host file,
data-composition-id
on the slot must exactly equal the inner template's
data-composition-id
and the
window.__timelines["<id>"]
key. Do not add
-mount
/
-slot
/
-host
suffixes.

See

references/sub-compositions.md

for the file shape, host wiring, pitfall examples, and the pre-render verification checklist.

两种根形式，不可互换。

独立合成（顶级
```
index.html
```
）—— 根元素
```
<div data-composition-id="…">
```
直接位于
```
<body>
```
中。不能用
<template>
包装。如果用
```
<template>
```
包装独立根元素，会将所有内容隐藏在浏览器外，导致渲染失败。
子合成（通过
```
data-composition-src
```
加载的文件）—— 根元素
```
<div data-composition-id="…">
```
必须用
```
<template>
```
包装。没有包装的话，运行时无法提取并挂载它。

⚠ 子合成传输规则：运行时仅克隆
<template>
内容到活动 DOM 中。模板外的所有内容 —— 包括
<head>
以及
<head>
中的任何
<style>
/
<script>
/
<link>
—— 都会被丢弃。请将
<style>
和
<script>
块放在模板内部，而非
<head>
中。
⚠ 宿主ID规则：在宿主文件中，插槽上的
data-composition-id
必须完全匹配内部模板的
data-composition-id
以及
window.__timelines["<id>"]
的键。不要添加
-mount
/
-slot
/
-host
后缀。

有关文件结构、宿主连接、陷阱示例以及预渲染验证清单，请查看

references/sub-compositions.md

。

Root must be sized (silent layout bug)

根元素必须设置尺寸（静默布局 bug）

The standalone root must establish an explicitly sized box, and every ancestor between it and a

height: 100%

element must have a resolved height. If the root or an intermediate wrapper has no height, a flex/

height:100%

content container collapses to ~0 and content piles into the top-left corner (often clipping the first glyph at x=0).

lint

validate

, and

inspect

do not catch this —

inspect

substitutes the authored

data-width

data-height

for a collapsed root and reports "0 layout issues."

html

<body style="margin: 0">
  <div
    id="root"
    data-composition-id="main"
    data-width="1920"
    data-height="1080"
    data-duration="5"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
  >
    <!-- Center robustly: position:absolute + inset:0 fills the sized root regardless of
         intermediate wrappers; or use a flex container ONLY if its parent chain is sized. -->
    <section
      class="clip"
      data-start="0"
      data-duration="5"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
    >
      <h1>Title</h1>
    </section>
  </div>
</body>

Keep the

padding

(≥80px) on the centering container — it is the title-safe margin that stops large type touching the frame edge. See

references/minimal-composition.md

独立根元素必须建立一个明确设置尺寸的容器，且它与任何

height: 100%

元素之间的所有祖先元素都必须有已解析的高度。如果根元素或中间包装器没有设置高度，flex/

height:100%

的内容容器会折叠到约0高度，内容会堆积在左上角（通常会裁剪x=0处的第一个字符）。

lint

、

validate

和

inspect

无法检测到这个问题 ——

inspect

会用已设置的

data-width

data-height

替代折叠的根元素，并显示“0个布局问题”。

html

<body style="margin: 0">
  <div
    id="root"
    data-composition-id="main"
    data-width="1920"
    data-height="1080"
    data-duration="5"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
  >
    <!-- 稳健居中：position:absolute + inset:0 会填充已设置尺寸的根元素，不受中间包装器影响；或者仅在父链已设置尺寸时使用flex容器。 -->
    <section
      class="clip"
      data-start="0"
      data-duration="5"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
    >
      <h1>Title</h1>
    </section>
  </div>
</body>

请在居中容器上保留

padding

（≥80px）—— 这是标题安全边距，可防止大字号文本触碰帧边缘。详情请查看

references/minimal-composition.md

。

Timeline Contract (GSAP default)

时间轴契约（默认 GSAP）

Every composition registers exactly one GSAP timeline.

Create with
```
gsap.timeline({ paused: true })
```
— the player owns playback.
Register at
```
window.__timelines["<composition-id>"]
```
; the key must exactly match the root's
```
data-composition-id
```
. Dot syntax (
```
window.__timelines.<id> = tl
```
) is equivalent when the id is a valid identifier; use brackets if the id contains
```
-
```
.
Build the timeline synchronously during page load — not inside
```
async
```
,
```
setTimeout
```
,
```
Promise
```
, or event handlers. The renderer samples after page load completes; any deferred timeline construction misses the sample.
Render duration comes from
```
data-duration
```
on the root, not from GSAP timeline length. Do not pad the timeline with empty tweens to set duration.
For sub-compositions, do not manually nest sub-timelines into the host (
```
master.add(sub)
```
); the framework drives them independently.

For non-GSAP runtimes (Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU), the equivalent contract lives in

hyperframes-animation/adapters/<runtime>.md

. See

references/determinism-rules.md

for the cross-runtime Animation Runtime Contract.

每个合成仅注册一个 GSAP 时间轴。

使用
```
gsap.timeline({ paused: true })
```
创建 —— 播放器托管播放。
在
```
window.__timelines["<composition-id>"]
```
处注册；键必须完全匹配根元素的
```
data-composition-id
```
。当ID是有效标识符时，点语法（
```
window.__timelines.<id> = tl
```
）等效；如果ID包含
```
-
```
，请使用方括号语法。
在页面加载期间同步构建时间轴 —— 不要在
```
async
```
、
```
setTimeout
```
、
```
Promise
```
或事件处理程序中构建。渲染器会在页面加载完成后采样；任何延迟的时间轴构建都会错过采样。
渲染时长来自根元素的
```
data-duration
```
，而非 GSAP 时间轴长度。不要用空补间填充时间轴来设置时长。
对于子合成，不要手动将子时间轴嵌套到宿主时间轴中（
```
master.add(sub)
```
）；框架会独立驱动它们。

对于非 GSAP 运行时（Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU），对应的契约位于

hyperframes-animation/adapters/<runtime>.md

。跨运行时的动画运行时契约请查看

references/determinism-rules.md

。

Non-Negotiable Rules

不可协商规则

These break the renderer — or produce silent visual bugs that
lint
/
validate
/
inspect
do NOT catch (rules 3, 7-8). (Synchronous timeline construction is covered above in Timeline Contract.)

No
```
Math.random()
```
/
```
Date.now()
```
/
```
performance.now()
```
driving visuals — use a seeded PRNG.

repeat: -1

. Use

repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)

— floor
, not
ceil
(

ceil

overshoots

data-duration

and trips the

gsap_repeat_ceil_overshoot

lint;

max(0, …)

avoids a negative repeat = infinite).

```
<video>
```
/
```
<audio>
```
must be a direct child of the host root (
```
index.html
```
) — never inside a sub-comp
```
<template>
```
, never inside a wrapper
```
<div>
```
; otherwise it is never decoded and renders blank/black (silent). The framework owns playback: no
```
video.play()
```
/
```
audio.play()
```
/
```
currentTime = …
```
. A sub-comp cannot drive host elements (selector or
```
querySelector
```
), so animate host media from the main timeline at global time. See
```
references/variables-and-media.md
```
.
No
```
gsap.set()
```
on clip elements from later scenes (they are not in the DOM yet). Use
```
tl.set(selector, vars, time)
```
at or after the clip's
```
data-start
```
.
No animating
```
display
```
/
```
visibility
```
. Animate
```
opacity
```
/ transforms; the clip lifecycle handles show/hide.
No
```
<br>
```
in body text. Let text wrap via
```
max-width
```
.
Transformed elements must be block-level + sized.
```
transform
```
/
```
scaleX
```
/
```
scaleY
```
is a no-op on an inline
<span>
, and scaling an auto-width (0px) element shows nothing → invisible bars/fills. Give them
```
display: block
```
/
```
inline-block
```
/flex-item and a real
```
width
```
/
```
height
```
(e.g.
```
width: 100%
```
inside a sized parent).
Absolutely-positioned decoratives (badges, pills, tags) that pulse or overshoot (
```
yoyo
```
scale,
```
back.out
```
) need clearance at their peak size and must not straddle an
```
overflow: hidden
```
edge — else they overlap a neighbor or get clipped. Position for the largest frame, not the resting one.

违反这些规则会导致渲染失败 —— 或产生**

lint

validate

inspect

无法检测到的静默视觉 bug**（规则3、7-8）。（同步时间轴构建已在时间轴契约中说明。）

不得使用
```
Math.random()
```
/
```
Date.now()
```
/
```
performance.now()
```
驱动视觉效果 —— 使用种子式伪随机数生成器（PRNG）。

不得使用

repeat: -1

。请使用

repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)

—— 必须用
floor
，不能用
ceil
（

ceil

会超出

data-duration

，触发

gsap_repeat_ceil_overshoot

检查错误；

max(0, …)

可避免负数重复导致无限循环）。

```
<video>
```
/
```
<audio>
```
必须是宿主根元素（
index.html
）的直接子元素 —— 绝不能放在子合成的
```
<template>
```
内，也不能放在包装器
```
<div>
```
内；否则媒体永远不会解码，渲染为空白/黑屏（静默错误）。框架托管播放：禁止调用
```
video.play()
```
/
```
audio.play()
```
/
```
currentTime = …
```
。子合成无法驱动宿主元素（通过选择器或
```
querySelector
```
），因此请在主时间轴上按全局时间为宿主媒体制作动画。详情请查看
```
references/variables-and-media.md
```
。
不得从后期场景对片段元素调用
```
gsap.set()
```
（这些元素尚未在 DOM 中）。请在片段的
```
data-start
```
时间点或之后使用
```
tl.set(selector, vars, time)
```
。
不得为
```
display
```
/
```
visibility
```
设置动画。请为
```
opacity
```
/ 变换设置动画；片段生命周期会处理显示/隐藏。
正文文本中不得使用
```
<br>
```
。请通过
```
max-width
```
让文本自动换行。
应用变换的元素必须是块级元素且已设置尺寸。
```
transform
```
/
```
scaleX
```
/
```
scaleY
```
对内联
```
<span>
```
无效，缩放自动宽度（0px）的元素会显示为空 → 不可见的条块/填充。请为它们设置
```
display: block
```
/
```
inline-block
```
/flex-item 并指定实际的
```
width
```
/
```
height
```
（例如，在已设置尺寸的父元素内使用
```
width: 100%
```
）。
绝对定位的装饰元素（徽章、胶囊、标签）如果有脉动或超出边界的动画（
```
yoyo
```
缩放、
```
back.out
```
），需要在最大尺寸时留有空间，且不得跨在
```
overflow: hidden
```
的边缘 —— 否则会与相邻元素重叠或被裁剪。请按最大帧尺寸定位，而非初始状态尺寸。

Editing Existing Compositions

编辑现有合成

Read the actual files before editing.
Preserve unrelated timing, tracks, IDs, variables, and media paths.
Match existing composition IDs and timeline registry keys.
When adding a clip, choose a non-overlapping
```
data-track-index
```
or intentionally adjust surrounding timing.
When adding a sub-composition, verify its internal
```
data-composition-id
```
before wiring the host.

编辑前先阅读实际文件。
保留无关的时序、轨道、ID、变量和媒体路径。
匹配现有的合成ID和时间轴注册键。
添加片段时，选择不重叠的
```
data-track-index
```
或有意调整周围的时序。
添加子合成时，在连接宿主前验证其内部的
```
data-composition-id
```
。

Validation

验证

Use

hyperframes-cli

for command details.

```
npx hyperframes lint
```
passes (0 errors)
```
npx hyperframes validate
```
passes (0 console errors)
```
npx hyperframes inspect
```
passes, or overflow is intentionally marked
Projects with sub-compositions:
```
npx hyperframes snapshot --at <midpoints>
```
and eyeball each frame

使用

hyperframes-cli

获取命令详情。

```
npx hyperframes lint
```
检查通过（0错误）
```
npx hyperframes validate
```
检查通过（0控制台错误）
```
npx hyperframes inspect
```
检查通过，或溢出已被标记为有意设置
包含子合成的项目：执行
```
npx hyperframes snapshot --at <midpoints>
```
并逐一检查每个帧