dsh-hyperframes 0.9.0 → 0.9.2

package/skills/hyperframes-keyframes/SKILL.md

@@ -1,264 +1,10 @@
 ---
 name: hyperframes-keyframes
-description: >
-  Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe,
-  Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe
-  2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths,
-  masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics.
-  Don't use for broad scene strategy, brand design, media sourcing, captions, or
-  general video planning.
+description: Compatibility entry for the retired hyperframes-keyframes skill; routes to the current official hyperframes skill.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+# hyperframes-keyframes: compatibility entry
 
-# HyperFrames Keyframes
+The current official HyperFrames release merged this workflow into the `hyperframes` skill. Load `hyperframes` from the DSH skill registry and follow its current instructions for the user's task. Use its bundled resources; do not reconstruct the retired workflow or download standalone skills.
 
-Keyframes are a pose contract: visible states, continuous subject identity, seek-safe runtime, verified pixels.
-
-Use `hyperframes-animation` for broad scene recipes. Use `hyperframes-cli` for full command docs. Use `references/keyframe-patterns.md` only when choosing implementation mechanisms, not visual style.
-
-## Creator editing boundary
-
-Keyframes own visual motion, not clip assembly. Source-range hard cuts, trim,
-splice, and reorder belong to `/hyperframes-core`: author one media element per
-kept range, place it with `data-start` and `data-duration`, and select its source
-offset with `data-media-start`. Adjacent ranges make a hard cut. A crossfade
-uses overlapping clips on different tracks plus visual opacity keyframes; sound
-fades use `/hyperframes-audio`.
-
-| Creator request                         | Truthful mechanism                                                                                                                                                                                                          |
-| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Punch-in / punch-out                    | Keyframe `scale` with `x`/`y` or percentage translation on a non-timed visual/crop wrapper inside the clip. Use a set/short tween for a hard punch and a tween for a smooth move.                                           |
-| Smooth multi-state zoom or reframe      | Keep one subject wrapper alive and author multiple zoom/reframe states as a pose ladder with per-segment easing.                                                                                                            |
-| Pan, reframe, or Ken Burns camera move  | Animate wrapper translation plus scale. Geometry is authored; this is not face tracking or automatic semantic reframing.                                                                                                    |
-| Chained camera moves                    | Chain labeled transform beats on one registered seek-safe timeline.                                                                                                                                                         |
-| Match cut or whip pan                   | `/hyperframes-animation` owns the visual handoff; `/hyperframes-registry` supplies primitives; keyframes preserve authored geometry, direction, and velocity. There is no automatic matching-frame discovery.               |
-| Crop and mask reframe                   | Interpolate `clip-path` or a mask on an inner visual wrapper to crop/reframe without changing source time. Polygon keyframes can form a polygon/mask transition.                                                            |
-| Directional wipe cut or iris/reveal cut | Animate a mask/clip boundary across overlapping visual clips; `/hyperframes-animation` owns the handoff choreography.                                                                                                       |
-| Split-screen handoff                    | Keep both visual clips placed by core, then keyframe their inner crop/mask wrappers and divider geometry.                                                                                                                   |
-| Constant source retime                  | `/hyperframes-core` owns normalized `data-playback-rate` (`0.1..10`) for render-safe picture and pitch-preserved sound. It is constant for the whole media element.                                                         |
-| Source speed ramps                      | A `rate` lane in `data-automation` on the `<video>`/`<audio>` (`t` in clip seconds, `v` 0.1..10, log interpolation); it wins over the constant rate.                                                                        |
-| Freeze / hold                           | A visual pose, final source frame, or finished sub-composition can hold. Arbitrary mid-source freeze is not supported; preprocess a still/derived segment, place it as its own clip, then resume with another source range. |
-
-When editing picture and sound together, load `/hyperframes-core`, this skill for
-visual motion, and `/hyperframes-audio` for fades, crossfades, volume automation,
-ducking/carve, or effects on the placed tracks.
-
-A visual transition or cropping treatment is not a temporal source trim or
-splice. `/hyperframes-core` owns the timeline, clip timing, and source ranges;
-keyframes only animate the visible handoff or crop on wrappers inside those clips.
-For copyable combined picture/sound recipes, use `/hyperframes-core` → `references/creator-editing-recipes.md`.
-
-## Procedure
-
-1. Identify the animated subject, visible states, final state, and runtime.
-2. Choose the smallest mechanism that proves the prompt. Read `references/keyframe-patterns.md` only if the mechanism is unclear.
-3. Author seek-safe keyframes in the declared runtime. Build synchronously and register the runtime instance.
-4. Verify with `hyperframes lint`, `hyperframes check`, `hyperframes keyframes`, one focused `--shot`, and snapshots at proof times.
-5. If proof fails, fix the source keyframes and rerun the smallest failing diagnostic before rendering.
-
-## Contract
-
-- Name the moving subject.
-- Name the poses needed to prove the intended motion, including the final state.
-- Keyframe visible channels, not hidden helper state.
-- Preserve object identity when continuity matters.
-- Crossfade only when the intended motion is replacement or dissolve.
-- Hold readable or semantic states long enough to see.
-- Final frame is part of the animation, not cleanup.
-- Do not reset to rest unless requested.
-- Do not end on black unless requested.
-- If editing a starter scene, preserve layout, copy, assets, colors, and final state unless asked to redesign.
-
-## Runtime Rules
-
-GSAP:
-
-- build synchronously at page load
-- use `gsap.timeline({ paused: true })`
-- register as `window.__timelines[compositionId]`
-- registry key must match `data-composition-id`
-- do not call `tl.play()` for render-critical motion
-- keep repeats finite
-
-CSS keyframes:
-
-- finite duration and iteration count
-- deterministic delay
-- `animation-fill-mode: both`
-- use `data-start` when timing belongs to a clip
-
-Anime.js:
-
-- create synchronously
-- `autoplay: false`
-- finite duration and loops
-- push every instance to `window.__hfAnime`
-
-WAAPI:
-
-- finite `duration`
-- `fill: "both"`
-- deterministic construction
-- the text surface does not list WAAPI; verify with `--shot` (it seeks WAAPI) and snapshots
-
-Never use for render-critical motion:
-
-- `Date.now()`
-- `performance.now()`
-- unseeded `Math.random()`
-- hover/scroll triggers
-- timers
-- async-created timelines
-- unregistered `requestAnimationFrame`
-- infinite loops
-
-## GSAP Skeleton
-
-```js
-const root = document.querySelector("[data-composition-id]");
-const compositionId = root.dataset.compositionId;
-const tl = gsap.timeline({ paused: true });
-
-tl.addLabel("state-a", 0);
-tl.to(".subject", {
-  keyframes: [
-    { x: 0, opacity: 1, duration: 0.2 },
-    { x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
-    { x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
-  ],
-  ease: "none",
-});
-
-window.__timelines = window.__timelines || {};
-window.__timelines[compositionId] = tl;
-```
-
-Use labels for semantic states. Use position parameters instead of chained delays. Use `immediateRender: false` for later `from()`/`fromTo()` tweens touching the same property.
-
-## Keyframe Forms
-
-- Array keyframes: pose ladder with per-step duration/ease.
-- Percentage keyframes: exact timing inside one tween.
-- Property arrays: compact multi-stop changes.
-- `ease: "none"` on the parent when each stop carries its own easing.
-- `easeEach` when every segment should share the same feel.
-
-Do not copy numeric distances or timing from examples. Derive them from the actual composition geometry and duration.
-
-For one subject moving between two boxes, prefer one continuous transform tween or FLIP. Split `x/y/scale` into multiple eased keyframes only when the viewer should feel distinct beats; every segment changes velocity and can read as a hitch.
-
-## Channels
-
-Prefer compositor/visual channels: `x/y/z`, `xPercent/yPercent`, `scale`, `rotationX/Y/Z`, `skew`, `transformOrigin`, `svgOrigin`, `opacity`, `autoAlpha`, `clip-path`, masks, CSS vars, SVG path/dash values, camera transforms, shader uniforms.
-
-Avoid layout/lifecycle channels: `top/left/right/bottom`, `width/height`, `margin/padding`, `display`, `visibility`, late DOM creation, helper overlays doing subject motion.
-
-For visibility changes, use `autoAlpha` on the registered seekable GSAP timeline, or a zero-duration `tl.set()` at an explicit boundary. Target only a non-clip element or a wrapper inside the clip; never target `.clip` itself. Never duration-tween raw `visibility`, and never tween `display`.
-
-## Mechanism Choice
-
-Choose the smallest mechanism that proves the prompt:
-
-| Need                                  | Mechanism                                          |
-| ------------------------------------- | -------------------------------------------------- |
-| Same subject changes box or hierarchy | shared element / FLIP                              |
-| Subject travels a visible route       | path travel                                        |
-| Stroke grows or traces                | stroke draw                                        |
-| Shape becomes another shape           | shape interpolation                                |
-| Reveal boundary is visible            | clip, mask, or shader uniform                      |
-| Many items move with order            | stagger / indexed delay                            |
-| Text itself moves                     | line, word, character, or band subdivision         |
-| Surface bends, stretches, or crops    | parent/child counter-transform                     |
-| UI has states                         | explicit state machine                             |
-| Scene has depth                       | DOM 3D, Three.js, or WebGL camera/object keyframes |
-
-Mechanisms can combine, but each one must clarify the idea. Decoration is not proof.
-
-## Timing
-
-- Anticipation only when it clarifies cause or direction.
-- Acceleration leaves rest.
-- Peak proof shows the mechanism unmistakably.
-- Follow-through sells energy and direction.
-- Overshoot only when the subject should feel elastic or tactile.
-- Constant-speed path travel usually needs `ease: "none"`.
-- Discrete UI states usually need a sharp ease-out.
-- Repeated elements need ordered offsets, not identical timing.
-- Final lockups need longer holds than transition poses.
-- Smoothness means continuous velocity on the same subject.
-- Do not overlap tweens that write the same transform property unless the overlap is intentional and verified.
-- Avoid animating large `clip-path`/mask changes while the same hero surface is also scaling or traveling; use nested reveals after the main move settles.
-
-## Text
-
-Preserve line boxes, word spacing, readability, and final fit. If text moves internally, move the glyphs or masked bands, not only decorations around the text. Snapshot readable frames.
-
-## SVG
-
-For stroke growth prefer `DrawSVGPlugin`, then `stroke-dasharray`/`stroke-dashoffset`. For shape interpolation prefer `MorphSVGPlugin`; convert primitives to paths when needed and split complex silhouettes into simpler parts.
-
-## 3D
-
-Scale alone is fake depth. Use perspective on a stable parent, `transform-style: preserve-3d`, z travel, rotation, camera/world motion, occlusion, and layer order when objects cross.
-
-Use one or two diagnostic angles that expose the depth relationship. If angled proof shows no depth crossing, improve z/camera/occlusion.
-
-## Canvas / WebGL
-
-Keyframe camera position, camera target, object transform, material opacity, shader uniforms, and postprocess intensity through deterministic state. Render from HyperFrames time. Use `--ghost` because marker boxes cannot see internal canvas motion.
-
-## CLI Proof
-
-```bash
-npx hyperframes lint
-npx hyperframes check
-npx hyperframes keyframes .
-npx hyperframes keyframes . --json
-npx hyperframes keyframes . --runtime all
-npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
-npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
-npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
-npx hyperframes snapshot . --at <times>
-```
-
-Choose `<selector>` for the real animated subject. Choose `<times>` for first frame, proof poses, final-minus-hold, and exact final. Choose `<angle>` only when depth must be proven.
-
-| Tool             | Proves                                                                                              |
-| ---------------- | --------------------------------------------------------------------------------------------------- |
-| `keyframes`      | targets, explicit stops, paths, traces, composed parent/child motion, CSS stops, Anime registration |
-| `--shot`         | ghosts, route shape, time spacing, DOM 3D projection, focused selector proof                        |
-| `--layout strip` | in-place motion, overlaps, contact, subtle scale/opacity, text waves                                |
-| `--ghost`        | canvas, WebGL, shader motion, rendered 3D                                                           |
-| `snapshot --at`  | masks, text readability, full state, final lockup, black/reset tails                                |
-
-If selector proof looks wrong:
-
-1. rerun `--json`
-2. find the actual animated target
-3. shoot that target
-4. snapshot full frames
-5. trust painted pixels over logs
-
-## Diagnostic Reading
-
-`flat` means no explicit middle poses. `keyframes` means explicit stops exist. `motionPath` means a route exists. `trace` means multi-stroke drawing. `composed with` means child motion inherits parent motion.
-
-Even ghost spacing means constant speed. Clustered ghosts mean slow-in or settle. Large gaps mean fast travel.
-
-A helper-selector shot is not proof. An onion shot over a broken full frame is not proof.
-
-## Error Handling
-
-| Failure            | Fix                                                                                |
-| ------------------ | ---------------------------------------------------------------------------------- |
-| endpoint-only      | add middle poses, hold peak proof, rerun `--shot`                                  |
-| identity break     | keep one element alive, use shared source/final boxes, remove substitute crossfade |
-| fake 3D            | add z/camera travel, occlusion, angled proof                                       |
-| wrong final        | add final hold, snapshot final-minus-hold and exact final                          |
-| unseekable runtime | pause autoplay, register instance, remove timers, build synchronously              |
-| unreadable text    | preserve line boxes, reduce displacement, add final hold, snapshot text frames     |
-
-## Done
-
-Run `hyperframes lint`, `hyperframes check`, `hyperframes keyframes`, one focused `--shot`, and snapshots. Confirm first frame, proof poses, final-minus-hold, exact final, subject-owned motion, and no debug overlays.
+For an existing project, preserve its files and dependencies. DSH plugin management owns this installed skill bundle. The upstream plugin launcher pins HyperFrames 0.8.207 and suppresses standalone skill installation; run it in the user's project directory. This entry preserves the previous DSH skill name while using the current workflow.

package/skills/hyperframes-registry/SKILL.md

@@ -1,147 +1,56 @@
 ---
 name: hyperframes-registry
-description: Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also 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).
+description: About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.
 
-# HyperFrames Registry
+# HyperFrames registry
 
-The registry provides reusable blocks and components installable via `hyperframes add <name>`.
+Starting from an item is faster and usually better than writing the effect yourself, and an installed item is ordinary source in your project: change it, cut it down, restyle it.
 
-- **Blocks** — standalone sub-compositions (own dimensions, duration, timeline). Included via `data-composition-src` in a host composition.
-- **Components** — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.
-
-## Quick reference
-
-```bash
-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`:
-
-```json
-{
-  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
-  "paths": {
-    "blocks": "compositions",
-    "components": "compositions/components",
-    "assets": "assets"
-  }
-}
-```
-
-See [install-locations.md](./references/install-locations.md) for full details.
-
-## Wiring blocks
-
-Blocks are standalone compositions — include them via `data-composition-src` in your host `index.html`:
-
-```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](./references/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](./references/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.
-
-```bash
-# 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:
+## Find and install
 
 ```bash
-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
+npx hyperframes catalog --query "<what the beat should do, in English>" --json
+npx hyperframes add <name> --json        # prints the written files and the mount snippet
 ```
 
-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`.
+- Query in English even when the video is not: the catalog is indexed in English, and another script returns `No searchable words in query`, which is not a gap.
+- Search is local and sends nothing. The default `words` tier only finds items that reuse your words; `--on-device` ranks by meaning after a one-time ~33 MB download. Offer that download and let the person decide; never enable it silently. The `--json` envelope names the tier that answered.
+- Narrow with `--type block|component` and `--tag <tag>`. `add <tag>` installs every block with that tag; dependencies install first. `add` needs the network even for an item installed before; search works offline from the cached manifest.
+- Nothing fits: report it before you hand-build, on either tier. `catalog --query` prints the line pre-filled (`report_gap` in `--json`): `npx hyperframes feedback --search-miss "<query>" --wanted "<the move you needed>" --tier <tier>`. Describe the effect, not an item name you imagined.
 
-### Report what the catalog does not have
+Tiers, `dropped` and `unindexed`, stale indexes, offline behaviour: `references/search.md`.
 
-When the search comes back and nothing in it does the job, say so before you hand-author the move:
-
-```bash
-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:
-
-```bash
-curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
-```
+## What's in it
 
-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.
+| Blocks: a scene with its own timeline | Examples |
+| --- | --- |
+| Transitions | `beat-freeze-cut`, `chromatic-radial-split`, `cinematic-zoom` |
+| Overlays and lower thirds | `camcorder-hud`, `editorial-flash-overlay`, `lt-clean-bar` |
+| Title cards and kinetic type | `canopy-part-title`, `code-slice-hero` |
+| Social, chat and UI cards | `ai-chat-reveal`, `chatgpt-exchange` |
+| Code, charts, data and maps | `code-diff`, `bar-chart-race`, `data-chart` |
+| 3D, shader and backgrounds | `app-showcase`, `aurora`, `blob` |
 
-**`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.
+| Components: a snippet merged into your scene | Examples |
+| --- | --- |
+| Motion primitives and text effects | `agent-cursor`, `blur-in`, `bottom-up-letters` |
+| Caption styles | `caption-clip-wipe`, `caption-editorial-emphasis` |
+| Camera moves | `camera-shake`, `camera-scan-gate` |
+| Product demo and UI props | `before-after-wipe`, `browser-device-stage` |
+| Textures, particles and effects | `ascii-render-pass`, `grain-overlay` |
 
-Each item's `registry-item.json` contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.
+## Wiring
 
-See [discovery.md](./references/discovery.md) for details on filtering by type and tags.
+- **Block**: installs to `compositions/<name>.html`. Mount it with `data-composition-src`, `data-composition-id` matching the block's own id, `data-start` and the `data-duration` you need; the snippet `add` prints is the starting point. `references/wiring-blocks.md`.
+- **Component**: installs to `compositions/components/<name>.html`. Copy its markup, `<style>` and script into your scene, and follow its comment block if it hooks into your timeline. `references/wiring-components.md`.
+- Take the largest unit that fits, then edit it. Keep an installed item's ids prefixed as they are, so two items can't collide.
+- An item keeps its own variables; set them for one mount with `data-variable-values` on its host (`add --vars '{"title":"…"}'` writes that), and point its colour and font variables at your brand's.
+- Beat-synced blocks take hit times from `npx hyperframes beats --json`: the beat times minus the mount's `data-start`.
+- Install paths come from `hyperframes.json` (`references/install-locations.md`).
 
-## Contributing a new block or component
+## Contributing
 
-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](./references/contributing.md). Copy-paste starter templates (caption / VFX / component / `registry-item.json`) are in [templates.md](./references/templates.md).
+Authoring a new block or component for an upstream PR: `references/contributing.md`, starter templates in `references/templates.md`, quality bar in `references/component-quality-bar.md`.

package/skills/hyperframes-registry/references/discovery.md

@@ -101,7 +101,7 @@ Showcase compositions grouping multiple CSS / GSAP transition styles by family.
 
 #### Liquid Glass (7)
 
-WebGPU + html-in-canvas frosted-glass surfaces. **Require Brave / Chrome canary** with WebGPU enabled — set `PRODUCER_HEADLESS_SHELL_PATH` to point at the browser; engine auto-passes `--enable-unsafe-webgpu`. See `/hyperframes-animation` → `adapters/typegpu.md`.
+WebGPU + html-in-canvas frosted-glass surfaces. **Require Brave / Chrome canary** with WebGPU enabled — set `PRODUCER_HEADLESS_SHELL_PATH` to point at the browser; engine auto-passes `--enable-unsafe-webgpu`. See `/hyperframes` → `references/runtimes.md`.
 
 | Name                        | Description                                                                             |
 | --------------------------- | --------------------------------------------------------------------------------------- |
@@ -113,7 +113,7 @@ WebGPU + html-in-canvas frosted-glass surfaces. **Require Brave / Chrome canary*
 
 #### VFX (6)
 
-HTML-in-canvas + WebGL composition blocks. See `/hyperframes-animation` → `adapters/three.md` and `adapters/html-in-canvas-patterns.md` for the underlying APIs.
+HTML-in-canvas + WebGL composition blocks. See `/hyperframes` → `references/runtimes.md` for the underlying runtimes.
 
 | Name                    | Description                                                                                             |
 | ----------------------- | ------------------------------------------------------------------------------------------------------- |

package/skills/hyperframes-registry/references/search.md

@@ -0,0 +1,67 @@
+# Searching the catalog
+
+How `hyperframes catalog` ranks, what its `--json` envelope means, offline behaviour, and reporting a miss.
+
+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.
+
+```bash
+# 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. The offline tier, the consent gate and refreshing a stale index are under "Search tiers" below.
+
+To browse or filter instead of search:
+
+```bash
+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:
+
+```bash
+npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>
+```
+
+`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:
+
+```bash
+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](./discovery.md) for details on filtering by type and tags.
+
+## Search tiers
+
+- **Search the catalog before writing motion by hand.** `npx hyperframes catalog --query "<the beat, in plain English>"`. Search is entirely local: there is no hosted tier, no account, and the query text is never sent anywhere. By default it ranks on vocabulary shared with the item's name, title, description and tags, which misses any phrasing that does not reuse the catalog's own wording. Add `--on-device` to rank by meaning instead (see the offline tier below).
+- **Query in English even when the video is not.** Both tiers index an English catalog, so a query in another script produces no searchable terms and returns nothing. Describe the move in English; the on-screen copy stays in whatever language the video needs. `No searchable words in query` means exactly this and is not a missing component, so do not report it as a catalog gap.
+- **Read which tier answered; never infer it from results appearing.** With `--json` the envelope carries `query`, `tier` (`on-device` or `words`), `tier_detail`, `dropped`, `unindexed`, `shown`, `total` and `results`, plus `top_score` when the answering tier produces one and `warnings` when a tier was asked for and could not run, or when a search returned nothing and a better tier is still waiting on someone's consent. A weak result on `words` is expected; the same result on `on-device` is a bug. `top_score` is on-device only and has no threshold behind it: the ranker returns the whole catalog in some order for every query, so read it as evidence rather than as a pass or fail.
+- **`dropped` and `unindexed` are opposite skews between the registry and the on-device index, and rewording the query fixes neither.** `dropped` counts ranked names this registry cannot install, so the strongest matches are the ones being lost. `unindexed` counts registry moves the index cannot see at all, which no query can ever return. Refreshing the registry is not the answer to either: its manifest carries a 24h TTL and heals itself, while the vectors are a separately published artifact fetched into `~/.hyperframes/catalog/`. Re-running with `--on-device` refetches that index when `unindexed` is above zero, so that is the remedy to hand the user. A pure over-coverage skew (`dropped` above zero while `unindexed` is zero) does not trigger the refetch; clearing `~/.hyperframes/catalog/` is the only way out of that one. Both counts are of names rather than of results, so either can exceed `total`.
+- **When a search comes back with nothing worth installing, say so.** `npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>`. You do not have to assemble that line: `catalog --query` prints it pre-filled, and every `--json` search envelope carries it as `report_gap` with the query and tier already correct — fill in `--wanted` and send. This is the only path that sends a query anywhere, and it is a separate deliberate command precisely so plain `catalog --query` keeps its promise of sending nothing. **Report on either tier**, whenever the results do not do the thing; do not hold out for the on-device tier, which needs a consented 33 MB download and is therefore off in most agent runs — waiting for it means never reporting at all. The tier rides along in the report, so a vocabulary miss stays distinguishable from a meaning miss without you having to judge which one you hit. What comes back is a list of moves the catalog does not have yet, read directly rather than guessed from install counts, so the phrasing that matters is the effect you wanted, not the item name you imagined. It carries no rating and never lands in the rating metric.
+- **Offer the offline tier; never enable it silently.** A one-time ~33 MB download (a quantized ONNX build of `bge-small-en-v1.5` plus its tokenizer, pinned to a fixed revision) and the catalog vectors from the registry, both cached under `~/.hyperframes/`, neither added to the project or any package. Once cached it ranks by meaning with nothing sent. Say the size out loud and let the person decide, then pass `--on-device` (with `-y` to skip the prompt) once they agree. The interactive offer only fires on a TTY. Under `--json` there is no prompt, but a search that found nothing puts the same ask in `warnings`, so read that array and put the decision to the user yourself. When the person asks what the download is, why this model, or what leaves the machine, point them to https://hyperframes.heygen.com/developers/catalog-search.

package/skills/hyperframes-studio/SKILL.md

@@ -1,77 +1,10 @@
 ---
 name: hyperframes-studio
-description: >
-  Use when building or editing a HyperFrames project that people open in
-  Studio: how the timeline should be laid out so it reads well (one caption
-  track, one element kind per track, every scene a sub-composition) and where
-  captions and key content may sit (safe zones). Don't use for how to perform an
-  individual edit (split, trim, retime, volume, copy, swap): that is
-  `creator-editing-recipes.md` in `/hyperframes-core`.
+description: Compatibility entry for the retired hyperframes-studio skill; routes to the current official hyperframes-cli skill.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+# hyperframes-studio: compatibility entry
 
-# HyperFrames Studio conventions
+The current official HyperFrames release merged this workflow into the `hyperframes-cli` skill. Load `hyperframes-cli` from the DSH skill registry and follow its current instructions for the user's task. Use its bundled resources; do not reconstruct the retired workflow or download standalone skills.
 
-Studio draws one timeline row per top-level element. A project that follows the
-rules below opens as a short, readable timeline; one that does not opens as a wall
-of unlabeled rows the user cannot edit. These are conventions for what to build.
-For how to change a clip, follow `/hyperframes-core` `references/creator-editing-recipes.md`
-and never invent a different form of the same edit.
-
-## 1. Every scene is a sub-composition
-
-The root composition holds only timed hosts, media and audio. Any scene with nested
-structure (a div containing children, a title with a subtitle, a chart) is its own
-file loaded with `data-composition-src`, wiring in
-`references/sub-compositions.md`.
-
-Nested markup left inside the root does not become a row of its own. It hides inside
-one opaque row that cannot be trimmed or moved part by part.
-
-Author as if a structure lint rejects any violation.
-
-## 2. One caption track
-
-- All captions live on one track: a single sub-composition host (one `data-track-index`)
-  marked `data-track-kind="captions"` that carries every caption group in order.
-- Never one row per caption group, and never captions mixed onto a track with
-  another kind.
-- Word-timing rules are unchanged: see `/embedded-captions` and the `caption_*` lint rules.
-
-## 3. One element kind per track
-
-Group by kind so each row is one thing the user can select, mute or drag as a set.
-
-| Kind                                    | `data-track-kind`      |
-| --------------------------------------- | ---------------------- |
-| Base video / A-roll                     | `video` (from the tag) |
-| Scenes, overlays, graphics              | `graphics`             |
-| Captions                                | `captions`             |
-| Audio (voiceover, music, sound effects) | `audio` (from the tag) |
-
-Put `data-track-kind` on sub-composition hosts. Video and audio kinds come from the tag, so
-`<video>` and `<audio>` need no attribute. Give each kind its own `data-track-index`; the number
-is display only; it never changes what renders on top. Use CSS for
-layering.
-
-## 4. Safe zones
-
-Any ruler or safe-box overlay lives in the preview pane, never inside the composition, so
-do not add guide elements to the HTML.
-Both framings (wide and vertical) use the same two safe boxes, Premiere's defaults. The preview
-toggle draws them with a tick at the midpoint of every edge. Source:
-`ACTION_SAFE_PERCENT` and `TITLE_SAFE_PERCENT` in `packages/studio/src/utils/previewSafeMargins.ts`.
-
-| Box         | Share of the frame | Inset on every edge |
-| ----------- | ------------------ | ------------------- |
-| Action-safe | 90%                | 5%                  |
-| Title-safe  | 80%                | 10%                 |
-
-- Safe margins: everything visible stays inside the action-safe box (90%), and captions and key content stay inside the title-safe box (80%).
-- Two-up and 50/50 layouts keep each half's content inside the title-safe box.
-
-## Checking your work
-
-Run `hyperframes lint` and fix every finding. Then open the project in Studio and
-check that the timeline shows a base row, one row per scene host, one caption row and the audio rows.
+For an existing project, preserve its files and dependencies. DSH plugin management owns this installed skill bundle. The upstream plugin launcher pins HyperFrames 0.8.207 and suppresses standalone skill installation; run it in the user's project directory. This entry preserves the previous DSH skill name while using the current workflow.