diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7806a628..d3adb1bce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,6 +61,42 @@ If you must add a cast, add a comment: const event = data as unknown as RuntimeEvent; ``` +## Adding Registry Items (Blocks & Components) + +The registry at `registry/` contains reusable items installable via `hyperframes add `. Each item lives in its own directory under `registry/blocks/` or `registry/components/`. + +### Directory structure + +``` +registry/blocks// + registry-item.json # Manifest (name, type, description, tags, files) + .html # The composition HTML + +registry/components// + registry-item.json # Manifest (no dimensions/duration for components) + .html # The snippet HTML to paste into a composition + demo.html # Required — standalone demo showing the effect +``` + +### The `demo.html` convention + +Every **component** must ship a companion `demo.html`. This file: + +1. Is a complete, standalone HTML document (with ``, GSAP CDN, etc.) +2. Shows the component effect applied to representative content +3. Registers a GSAP timeline on `window.__timelines` so it can be previewed in the Studio and rendered by the CI preview pipeline +4. Uses `data-composition-id="-demo"` to avoid ID collisions + +Blocks don't need `demo.html` — they are already standalone compositions. + +### Checklist for new items + +1. Create `registry///registry-item.json` following the [schema](packages/core/schemas/registry-item.json) +2. Add the item to `registry/registry.json` +3. For components: include a `demo.html` +4. Run `npx hyperframes lint` and `npx hyperframes validate` on your HTML +5. Test the install flow: `hyperframes add --dir /tmp/test-project` + ## Pull Requests - Use [conventional commit](https://www.conventionalcommits.org/) format for **all commits** (e.g., `feat: add timeline export`, `fix: resolve seek overflow`). Enforced by a git hook. diff --git a/registry/components/grain-overlay/demo.html b/registry/components/grain-overlay/demo.html new file mode 100644 index 000000000..89c85f286 --- /dev/null +++ b/registry/components/grain-overlay/demo.html @@ -0,0 +1,156 @@ + + + + + + Grain Overlay — Demo + + + + +
+ +
+
+
+ Grain Overlay +
+
+ Adds warmth and analog character +
+
+
+ + +
+
+
+ + + + +
+ + diff --git a/registry/components/grain-overlay/grain-overlay.html b/registry/components/grain-overlay/grain-overlay.html new file mode 100644 index 000000000..78b6a9b75 --- /dev/null +++ b/registry/components/grain-overlay/grain-overlay.html @@ -0,0 +1,75 @@ + + +
+
+
+ + diff --git a/registry/components/grain-overlay/registry-item.json b/registry/components/grain-overlay/registry-item.json new file mode 100644 index 000000000..2c0454ff6 --- /dev/null +++ b/registry/components/grain-overlay/registry-item.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://hyperframes.heygen.com/schema/registry-item.json", + "name": "grain-overlay", + "type": "hyperframes:component", + "title": "Grain Overlay", + "description": "Animated film grain texture overlay using CSS keyframes — adds warmth and analog character to any composition", + "tags": ["texture", "grain", "overlay", "film"], + "files": [ + { + "path": "grain-overlay.html", + "target": "compositions/components/grain-overlay.html", + "type": "hyperframes:snippet" + } + ] +} diff --git a/registry/components/grid-pixelate-wipe/demo.html b/registry/components/grid-pixelate-wipe/demo.html new file mode 100644 index 000000000..41fa31c5d --- /dev/null +++ b/registry/components/grid-pixelate-wipe/demo.html @@ -0,0 +1,179 @@ + + + + + + Grid Pixelate Wipe — Demo + + + + +
+ +
+
+
Scene A
+
+ The grid wipe dissolves this away +
+
+
+ + +
+
+
Scene B
+
Revealed from the grid
+
+
+ + +
+ + + + +
+ + diff --git a/registry/components/grid-pixelate-wipe/grid-pixelate-wipe.html b/registry/components/grid-pixelate-wipe/grid-pixelate-wipe.html new file mode 100644 index 000000000..a0c8ebc54 --- /dev/null +++ b/registry/components/grid-pixelate-wipe/grid-pixelate-wipe.html @@ -0,0 +1,80 @@ + + +
+ + + + + + diff --git a/registry/components/grid-pixelate-wipe/registry-item.json b/registry/components/grid-pixelate-wipe/registry-item.json new file mode 100644 index 000000000..a4826db63 --- /dev/null +++ b/registry/components/grid-pixelate-wipe/registry-item.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://hyperframes.heygen.com/schema/registry-item.json", + "name": "grid-pixelate-wipe", + "type": "hyperframes:component", + "title": "Grid Pixelate Wipe", + "description": "Transition effect where the screen dissolves into a grid of squares that fade out with staggered timing — use between scenes", + "tags": ["transition", "wipe", "grid", "pixelate"], + "files": [ + { + "path": "grid-pixelate-wipe.html", + "target": "compositions/components/grid-pixelate-wipe.html", + "type": "hyperframes:snippet" + } + ] +} diff --git a/registry/components/shimmer-sweep/demo.html b/registry/components/shimmer-sweep/demo.html new file mode 100644 index 000000000..b57862119 --- /dev/null +++ b/registry/components/shimmer-sweep/demo.html @@ -0,0 +1,163 @@ + + + + + + Shimmer Sweep — Demo + + + + +
+
+ +
+
+ AI-Powered +
+
+ + +
+
+ Video generation, reimagined +
+
+ + +
+
+ Try it free → +
+
+
+ + + + + +
+ + diff --git a/registry/components/shimmer-sweep/registry-item.json b/registry/components/shimmer-sweep/registry-item.json new file mode 100644 index 000000000..91b18690f --- /dev/null +++ b/registry/components/shimmer-sweep/registry-item.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://hyperframes.heygen.com/schema/registry-item.json", + "name": "shimmer-sweep", + "type": "hyperframes:component", + "title": "Shimmer Sweep", + "description": "Animated light sweep across text or elements using a CSS gradient mask — ideal for AI accents and premium reveals", + "tags": ["text", "shimmer", "highlight", "effect"], + "files": [ + { + "path": "shimmer-sweep.html", + "target": "compositions/components/shimmer-sweep.html", + "type": "hyperframes:snippet" + } + ] +} diff --git a/registry/components/shimmer-sweep/shimmer-sweep.html b/registry/components/shimmer-sweep/shimmer-sweep.html new file mode 100644 index 000000000..979627c93 --- /dev/null +++ b/registry/components/shimmer-sweep/shimmer-sweep.html @@ -0,0 +1,65 @@ + + + + + + + diff --git a/registry/registry.json b/registry/registry.json index b320d91a6..c5ce44978 100644 --- a/registry/registry.json +++ b/registry/registry.json @@ -46,6 +46,18 @@ { "name": "logo-outro", "type": "hyperframes:block" + }, + { + "name": "grain-overlay", + "type": "hyperframes:component" + }, + { + "name": "shimmer-sweep", + "type": "hyperframes:component" + }, + { + "name": "grid-pixelate-wipe", + "type": "hyperframes:component" } ] }