contribute-catalog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contribute to HyperFrames Registry

为HyperFrames注册表做贡献

Guide the user from idea to merged PR for a new registry block or component.

引导用户从创意构思到提交合并PR，完成新注册表区块或组件的开发。

Workflow

工作流程

1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship

1. 明确需求 → 2. 搭建结构 → 3. 开发实现 → 4. 验证检查 → 5. 预览测试 → 6. 提交上线

Step 1: Clarify

步骤1：明确需求

Ask what they're building. The registry has two item types:

Block (
```
registry/blocks/
```
, type
```
hyperframes:block
```
) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
Component (
```
registry/components/
```
, type
```
hyperframes:component
```
) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.

Then ask:

One-sentence description of the effect
Visual reference (URL, screenshot, or description)
Who uses this and when?

询问用户要开发的内容。注册表包含两种类型的项目：

区块（
```
registry/blocks/
```
，类型
```
hyperframes:block
```
）—— 完整的独立合成内容，具有固定尺寸和时长。例如字幕样式、VFX特效、标题卡片、下三分之一栏。
组件（
```
registry/components/
```
，类型
```
hyperframes:component
```
）—— 可复用的代码片段，无固定尺寸或时长。例如CSS特效、文字样式、适配任意合成尺寸的覆盖层。

接着询问：

特效的一句话描述
视觉参考（URL、截图或文字描述）
使用人群及使用场景

Step 2: Scaffold

步骤2：搭建结构

Create the registry structure:

For blocks:

registry/blocks/{block-name}/
  {block-name}.html
  registry-item.json

For components:

registry/components/{component-name}/
  {component-name}.html
  registry-item.json

Naming convention:

Item name	ID prefix	Example IDs
`cap-hormozi`	`hz`	`hz-cg-0` , `hz-cw-3`
`cap-typewriter`	`tw`	`tw-cg-0` , `tw-ch-0-5`
`vfx-chrome`	`vc`	`vc-canvas`

Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.

registry-item.json for blocks:

json

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{block-name}",
  "type": "hyperframes:block",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "dimensions": { "width": 1920, "height": 1080 }, // adjust: 1080x1920 for portrait/social
  "duration": 10, // adjust for your composition
  "tags": ["{category}", "{subcategory}"],
  "files": [
    {
      "path": "{block-name}.html",
      "target": "compositions/{block-name}.html",
      "type": "hyperframes:composition"
    }
  ]
}

registry-item.json for components (no

dimensions

duration

json

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{component-name}",
  "type": "hyperframes:component",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "tags": ["{category}"],
  "files": [
    {
      "path": "{component-name}.html",
      "target": "compositions/components/{component-name}.html",
      "type": "hyperframes:snippet"
    }
  ]
}

创建注册表结构：

区块结构：

registry/blocks/{block-name}/
  {block-name}.html
  registry-item.json

组件结构：

registry/components/{component-name}/
  {component-name}.html
  registry-item.json

命名规范：

项目名称	ID前缀	示例ID
`cap-hormozi`	`hz`	`hz-cg-0` , `hz-cw-3`
`cap-typewriter`	`tw`	`tw-cg-0` , `tw-ch-0-5`
`vfx-chrome`	`vc`	`vc-canvas`

使用2-3个字母的前缀。所有元素ID必须使用该前缀，以避免子合成中的冲突。

区块的registry-item.json：

json

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{block-name}",
  "type": "hyperframes:block",
  "title": "{人性化标题}",
  "description": "{一句话描述}",
  "dimensions": { "width": 1920, "height": 1080 }, // 可调整：竖版/社交平台使用1080x1920
  "duration": 10, // 根据你的合成内容调整
  "tags": ["{分类}", "{子分类}"],
  "files": [
    {
      "path": "{block-name}.html",
      "target": "compositions/{block-name}.html",
      "type": "hyperframes:composition"
    }
  ]
}

组件的registry-item.json（无

dimensions

或

duration

字段）：

json

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{component-name}",
  "type": "hyperframes:component",
  "title": "{人性化标题}",
  "description": "{一句话描述}",
  "tags": ["{分类}"],
  "files": [
    {
      "path": "{component-name}.html",
      "target": "compositions/components/{component-name}.html",
      "type": "hyperframes:snippet"
    }
  ]
}

Step 3: Build

步骤3：开发实现

Apply the correct template based on type. See templates.md for copy-paste starters.

根据类型选择正确的模板。可参考templates.md中的可复制模板。

Caption blocks

字幕区块

Non-negotiable caption rules:

Font: 96px minimum for proportional fonts. 64-72px acceptable for monospace (wider characters need less size).
Readability:
```
-webkit-text-stroke: 2-3px
```
OR multi-layer
```
text-shadow
```
Overflow: call
```
window.__hyperframes.fitTextFontSize()
```
on every group

Karaoke: highlight active word via

tl.to(wordEl, { color/scale }, WORDS[wi].start)

Hard kill:

tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)

on EVERY group

Never use
tl.from(el, { opacity: 0 })
at the same position as
tl.set(el, { opacity: 1 })
— the from clobbers the set. Use
```
tl.to
```
instead.

Per-character animation (typewriter, scramble):

Wrap each character in
```
<span>
```
with ID
```
{prefix}-ch-{group}-{char}
```
Stagger via
```
tl.set
```
at computed intervals from word timestamps
Cursors/decorative elements: use
```
tl.set
```
at intervals — NOT CSS animation (not seekable)

Positioning variants:

Centered:

display: flex; align-items: center; justify-content: center;

Lower-third:

position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;

Left-aligned:

position: absolute; bottom: 100px; left: 120px; text-align: left;

不可妥协的字幕规则：

字体：比例字体最小96px。等宽字体可接受64-72px（字符较宽，无需过大尺寸）。
可读性：使用
```
-webkit-text-stroke: 2-3px
```
或多层
```
text-shadow
```
溢出处理：对每个组调用
```
window.__hyperframes.fitTextFontSize()
```

卡拉OK效果：通过

tl.to(wordEl, { color/scale }, WORDS[wi].start)

高亮当前单词

强制隐藏：对每个组执行

tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)

绝对不要在
tl.set(el, { opacity: 1 })
的同一位置使用
tl.from(el, { opacity: 0 })
——前者会被后者覆盖。请使用
```
tl.to
```
替代。

逐字符动画（打字机、打乱效果）：

将每个字符包裹在ID为
```
{prefix}-ch-{group}-{char}
```
的
```
<span>
```
中
根据单词时间戳计算间隔，通过
```
tl.set
```
实现 stagger 动画
光标/装饰元素：使用
```
tl.set
```
按间隔控制——不要使用CSS动画（无法定位到特定帧）

定位变体：

居中：

display: flex; align-items: center; justify-content: center;

下三分之一栏：

position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;

左对齐：

position: absolute; bottom: 100px; left: 120px; text-align: left;

VFX blocks (Three.js)

VFX区块（Three.js）

Use
```
three@0.147.0
```
from CDN (global script)

tl.eventCallback("onUpdate", renderScene); renderScene();

— NO requestAnimationFrame

State proxy pattern: GSAP animates plain JS object, render function reads it
Seeded PRNG (
```
mulberry32
```
) for randomness

使用CDN引入的
```
three@0.147.0
```
（全局脚本）

使用

tl.eventCallback("onUpdate", renderScene); renderScene();

——不要使用requestAnimationFrame

状态代理模式：GSAP动画普通JS对象，渲染函数读取该对象状态
使用种子PRNG（
```
mulberry32
```
）实现随机效果

All types

所有类型通用规则

data-composition-id

MUST match

window.__timelines["id"]

All element IDs prefixed with block abbreviation
```
gsap.timeline({ paused: true })
```
— always paused
No
```
Math.random()
```
, no
```
Date.now()
```

data-composition-id

必须与

window.__timelines["id"]

匹配

所有元素ID都要添加区块缩写前缀
使用
```
gsap.timeline({ paused: true })
```
——始终保持暂停状态
禁止使用
```
Math.random()
```
和
```
Date.now()
```

Step 4: Validate

步骤4：验证检查

bash

hyperframes lint                    # 0 errors required
hyperframes validate --no-contrast  # 0 console errors required

bash

hyperframes lint                    # 需要0错误
hyperframes validate --no-contrast  # 需要0控制台错误

Step 5: Preview

步骤5：预览测试

bash

undefined

bash

undefined

Render preview video

渲染预览视频

hyperframes render -o preview.mp4

Snapshot for visual QA

生成快照用于视觉QA

hyperframes snapshot --at "1.0,3.0,5.0,7.0"

Publish to hyperframes.dev for review

发布到hyperframes.dev供评审

npx hyperframes publish


**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:

- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.

npx hyperframes publish


**目录预览图片**——目录卡片使用位于`docs/images/catalog/{kind}/{name}.png`的PNG图片（`{kind}`为`blocks`或`components`）。从快照生成该图片后：

- **HeyGen内部贡献者：** 运行`scripts/upload-docs-images.sh`（需要AWS配置文件`engineering-767398024897`）
- **外部贡献者：** 将预览MP4附加到PR描述中。维护者会在合并前生成并上传目录图片。

Step 6: Ship

步骤6：提交上线

All steps are required. Missing any one produces a broken catalog entry.

{kind}

blocks

components

depending on what you built in Step 1.

bash

undefined

所有步骤均为必填项。缺少任何一步都会导致目录条目损坏。

{kind}

根据步骤1中开发的内容，取值为

blocks

或

components

。

bash

undefined

1. Create branch

1. 创建分支

git checkout -b feat/registry-{name}

2. Format HTML

2. 格式化HTML

npx oxfmt registry/{kind}/{name}/*.html

3. Update registry/registry.json — add entry to the "items" array:

3. 更新registry/registry.json —— 在"items"数组中添加条目：

{ "name": "{name}", "type": "hyperframes:block" } (or "hyperframes:component")

{ "name": "{name}", "type": "hyperframes:block" } （或"hyperframes:component"）

4. Generate catalog docs page

4. 生成目录文档页面

npx tsx scripts/generate-catalog-pages.ts

5. Publish to hyperframes.dev so reviewers can preview

5. 发布到hyperframes.dev以便评审人员预览

npx hyperframes publish

6. Stage everything

6. 暂存所有更改

git add registry/{kind}/{name}/ registry/registry.json docs/catalog/

7. Commit

7. 提交更改

git commit -m "feat(registry): add {name} — {one sentence}"

8. Push and open PR with hyperframes.dev link

8. 推送分支并打开包含hyperframes.dev链接的PR

git push origin feat/registry-{name} gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"


**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.

git push origin feat/registry-{name} gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"


**如果没有GitHub账户：** 需要注册一个账户才能提交PR。请访问https://github.com/signup注册，然后运行`gh auth login`。

Quality Gate

质量检查清单

```
hyperframes lint
```
→ 0 errors
```
hyperframes validate
```
→ 0 console errors
```
npx oxfmt --check
```
passes
```
registry/registry.json
```
updated with new entry
```
scripts/generate-catalog-pages.ts
```
run (docs page generated)
```
npx hyperframes publish
```
run (claim your project URL)
Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
All IDs unique and prefixed

```
hyperframes lint
```
→ 0错误
```
hyperframes validate
```
→ 0控制台错误
```
npx oxfmt --check
```
检查通过
```
registry/registry.json
```
已添加新条目
已运行
```
scripts/generate-catalog-pages.ts
```
（已生成文档页面）
已运行
```
npx hyperframes publish
```
（已获取项目URL）
PR中已附加预览MP4（外部贡献者）或已上传目录PNG（内部贡献者）
所有ID唯一且带有前缀