贡献到 Catalog

你的 agent 已经知道如何构建视频组件。它编写 HTML，HyperFrames 渲染它。注册表是所有已构建内容的集合——目前有 52 个 block 且仍在增长。

本指南展示如何参与贡献。

为什么贡献？

注册表中的每个 block 都是因为有人需要它而构建的。当你添加一个 block，每个 HyperFrames 用户都可以通过一条命令获取它：

npx hyperframes add instagram-follow

注册表不断增长，HyperFrames 变得更有用，你的工作将交付给所有人。

两种途径

提供创意（无需写代码）

你在别人之前发现了视觉趋势。这是最有价值的贡献。

• 从 TikTok/YouTube 录屏一种尚未存在的字幕样式
• 在 Figma 中绘制带有字体、颜色和时序的下三分之一条
• 安装一个组件，预览它，反馈哪里感觉不对

在 GitHub 上提交 issue 并附上视觉参考。标记为 component-request。

自己构建

每个 block 就是一个 HTML 文件。无需构建步骤，无需框架。

如果你使用 Claude Code 配合 HyperFrames skills：

"我想贡献一个新的转场效果，看起来像 描述"

/contribute-catalog skill 会搭建结构、验证、渲染预览、发布到 hyperframes.dev，并准备 PR。

注册表包含什么

Blocks（registry/blocks/）—— 完整的独立 composition。固定尺寸，固定时长。字幕样式、VFX 特效、标题卡片、转场。

Components（registry/components/）—— 可复用的代码片段。无固定尺寸。CSS 效果、文字处理、适配任意 composition 的覆盖层。

目录结构

registry/blocks/my-block/
my-block.html           ← composition
registry-item.json      ← 元数据

registry-item.json

{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "my-block",
"type": "hyperframes:block",
"title": "My Block",
"description": "What this block does in one sentence",
"tags": ["category", "subcategory"],
"dimensions": { "width": 1920, "height": 1080 },
"duration": 5,
"files": [
{
"path": "my-block.html",
"target": "compositions/my-block.html",
"type": "hyperframes:composition"
}
]
}

规则

每个注册表项目必须满足以下五个条件：

确定性

不使用 Math.random()，不使用 Date.now()。仅使用带种子的伪随机数生成器。

暂停时间轴

gsap.timeline({ paused: true })。由播放器控制播放。

注册时间轴

window.__timelines["id"] 必须与 data-composition-id 匹配。

不使用 requestAnimationFrame

对于 Three.js/WebGL 场景使用 tl.eventCallback("onUpdate", render)。

字幕必须硬结束

tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) —— 不允许残留文字。

⚠️ Warning

违反任何一条都将导致渲染不可复现。渲染器通过 seek 时间轴来捕获每一帧——如果你的动画依赖于真实时间或随机状态，它就会出问题。

质量标准

不是所有内容都适合进入注册表。标准是生产质量。

常见拒绝原因

1. "看起来像个 demo" —— 旋转的立方体不算组件
2. "文字不可读" —— 字体太小，没有对比度处理
3. "非确定性" —— 使用了 Math.random() 或 Date.now()
4. "时间轴未找到" —— HTML 和 JS 之间的 ID 不匹配
5. "作为子 composition 时出错" —— 元素 ID 冲突（所有内容都要加前缀）

工作流程

Fork 并创建

Fork heygen-com/hyperframes 并创建你的 block 目录：

mkdir -p registry/blocks/your-block

编写你的 block

创建 HTML composition 和 registry-item.json。使用上面的模板。

验证

hyperframes lint
hyperframes validate
npx oxfmt your-block.html

更新注册表

# 添加到注册表索引
# 更新 registry/registry.json
npx tsx scripts/generate-catalog-pages.ts

渲染预览

hyperframes render -o preview.mp4

发布并提交 PR

npx hyperframes publish

提交 PR 并附上你的 hyperframes.dev 预览链接。

外部贡献者： 将预览 MP4 附加到你的 PR。维护者会处理 catalog 图片。

HeyGen 内部： 运行 scripts/upload-docs-images.sh 上传 catalog PNG。

当前需要的内容

以下是注册表中的空白。如果你在寻找要构建的东西，从这里开始。