contribute-catalog

为 HyperFrames Registry 做出贡献

指导用户从构思到合并 PR，创建新的注册表区块或组件。

工作流

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

第 1 步：明确需求

询问他们正在构建什么。注册表包含两种条目类型：

• 区块（registry/blocks/，类型为 hyperframes:block）——具有固定尺寸和时长的完整独立合成。字幕样式、VFX 效果、标题卡、下三分之一字幕。
• 组件（registry/components/，类型为 hyperframes:component）——没有固定尺寸或时长的可复用片段。CSS 效果、文本样式、可适应任意合成尺寸的叠加层。

然后询问：

• 用一句话描述效果
• 视觉参考（URL、截图或描述）
• 谁会在什么情况下使用它？

第 2 步：搭建脚手架

创建注册表结构：

区块：

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：

{
  "$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（没有 dimensions 或 duration）：

{
  "$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"
    }
  ]
}

第 3 步：构建

根据类型应用正确的模板。请参阅 templates.md，获取可复制粘贴的起始模板。

字幕区块

字幕规则，不容妥协：

• 字体：比例字体至少 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.from(el, { opacity: 0 }) 和 tl.set(el, { opacity: 1 })——from 会覆盖 set。请改用 tl.to。

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

• 将每个字符包在带有 ID {prefix}-ch-{group}-{char} 的 <span> 中
• 根据单词时间戳计算时间间隔，并通过 tl.set 逐个错开
• 光标/装饰元素：使用 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 区块（Three.js）

• 从 CDN 使用 [email protected]（全局脚本）
• tl.eventCallback("onUpdate", renderScene); renderScene();——不要使用 requestAnimationFrame
• 状态代理模式：由 GSAP 为普通 JS 对象制作动画，渲染函数读取该对象
• 使用带种子的 PRNG（mulberry32）生成随机数

所有类型

• data-composition-id 必须与 window.__timelines["id"] 相符
• 所有元素 ID 都必须以区块缩写为前缀
• 始终使用 gsap.timeline({ paused: true })，保持暂停状态
• 不要使用 Math.random() 或 Date.now()

第 4 步：验证

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

第 5 步：预览

# Render preview video
hyperframes render -o preview.mp4

# Snapshot for visual QA
hyperframes snapshot --at "1.0,3.0,5.0,7.0"

# Publish to hyperframes.dev for review
npx hyperframes publish

目录预览图片——目录卡片使用位于 docs/images/catalog/{kind}/{name}.png 的 PNG 图片（其中 {kind} 为 blocks 或 components）。根据快照生成图片，然后：

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

步骤 6：发布

所有步骤都必须完成。缺少任何一步都会导致目录条目损坏。

{kind} 根据你在步骤 1 中构建的内容，取值为 blocks 或 components。

# 1. Create branch
git checkout -b feat/registry-{name}

# 2. Format HTML
npx oxfmt registry/{kind}/{name}/*.html

# 3. Update registry/registry.json — add entry to the "items" array:
#    { "name": "{name}", "type": "hyperframes:block" }  (or "hyperframes:component")

# 4. Generate catalog docs page
npx tsx scripts/generate-catalog-pages.ts

# 5. Publish to hyperframes.dev so reviewers can preview
npx hyperframes publish

# 6. Stage everything
git add registry/{kind}/{name}/ registry/registry.json docs/catalog/

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

# 8. Push and open PR with hyperframes.dev link
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。

质量检查

• 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 唯一且带有前缀