Miguel Ángel
6b17c24f98
* fix(catalog): rank on where a word appears and how rare it is Word search returned the right move in the top three for 87% of a 39-query eval set built from real catalog intents. Three defects, all in the same 75-line scorer, and all found by running the queries rather than by reading the code. A token matching an item's NAME counted exactly as much as one buried in a description. Searching "typewriter effect on a title" ranked the item literally called `typewriter` seventh, behind entries that merely mention typing. Name and title now carry three times the weight: an author who types a move's name is giving the strongest signal available and it was being averaged away. Plurals shared no vocabulary with the singular. "a stat that counts up and then pulses once" matched nothing in a description reading "lands with a restrained scale pulse", because `counts` is not `count`. Adding detail to a query made results strictly worse, which is the opposite of what a search should do. Plurals now fold, and only plurals: Porter would fold `counter` to `count` and `values` to `valu`, merging moves that mean different things. Field weighting alone made one case worse, which is why inverse document frequency is here too. "reveal a headline one line at a time" put every item merely NAMED `*-reveal` on top, because one strong hit on the catalog's most common word outscored several weak hits on the words that actually narrowed it down. Rarity now scales each term. Separately: a query in a script this ranker cannot index no longer reports itself as an empty catalog. Tokenising on [a-z]+ leaves nothing of a Japanese query, and returning "no items match" told the author the catalog lacked a move it may well have, then invited them to file a gap report about it. That case now says what actually happened and withholds the gap prompt, since nothing was searched. Measured on the same 39 queries, before and after: top-1 31/39 (79%) -> 33/39 (85%) top-3 34/39 (87%) -> 39/39 (100%) Test plan: 13 new tests, each a real failing query reduced to the smallest fixture that still reproduces it. Existing tests migrated to the fields API (two callers total). Full CLI suite 2643 passed, 2 pre-existing transcribe failures unchanged. Verified against the real CLI: "typewriter effect on a title" now returns typewriter first, and "chat conversation between a user and an assistant" returns chat-message, chat-thread, ai-chat-reveal instead of transitions-blur. * docs(skills): say to query the catalog in English The runtime message added alongside this explains an unsearchable query after the fact. Saying it up front is cheaper: an agent that never writes the query in Japanese never sees the error, never wastes the turn, and never files a gap report about a component that exists. Worth stating rather than assuming, because the mistake is a reasonable one. On a Japanese or Chinese project the brief, the narration and the captions are all in that language and the query naturally follows. The rule is that the query language and the video language are unrelated: describe the move in English, write the on-screen copy in whatever the video needs. Both skills that own `catalog --query` carry it, and those are the only two that mention the command at all. * fix(catalog): fail a non-English query instead of returning nothing The message explaining an unsearchable query went to stdout and the command exited 0. An agent that checks the exit code, which is most of them, read that as "searched successfully, the catalog has nothing" and went off to hand-author a move that is sitting in the registry. The explanation only helped a human who happened to be reading the terminal. It is bad input, not an empty shelf, so it now behaves like one: the guidance goes to stderr and the command exits 1, matching what an invalid --type already does. A genuine empty result, where the query parsed fine and the catalog simply has nothing, still exits 0 -- that distinction is the whole point, and both halves are pinned by tests. The wording now also says what to do rather than only what happened: search in English, and let the on-screen copy of the video stay in whatever language it needs. That was the part agents were getting wrong, since a Japanese project makes a Japanese query feel natural. Test plan: 3 new tests covering the exit code, the wording, and the genuine-empty case that must stay at 0. Also asserts the gap-report line is absent, since nothing was searched and a report there is noise in the one signal that tells us what to build. catalog.test.ts 32 passed; commands + registry suites 887 passed with the 2 pre-existing transcribe failures unchanged. Verified against the real CLI: a CJK query exits 1, a genuine miss exits 0.
9.0 KiB
name, description
| name | description |
|---|---|
| hyperframes-registry | Install, discover, and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR). |
HyperFrames Registry
The registry provides reusable blocks and components installable via hyperframes add <name>.
- Blocks — standalone sub-compositions (own dimensions, duration, timeline). Included via
data-composition-srcin a host composition. - Components — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.
Quick reference
hyperframes add data-chart # install a block
hyperframes add grain-overlay # install a component
hyperframes add captions # install every block tagged captions
hyperframes add shimmer-sweep --dir . # target a specific project
hyperframes add data-chart --json # machine-readable output
hyperframes 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.
The positional value is resolved as an exact item name first. If no item matches and the value is a tag, the command installs every block with that tag. Registry dependencies are installed before the requested item. hyperframes add works only for blocks and components; for examples, use hyperframes 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 hyperframes.json:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/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 filedata-composition-id— must match the block's internal IDdata-start— when the block appears in the host timeline (seconds)data-duration— how long the block playsdata-width/data-height— block canvas dimensionsdata-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):
- Read the installed file (e.g.,
compositions/components/grain-overlay.html) - Copy the HTML elements into your composition's
<div data-composition-id="..."> - Copy the
<style>block into your composition's styles - Copy any
<script>content into your composition's script (before your timeline code) - 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
Use the CLI as the primary discovery surface. Search by intent before browsing: the registry holds more items than you can scan by eye, so listing them and matching on names or tags is the slow path, and it fails whenever the author's wording differs from yours.
# Rank the whole catalog against what the beat should do
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
Search is local and sends nothing. By default it ranks on vocabulary shared with the item's name, title and description, so it only finds items that reuse your words; --on-device ranks by meaning instead, after a one-time model download. With --json the envelope names which tier answered, so check that rather than assuming a ranking happened.
Always query in English, whatever language the video is in. The catalog is written in English and both tiers index it that way (the on-device model is English-only too). A query in another script produces no searchable terms and returns nothing at all. This is easy to get wrong on a Japanese or Chinese project, where the brief, the captions and the narration are all in that language and the query naturally follows: describe the move in English, then write the on-screen copy in whatever language the video needs. If a query does come back with No searchable words in query, that is this rule, not a missing component, and it is not worth a gap report.
Installability is applied after ranking, not before it: a name the vectors carry but this registry cannot serve is dropped from the results and counted in dropped, so a non-zero dropped means the two are different generations. See /hyperframes-cli for the offline tier, the consent gates, and how to refresh a stale index.
To browse or filter instead of search:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
The normal table and --json modes only list matches; install a selected name with hyperframes add <name>. --human-friendly opens an interactive picker and installs the selected item immediately. In CI or agent workflows, prefer --json followed by an explicit add.
Report what the catalog does not have
When the search comes back and nothing in it does the job, say so before you hand-author the move:
npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier on-device
catalog --query prints this line for you, pre-filled, and --json carries it as report_gap — so it is already in hand at the moment you decide nothing fits.
Report whenever nothing in the results does the job, on either tier. Do not wait for the on-device tier to have answered: it needs a consented 33 MB download, so an agent run is on words unless it explicitly opted in, and gating on on-device would silence almost every report. The --tier value rides along so a vocabulary miss stays distinguishable from a meaning miss when these are read. Describe the effect you wanted, not the item name you imagined: what comes back is a list of moves worth building, and a report naming a non-existent item teaches nothing. This is the only path that sends a query anywhere, which is exactly why it is a separate deliberate command rather than something the search does on its own. It carries no rating and never lands in the rating metric.
This is the whole demand signal for the catalog. Skipping it means the gap you hit gets guessed at from install counts instead, which cannot see a move nobody could install.
If the CLI cannot reach the configured registry, inspect the raw manifest as a fallback:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
A registry the CLI cannot reach does not empty the catalog for discovery: a previously fetched manifest keeps serving past its 24h refresh window whenever revalidation fails, so catalog and catalog --query still list and rank against the last copy on disk.
add still needs the network, even for an item you installed yesterday. Only manifests are cached; the item's actual files are fetched on every install. So offline you can search, and you can see what an item is, but installing it fails at the file fetch. Do not promise a user an offline install.
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.
Contributing a new block or component
To author a NEW registry item (caption style, VFX block, transition, lower third, or a reusable component) and ship it as an upstream PR — not install an existing one — follow the full idea → scaffold → build → validate → preview → ship workflow in contributing.md. Copy-paste starter templates (caption / VFX / component / registry-item.json) are in templates.md.