Contribute Catalog — 贡献目录

Contribute to HyperFrames Registry

图形界面de the user from idea to merged PR for a new registry block or 组件.

工作流

• Clarify → 2. Scaffold → 3. Build → 4. 验证 → 5. Preview → 6. Ship

Step 1: Clarify

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. 组件 (registry/组件s/, type hyperframes:组件) — 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? Step 2: Scaffold

创建 the registry structure:

For blocks:

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

For 组件s:

registry/组件s/{组件-name}/ {组件-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:

{ "$模式": "https://hyperframes.heygen.com/模式/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", "tar获取": "compositions/{block-name}.html", "type": "hyperframes:composition" } ] }

registry-item.json for 组件s (no dimensions or duration):

{ "$模式": "https://hyperframes.heygen.com/模式/registry-item.json", "name": "{组件-name}", "type": "hyperframes:组件", "title": "{Human Title}", "description": "{one sentence}", "tags": ["{category}"], "files": [ { "path": "{组件-name}.html", "tar获取": "compositions/组件s/{组件-name}.html", "type": "hyperframes:snippet" } ] }

Step 3: Build

应用ly the correct template based on type. See templates.md for copy-paste 启动ers.

Caption blocks

Non-negotiable caption rules:

Font: 96px minimum for proportional fonts. 64-72px acceptable for monospace (wider characters need less size). Readability: -网页kit-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/扩展 }, WORDS[wi].启动) Hard kill: tl.设置(groupEl, { opacity: 0, visibility: "hidden" }, g.end) on EVERY group Never use tl.from(el, { opacity: 0 }) at the same position as tl.设置(el, { opacity: 1 }) — the from clobbers the 设置. Use tl.to instead.

Per-character animation (typewriter, scramble):

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

Positioning variants:

Centered: display: flex; align-items: center; justify-content: center; Lower-third: position: absolute; 机器人tom: 100px; left: 0; width: 100%; text-align: center; Left-aligned: position: absolute; 机器人tom: 100px; left: 120px; text-align: left; VFX blocks (Three.js) Use three@0.147.0 from CDN (global script) tl.eventCallback("on更新", renderScene); renderScene(); — NO 请求AnimationFrame 状态 proxy pattern: GSAP animates plAIn JS object, render function reads it 种子ed PRNG (mulberry32) for randomness All types data-composition-id MUST match window.__timelines["id"] All element IDs prefixed with block abbreviation gsap.timeline({ 暂停d: true }) — always 暂停d No Math.random(), no Date.now() Step 4: 验证 hyperframes lint # 0 errors required hyperframes 验证 --no-contrast # 0 console errors required

Step 5: Preview # 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

Cata记录 preview image — The cata记录 card uses a PNG at docs/images/cata记录/{kind}/{name}.png (where {kind} is blocks or 组件s). 生成 it from a snapshot, then:

HeyGen internal contributors: 运行 scripts/上传-docs-images.sh (requires AWS 性能分析 engineering-767398024897) External contributors: attach the preview MP4 to your PR description. A mAIntAIner will 生成 and 上传 the cata记录 image before merging. Step 6: Ship

All steps are required. Missing any one produces a broken cata记录 entry.

{kind} is blocks or 组件s depending on what you built in Step 1.

# 1. 创建 branch git 检查out -b feat/registry-{name}

# 2. 格式化 HTML npx oxfmt re