mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-07 10:06:21 +00:00
WaterrrForever
b9be0b2625
* feat(studio,cli): per-frame board comments, self-refreshing storyboard, status-aware preview landing Per-frame comment boxes on the storyboard board batch into .hyperframes/frame-comments.json (a resubmit wins per frame; unconsumed comments on other frames are kept). Submitted-but-unconsumed comments stay visible — a toolbar banner plus a per-tile echo — until the agent consumes the file; the banner also says what to do next (reply anything in the agent chat). The board keeps itself current: GET /projects/:id/signature exposes the watcher-cached project signature, the storyboard payload carries the signature it was derived from, and the view polls at 2s (hidden tabs skipped, re-checked on visibility), refetching in place with no loading flash. Posters bake the signature into their URL so tiles fill in as sketches land and a poster that failed mid-write retries on the next version; the empty state upgrades itself when STORYBOARD.md appears, and its handoff prompt now points the agent at the review loop and uses the parser's real status vocabulary (outline, not planned). preview lands the browser on the storyboard view while the board is the review surface — any frame built, or pure planning (srcs declared, none on disk yet) — and on the timeline once the video is assembled. * feat(skills): the review loop — plan, sketch, build as one shared process hyperframes-core/references/review-loop.md is the single source for the three-pass collaborative review: the plan proposed on a live board (§ 1), wireframe sketches marked built with one layout question (§ 2 — real words on plain blocks, run no CLI; a confirmed board is itself a valid deliverable when the user asked for a storyboard, not a video), the build dressing confirmed layouts (§ 3, worker or inline), and the final look (§ 4). Autonomous runs skip every gate and keep one question before render. The three narrative workflows' Steps 3/4/6 collapse to references plus their sketch stand-ins (captured-asset blocks for product-launch-video, plain code panels for pr-to-video); the confirmed-sketch handoff stays in each frame-worker prompt. general-video plans on a board for multi-scene narrative pieces in collaborative mode — its sketch pass is layout-before-animation with the user watching. The router treats "I want a storyboard" as a process request rather than a route, and closes exploratory intake by recommending a route plus how the run will review. The supporting contracts land next door: the comments channel (silent submit, one reply picks it up, check the file before the words) in brief-contract § 1; the sidecar schema and the built status rung in storyboard-format; the mode question asked first and alone in the three workflows' Step 0. * feat(media-use): user memory — remembered preferences and frozen recipes Two tiers of memory on media-use's existing two-tier storage split. Preferences (lightweight): confirmed brief answers — destination, aspect, language, mode, voice, style preset — recorded to the project's .media/preferences.json (committed, the team inherits it) and promoted to the personal ~/.media/preferences.json once the same value is confirmed in two different projects (a sightings ledger accumulates the cross-project evidence user-side, since project files can't see each other). prefs.mjs get/record; merge reads project-over-user; a changed value restarts its provenance. Recipes (heavyweight): one approved run frozen as a named, versioned bundle — frame.md, the storyboard skeleton (structure kept: durations, transitions, srcs, Video direction; statuses reset to outline; content blanked to per-frame fill-ins naming the beat's role), and the confirmed brief values. Named folders, not content hashes: re-freezing bumps version and archives <name>@v<N>; a freeze is already confirmed, so it promotes to the user tier immediately. recipe.mjs freeze/list/use, plus resolve --type recipe --entity <name> delegating like grade/lut. 16 new node --test cases; the media-use lib suite is 168/168. * feat(skills): wire user memory into the brief and the review loop brief-contract § 2 gains Remembered defaults: read the merged preferences before Round 2 and let a remembered value become the recommended option with a receipt naming its source project. Memory changes the default, never the question — every ask-marked field still gets asked, and what the request says this time beats what was picked last time. Record only what the user actually confirmed (a defaulted voice nobody chose is not an answer; a "go" that accepts the recommended defaults is). The first record announces itself once; after that the receipts carry the reminder. In autonomous mode a remembered value becomes the decided value, receipt included. The three narrative workflows read the remembered defaults before Round 2, record the confirmed answers at the Step 0 gate, record the chosen preset at the Step 2 gate (pr-to-video excepted — its preset is fixed), and fall back to the remembered voice when the request names none. general-video's discovery reads the same defaults. Recipes wire in at both ends: Step 0 checks for a matching recipe before the mode question — one question, plural-aware, and adopting one fills the brief, skips the design step, and drafts the storyboard from the frozen skeleton while every review gate still runs. The review loop's final look (§ 4) offers the freeze once after approval, and the confirmation teaches the recall phrase — the name is something the system reminds the user of, never something they must remember. The router recognizes a named recipe or "like last time" as a route. * docs(skills): the sketch pass names check, not the deprecated validate * feat(skills): intent-layer references — process, route briefs, capability menu, BRIEF.md format * feat(media-use): brief skeleton as the recipe's fourth artifact; flow/storyboard preference keys * feat(skills): the intent layer conducts every brief — workflows execute BRIEF.md * feat(skills): retire the mode preference key; sync catalog surfaces for intent layer * refactor(skills): dedupe router vs intent-layer guidance — one owner per rule * feat(skills): the design ask — own spec, pick by eye from showcases, or defer * docs(skills): the design ask says the honest line on capture routes * feat(skills): product-launch-video absorbs website-to-video as the tour angle * refactor(skills): keep product-launch-video pristine — a tour is brief intent, not a pipeline branch * feat(skills): production loop + genre lenses; general-video goes freeform (route yours, laws hold) * refactor(skills): /hyperframes is the front door - route tables and scope lists leave the workflows * docs(skills): review-loop pass across skill catalog * fix(cli): pass project dir to openStudioBrowser in background-server path * feat(skills): add pitch-round reference - verbalized sampling concept gate * feat(skills): wire pitch round into intent layer - completeness triage + route eligibility * feat(skills): editorial capability recommendations, handoff disciplines, menu-probe split * feat(skills): pitches carry their machinery; source-only-formed requests pitch the telling * feat(skills): companion goes director - ceiling treatment plus blueprint/rule citation discipline * fix(scripts): sandbox npx-leak guard - private npm global prefix keeps npx on the branch CLI * chore(skills): resync manifest hash after formatter pass reflowed general-video tables * fix(skills): recipe freeze reads workflow from BRIEF.md; style_preset records require workflow scope Two holes found by a live companion-run freeze: the agent-supplied --workflow contradicted the run's actual workflow (recipe.json said faceless-explainer, brief-skeleton said general-video), and the style_preset lookup missed because the preference had been recorded under the bare key. - freezeRecipe resolves the workflow from BRIEF.md frontmatter; the flag is a fallback for briefless projects and a contradicting flag is ignored (noted). - recordPreference refuses a bare style_preset — the scoped key is the only writable shape; freeze tolerates legacy bare records via read fallback. - review-loop § 4 / media-use SKILL / brief-format wording follow the machinery.
232 lines
18 KiB
Markdown
232 lines
18 KiB
Markdown
# Registry discovery
|
||
|
||
## Use the catalog command first
|
||
|
||
```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
|
||
```
|
||
|
||
- Default output is a readable table. It does not install anything.
|
||
- `--type` accepts `block` or `component`; `--tag` may narrow either result.
|
||
- `--json` is the deterministic agent and CI surface. Select a name, then run `npx hyperframes add <name>`.
|
||
- `--human-friendly` opens a picker and installs the selected item immediately.
|
||
|
||
## Read the registry manifest as a fallback
|
||
|
||
When the CLI is unavailable, the top-level `registry.json` lists all available items:
|
||
|
||
```bash
|
||
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
|
||
```
|
||
|
||
Each entry has `name` and `type` (`hyperframes:example`, `hyperframes:block`, or `hyperframes:component`).
|
||
|
||
## Reading an item's manifest
|
||
|
||
Each item has a `registry-item.json` with full metadata:
|
||
|
||
```
|
||
<base>/<type-dir>/<name>/registry-item.json
|
||
```
|
||
|
||
Where `<type-dir>` is `examples`, `blocks`, or `components`.
|
||
|
||
## Item manifest fields
|
||
|
||
| Field | Type | Required | Description |
|
||
| ---------------------- | -------- | -------- | ---------------------------------------------- |
|
||
| `name` | string | yes | Kebab-case identifier |
|
||
| `type` | string | yes | `hyperframes:block` or `hyperframes:component` |
|
||
| `title` | string | yes | Human-readable title |
|
||
| `description` | string | yes | One-line description |
|
||
| `tags` | string[] | no | Filter tags (e.g., `["data", "chart"]`) |
|
||
| `dimensions` | object | blocks | `{ width, height }` — blocks only |
|
||
| `duration` | number | blocks | Duration in seconds — blocks only |
|
||
| `files` | array | yes | Files to install (`path`, `target`, `type`) |
|
||
| `registryDependencies` | string[] | no | Other registry items this depends on |
|
||
|
||
## Available items
|
||
|
||
### Blocks
|
||
|
||
For an always-current list run `npx hyperframes catalog --type block`. The tables below group the 97 blocks by category. **Block name ≠ shader name**: shader-transition blocks (e.g. `domain-warp-dissolve`) wrap a HyperShader runtime whose internal name omits the `-dissolve`/`-warp` suffix — see the showcase HTML installed alongside the block for the canonical name.
|
||
|
||
#### Shader transitions (14)
|
||
|
||
Single-shader blocks; each installs one HyperShader runtime + a showcase composition. Use ≤2 per video.
|
||
|
||
| Name | Description |
|
||
| ------------------------ | ------------------------------------------------------------------------ |
|
||
| `chromatic-radial-split` | Chromatic aberration radial split |
|
||
| `cinematic-zoom` | Dramatic zoom blur |
|
||
| `cross-warp-morph` | Cross-warped morphing |
|
||
| `domain-warp-dissolve` | Fractal noise domain warping |
|
||
| `flash-through-white` | White flash crossfade (rarely a neutral default — see SKILL.md guidance) |
|
||
| `glitch` | Digital glitch artifacts |
|
||
| `gravitational-lens` | Gravitational lensing distortion |
|
||
| `light-leak` | Cinematic light leak overlay |
|
||
| `ridged-burn` | Ridged turbulence burn |
|
||
| `ripple-waves` | Concentric ripple wave distortion |
|
||
| `sdf-iris` | Signed-distance-field iris reveal |
|
||
| `swirl-vortex` | Swirling vortex distortion |
|
||
| `thermal-distortion` | Heat-haze thermal distortion |
|
||
| `whip-pan` | Fast camera whip-pan |
|
||
|
||
#### Transition galleries (13)
|
||
|
||
Showcase compositions grouping multiple CSS / GSAP transition styles by family. Use as reference for picking a CSS scene transition; not meant to embed as-is.
|
||
|
||
| Name | Description |
|
||
| ------------------------- | ----------------------------------- |
|
||
| `transitions-3d` | 3D perspective flip and rotate |
|
||
| `transitions-blur` | Blur-based scene transitions |
|
||
| `transitions-cover` | Cover / uncover slide |
|
||
| `transitions-destruction` | Destructive break-apart |
|
||
| `transitions-dissolve` | Dissolve and fade |
|
||
| `transitions-distortion` | Warp and distortion |
|
||
| `transitions-grid` | Grid-based tile |
|
||
| `transitions-light` | Light-based glow and flash |
|
||
| `transitions-mechanical` | Mechanical shutter and iris |
|
||
| `transitions-other` | Misc creative (VHS, gravity, morph) |
|
||
| `transitions-push` | Push and slide |
|
||
| `transitions-radial` | Radial wipe and reveal |
|
||
| `transitions-scale` | Scale and zoom |
|
||
|
||
#### 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`.
|
||
|
||
| Name | Description |
|
||
| ----------------------------- | --------------------------------------------------------------------------------------- |
|
||
| `ios26-liquid-glass` | 3D iPhone (GLTF) + iOS 26 home screen, glass app icons, shader wallpaper, notifications |
|
||
| `macos-tahoe-liquid-glass` | 3D MacBook (GLTF) + macOS Tahoe-style desktop, glass menu bar, Finder, dock |
|
||
| `liquid-glass-widgets` | Frosted stat cards, showcase panel, pill chips over aurora shader |
|
||
| `liquid-glass-notification` | Frosted notification cards floating over aurora shader |
|
||
| `liquid-glass-context-menu` | Frosted context-menu panel drifting over aurora shader |
|
||
| `liquid-glass-media-controls` | Frosted media-control panels spreading over aurora shader |
|
||
| `vfx-liquid-glass` | Bare VFX composition shell for liquid-glass effects |
|
||
|
||
#### 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.
|
||
|
||
| Name | Description |
|
||
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
|
||
| `vfx-iphone-device` | GLTF iPhone 15 Pro Max + MacBook Pro with live HTML-in-canvas screens, glass-lens morph, 360° turntable |
|
||
| `vfx-liquid-background` | Organic liquid sim — vertex displacement on subdivided plane, HTML floats above |
|
||
| `vfx-magnetic` | VFX shell (magnetic field-line treatment) |
|
||
| `vfx-portal` | VFX shell (portal reveal) |
|
||
| `vfx-shatter` | VFX shell (shatter into fragments) |
|
||
| `vfx-text-cursor` | Cursor glow + chromatic shadow rays + spectral edges on a black stage |
|
||
|
||
#### Showcases (6)
|
||
|
||
Story-driven showcase compositions — narrated YouTube-style inserts. Most include bundled SFX.
|
||
|
||
| Name | Description |
|
||
| -------------------------- | ----------------------------------------------------------------- |
|
||
| `app-showcase` | Three floating smartphone screens, fitness app product showcase |
|
||
| `apple-money-count` | Counter $0 → $10,000, green flash, money-icon burst, SFX |
|
||
| `blue-sweater-intro-video` | Warm AI-creator intro resolving into an X follow card |
|
||
| `north-korea-locked-down` | Map zoom with red scribble circle, locked-down pop-up label |
|
||
| `nyc-paris-flight` | Map animation, plane NYC → Paris, marker circle, landing pop, SFX |
|
||
| `vpn-youtube-spot` | App-store scroll, VPN install flow, SFX |
|
||
|
||
#### Maps + data viz (8)
|
||
|
||
D3 + GSAP animated geographies and charts.
|
||
|
||
| Name | Description |
|
||
| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||
| `us-map` | US choropleth, staggered state reveals, value labels, gradient legend |
|
||
| `us-map-bubble` | US bubble map — proportional city markers, callouts, connection lines |
|
||
| `us-map-flow` | US flow map — animated origin-destination arcs |
|
||
| `us-map-hex` | US hex-grid map — each state as equal-weight hex with data fill |
|
||
| `spain-map` | Spain choropleth by autonomous community — D3 conic conformal |
|
||
| `world-map` | World choropleth + rotating globe inset, D3 Natural Earth |
|
||
| `data-chart` | Animated bar + line chart, staggered reveal, NYT-style typography |
|
||
| `flowchart` / `flowchart-vertical` | Decision tree, SVG connectors, sticky-note nodes, cursor + typing correction (vertical = portrait) |
|
||
|
||
#### Social overlays (7)
|
||
|
||
Platform-recognizable UI overlays. Stamp on top of a beat or use as a beat closer.
|
||
|
||
| Name | Description |
|
||
| -------------------- | ------------------------------------------------ |
|
||
| `instagram-follow` | Profile card + follow button |
|
||
| `tiktok-follow` | Profile card + follow button |
|
||
| `yt-lower-third` | YouTube subscribe lower third with avatar |
|
||
| `x-post` | X/Twitter post card with engagement metrics |
|
||
| `reddit-post` | Post card with upvotes and comments |
|
||
| `spotify-card` | Now-playing card with album art and progress bar |
|
||
| `macos-notification` | macOS-style banner with app icon and message |
|
||
|
||
#### Branding + 3D UI (2)
|
||
|
||
| Name | Description |
|
||
| -------------- | ------------------------------------------------------------------- |
|
||
| `logo-outro` | Piece-by-piece logo assembly, glow bloom, tagline fade-in, URL pill |
|
||
| `ui-3d-reveal` | Perspective 3D reveal for UI elements |
|
||
|
||
#### Code snippets (24)
|
||
|
||
A code/terminal window that **types a code or shell session per-character**. Theme = visual chrome only; structure, wiring, and install are identical across all 24 — pick one by name, wire it like any block (`data-composition-id` + `data-start` + `data-track-index`, see `wiring-blocks.md`). Two chrome families:
|
||
|
||
**VS Code workbench (12)** — full editor chrome (activity bar, sidebar, tabs, integrated terminal, status bar). Theme variants: `code-snippet-dark-2026`, `code-snippet-dark-modern`, `code-snippet-dark-plus`, `code-snippet-light-2026`, `code-snippet-light-modern`, `code-snippet-light-plus`, `code-snippet-high-contrast`, `code-snippet-high-contrast-light`, `code-snippet-monokai`, `code-snippet-solarized-light`, `code-snippet-visual-studio-dark`, `code-snippet-visual-studio-light`.
|
||
|
||
**Apple Terminal (12)** — macOS Terminal.app window typing a shell session. Profile = window colors:
|
||
|
||
| Name | Look |
|
||
| -------------------------------------------- | ---------------------------------------- |
|
||
| `code-snippet-apple-terminal-basic` | White bg, black text |
|
||
| `code-snippet-apple-terminal-clear-dark` | Semi-transparent dark bg |
|
||
| `code-snippet-apple-terminal-clear-light` | Semi-transparent light bg |
|
||
| `code-snippet-apple-terminal-grass` | Black bg, green text |
|
||
| `code-snippet-apple-terminal-homebrew` | Black bg, bright green text, lime cursor |
|
||
| `code-snippet-apple-terminal-man-page` | Pale yellow bg, black text |
|
||
| `code-snippet-apple-terminal-novel` | Warm parchment bg, dark brown text |
|
||
| `code-snippet-apple-terminal-ocean` | Deep blue bg, white text |
|
||
| `code-snippet-apple-terminal-pro` | Black bg, grey text, lime cursor |
|
||
| `code-snippet-apple-terminal-red-sands` | Deep red bg, sandy text |
|
||
| `code-snippet-apple-terminal-silver-aerogel` | Dark grey bg, white text |
|
||
| `code-snippet-apple-terminal-solid-colors` | Deep purple bg, white text |
|
||
|
||
#### Code Animations (9)
|
||
|
||
The richer, motion-first counterpart to the static `code-snippet-*` window themes above: each is a self-contained 1920×1080 block (~5–8s) with a paused, deterministic GSAP timeline that _animates_ code — typing, diffing, morphing, spotlighting, or GPU hero reveals — rather than typing a fixed snippet inside editor/terminal chrome. **Reuse-first**: `npx hyperframes add <name>`, then customize the baked code/diff content in place; hand-author only when no block covers the motion you need.
|
||
|
||
**DOM / text reveal (6):**
|
||
|
||
| Name | Description |
|
||
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||
| `code-typing` | Token-streamed typing reveal, caret tracks the frontier (no CSS animation) — live-coding on screen |
|
||
| `code-diff` | An edit shown as a colored diff: removed lines collapse red, added expand green — before/after at line level |
|
||
| `code-morph` | One snippet transforms into another, tokens glide between positions (Shiki Magic Move) — a refactor / one state to another |
|
||
| `code-highlight` | A highlight band sweeps a target line while surrounding context dims — spotlight one line |
|
||
| `code-scroll` | Camera scrolls a long file to center + spotlight a target line — walk through a real module |
|
||
| `code-snippet-flight` | Discrete snippets fly in from the side and assemble into a stacked program (block-level FLIP) |
|
||
|
||
**GPU / WebGL hero reveals (3):** heavier, for a title-card / hero code moment.
|
||
|
||
| Name | Description |
|
||
| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
|
||
| `code-3d-extrude` | Syntax-highlighted code on a lit beveled 3D slab that rotates through real space and settles (true WebGL depth) |
|
||
| `code-shader-dissolve` | Code resolves out of seeded noise with a chromatic dissolve front + edge glow, then holds crisp |
|
||
| `code-particle-assemble` | Thousands of GPU points fly to the exact glyph pixels and resolve into readable syntax-highlighted code |
|
||
|
||
### Components
|
||
|
||
| Name | Description | Tags |
|
||
| -------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
|
||
| `grain-overlay` | Animated film grain texture overlay | texture, grain, overlay, film |
|
||
| `shimmer-sweep` | CSS gradient light sweep for AI accents | text, shimmer, highlight, effect |
|
||
| `morph-text` | Gooey text morph cycling an editable word list (SVG threshold + GSAP blur) | text, text-effect, typography, morph, gooey |
|
||
| `grid-pixelate-wipe` | Grid dissolve transition between scenes | transition, wipe, grid, pixelate |
|
||
| `parallax-zoom` | Center card scales up to fill the frame while siblings parallax outward (single `--pz-progress` 0→1) | transition, zoom, parallax, grid, hero |
|
||
| `parallax-unzoom` | Reverse of `parallax-zoom` — focus card shrinks from full frame as siblings parallax in (`--pu-progress`) | transition, reveal, unzoom, parallax, grid, hero |
|