mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-05 00:56:23 +00:00
James RussoandJake Moran
e96ebd74de
Packages Jake Moran's changelog-video pipeline (v1, validated end-to-end
by Home on the Jun 23-29 range) as a repo-native skill set that Claude
Code (.claude/skills/) and Codex CLI (.agents/skills/) auto-discover the
moment the repo is opened. No install step; run the skill against a
changelog markdown for a given git range and it produces a lint-clean,
seam-gate-green 1080x1080 MP4 (~45-60s, Annie VO, mock-UI visualizations,
caption rail) end-to-end.
Six skills added byte-identical in both mirror dirs:
- changelog-video (pipeline entry point)
- motion-doctrine (carries seam-stamp.mjs + seam-gate.mjs)
- cut-the-curve, captions-overlay, seam-craft, oversized-cursor
Layout:
- .claude/skills/ - Claude Code project-local auto-discover
- .agents/skills/ - Codex CLI project-local auto-discover (verified via
Magi's clean-home Codex 0.144.3 repro; NOT .codex/skills/)
Fonts, animated background (12 MB), house BGM (5 MB), lexicon, and
align-captions ship inside the skill dirs. .gitattributes routes only
.claude/skills/**/*.{mp4,mp3} + .agents/skills/**/*.{mp4,mp3} through
LFS — narrowly scoped so unrelated Player, Studio, registry, and
marketplace media stay put. HeyGen CLI auth is the one credential the
skill needs; Node >= 22, ffmpeg, and headless Chrome are documented
alongside in both READMEs.
.gitignore: rewrites .claude/ and .agents/ blocks to keep agent-installed
skill hygiene while re-including the six repo-native skill dirs plus
README.md.
CI:
- Extends changes.skills filter to match .claude/skills/**,
.agents/skills/**, scripts/lint-skills.ts, and scripts/check-skill-mirror.mjs.
- New 'Skills: project-native lint + mirror' job runs the extended
lint-skills.ts (schema-driven; required { name, description } + optional
{ license, allowed-tools, metadata }, name pattern check, description
length check) plus a new check-skill-mirror.mjs byte-integrity script
(24 mirrored files must match; README.md deliberately per-CLI).
- Wired into 'bun run lint' locally.
Frontmatter validator:
- Rejects unsupported top-level keys (catches category:-style drift).
- Requires name + description.
- Validates name pattern (^[a-z][a-z0-9-]{0,63}$) and description shape
(non-empty, <=1024 chars).
- Missing frontmatter block itself is a first-class error.
Also strips unsupported top-level 'category:' frontmatter from Jake's
motion-doctrine and cut-the-curve SKILL.mds (both mirrors), rewrites the
TTS invocation from ~/.claude/skills/media-use/... to the tracked
skills/hyperframes-media/scripts/heygen-tts.mjs, swaps npx hyperframes@latest
for the repo-local CLI in the gate step, and fixes a lint issue in Jake's
seam-gate.mjs (ternary-for-side-effect -> if/else).
Validated end-to-end by Home on Jun 23-29 (MP4 posted in C0ACCNHLG3U
thread 1784181166.041319). Independently reviewed R1/R2/R3 by Magi.
Co-authored-by: Jake Moran <jake@heygen.com>
7.2 KiB
7.2 KiB
Visualization Registry
The routing table for "show, don't tell". Classes, strongest first:
- ui-recreate — the change lives in a surface we can faithfully mock.
- ui-analog — no exact surface, but an honest UI metaphor exists (panel, meter, pipeline) whose behavior IS the change.
- terminal — the change is a CLI command/flag; type it, show the result.
- checklist — non-visual (fix lists, dependency bumps). Last resort.
Never invent UI that implies a screen that doesn't exist — an analog must depict the behavior (speed, batching, caching), not a fake product page.
Known surfaces (ui-recreate)
| Surface | Mock anatomy | Proven choreography |
|---|---|---|
| Studio editor / timeline | glass app frame: titlebar (traffic dots, mono app name, Export pill), preview strip w/ gradient art, ruler + ticks, lanes, playhead, mono-labeled clips | clips drop/stack into lanes; drag→edge/playhead snap w/ green snap-line flash; marquee → group move → group resize; playhead scrub drives preview art (hue-rotate) |
| Inspector / design panel | panel: MONO section headers (INSPECTOR / VARIABLES), key-value rows, hairline dividers, dashed empty slot | binding pill ({{ var }}) flies into a property slot; value swap via masked slide (old up-out, new up-in); selection box draws on canvas |
| Canvas + element | mini stage card, dashed selection box, live text element | text updates same-frame with panel edits (green underline pulse = the live-preview moment) |
| Variant renders | small cards: display-font title + mono filename | cascade out diagonally, stagger ≤0.15s |
| Storyboard view | row of scene thumbnails w/ mono scene labels | thumbnails file in as a waterfall; one gets dragged to reorder |
| Terminal / CLI | glass strip, mono 19-20px, $ prompt dim |
chars type (stagger .02), result line lands after a 0.3-0.5s beat |
| Render panel | RENDER header, big tabular-nums frame counter, progress bar (green fill = the moment), status chips | bar + counter run with power2.in (slow→fast reads as "faster"); chips land on their VO words |
Proven analogs (ui-analog)
| Change type | Analog | Behavior |
|---|---|---|
| Color grading / LUT | slider rows (label + track + knob) beside footage art | each knob move re-filters the art SAME frame (causal) |
| Render/extraction speed | render panel counter + bar | ease tells the story; add a before/after time chip if the claim is numeric |
| Batching (frames, requests) | row of small ticks | brackets draw around groups; ticks nudge into clusters |
| Caching | two identical request rows | first row runs a full bar; second short-circuits instantly to ✓ with a cache chip |
| Import/translation pipelines (e.g. Figma→HF) | source artifact card morphs/docks into a HF comp card — a pure DOM/CSS mock of the source (NO Figma API, no tokens, nothing fetched) | staged: source card → arrow/flight of extracted chips (tokens, components, motion) → assembled comp; chips are the carriers |
| One-pass / dedupe | N parallel item rows collapse onto one shared lane | rows glide onto one bar; count chip decrements |
| Concurrency caps / locks | queue of chips entering a gate | first k pass, rest hold; gate chip shows the cap |
| Error surfacing (toast, reason) | the surface's corner grows a toast card | action fails subtly → toast slides in, mono reason text |
Checklist scene (last resort)
Glass card, ≤6 mono rows, green ✓ ticks landing on each item's VO word (back.out(1.5), 0.3s) + row brightness pulse. Items beyond 6: cut, they live in the digest link.
Adding a surface
When a new UI area ships, add a row here (anatomy + choreography) the first time it's mocked, so the next changelog reuses it instead of re-deriving it.