Contribute Catalog

Contribute to FrameVideo Registry

Guide the user from idea to merged PR for a new registry block or component.

Workflow

1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship

Step 1: Clarify

Ask what they're building. The registry has two item types:

• Block (registry/blocks/, type framevideo:block) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
• Component (registry/components/, type framevideo:component) — 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

Create the registry structure:

For blocks:

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

For components:

registry/components/{component-name}/
  {component-name}.html
  registry-item.json

Naming convention:

Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.

registry-item.json for blocks:

{
  "$schema": "https://framevideo.chanjing.com/schema/registry-item.json",
  "name": "{block-name}",
  "type": "framevideo: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",
      "target": "compositions/{block-name}.html",
      "type": "framevideo:composition"
    }
  ]
}

registry-item.json for components (no dimensions or duration):

{
  "$schema": "https://framevideo.chanjing.com/schema/registry-item.json",
  "name": "{component-name}",
  "type": "framevideo:component",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "tags": ["{category}"],
  "files": [
    {
      "path": "{component-name}.html",
      "target": "compositions/components/{component-name}.html",
      "type": "framevideo:snippet"
    }
  ]
}

Step 3: Build

Apply the correct template based on type. See templates.md for copy-paste starters.

Caption blocks

Non-negotiable caption rules:

• Font: 96px minimum for proportional fonts. 64-72px acceptable for monospace (wider characters need less size).
• Readability: -webkit-text-stroke: 2-3px OR multi-layer text-shadow
• Overflow: call window.__framevideo.fitTextFontSize() on every group
• Karaoke: highlight active word via tl.to(wordEl, { color/scale }, WORDS[wi].start)
• Hard kill: tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) on EVERY group
• Never use `tl.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):

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

Positioning variants:

• Centered: display: flex; align-items: center; justify-content: center;
• Lower-third: position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;
• Left-aligned: position: absolute; bottom: 100px; left: 120px; text-align: left;

VFX blocks (Three.js)

• Use three@0.147.0 from CDN (global script)
• tl.eventCallback("onUpdate", renderScene); renderScene(); — NO requestAnimationFrame
• State proxy pattern: GSAP animates plain JS object, render function reads it
• Seeded PRNG (mulberry32) for randomness

All types

• data-composition-id MUST match window.__timelines["id"]
• All element IDs prefixed with block abbreviation
• gsap.timeline({ paused: true }) — always paused
• No Math.random(), no Date.now()

Step 4: Validate

framevideo lint                    # 0 errors required
framevideo validate --no-contrast  # 0 console errors required

Step 5: Preview

# Render preview video
framevideo render -o preview.mp4

# Snapshot for visual QA
framevideo snapshot --at "1.0,3.0,5.0,7.0"

# Publish to framevideo.dev for review
npx framevideo publish

Catalog preview image — The catalog card uses a PNG at docs/images/catalog/{kind}/{name}.png (where {kind} is blocks or components). Generate it from a snapshot, then:

• Chanjing internal contributors: run scripts/upload-docs-images.sh (requires AWS profile engineering-767398024897)
• External contributors: attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.

Step 6: Ship

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. Update registry/registry.json — add entry to the "items" array:
#    { "name": "{name}", "type": "framevideo:block" }  (or "framevideo:component")

# 4. Generate catalog docs page
npx tsx scripts/generate-catalog-pages.ts

# 5. Publish to framevideo.dev so reviewers can preview
npx framevideo 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 framevideo.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {framevideo.dev-url}"

If you don't have a GitHub account: you need one to open a PR. Sign up at https://github.com/signup, then run gh auth login.

Quality Gate

• [ ] framevideo lint → 0 errors
• [ ] framevideo validate → 0 console errors
• [ ] npx oxfmt --check passes
• [ ] registry/registry.json updated with new entry
• [ ] scripts/generate-catalog-pages.ts run (docs page generated)
• [ ] npx framevideo publish run (claim your project URL)
• [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
• [ ] All IDs unique and prefixed

Contribute Templates

Copy-paste starter templates for each component type. These embed the proven patterns that pass lint and validate.

Caption Template

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link
      href="https://fonts.googleapis.com/css2?family=Montserrat:wght@800;900&display=swap"
      rel="stylesheet"
    />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      *,
      *::before,
      *::after {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      body {
        background: #111;
        overflow: hidden;
      }
      #root-BLOCKNAME {
        position: relative;
        width: 1920px;
        height: 1080px;
        overflow: hidden;
        background: #111;
      }
      .cap-container {
        position: absolute;
        top: 0;
        left: 0;
        width: 100%;
        height: 100%;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      .cg {
        position: absolute;
        display: flex;
        align-items: center;
        justify-content: center;
        gap: 32px;
        max-width: 1700px;
        overflow: visible;
        opacity: 0;
        visibility: hidden;
      }
      .cw {
        font-family: "Montserrat", sans-serif;
        font-weight: 900;
        font-size: 128px;
        color: #ffffff;
        text-transform: uppercase;
        line-height: 1;
        display: inline-block;
        -webkit-text-stroke: 3px rgba(0, 0, 0, 0.8);
        paint-order: stroke fill;
        text-shadow: 0 4px 12px rgba(0, 0, 0, 0.5);
      }
    </style>
  </head>
  <body>
    <div
      id="root-BLOCKNAME"
      data-composition-id="BLOCKNAME"
      data-start="0"
      data-duration="9"
      data-width="1920"
      data-height="1080"
    >
      <div class="cap-container" id="cc-BLOCKNAME"></div>
      <div
        id="drv-BLOCKNAME"
        class="clip"
        data-start="0"
        data-duration="9"
        data-track-index="0"
        style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"
      ></div>
    </div>
    <script>
      (function () {
        window.__timelines = window.__timelines || {};

        // REPLACE with actual transcript data
        var WORDS = [
          { text: "Welcome", start: 0.3, end: 0.65 },
          { text: "to", start: 0.65, end: 0.8 },
          { text: "the", start: 0.8, end: 0.95 },
          { text: "future", start: 0.95, end: 1.4 },
          // ... add all words
        ];

        var GROUPS = [
          { start: 0.3, end: 1.3, wordStart: 0, wordEnd: 3, text: "Welcome to the future" },
          // ... add all groups
        ];

        var container = document.getElementById("cc-BLOCKNAME");

        GROUPS.forEach(function (g, gi) {
          var groupEl = document.createElement("div");
          groupEl.id = "PREFIX-cg-" + gi;
          groupEl.className = "cg";

          for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {
            var wordEl = document.createElement("span");
            wordEl.id = "PREFIX-cw-" + wi;
            wordEl.className = "cw";
            wordEl.textContent = WORDS[wi].text;
            groupEl.appendChild(wordEl);
          }

          // Pretext overflow prevention
          if (window.__framevideo && window.__framevideo.fitTextFontSize) {
            var _fit = window.__framevideo.fitTextFontSize(g.text.toUpperCase(), {
              fontFamily: "Montserrat",
              fontWeight: 900,
              maxWidth: 1550,
              baseFontSize: 128,
              minFontSize: 48,
            });
            if (_fit.fontSize < 128) {
              for (var _fi = 0; _fi < groupEl.children.length; _fi++) {
                groupEl.children[_fi].style.fontSize = _fit.fontSize + "px";
              }
            }
          }
          container.appendChild(groupEl);
        });

        var tl = gsap.timeline({ paused: true });

        GROUPS.forEach(function (g, gi) {
          var groupEl = document.getElementById("PREFIX-cg-" + gi);

          // SHOW — set opacity to 1 (never use tl.from with opacity:0 here)
          tl.set(groupEl, { opacity: 1, visibility: "visible" }, g.start);

          // ENTRANCE — customize this per style
          tl.from(groupEl, { scale: 1.3, duration: 0.15, ease: "back.out(2)" }, g.start);

          // KARAOKE — highlight each word
          for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {
            var wordEl = document.getElementById("PREFIX-cw-" + wi);
            tl.to(wordEl, { color: "#FFD700", scale: 1.1, duration: 0.06 }, WORDS[wi].start);
            tl.to(wordEl, { color: "#FFFFFF", scale: 1, duration: 0.08 }, WORDS[wi].end);
          }

          // EXIT
          tl.to(groupEl, { opacity: 0, scale: 0.9, duration: 0.1 }, g.end - 0.1);

          // HARD KILL (mandatory)
          tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end);
        });

        window.__timelines["BLOCKNAME"] = tl;
      })();
    </script>
  </body>
</html>

Replace checklist:

• BLOCKNAME → your block name (e.g., cap-swoosh)
• PREFIX → short unique prefix for IDs (e.g., sw)
• Font family, weight, size → your style's typography
• Entrance animation → your style's entrance
• Karaoke highlight → your style's active word treatment
• Colors → your style's palette

---

VFX Template

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js"></script>
    <style>
      *,
      *::before,
      *::after {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      body {
        background: #030308;
        overflow: hidden;
      }
      #root-BLOCKNAME {
        position: relative;
        width: 1920px;
        height: 1080px;
        overflow: hidden;
        background: #030308;
      }
      #canvas-BLOCKNAME {
        position: absolute;
        top: 0;
        left: 0;
        width: 1920px;
        height: 1080px;
      }
    </style>
  </head>
  <body>
    <div
      id="root-BLOCKNAME"
      data-composition-id="BLOCKNAME"
      data-start="0"
      data-duration="10"
      data-width="1920"
      data-height="1080"
    >
      <canvas id="canvas-BLOCKNAME" width="1920" height="1080"></canvas>
      <div
        id="drv-BLOCKNAME"
        class="clip"
        data-start="0"
        data-duration="10"
        data-track-index="0"
        style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"
      ></div>
    </div>
    <script>
      (function () {
        window.__timelines = window.__timelines || {};

        // Seeded PRNG — NEVER use Math.random()
        function mulberry32(a) {
          return function () {
            a |= 0;
            a = (a + 0x6d2b79f5) | 0;
            var t = Math.imul(a ^ (a >>> 15), 1 | a);
            t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
          };
        }
        var rng = mulberry32(42);

        var W = 1920,
          H = 1080;
        var canvas = document.getElementById("canvas-BLOCKNAME");
        var renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true });
        renderer.setSize(W, H);
        renderer.setPixelRatio(1);
        renderer.toneMapping = THREE.ACESFilmicToneMapping;
        renderer.toneMappingExposure = 1.1;

        var scene = new THREE.Scene();
        scene.background = new THREE.Color(0x030308);
        var camera = new THREE.PerspectiveCamera(50, W / H, 0.1, 100);
        camera.position.set(0, 0, 8);

        // YOUR SCENE SETUP HERE
        // - lights
        // - geometry
        // - materials

        // State proxy — GSAP animates this, render reads it
        var st = {
          rotY: 0,
          camZ: 8,
          // add your animated properties
        };

        var tl = gsap.timeline({ paused: true });

        // YOUR TWEENS HERE
        tl.to(st, { rotY: Math.PI * 2, duration: 10, ease: "none" }, 0);

        window.__timelines["BLOCKNAME"] = tl;

        function renderScene() {
          // Apply state to Three.js objects
          camera.position.z = st.camZ;
          // mesh.rotation.y = st.rotY;

          renderer.render(scene, camera);
        }

        // Render via onUpdate — NO requestAnimationFrame
        tl.eventCallback("onUpdate", renderScene);
        renderScene();
      })();
    </script>
  </body>
</html>

Replace checklist:

• BLOCKNAME → your block name (e.g., vfx-chrome-blob)
• Scene setup → your geometry, lights, materials
• State proxy → your animated properties
• Tweens → your animation timeline
• renderScene → apply state to your Three.js objects

---

registry-item.json Templates

For blocks:

{
  "$schema": "https://framevideo.chanjing.com/schema/registry-item.json",
  "name": "BLOCKNAME",
  "type": "framevideo:block",
  "title": "Human-Readable Title",
  "description": "One sentence: what it does and who uses it",
  "dimensions": { "width": 1920, "height": 1080 },
  "duration": 10,
  "tags": ["category", "subcategory"],
  "files": [
    {
      "path": "BLOCKNAME.html",
      "target": "compositions/BLOCKNAME.html",
      "type": "framevideo:composition"
    }
  ]
}

For components (no dimensions or duration):

{
  "$schema": "https://framevideo.chanjing.com/schema/registry-item.json",
  "name": "COMPONENTNAME",
  "type": "framevideo:component",
  "title": "Human-Readable Title",
  "description": "One sentence: what it does",
  "tags": ["category"],
  "files": [
    {
      "path": "COMPONENTNAME.html",
      "target": "compositions/components/COMPONENTNAME.html",
      "type": "framevideo:snippet"
    }
  ]
}

Tags by category:

• Captions: captions, viral, professional, karaoke, minimal
• VFX: three-js, particles, shader, gpu
• Transitions: transition, shader, wipe, dissolve
• Blocks: lower-third, social, title-card, data-viz
• Components: effect, overlay, text-treatment

---

Component Template

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      *,
      *::before,
      *::after {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      body {
        background: transparent;
        overflow: hidden;
      }
      .COMPNAME-wrap {
        position: absolute;
        inset: 0;
        overflow: hidden;
        pointer-events: none;
      }
    </style>
  </head>
  <body>
    <div class="COMPNAME-wrap">
      <!-- Your reusable effect/overlay here -->
    </div>
    <script>
      (function () {
        // Component snippet — no data-composition-id, no __timelines.
        // The parent composition controls timing.
        // Keep all class names and IDs prefixed with COMPNAME.
      })();
    </script>
  </body>
</html>

Replace checklist:

• COMPNAME → your component name (e.g., shimmer-sweep)
• Background should be transparent so it overlays cleanly
• No data-composition-id or window.__timelines — the parent owns timing