From b0f754a7f7f90e14ee3a51c3a5d1eee9d6e1e576 Mon Sep 17 00:00:00 2001
From: James Russo <james.russo@heygen.com>
Date: Tue, 14 Apr 2026 16:18:22 -0700
Subject: [PATCH] =?UTF-8?q?feat(registry):=20seed=20components=20=E2=80=94?=
 =?UTF-8?q?=20grain-overlay,=20shimmer-sweep,=20grid-pixelate-wipe=20(#260?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## What

Three reusable effect components for the registry, each with a snippet HTML and companion `demo.html`:

| Component | Description |
|-----------|-------------|
| `grain-overlay` | Animated film grain texture overlay (CSS keyframes, extracted from warm-grain example) |
| `shimmer-sweep` | CSS gradient light sweep across text/elements, driven by GSAP custom property animation |
| `grid-pixelate-wipe` | Grid-based dissolve transition — screen breaks into 16×9 squares that scale in/out with stagger |

Establishes the `demo.html` convention in `CONTRIBUTING.md`.

## Why

Phase B of the catalog plan — seed the first components in the registry. Components are effect snippets that get merged into existing compositions (vs. blocks which are standalone sub-compositions).

## How

- **grain-overlay**: Extracted the grain texture pattern from the warm-grain example. Uses a 200% oversized tiled texture with `steps(1)` keyframe animation for the random-noise effect.
- **shimmer-sweep**: Original implementation using CSS custom properties (`--shimmer-pos`) animated by GSAP. The gradient mask uses `mix-blend-mode: overlay` for a natural light sweep. Auto-injects `.shimmer-mask` elements into `.shimmer-sweep-target` wrappers.
- **grid-pixelate-wipe**: Creates a 16×9 CSS Grid of cells, animated with GSAP stagger. Users drive `.grid-cell` `scale` directly in their timeline.

Simplify review addressed: scoped `.grain-texture` under `#grain-overlay`, scoped `.grid-cell` under `#grid-pixelate-overlay`, removed `window.gridPixelateIn/Out` globals in favor of direct GSAP patterns.

Each component ships a `demo.html` — a standalone composition that previews the effect and doubles as a fixture for the CI preview pipeline (PR 8).

## Test plan

- [x] `hyperframes add grain-overlay` installs to `compositions/components/grain-overlay.html`
- [x] `hyperframes add shimmer-sweep` installs to `compositions/components/shimmer-sweep.html`
- [x] `hyperframes add grid-pixelate-wipe` installs to `compositions/components/grid-pixelate-wipe.html`
- [x] All three return correct `--json` output with snippet and type info
- [x] `registry-item.json` files validate against the JSON Schema
- [x] `demo.html` files are self-contained with correct `data-composition-id` and `window.__timelines` registration
- [x] `oxfmt --check` and `oxlint` pass on all files
- [x] `CONTRIBUTING.md` documents the `demo.html` convention and registry item checklist
---
 CONTRIBUTING.md                               |  36 ++++
 registry/components/grain-overlay/demo.html   | 156 +++++++++++++++
 .../grain-overlay/grain-overlay.html          |  75 ++++++++
 .../grain-overlay/registry-item.json          |  15 ++
 .../components/grid-pixelate-wipe/demo.html   | 179 ++++++++++++++++++
 .../grid-pixelate-wipe.html                   |  80 ++++++++
 .../grid-pixelate-wipe/registry-item.json     |  15 ++
 registry/components/shimmer-sweep/demo.html   | 163 ++++++++++++++++
 .../shimmer-sweep/registry-item.json          |  15 ++
 .../shimmer-sweep/shimmer-sweep.html          |  65 +++++++
 registry/registry.json                        |  12 ++
 11 files changed, 811 insertions(+)
 create mode 100644 registry/components/grain-overlay/demo.html
 create mode 100644 registry/components/grain-overlay/grain-overlay.html
 create mode 100644 registry/components/grain-overlay/registry-item.json
 create mode 100644 registry/components/grid-pixelate-wipe/demo.html
 create mode 100644 registry/components/grid-pixelate-wipe/grid-pixelate-wipe.html
 create mode 100644 registry/components/grid-pixelate-wipe/registry-item.json
 create mode 100644 registry/components/shimmer-sweep/demo.html
 create mode 100644 registry/components/shimmer-sweep/registry-item.json
 create mode 100644 registry/components/shimmer-sweep/shimmer-sweep.html

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 <name>`. Each item lives in its own directory under `registry/blocks/` or `registry/components/`.
+
+### Directory structure
+
+```
+registry/blocks/<name>/
+  registry-item.json     # Manifest (name, type, description, tags, files)
+  <name>.html            # The composition HTML
+
+registry/components/<name>/
+  registry-item.json     # Manifest (no dimensions/duration for components)
+  <name>.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 `<!doctype html>`, 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="<name>-demo"` to avoid ID collisions
+
+Blocks don't need `demo.html` — they are already standalone compositions.
+
+### Checklist for new items
+
+1. Create `registry/<blocks|components>/<name>/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 <name> --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 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Grain Overlay — Demo</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="demo"
+      data-composition-id="grain-overlay-demo"
+      data-width="1920"
+      data-height="1080"
+      data-duration="5"
+    >
+      <!-- Background content to demonstrate the overlay -->
+      <div
+        class="demo-bg"
+        style="
+          width: 1920px;
+          height: 1080px;
+          background: linear-gradient(135deg, #f5f0e0 0%, #e8d8b8 50%, #d4c4a0 100%);
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          font-family: &quot;Inter&quot;, sans-serif;
+          position: relative;
+        "
+      >
+        <div style="text-align: center; z-index: 1">
+          <div
+            class="demo-title"
+            style="font-size: 80px; font-weight: 700; color: #2c1e16; opacity: 0"
+          >
+            Grain Overlay
+          </div>
+          <div
+            class="demo-subtitle"
+            style="font-size: 32px; color: #5a4a3a; margin-top: 20px; opacity: 0"
+          >
+            Adds warmth and analog character
+          </div>
+        </div>
+      </div>
+
+      <!-- The grain overlay component -->
+      <div
+        id="grain-overlay"
+        style="
+          position: absolute;
+          top: 0;
+          left: 0;
+          width: 100%;
+          height: 100%;
+          pointer-events: none;
+          z-index: 100;
+        "
+      >
+        <div class="grain-texture"></div>
+      </div>
+
+      <style>
+        @keyframes grain-noise {
+          0%,
+          100% {
+            transform: translate(0, 0);
+          }
+          10% {
+            transform: translate(-5%, -5%);
+          }
+          20% {
+            transform: translate(-10%, 5%);
+          }
+          30% {
+            transform: translate(5%, -10%);
+          }
+          40% {
+            transform: translate(-5%, 15%);
+          }
+          50% {
+            transform: translate(-10%, 5%);
+          }
+          60% {
+            transform: translate(15%, 0);
+          }
+          70% {
+            transform: translate(0, 10%);
+          }
+          80% {
+            transform: translate(-15%, 0);
+          }
+          90% {
+            transform: translate(10%, 5%);
+          }
+        }
+
+        #grain-overlay .grain-texture {
+          position: absolute;
+          top: -50%;
+          left: -50%;
+          width: 200%;
+          height: 200%;
+          background: url("https://www.transparenttextures.com/patterns/natural-paper.png");
+          opacity: 0.15;
+          animation: grain-noise 0.5s steps(1) infinite;
+        }
+      </style>
+
+      <script>
+        (function () {
+          const tl = gsap.timeline({ paused: true });
+
+          tl.to(
+            ".demo-title",
+            {
+              opacity: 1,
+              y: -10,
+              duration: 1,
+              ease: "power3.out",
+            },
+            0.5,
+          );
+
+          tl.to(
+            ".demo-subtitle",
+            {
+              opacity: 1,
+              y: -5,
+              duration: 0.8,
+              ease: "power3.out",
+            },
+            1.0,
+          );
+
+          window.__timelines = window.__timelines || {};
+          window.__timelines["grain-overlay-demo"] = tl;
+        })();
+      </script>
+    </div>
+  </body>
+</html>
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 @@
+<!--
+  Grain Overlay — animated film grain texture.
+
+  Usage: paste this snippet into your composition's HTML.
+  The overlay covers the full viewport with pointer-events: none
+  so it sits on top of all content without blocking interaction.
+
+  Customize:
+  - opacity: adjust .grain-texture opacity (default 0.15)
+  - speed: change animation duration (default 0.5s)
+  - texture: swap the background URL for a different pattern
+  - z-index: adjust #grain-overlay z-index to layer correctly
+-->
+
+<div
+  id="grain-overlay"
+  style="
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    z-index: 100;
+  "
+>
+  <div class="grain-texture"></div>
+</div>
+
+<style>
+  @keyframes grain-noise {
+    0%,
+    100% {
+      transform: translate(0, 0);
+    }
+    10% {
+      transform: translate(-5%, -5%);
+    }
+    20% {
+      transform: translate(-10%, 5%);
+    }
+    30% {
+      transform: translate(5%, -10%);
+    }
+    40% {
+      transform: translate(-5%, 15%);
+    }
+    50% {
+      transform: translate(-10%, 5%);
+    }
+    60% {
+      transform: translate(15%, 0);
+    }
+    70% {
+      transform: translate(0, 10%);
+    }
+    80% {
+      transform: translate(-15%, 0);
+    }
+    90% {
+      transform: translate(10%, 5%);
+    }
+  }
+
+  #grain-overlay .grain-texture {
+    position: absolute;
+    top: -50%;
+    left: -50%;
+    width: 200%;
+    height: 200%;
+    background: url("https://www.transparenttextures.com/patterns/natural-paper.png");
+    opacity: 0.15;
+    animation: grain-noise 0.5s steps(1) infinite;
+  }
+</style>
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 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Grid Pixelate Wipe — Demo</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="demo"
+      data-composition-id="grid-pixelate-wipe-demo"
+      data-width="1920"
+      data-height="1080"
+      data-duration="8"
+    >
+      <!-- Scene A -->
+      <div
+        id="scene-a"
+        style="
+          position: absolute;
+          width: 1920px;
+          height: 1080px;
+          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          font-family: &quot;Inter&quot;, sans-serif;
+        "
+      >
+        <div style="text-align: center; color: white">
+          <div style="font-size: 80px; font-weight: 800">Scene A</div>
+          <div style="font-size: 32px; margin-top: 20px; opacity: 0.7">
+            The grid wipe dissolves this away
+          </div>
+        </div>
+      </div>
+
+      <!-- Scene B (hidden initially) -->
+      <div
+        id="scene-b"
+        style="
+          position: absolute;
+          width: 1920px;
+          height: 1080px;
+          background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          font-family: &quot;Inter&quot;, sans-serif;
+          opacity: 0;
+        "
+      >
+        <div style="text-align: center; color: white">
+          <div style="font-size: 80px; font-weight: 800">Scene B</div>
+          <div style="font-size: 32px; margin-top: 20px; opacity: 0.7">Revealed from the grid</div>
+        </div>
+      </div>
+
+      <!-- Grid Pixelate Wipe overlay -->
+      <div
+        id="grid-pixelate-overlay"
+        style="
+          position: absolute;
+          top: 0;
+          left: 0;
+          width: 100%;
+          height: 100%;
+          pointer-events: none;
+          z-index: 999;
+          display: grid;
+        "
+      ></div>
+
+      <style>
+        #grid-pixelate-overlay {
+          --grid-color: black;
+        }
+
+        #grid-pixelate-overlay .grid-cell {
+          background: var(--grid-color);
+          transform: scale(0);
+          transform-origin: center center;
+        }
+      </style>
+
+      <script>
+        (function () {
+          const COLS = 16;
+          const ROWS = 9;
+          const overlay = document.getElementById("grid-pixelate-overlay");
+
+          overlay.style.gridTemplateColumns = `repeat(${COLS}, 1fr)`;
+          overlay.style.gridTemplateRows = `repeat(${ROWS}, 1fr)`;
+
+          for (let i = 0; i < COLS * ROWS; i++) {
+            const cell = document.createElement("div");
+            cell.className = "grid-cell";
+            overlay.appendChild(cell);
+          }
+
+          const tl = gsap.timeline({ paused: true });
+
+          // Scene A visible for 2 seconds
+          // Grid covers screen (transition out of A)
+          tl.to(
+            ".grid-cell",
+            {
+              scale: 1,
+              duration: 0.6,
+              stagger: { amount: 0.6, from: "center" },
+              ease: "power2.inOut",
+            },
+            2.0,
+          );
+
+          // Swap scenes at midpoint
+          tl.set("#scene-a", { opacity: 0 }, 3.0);
+          tl.set("#scene-b", { opacity: 1 }, 3.0);
+
+          // Grid reveals scene B
+          tl.to(
+            ".grid-cell",
+            {
+              scale: 0,
+              duration: 0.6,
+              stagger: { amount: 0.6, from: "edges" },
+              ease: "power2.inOut",
+            },
+            3.0,
+          );
+
+          // Second transition: back to A using random pattern
+          tl.to(
+            ".grid-cell",
+            {
+              scale: 1,
+              duration: 0.5,
+              stagger: { amount: 0.5, from: "random" },
+              ease: "power2.inOut",
+            },
+            5.5,
+          );
+
+          tl.set("#scene-b", { opacity: 0 }, 6.3);
+          tl.set("#scene-a", { opacity: 1 }, 6.3);
+
+          tl.to(
+            ".grid-cell",
+            {
+              scale: 0,
+              duration: 0.5,
+              stagger: { amount: 0.5, from: "random" },
+              ease: "power2.inOut",
+            },
+            6.3,
+          );
+
+          window.__timelines = window.__timelines || {};
+          window.__timelines["grid-pixelate-wipe-demo"] = tl;
+        })();
+      </script>
+    </div>
+  </body>
+</html>
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 @@
+<!--
+  Grid Pixelate Wipe — transition effect.
+
+  Usage: place this overlay in your composition. To transition between
+  scenes, animate .grid-cell scale from 0→1 (cover) then 1→0 (reveal)
+  using GSAP stagger with a "from" pattern.
+
+  Customize:
+  - COLS / ROWS: grid density (default 16×9), edit in the script below
+  - --grid-color: cell fill color (default black)
+  - Stagger "from": "center" for radial, "edges" for inward, "random" for scatter
+-->
+
+<div
+  id="grid-pixelate-overlay"
+  style="
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    z-index: 999;
+    display: grid;
+  "
+></div>
+
+<style>
+  #grid-pixelate-overlay {
+    --grid-color: black;
+  }
+
+  #grid-pixelate-overlay .grid-cell {
+    background: var(--grid-color);
+    transform: scale(0);
+    transform-origin: center center;
+  }
+</style>
+
+<script>
+  (function () {
+    const COLS = 16;
+    const ROWS = 9;
+    const overlay = document.getElementById("grid-pixelate-overlay");
+    if (!overlay) return;
+
+    overlay.style.gridTemplateColumns = `repeat(${COLS}, 1fr)`;
+    overlay.style.gridTemplateRows = `repeat(${ROWS}, 1fr)`;
+
+    for (let i = 0; i < COLS * ROWS; i++) {
+      const cell = document.createElement("div");
+      cell.className = "grid-cell";
+      overlay.appendChild(cell);
+    }
+  })();
+</script>
+
+<!--
+  Timeline integration example:
+
+  // Cover screen with grid (transition out of scene A)
+  tl.to(".grid-cell", {
+    scale: 1,
+    duration: 0.6,
+    stagger: { amount: 0.6, from: "center" },
+    ease: "power2.inOut",
+  }, 3.0);
+
+  // Swap scene content at midpoint
+  tl.set("#scene-a", { opacity: 0 }, 3.6);
+  tl.set("#scene-b", { opacity: 1 }, 3.6);
+
+  // Reveal scene B by removing grid
+  tl.to(".grid-cell", {
+    scale: 0,
+    duration: 0.6,
+    stagger: { amount: 0.6, from: "edges" },
+    ease: "power2.inOut",
+  }, 3.6);
+-->
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 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Shimmer Sweep — Demo</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="demo"
+      data-composition-id="shimmer-sweep-demo"
+      data-width="1920"
+      data-height="1080"
+      data-duration="6"
+    >
+      <div
+        class="demo-canvas"
+        style="
+          width: 1920px;
+          height: 1080px;
+          background: #0a0a0f;
+          display: flex;
+          flex-direction: column;
+          justify-content: center;
+          align-items: center;
+          gap: 60px;
+          font-family: &quot;Inter&quot;, sans-serif;
+        "
+      >
+        <!-- Example 1: Large heading -->
+        <div class="shimmer-sweep-target" style="--shimmer-color: rgba(255, 255, 255, 0.5)">
+          <div
+            class="demo-heading"
+            style="font-size: 120px; font-weight: 800; color: #ffffff; opacity: 0"
+          >
+            AI-Powered
+          </div>
+        </div>
+
+        <!-- Example 2: Subheading -->
+        <div class="shimmer-sweep-target" style="--shimmer-color: rgba(100, 200, 255, 0.4)">
+          <div
+            class="demo-subheading"
+            style="font-size: 48px; font-weight: 400; color: #888888; opacity: 0"
+          >
+            Video generation, reimagined
+          </div>
+        </div>
+
+        <!-- Example 3: Pill badge -->
+        <div
+          class="shimmer-sweep-target"
+          style="--shimmer-color: rgba(255, 255, 255, 0.3); --shimmer-width: 30%"
+        >
+          <div
+            class="demo-pill"
+            style="
+              background: linear-gradient(135deg, #1a1a2e, #2a2a4e);
+              border: 1px solid #333;
+              border-radius: 100px;
+              padding: 16px 40px;
+              font-size: 20px;
+              color: #aaa;
+              opacity: 0;
+            "
+          >
+            Try it free →
+          </div>
+        </div>
+      </div>
+
+      <!-- Shimmer Sweep component -->
+      <style>
+        .shimmer-sweep-target {
+          position: relative;
+          display: inline-block;
+        }
+
+        .shimmer-sweep-target .shimmer-mask {
+          position: absolute;
+          top: 0;
+          left: 0;
+          width: 100%;
+          height: 100%;
+          pointer-events: none;
+          background: linear-gradient(
+            var(--shimmer-angle, 120deg),
+            transparent 0%,
+            transparent calc(var(--shimmer-pos, -20%) - var(--shimmer-width, 20%) / 2),
+            var(--shimmer-color, rgba(255, 255, 255, 0.6)) var(--shimmer-pos, -20%),
+            transparent calc(var(--shimmer-pos, -20%) + var(--shimmer-width, 20%) / 2),
+            transparent 100%
+          );
+          mix-blend-mode: overlay;
+        }
+      </style>
+
+      <script>
+        (function () {
+          // Inject shimmer masks
+          document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
+            if (!el.querySelector(".shimmer-mask")) {
+              const mask = document.createElement("div");
+              mask.className = "shimmer-mask";
+              el.appendChild(mask);
+            }
+          });
+
+          const tl = gsap.timeline({ paused: true });
+
+          // Fade in elements
+          tl.to(".demo-heading", { opacity: 1, duration: 0.6, ease: "power2.out" }, 0.3);
+          tl.to(".demo-subheading", { opacity: 1, duration: 0.6, ease: "power2.out" }, 0.6);
+          tl.to(".demo-pill", { opacity: 1, duration: 0.6, ease: "power2.out" }, 0.9);
+
+          // First shimmer sweep across all targets
+          tl.fromTo(
+            ".shimmer-sweep-target",
+            { "--shimmer-pos": "-20%" },
+            {
+              "--shimmer-pos": "120%",
+              duration: 1.2,
+              ease: "power2.inOut",
+              stagger: 0.15,
+            },
+            1.5,
+          );
+
+          // Second sweep
+          tl.fromTo(
+            ".shimmer-sweep-target",
+            { "--shimmer-pos": "-20%" },
+            {
+              "--shimmer-pos": "120%",
+              duration: 1.0,
+              ease: "power2.inOut",
+              stagger: 0.1,
+            },
+            3.5,
+          );
+
+          window.__timelines = window.__timelines || {};
+          window.__timelines["shimmer-sweep-demo"] = tl;
+        })();
+      </script>
+    </div>
+  </body>
+</html>
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 @@
+<!--
+  Shimmer Sweep — animated light pass across text or elements.
+
+  Usage: wrap your text element with class="shimmer-sweep-target" and
+  paste this snippet into your composition. The GSAP timeline drives
+  the sweep position for deterministic frame-by-frame rendering.
+
+  Customize:
+  - --shimmer-color: highlight color (default rgba(255,255,255,0.6))
+  - --shimmer-width: highlight band width as % (default 20%)
+  - --shimmer-angle: sweep angle (default 120deg)
+  - Timeline duration/ease: adjust in the script below
+-->
+
+<style>
+  .shimmer-sweep-target {
+    position: relative;
+    display: inline-block;
+  }
+
+  .shimmer-sweep-target .shimmer-mask {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    background: linear-gradient(
+      var(--shimmer-angle, 120deg),
+      transparent 0%,
+      transparent calc(var(--shimmer-pos, -20%) - var(--shimmer-width, 20%) / 2),
+      var(--shimmer-color, rgba(255, 255, 255, 0.6)) var(--shimmer-pos, -20%),
+      transparent calc(var(--shimmer-pos, -20%) + var(--shimmer-width, 20%) / 2),
+      transparent 100%
+    );
+    mix-blend-mode: overlay;
+  }
+</style>
+
+<script>
+  (function () {
+    // Auto-inject .shimmer-mask into every .shimmer-sweep-target
+    document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
+      if (!el.querySelector(".shimmer-mask")) {
+        const mask = document.createElement("div");
+        mask.className = "shimmer-mask";
+        el.appendChild(mask);
+      }
+    });
+  })();
+</script>
+
+<!--
+  Timeline integration example (add to your composition's GSAP timeline):
+
+  // Single sweep from left to right
+  tl.fromTo(".shimmer-sweep-target", {
+    "--shimmer-pos": "-20%",
+  }, {
+    "--shimmer-pos": "120%",
+    duration: 1.2,
+    ease: "power2.inOut",
+    stagger: 0.15,
+  }, startTime);
+-->
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"
     }
   ]
 }