contribute-catalog

为 FrameVideo Registry 做贡献

适用场景

在以下情况使用此技能：

• 为公开目录做贡献 — 用户想向上游 FrameVideo Registry 添加区块／组件
• 提交 PR — 用户制作了可复用效果，并想分享它
• 为目录打包 — 用户需要帮助整理 registry-item.json 和文件

不适用场景

以下情况请勿使用此技能：

• 项目内效果 — 使用 framevideo 技能制作项目专属字幕／转场
• 安装现有条目 — 使用 framevideo-registry 技能
• 学习 FrameVideo — 使用 framevideo 技能编写合成内容

---

快速开始

完整的贡献工作流：

# 1. Clarify what to build
User: "I want to contribute a Hormozi-style caption block"
→ Ask: description, visual reference, use case

# 2. Scaffold registry structure
registry/blocks/cap-hormozi/
  cap-hormozi.html
  registry-item.json

# 3. Build the block
→ Use `framevideo` skill for HTML authoring
→ Use 2-3 letter prefix for all element IDs (e.g., "hz-")

# 4. Validate
npx framevideo lint registry/blocks/cap-hormozi/cap-hormozi.html
npx framevideo add cap-hormozi --dir ./test-project

# 5. Preview
npx framevideo preview ./test-project

# 6. Ship
git checkout -b contrib/cap-hormozi
git add registry/blocks/cap-hormozi/
git commit -m "Add Hormozi-style caption block"
# Create PR to framevideo repo

要点：

• 所有元素 ID 必须使用统一前缀，以避免冲突
• 区块具有固定尺寸／时长，组件则没有
• 提交 PR 前，使用 framevideo add 进行测试

---

工作流

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

第 1 步：明确需求

询问用户正在制作什么。目录有两种条目类型：

• 区块（registry/blocks/，类型为 framevideo:block）— 具有固定尺寸和时长的完整独立合成内容。字幕样式、VFX 效果、标题卡、底部字幕条。
• 组件（registry/components/，类型为 framevideo: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://www.chanjing.cc/schema/registry-item.json",
  "name": "{block-name}",
  "type": "framevideo: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": "framevideo:composition"
    }
  ]
}

组件的 registry-item.json（不含 dimensions 或 duration）：

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

第 3 步：构建

根据类型应用相应模板。可查看 templates.md 获取可直接复制粘贴的起始模板。

字幕区块

必须遵守的字幕规则：

• 字体：比例字体至少 96px。等宽字体可使用 64-72px（字符较宽，因此字号可以较小）。
• 可读性：使用 -webkit-text-stroke: 2-3px 或多层 text-shadow
• 溢出：对每个组调用 window.__framevideo.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 animation（无法跳转定位）

定位变体：

• 居中：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 MUST 与 window.__timelines["id"] 匹配
• 所有元素 ID 都必须以区块缩写为前缀
• gsap.timeline({ paused: true }) — 始终暂停
• 不使用 Math.random()，不使用 Date.now()

步骤 4：验证

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

步骤 5：预览

# Render preview video
framevideo render -o preview.mp4

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

# Publish to framevideo.dev for review
npx framevideo publish

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

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

步骤 6：发布

所有步骤都必须完成。缺少任何一步都会导致目录条目无法正常显示。

根据你在步骤 1 中构建的内容，{kind} 为 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": "framevideo:block" }  (or "framevideo:component")

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

# 5. Publish to framevideo.dev so reviewers can preview
npx framevideo 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 framevideo.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {framevideo.dev-url}"

**如果你没有 GitHub 账号：**你需要先注册一个才能创建 PR。访问 https://github.com/signup 注册，然后运行 gh auth login。

质量门槛

• framevideo lint → 0 个错误
• framevideo validate → 0 个控制台错误
• npx oxfmt --check 通过
• 已使用新条目更新 registry/registry.json
• 已运行 scripts/generate-catalog-pages.ts（已生成文档页面）
• 已运行 npx framevideo publish（认领你的项目 URL）
• 已将预览 MP4 附加到 PR（外部）或上传目录 PNG（内部）
• 所有 ID 都唯一且带有前缀