diff --git a/docs/contributing/catalog.mdx b/docs/contributing/catalog.mdx new file mode 100644 index 000000000..e060a8328 --- /dev/null +++ b/docs/contributing/catalog.mdx @@ -0,0 +1,186 @@ +--- +title: Contributing to the Catalog +description: How to add blocks and components to the HyperFrames registry. +--- + +Your agent already knows how to build video components. It writes HTML. HyperFrames renders it. The registry is the collection of everything that's been built — 52 blocks and counting. + +This guide shows you how to add to it. + + +**Quick version** — Fork the repo. Write one HTML file with a paused GSAP timeline. Add `registry-item.json`. Run `hyperframes lint` + `validate`. Publish with `npx hyperframes publish`. Open a PR. + + +## Why Contribute? + +Every block in the registry exists because someone needed it and built it. When you add a block, every HyperFrames user gets it with one command: + +```bash +npx hyperframes add instagram-follow +``` + +The registry grows, HyperFrames gets more useful, and your work ships to everyone. + +## Two Paths + +### Ideas (No Code) + +You spot visual trends before anyone. That's the most valuable contribution. + +- Screen-record a caption style from TikTok/YouTube that doesn't exist yet +- Sketch a lower-third in Figma with fonts, colors, and timing +- Install a component, preview it, report what feels off + +Open an issue on [GitHub](https://github.com/heygen-com/hyperframes/issues) with a visual reference. Tag it `component-request`. + +The bar for ideas is low. We'd rather have 100 and build the best 10. + +### Build It + +Every block is a single HTML file. No build step, no framework. + +If you use Claude Code with HyperFrames skills: + +> "I want to contribute a new transition that looks like \[description\]" + +The `/contribute-catalog` skill scaffolds the structure, validates, renders a preview, publishes to [hyperframes.dev](https://hyperframes.dev), and prepares the PR. + +## What Goes in the Registry + +**Blocks** (`registry/blocks/`) — full standalone compositions. Fixed dimensions, fixed duration. Caption styles, VFX effects, title cards, transitions. + +**Components** (`registry/components/`) — reusable snippets. No fixed size. CSS effects, text treatments, overlays that adapt to any composition. + +### Structure + +``` +registry/blocks/my-block/ + my-block.html ← the composition + registry-item.json ← metadata +``` + +### registry-item.json + +```json +{ + "$schema": "https://hyperframes.heygen.com/schema/registry-item.json", + "name": "my-block", + "type": "hyperframes:block", + "title": "My Block", + "description": "What this block does in one sentence", + "tags": ["category", "subcategory"], + "dimensions": { "width": 1920, "height": 1080 }, + "duration": 5, + "files": [ + { + "path": "my-block.html", + "target": "compositions/my-block.html", + "type": "hyperframes:composition" + } + ] +} +``` + +## The Rules + +Five things that must be true for every registry item: + + + + No `Math.random()`, no `Date.now()`. Use seeded PRNG only. + + + `gsap.timeline({ paused: true })`. The player controls playback. + + + `window.__timelines["id"]` must match `data-composition-id`. + + + Use `tl.eventCallback("onUpdate", render)` for Three.js/WebGL scenes. + + + `tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)` — no lingering text. + + + + +Break any of these and renders won't be reproducible. The renderer captures every frame by seeking the timeline — if your animation depends on real time or random state, it breaks. + + +## Quality Bar + +Not everything belongs in the registry. The bar is production quality. + +| Type | Minimum standard | +|------|-----------------| +| Captions | 96px+ font, text-stroke/shadow, overflow prevention | +| VFX | Solves a problem that takes 4+ hours from scratch | +| Transitions | Smoother than CSS — if opacity 0→1 works, it's not a transition | +| Blocks | Would a professional use this in a client project? | + +### Common rejection reasons + +1. **"Looks like a demo"** — a spinning cube is not a component +2. **"Text unreadable"** — font too small, no contrast treatment +3. **"Non-deterministic"** — `Math.random()` or `Date.now()` +4. **"Timeline not found"** — ID mismatch between HTML and JS +5. **"Breaks as sub-composition"** — element IDs collide (prefix everything) + +## Workflow + + + + Fork [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) and create your block directory: + ```bash + mkdir -p registry/blocks/your-block + ``` + + + Create the HTML composition and `registry-item.json`. Use the templates above. + + + ```bash + hyperframes lint + hyperframes validate + npx oxfmt your-block.html + ``` + + + ```bash + # Add to registry index + # Update registry/registry.json + npx tsx scripts/generate-catalog-pages.ts + ``` + + + ```bash + hyperframes render -o preview.mp4 + ``` + + + ```bash + npx hyperframes publish + ``` + Open a PR with your [hyperframes.dev](https://hyperframes.dev) preview link. + + + +**External contributors:** attach the preview MP4 to your PR. A maintainer handles the catalog image. + +**HeyGen internal:** run `scripts/upload-docs-images.sh` to push catalog PNGs. + +## What's Needed Right Now + +These are gaps in the registry. If you're looking for something to build, start here. + +| Category | Gap | Difficulty | +|----------|-----|-----------| +| Captions | Karaoke with clip-path sweep (CapCut style) | Medium | +| Captions | RTL language layouts (Arabic, Hebrew) | Medium | +| Lower thirds | 10 variations for podcasts/interviews | Easy | +| Lower thirds | News ticker / scrolling text bar | Easy | +| Maps | Animated route maps, region highlights, location pins | Medium | +| VFX | Product turntable with HDRI | Hard | +| VFX | Particle system with physics (collisions, gravity) | Hard | +| Transitions | Morphing shape transitions | Hard | +| Data viz | Sankey / flow diagrams | Medium | diff --git a/docs/docs.json b/docs/docs.json index 025e5600b..5c9452580 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -219,6 +219,7 @@ "group": "Contributing", "pages": [ "contributing", + "contributing/catalog", "contributing/release-channels", "contributing/testing-local-changes" ] diff --git a/skills/contribute/SKILL.md b/skills/contribute-catalog/SKILL.md similarity index 99% rename from skills/contribute/SKILL.md rename to skills/contribute-catalog/SKILL.md index a0b8fa422..db570cff8 100644 --- a/skills/contribute/SKILL.md +++ b/skills/contribute-catalog/SKILL.md @@ -1,5 +1,5 @@ --- -name: contribute +name: contribute-catalog description: Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill. --- diff --git a/skills/contribute/templates.md b/skills/contribute-catalog/templates.md similarity index 100% rename from skills/contribute/templates.md rename to skills/contribute-catalog/templates.md