HyperFrames Registry

The registry is a public catalogue of about 400 ready-made HyperFrames items: blocks (whole scenes with their own size, length and timeline) and components (effect snippets you merge into a scene you already have). Work reuse first: rank the whole catalogue against what the beat must do, install the best fit with one command, wire it so it plays at the right second, size and layer, and prove it with lint and frames. Hand-build a look only after an honest search came up empty, and say so in your hand-off.

When to use

• A brief, a storyboard or the owner names a look: "add CRT scanlines", "glitch the cut", "film grain over everything", "a shimmer across the title", "chromatic aberration", "a light leak".
• A beat needs a ready-made object: "a bar chart of these numbers", "a terminal typing this command", "a map of the flight", "confetti when the counter lands", "an X post card", "a subscribe lower third", "karaoke captions".
• Someone mentions hyperframes add, hyperframes catalog, "install every caption block", or hyperframes.json.
• An installed item does not show, plays at the wrong time, renders black or sits behind the wrong layer.
• The owner wants a look of their own kept for reuse ("make this our house lower third"): author it as a local block or component (Method step 8).

What you need

• Node 22+ and FFmpeg on your computer. Run the check in references/computer-setup.md first, every time: they are not installed by default, and anything installed outside /home/user is gone after a rebuild. Every command below assumes the environment line from step 4 of that file:

  export PATH="$HOME/.local/node/bin:$PATH" HYPERFRAMES_NO_TELEMETRY=1 HYPERFRAMES_SKIP_SKILLS=1
  

• A HyperFrames project in ~/Desktop/<your name> - Work space/<job>/<project>/ (made with npx hyperframes init), or its path to pass with --dir.
• Network for add: item files are fetched on every install. Search still works offline from the cached manifest.
• What the beat must do in plain words, plus its start time, length, and where on screen it sits. If the brief names a look but not the moment, ask with clarify.
• The composition contract (clip timing, sub-compositions, z-index): load hyperframes-core with skill_view when unsure.

Blocks and components

Kind	What it is	Installs to	How it enters the video
Block (hyperframes:block)	A standalone composition: own dimensions, duration and paused GSAP timeline registered on window.__timelines	compositions/<name>.html	A host <div> with data-composition-src
Component, snippet shape (hyperframes:component)	HTML, CSS and optional JS with no size or length of its own	compositions/components/<name>.html	Pasted into a scene: markup, styles, setup script, then the timeline call from its header
Component, self-mounting shape	A component file that (comments stripped) contains its own data-composition-id and timeline	compositions/components/<name>.html	Mounted like a block, never pasted
Example (hyperframes:example)	A whole starter project	not installable with add	npx hyperframes init <dir> --example <name>

Method

1. Search by intent before anything else. The catalogue is too big to scan by eye, and matching on names fails whenever the author worded it differently from you.

   npx hyperframes catalog --query "old TV scanlines rolling over footage" --json
   

   • Always query in English, whatever language the video is in: the catalogue and both search tiers are English. A query in another script yields No searchable words in query, which means exactly this, not a missing item. Describe the move in English; on-screen copy stays in the video's language.
   • Describe the effect, not an item name you imagine. Try two or three phrasings (the look, the technique, the feeling: "CRT scanlines", "retro monitor", "VHS").
   • The default tier (words) ranks on vocabulary shared with each item's name, title, description and tags. --on-device ranks by meaning: a one-time download of about 33 MB (a small English embedding model plus the catalogue vectors) cached under ~/.hyperframes/, which sends nothing anywhere. It is fine on your own computer: add --on-device --yes. Use it whenever words comes back weak.
2. Read the envelope, not just the list. The --json result carries tier (words or on-device), tier_detail, shown, total, results, top_score (on-device only, no threshold behind it: evidence, not a verdict) and warnings. A weak list on words is expected; the same on on-device is a real miss. dropped counts ranked names this registry cannot install, unindexed counts registry items the index cannot see; rewording fixes neither. Re-running with --on-device refetches the index when unindexed is above zero; when only dropped is above zero, clear ~/.hyperframes/catalog/. For each candidate, read its registry-item.json (description, dimensions, duration, registryDependencies, declared variables) and pick by: does it promise this move, does its size match the project (1920x1080 or 1080x1920), does its length cover the beat. Details: references/discovery.md.
3. Install with add.

   npx hyperframes add data-chart --no-clipboard --json
   

   • The name is matched as an exact item name first. If no item has that name and it is a tag, add installs every block with that tag (captions, html-in-canvas): read the written list.
   • Registry dependencies install before the item. --dir <project> targets another project. --json prints the written files and the include snippet. Always pass --no-clipboard: your computer is headless and the clipboard copy helps nobody.
   • --vars '<json>' bakes variable values into the printed snippet (only for the item you named, not its dependencies).
   • Re-running add keeps any file you have edited since installing (hashes live in hyperframes.lock.json); --force overwrites those edits.
   • The printed snippet is a starting point. For a block you still set data-start, data-duration, the size and the layer. Paths follow hyperframes.json#paths: references/install-locations.md.
4. Wire a block into the scene that hosts it:

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

   • data-composition-id must equal the block's internal data-composition-id and its window.__timelines key. Read it from the installed file; never rename the slot. A mismatch makes the render wait 45 s per slot, then capture frozen frames.
   • data-start is seconds on the host timeline. data-duration is the slot's visible window: if the block's own timeline ends first, the slot holds its last frame; a full-bleed block shorter than the host leaves a blank tail (subcomposition_blanks_before_host).
   • data-width / data-height match the block's dimensions. Place and size the slot with CSS on the host <div>.
   • Front and back are CSS z-index. data-track-index is only the lane the clip sits in on Studio's timeline; the render never reads it, and clips on one lane may overlap. Give each kind of element its own lane for readability (see hyperframes-studio).
   • Never add the block's timeline to the host's GSAP timeline: the runtime seeks it in sync, and nesting it double-seeks. Full rules: references/wiring-blocks.md, worked example references/example-add-block.md.
5. Wire a component. Open the installed file and read its comment header (usage, what to customise, Timeline integration:). Strip the comments mentally: if a data-composition-id remains, it is self-mounting, so mount it like a block (inlining it nests a document and renders black). Otherwise paste it into the scene's own composition file: markup inside the root, the <style> into the scene's styles, any setup <script> before your timeline code, then the timeline call from the header at the moment the beat needs it. A snippet with a Timeline integration: recipe renders a still frame until you add that call. Layer it with z-index. Pasting nested markup straight into the root index.html draws the nested_structure_needs_subcomposition warning; put it in a scene sub-composition. Details: references/wiring-components.md, references/example-add-component.md.
6. Prove it on your own computer.

   npx hyperframes lint
   npx hyperframes check
   SNAP=$(mktemp -d); npx hyperframes snapshot --at 2.5,6,12 --no-end --describe false -o "$SNAP"; ls "$SNAP"
   

   Look at the PNGs with vision_analyze (batch them into one contact sheet): the item appears at its time, at the right size, on the right layer, legible. lint must show 0 errors.
7. When nothing fits, say so and build it yourself. Never run npx hyperframes feedback --search-miss, and ignore the pre-filled report_gap line the search prints: it sends your query to the CLI's maker. Instead, record in your hand-off the queries you ran (with the tier), the nearest candidates and why each was rejected. Then hand-build the move following hyperframes-animation (motion) and hyperframes-core (structure), and consider shaping it as a local item if the owner will want it again.
8. Author a new item locally by default. Build it as a block or component in the owner's project, or in a reusable library folder in your work space (~/Desktop/<your name> - Work space/hyperframes-library/<blocks|components>/<name>/), with the same structure, templates, quality bar and validation as the registry. To use a library item, copy its file to the path add would have used. Contributing it upstream to the open-source repository is optional, public and external: do it only with the owner's explicit go-ahead, through the owner's GitHub account in your browser or a connected GitHub app. Steps: references/authoring.md, starters: references/templates.md, bar: references/component-quality-bar.md and references/placeholder-material.md, demo convention: references/demo-html-pattern.md.

Commands at a glance

npx hyperframes catalog --query "<the move, in English>" --json      # rank everything (words tier)
npx hyperframes catalog --query "<the move>" --on-device --yes --json # rank by meaning (one-time ~33 MB)
npx hyperframes catalog --type block --tag social --json              # browse with filters
npx hyperframes add grain-overlay --no-clipboard --json               # one component
npx hyperframes add captions --no-clipboard                           # every block tagged captions
npx hyperframes add shimmer-sweep --dir . --no-clipboard              # target a project
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json  # raw manifest

--human-friendly opens an interactive picker that installs the moment you choose: do not use it. Use --json, choose, then run an explicit add.

Offline and special cases

• Offline: a manifest fetched before keeps serving past its 24 h refresh whenever revalidation fails, so catalog and catalog --query still list and rank. add still needs the network, even for an item installed yesterday: only manifests are cached, item files are fetched on every install. Never promise the owner an offline install.
• CLI cannot reach the registry: read the raw manifest with the curl line above; each item's manifest sits at <registry>/<blocks|components|examples>/<name>/registry-item.json.
• Liquid Glass blocks (ios26-liquid-glass, macos-tahoe-liquid-glass, liquid-glass-widgets, liquid-glass-notification, vfx-liquid-glass) need WebGPU: a Chrome build with WebGPU enabled, pointed to with PRODUCER_HEADLESS_SHELL_PATH (the engine adds --enable-unsafe-webgpu itself). On a cloud Linux computer without a GPU expect them to fail or render very slowly. Say so before offering one, and offer a non-WebGPU alternative.
• Shader transitions: use at most two per video. The block name is not the shader name (domain-warp-dissolve wraps a shader without the suffix): read the showcase HTML installed with the block for the real name.
• Transition galleries (transitions-*) are references for picking a CSS scene transition, not something to embed as is.
• Bundled sound: some showcase blocks ship sound effects. Before they reach the owner's video, find each sound file's licence in the repository, confirm it allows commercial use and record it in assets/LICENSES.md; otherwise remove or mute it (see media-use for licensed sources).

Output

• The project with the item installed and wired, lint at 0 errors, check passing, and frames you have looked at.
• A short note in your hand-off: each item used (name, block or component), the query and tier that found it, where it plays (start, duration, layer), what you customised; anything the catalogue did not have and what you built instead; any WebGPU or licence caveat.
• For a new item: its folder path, registry-item.json, the lint and check results, key frames and a draft MP4 attached with MEDIA:/absolute/path. For an upstream contribution, the pull request link once the owner has approved it.

Checks before you finish

• The query was in English, ran with --json, and you read tier, dropped and unindexed.
• Every block slot's data-composition-id equals the file's internal id and its __timelines key.
• No front-or-back expectation rests on data-track-index; layering is set with z-index.
• Each slot's data-start and data-duration cover the beat with no unintended blank tail.
• Every snippet's Timeline integration: call is in your timeline; its classes and ids are unchanged; no self-mounting component was pasted inline.
• npx hyperframes lint reports 0 errors and you looked at snapshots with vision_analyze.
• You did not run feedback, publish or --human-friendly, and nothing upstream happened without the owner's yes.
• Kill any preview server or browser you started (pkill -f "hyperframes preview").

Pitfalls

• Hand-building a named look without searching. Many looks already exist, tested and seek-safe. Search first, every time.
• Treating the sample tables as the catalogue. They cover a fraction by design. Only an empty search (on both tiers) is evidence the registry lacks something.
• Renaming the slot (chart-mount for data-chart). The host id is the lookup key; a mismatch passes lint and fails at render.
• Layering with track numbers. Track 5 is not in front of track 1. Use z-index.
• Pasting a self-mounting component inline. It renders black and looks like a dead item. Mount it with data-composition-src.
• Forgetting the snippet's timeline call. The effect sits still and you blame the item.
• A tag where you meant a name. add captions installs every caption block. Check the written list and delete what you will not use.
• --force on an edited item silently throws away your customisation.
• Promising Liquid Glass, or an offline install. Both fail on a typical cloud computer; say so up front.
• Sending a gap report. It shares the query with the CLI's maker. Note the gap for the owner instead.

References

• references/computer-setup.md: Node, FFmpeg, the render browser, the environment line, what never to run.
• references/discovery.md: search tiers, browsing, the raw manifest, item fields, the sample item tables.
• references/install-locations.md: default paths, hyperframes.json remapping, the install record.
• references/wiring-blocks.md and references/wiring-components.md: every attribute and both component shapes.
• references/example-add-block.md and references/example-add-component.md: worked examples.
• references/authoring.md, references/templates.md, references/demo-html-pattern.md: making a new item, local or upstream.
• references/component-quality-bar.md and references/placeholder-material.md: what a good item is, and how to audit one.
• references/CREDITS.md: origin, licence and what we changed.