Back to Details

hyperframes-core

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HyperFrames Core

HyperFrames Core

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 — how to build one hyperframes project. The body below is the build guide; per-topic detail lives in 
references/
(index next), read on demand. Other concerns live in the sibling domain skills — 
hyperframes-animation
, 
hyperframes-creative
, 
hyperframes-media
, 
hyperframes-cli
, 
hyperframes-registry
. The capability map in 
/hyperframes
says what each one covers.
HyperFrames 从 HTML 渲染视频。Composition（合成）是一个 HTML 文件，其 DOM 通过 
data-*
属性声明时间信息，动画 runtime（运行时）支持 seek（定位），媒体播放由框架掌控。
本 Skill 是技术契约——说明如何构建一个 HyperFrames 项目。以下正文是构建指南；各主题的详细说明位于 
references/
（接下来是索引），可按需阅读。其他关注点由同级领域 Skill 负责——
hyperframes-animation
、
hyperframes-creative
、
hyperframes-media
、
hyperframes-cli
、
hyperframes-registry
。
/hyperframes
中的能力映射说明了每个 Skill 的覆盖范围。

References

参考资料（References）

FileRead it to…
references/minimal-composition.md
start from the smallest renderable composition skeleton
references/composition-patterns.md
choose monolithic vs modular; structure a modular 
index.html
; pick a sub-comp archetype
references/data-attributes.md
look up any 
data-*
(root / clip / sub-comp host / legacy aliases); use 
class="clip"
references/tracks-and-clips.md
pick 
data-track-index
, handle same-track overlap / z-index, time a clip relative to another
references/sub-compositions.md
wire a sub-composition (host attrs, 
<template>
, per-instance vars) and animate inside it
references/variables-and-media.md
declare variables; place 
<video>
/
<audio>
, set volume, trim
references/determinism-rules.md
build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit
references/full-screen-motion.md
author full-frame motion with shared backgrounds
references/storyboard-format.md
author a 
STORYBOARD.md
plan (+ the parsed manifest)
references/script-format.md
author the optional 
SCRIPT.md
locked narration
references/subagent-dispatch.md
map subagent dispatch verbs (parallel fan-out / background / wait) to your harness
references/tailwind.md
work in a Tailwind v4 project (
init --tailwind
; runtime contract differs from Studio's v3)
For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to 
hyperframes-animation
→ 
adapters/<runtime>.md
.
文件阅读它以…
references/minimal-composition.md
从最小可渲染 Composition 骨架开始
references/composition-patterns.md
在单体与模块化之间选择；搭建模块化 
index.html
的结构；选择 sub-composition 原型
references/data-attributes.md
查找任意 
data-*
（root / clip / sub-composition host / legacy aliases）的用法；使用 
class="clip"
references/tracks-and-clips.md
选择 
data-track-index
；处理同一 track 上的重叠 / z-index；相对于另一个 clip 设置时间
references/sub-compositions.md
连接 sub-composition（host 属性、
<template>
、每实例变量），并在其中制作动画
references/variables-and-media.md
声明变量；放置 
<video>
/
<audio>
，设置音量、裁剪
references/determinism-rules.md
构建可 seek 的时间轴；确定性禁用项；可动画属性允许列表；布局 / 文本适配
references/full-screen-motion.md
使用共享背景创作全屏运动
references/storyboard-format.md
编写 
STORYBOARD.md
规划（以及解析后的 manifest）
references/script-format.md
编写可选的 
SCRIPT.md
锁定旁白
references/subagent-dispatch.md
将 subagent 调度动词（并行 fan-out / background / wait）映射到你的 harness
references/tailwind.md
在 Tailwind v4 项目中工作（
init --tailwind
；runtime 契约不同于 Studio 的 v3）
有关动画 runtime 的具体内容（GSAP API、Lottie、Three.js 等），请转到 
hyperframes-animation
→ 
adapters/<runtime>.md
。

Building a composition

构建 Composition

Two root forms (not interchangeable)

两种根形式（不可互换）

  • Standalone (top-level 
    index.html
    ) — root 
    <div data-composition-id="…">
    sits directly in 
    <body>
    , no 
    <template>
    wrapper     (wrapping it hides all content and breaks rendering).
  • Sub-composition (loaded via 
    data-composition-src
    ) — root must be wrapped in 
    <template>
    .
⚠ Transport rule: the runtime only clones 
<template>
contents; everything outside (incl. 
<head>
styles/scripts) is discarded — put 
<style>
/
<script>
inside the template. ⚠ Host-id rule: the host slot's 
data-composition-id
must exactly equal the inner template's 
data-composition-id
and the 
window.__timelines["<id>"]
key — no 
-mount
/
-slot
/
-host
suffix.
File shape, host wiring, and the pre-render checklist → 
references/sub-compositions.md
.
  • Standalone（顶层 
    index.html
    ）——根 
    <div data-composition-id="…">
    直接位于 
    <body>
    中，不得使用 
    <template>
    包装    （包装后会隐藏所有内容并导致渲染失败）。
  • Sub-composition（通过 
    data-composition-src
    加载）——根元素必须用 
    <template>
    包装。
⚠ 传输规则：runtime 只克隆 
<template>
的内容；外部的所有内容（包括 
<head>
中的样式/脚本）都会被丢弃——请将 
<style>
/
<script>
放在 template 内部。 ⚠ Host-id 规则：host 插槽的 
data-composition-id
必须与 template 内部的 
data-composition-id
完全一致，并且必须与 
window.__timelines["<id>"]
的 key 完全一致——不能添加 
-mount
/
-slot
/
-host
后缀。
文件结构、host 连接方式和预渲染检查清单 → 
references/sub-compositions.md
。

Root must be sized (silent layout bug)

根元素必须有明确尺寸（静默布局错误）

The standalone root needs an explicit sized box (
width
/
height
in px), and every ancestor down to a 
height:100%
element must have a resolved height — otherwise a flex/
100%
child collapses to ~0 and content piles into the top-left corner. 
lint
/
validate
/
inspect
do not catch this. Skeleton → 
references/minimal-composition.md
.
Standalone 根元素需要一个明确设有尺寸的盒子（
width
/
height
使用 px），并且从根元素到 
height:100%
元素这一路径上的每个祖先元素都必须具有已解析的高度——否则 flex/
100%
子元素会塌缩到约 0，内容会堆叠在左上角。
lint
/
validate
/
inspect
无法检测到这个问题。骨架 → 
references/minimal-composition.md
。

One paused timeline

一个暂停的时间轴

Each composition registers exactly one 
gsap.timeline({ paused: true })
at 
window.__timelines["<id>"]
(key = root 
data-composition-id
), built synchronously at page load. Render duration = root 
data-duration
, not timeline length. Don't manually nest sub-timelines into the host. Full contract (incl. non-GSAP runtimes) → 
references/determinism-rules.md
+ 
hyperframes-animation/adapters/
.
每个 Composition 必须在 
window.__timelines["<id>"]
注册恰好一个 
gsap.timeline({ paused: true })
（key = 根元素的 
data-composition-id
），并在页面加载时同步创建。渲染时长 = 根元素的 
data-duration
，而不是时间轴长度。不要手动将子时间轴嵌套到 host 中。完整契约（包括非 GSAP runtime）→ 
references/determinism-rules.md
+ 
hyperframes-animation/adapters/
。

Non-negotiable rules (silent bugs 
lint
/
validate
/
inspect
won't catch)

不可协商的规则（
lint
/
validate
/
inspect
无法发现的静默错误）

Surfaced here; full rationale in the linked reference. Do not violate:
  • No render-time clocks / unseeded 
    Math.random
    / network / input-state; no 
    repeat: -1
    (use a finite count). → 
    determinism-rules.md
  • Animate only the visual-property allowlist; never 
    display
    /
    visibility
    ; no 
    gsap.set
    on later-scene clips. → 
    determinism-rules.md
  • No 
    <br>
    in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → 
    determinism-rules.md
  • <video>
    /
    <audio>
    must be a direct child of the host root (never inside a sub-comp 
    <template>
    /wrapper); the framework owns playback. → 
    variables-and-media.md
  • Every 
    id
    must be unique across the assembled page; inside a sub-comp, prefix ids with the composition id (
    #<id>-hero
    ). Duplicate 
    <video>
    /
    <img>
    ids render blank — the producer injects frames by 
    getElementById
    , and cross-file dupes slip past 
    lint
    . → 
    composition-patterns.md
  • A full-screen scene fill goes on a full-bleed child (
    position:absolute; inset:0
    ), never on the composition root itself — the producer's frame compositing can drop the root element's own 
    background
    (the frame renders black) even though preview/
    snapshot
    show it correctly. → 
    composition-patterns.md
这里列出这些规则；完整原因见链接的参考文档。不得违反：
  • 禁止使用渲染时时钟 / 未设定种子的 
    Math.random
    / 网络 / 输入状态；禁止 
    repeat: -1
    （请使用有限次数）。→ 
    determinism-rules.md
  • 只能动画化视觉属性允许列表中的属性；绝不能使用 
    display
    /
    visibility
    ；不得对较后场景的 clip 使用 
    gsap.set
    。→ 
    determinism-rules.md
  • 正文文本中不得使用 
    <br>
    ；带 transform 的元素必须是块级且具有尺寸；脉动的绝对定位装饰元素在峰值时必须留出足够空间。→ 
    determinism-rules.md
  • <video>
    /
    <audio>
    必须是 host 根元素的直接子元素（绝不能放在 sub-composition 的 
    <template>
    /包装元素内）；播放由框架掌控。→ 
    variables-and-media.md
  • 每个 
    id
    在组装后的页面中都必须唯一；在 sub-composition 内，使用 Composition id 作为 id 前缀（
    #<id>-hero
    ）。重复的 
    <video>
    /
    <img>
    id 会渲染为空白——producer 通过 
    getElementById
    注入帧，而跨文件重复 id 能绕过 
    lint
    。→ 
    composition-patterns.md
  • 全屏场景填充应放在铺满画面的子元素上（
    position:absolute; inset:0
    ），绝不能放在 Composition 根元素自身上——producer 的帧合成可能会丢弃根元素自身的 
    background
    （帧会渲染为黑色），即使 preview/
    snapshot
    显示正确。→ 
    composition-patterns.md

Editing existing compositions

编辑现有 Composition

  • Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.
  • Match existing composition IDs and timeline keys.
  • Adding a clip: pick a non-overlapping 
    data-track-index
    or adjust surrounding timing intentionally.
  • Adding a sub-composition: verify its internal 
    data-composition-id
    before wiring the host.
  • 先阅读相关文件。保留不相关的时序、轨道、ID、变量和媒体路径。
  • 匹配现有 Composition ID 和时间轴 key。
  • 添加 clip：选择不会重叠的 
    data-track-index
    ，或有意识地调整周边时序。
  • 添加 sub-composition：连接 host 前，先验证其内部 
    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 (0 errors)
  • Projects with sub-compositions: 
    npx hyperframes snapshot --at <midpoints>
    and eyeball each frame
  • npx hyperframes preview
    for review (the user can edit anything in Studio's timeline)
  • npx hyperframes render
    only after the user approves
有关命令详情，请使用 
hyperframes-cli
  • npx hyperframes lint
    通过（0 个错误）
  • npx hyperframes validate
    通过（0 个控制台错误）
  • npx hyperframes inspect
    通过（0 个错误）
  • 包含 sub-composition 的项目：运行 
    npx hyperframes snapshot --at <midpoints>
    ，并逐一检查每个帧
  • 使用 
    npx hyperframes preview
    审阅（用户可以在 Studio 的时间轴中编辑任何内容）
  • 仅在用户批准后运行 
    npx hyperframes render