Setting the file. One moment.
Skill 24 · Hyperframes Registry
Subchapter 24.2
references/contributing.mdMarkdown7 KBView on GitHub
Guide the user from idea to merged PR for a new registry block or component.
1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. ShipAsk what they’re building. The registry has two item types:
registry/blocks/, type hyperframes:block) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.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:
Create the registry structure:
For blocks:
registry/blocks/{block-name}/
{block-name}.html
registry-item.jsonFor components:
registry/components/{component-name}/
{component-name}.html
registry-item.jsonNaming 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 — use the canonical templates in templates.md (block and component variants, both with all required fields).
Apply the correct template based on type. See templates.md for copy-paste starters.
Non-negotiable caption rules:
-webkit-text-stroke: 2-3px OR multi-layer text-shadowwindow.__hyperframes.fitTextFontSize() on every grouptl.to(wordEl, { color/scale }, WORDS[wi].start)tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) on EVERY grouptl.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):
<span> with ID {prefix}-ch-{group}-{char}tl.set at computed intervals from word timestampstl.set at intervals — NOT CSS animation (not seekable)Positioning variants:
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;three@0.147.0 from CDN (global script)tl.eventCallback("onUpdate", renderScene); renderScene(); — NO requestAnimationFramemulberry32) for randomnessdata-composition-id MUST match window.__timelines["id"]gsap.timeline({ paused: true }) — always pausedMath.random(), no Date.now()hyperframes lint # 0 errors required
hyperframes check --no-contrast # 0 console errors required# 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 publishCatalog preview image — For the default PNG preview, save your snapshot at docs/images/catalog/{kind}/{name}.png in the repository checkout ({kind} is blocks or components). After upload, the catalog serves it from https://static.heygen.ai/hyperframes-oss/docs/images/catalog/{kind}/{name}.png. If registry-item.json declares preview, the card uses its poster URL; a preview without poster has no image fallback.
scripts/upload-docs-images.sh from the repository root (requires AWS profile engineering-767398024897)All steps are required. Missing any one produces a broken catalog entry.
{kind} is blocks or components depending on what you built in Step 1.
# 1. Create branch
git checkout -b feat/registry-{name}
# 2. Format HTML
npx oxfmt registry/{kind}/{name}/*.html
# 3. Regenerate registry/registry.json from the item directories.
# Do not hand-edit it: an entry added by hand survives until the next
# regeneration and then vanishes, and one left behind for a directory that
# no longer exists is worse, because `hyperframes add <name>` resolves the
# name and then fails on missing files.
npx tsx scripts/generate-registry-items.ts
# 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}"If you don’t have a GitHub account: you need one to open a PR. Sign up at https://github.com/signup (opens in a new tab), then run gh auth login.
hyperframes lint → 0 errorshyperframes check → 0 console errorsnpx oxfmt --check passesregistry/registry.json updated with new entryscripts/generate-catalog-pages.ts run (docs page generated)npx hyperframes publish run (claim your project URL)