framevideo-registry

FrameVideo Registry

When To Use

Use this skill for:

• Installing blocks — framevideo add <block-name> to install reusable compositions
• Installing components — framevideo add <component-name> for effect snippets
• Wiring blocks — integrate installed blocks into host composition
• Merging components — paste component snippets into existing HTML
• Registry discovery — find available blocks/components
• Configuration — manage framevideo.json registry settings

Do NOT Use

Avoid this skill for:

• Example templates — use framevideo init --example <name> instead
• Writing custom compositions — use framevideo skill
• Asset preprocessing — use framevideo-media
• CLI commands (init, render, etc.) — use framevideo-cli

---

Quick Start

Install and wire a block

# 1. Install block
npx framevideo add data-chart

# 2. Wire into host composition (index.html)
<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="5"
  data-track-index="3"
></div>

Install and merge a component

# 1. Install component
npx framevideo add grain-overlay

# 2. Copy snippet from CLI output
# 3. Paste into your composition HTML
# Component snippets merge directly into HTML (no data-composition-src)

---

Block vs Component

Type	Description	Install location	How to use
Block	Standalone sub-composition	compositions/<name>.html	Include via data-composition-src
Component	Effect snippet	compositions/components/<name>.html	Paste directly into HTML

---

When to use this skill

• User mentions framevideo add, "block", "component", or framevideo.json
• Output from framevideo add appears in the session (file paths, clipboard snippet)
• You need to wire an installed item into an existing composition
• You want to discover what's available in the registry

Quick reference

framevideo add data-chart              # install a block
framevideo add grain-overlay           # install a component
framevideo add shimmer-sweep --dir .   # target a specific project
framevideo add data-chart --json       # machine-readable output
framevideo add data-chart --no-clipboard  # skip clipboard (CI/headless)

After install, the CLI prints which files were written and a snippet to paste into your host composition. The snippet is a starting point — you'll need to add data-composition-id (must match the block's internal composition ID), data-start, and data-track-index attributes when wiring blocks.

Note: framevideo add only works for blocks and components. For examples, use framevideo init <dir> --example <name> instead.

Install locations

Blocks install to compositions/<name>.html by default. Components install to compositions/components/<name>.html by default.

These paths are configurable in framevideo.json:

{
  "registry": "https://raw.githubusercontent.com/chanjing/framevideo/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

See install-locations.md for full details.

Wiring blocks

Blocks are standalone compositions — include them via data-composition-src in your host index.html:

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

Key attributes:

• data-composition-src — path to the block HTML file
• data-composition-id — must match the block's internal ID
• data-start — when the block appears in the host timeline (seconds)
• data-duration — how long the block plays
• data-width / data-height — block canvas dimensions
• data-track-index — layer ordering (higher = in front)

See wiring-blocks.md for full details.

Wiring components

Components are snippets — paste their HTML into your composition's markup, their CSS into your style block, and their JS into your script (if any):

1. Read the installed file (e.g., compositions/components/grain-overlay.html)
2. Copy the HTML elements into your composition's <div data-composition-id="...">
3. Copy the <style> block into your composition's styles
4. Copy any <script> content into your composition's script (before your timeline code)
5. If the component exposes GSAP timeline integration (see the comment block in the snippet), add those calls to your timeline

See wiring-components.md for full details.

Discovery

Browse available items:

# Read the registry manifest
curl -s https://raw.githubusercontent.com/chanjing/framevideo/main/registry/registry.json

Each item's registry-item.json contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.

See discovery.md for details on filtering by type and tags.