The hero was an 11MB export of the website-launch film. The finished master is
36.3s at 8.15 Mbps, so the page now serves a high-quality encode made from that
instead - 9MB at CRF 21, which is oversampled for a column under 900px wide.
The colour-grading film was also being derived from a 1080p variant while a
3840x2160 60fps master sat on disk. Its tile and full film are now encoded from
that master.
Both are published under versioned filenames. The first upload set
max-age=31536000, immutable, so the CDN edge kept serving the old bytes when I
replaced the objects in place - the corrected files measured identical to the
originals over HTTP until they were renamed. The component takes optional tile and
full overrides per film so a single asset can be revised this way without renaming
the rest.
Worth recording plainly: none of these films were rendered for the docs. They are
existing renders, transcoded down for the web, so each one's quality is capped by
whatever file already existed. Re-rendering from the launch projects at 4K60 would
raise that ceiling.
The front page was showing a film I generated, and it was the weakest asset in the
project: silent, slow, and stylistically plain. Meanwhile roughly 260 finished
films made with HyperFrames sat in ~/Downloads/hyperframes-launches and
~/Desktop/hyperframes-launches, most at 1080p with audio, and the good ones were
only reachable from /examples.
The hero is now the website-launch film - 38s, 1080p, real audio at -14.3 dB. It
shows the whole loop in one take: a site captured, FRAME.md, STORYBOARD.md and
SCRIPT.md written, the film rendered. It autoplays muted and unmutes on demand.
"What can it make?" was four five-second catalog snippets. It is now six finished
films: colour grading, one shoot cut many ways, a music-driven edit, a pull request
explained, timeline editing, and a personalised year-in-review. Each tile is a
silent six-second loop of 37-241KB; selecting one loads the full film with sound,
so the 1-8MB files are only fetched when someone asks for them. Tile moments were
chosen by looking at them at the 320px they actually render: the first cuts of the
music and pull-request films were an empty waveform and an illegible terminal, so
both were re-cut to the sections that read.
Removed the silent film I had committed, now that nothing references it.
The introduction now plays a film built for it rather than an older showcase
clip: one request - "make a 30-second launch video for our new pricing page" -
carried through the agent building the project, Studio opening it, a person
changing one line, and the export finishing. It was produced with HyperFrames.
Hosting solved without the CDN. The clip sits in docs/images/showcase/ at 332KB,
under the repository's 500KB non-LFS limit, because the hero autoplays muted and
therefore does not need the audio track. Encoding it silently at 720p bought the
whole 42 seconds for less than the size of one catalog preview. The master with
its music bed still needs the shared asset host, and the SSO credentials for that
bucket have expired, so it stays out of the repo for now.
The quickstart's leading example is now that same pricing-page request, and says
so. Using a different example on every page forces the reader to rebuild the
mental model each time; one project carried across the pages is the cheapest
change available that makes them read as a single path.
At this column width the breakout rendered 968px and dominated the page instead
of supporting it. The film is back inside a Frame at the column width. The part
worth keeping was the motion, not the size: it still autoplays muted on a loop
rather than sitting behind a play button, so the page is already moving when it
loads. Removed the now-unused wrapper CSS rather than leaving a dead rule.
The film now reaches into the shell padding so it reads edge to edge, and it
autoplays muted on a loop instead of waiting behind a play button. Motion is
pre-attentive - the eye goes to it before any text is read - so a page that is
already moving answers 'what is this?' faster than a poster the reader has to
decide to click. Controls stay available for scrubbing and for unmuting once a
film with a real audio track is hosted.
Not implemented as 100vw: this column is not centred in the viewport because the
sidebar is a flex sibling, so the usual margin-left: calc(50% - 50vw) breakout
would sit off-centre. Noted in the CSS.
introduction: the showcase file has a single h264 stream and no audio track, so
'press play - it has sound' was simply untrue. Removed the claim; the caption now
only says what the clip is.
workflows: the page listed all eight situations twice - once as cards linking to
anchors a short scroll down, then again as full sections repeating the same
'best for' line. Collapsed both into one accordion per situation whose title is
the chooser and whose body holds the brief and the copyable request, so the eight
cards now lead somewhere real instead of jumping down the page. Dropped the
five-step 'what happens after you choose' (it restates quickstart) and the
six-part request checklist (it restates the prompting guide) in favour of links.
187 lines to 165, eleven headings to one; no starter request was lost.
The karaoke clip rendered as an almost-black tile with one small pill, which is
weak proof on first load. Every caption component in the catalog is type on a
black ground rather than captions burned over footage, so 'Captions on footage'
was also the wrong label. Swapped to the highlight style, which holds up at
tile size, and renamed the tile 'Kinetic captions'.
Reviewed the rendered page instead of the source: the four preview tiles came
out ~110px wide in a 730px content column, with labels wrapping mid-phrase, and
the three-column workflow cards were cramped enough to hyphenate a title into
'presentation s'. Two columns is the practical maximum for this column width, so
the tiles are now a readable 2x2 and the cards are back to two across.
- Lead with the film: the video moves directly under the one-line definition,
so a stranger sees a real result before reading anything.
- Delete the mermaid flow diagram. It duplicated the Steps list underneath it
word for word; the section heading already carries the flow.
- Replace the wall of text under 'What can it make?' with four real HyperFrames
outputs playing inline (~960KB total, deliberately the small clips), then keep
the six workflow paths as compact three-column links.
- Compress the four-row Studio-vs-agent table to two lines. A newcomer needs the
principle, not a decision matrix; the detail belongs in Studio.
- One primary next step instead of three equal cards.
Make /introduction the single "What is HyperFrames?" page a stranger can be
sent, and retire the switchboard that sat in front of it.
- introduction: lead with one sentence + a sound-on result (drop `muted`),
simplify the loop diagram to request -> agent -> project -> video, cut the
fake "See how it works" scroll button, and replace the equal-weight card
walls with one clear "Start here" action.
- guides/index: remove the six-card "What do you need to do?" menu-of-menus.
The nav already routes people and /introduction is the real entry point.
Redirect /guides -> /introduction.
- developers: point the "create a video" link at /quickstart.
mint validate and mint broken-links both pass.
* docs: list all 19 skills in README + add CLAUDE.md maintenance reminder
Agents discover skills via the README, so silently-out-of-date entries
kill discovery. This change:
- Adds a `## Skills` section to the README listing all 19 skills,
grouped Router / Creation workflows / Domain skills, with a one-line
"use when" blurb for each (sourced from each skill's SKILL.md
frontmatter `description:`).
- Updates the existing CLAUDE.md `## Skills` section to cover all 19
skills (was missing the domain skills, `/media-use`, `/slideshow`,
and `/music-to-video`), mirroring the README's Router / Creation /
Domain grouping.
- Adds a "Skill catalog maintenance" section to CLAUDE.md so future
skill additions / renames update both surfaces and the
`/hyperframes` router skill in lockstep.
Docs-only — no source or test changes.
— Jerrai (https://claude.com/claude-code)
* docs(mintlify): add skills catalog page + extend maintenance reminder
Per follow-up on HF#1722: the Mintlify docs at
hyperframes.heygen.com also need the skills catalog so agent
discoverability is consistent across README and docs site.
- New: docs/guides/skills.mdx (3-group catalog — router / creation
workflows / domain skills — mirrors README structure, sourced from
the same SKILL.md frontmatter)
- Update: docs/quickstart.mdx — completes the workflow-skills list
(was missing /music-to-video, /slideshow, /general-video) and
cross-links the new page
- Update: docs/introduction.mdx — adds a skills-catalog card to the
hero CardGroup and the Next Steps section
- Update: docs/docs.json — adds /guides/skills to the Guides nav
- Update: CLAUDE.md "Skill catalog maintenance" — adds
docs/guides/skills.mdx as the third sync target alongside README
and skills/hyperframes/SKILL.md, and notes the count drift surface
(README + CLAUDE.md mention "19 AI agent skills" in their intros;
the new docs page deliberately omits a count to avoid drift)
Docs-only — no source, packages, or test changes.
— Jerrai (https://claude.com/claude-code)
* docs(readme): oxfmt table column-alignment fix
Pure whitespace — oxfmt's table-column alignment caught README.md
after the previous commit. No content change.
— Jerrai (https://claude.com/claude-code)
* docs(skills): reconcile install-command contract across README/CLAUDE/Mintlify
Per Magi's review on HF#1722: the new README/CLAUDE/skills.mdx pages
described bare `npx skills add heygen-com/hyperframes` as installing all
19 skills, while existing quickstart/prompting docs said the bare command
opens a picker and `--all` installs everything.
Verified actual CLI behavior with `npx skills add --help` and a clean-dir
run: bare command opens an interactive picker for human users (the CLI
help documents `--all` as "Shorthand for --skill '*' --agent '*' -y" —
the picker-skipping form). Inside an agent the bare command auto-installs
all non-interactively, but that's an agent-detection UX shortcut, not the
public contract — documenting the picker is correct for human readers.
All touched docs now use the consistent contract:
- `npx skills add heygen-com/hyperframes` -> interactive picker
- `npx skills add heygen-com/hyperframes --all` -> install all 19 (skips picker)
- `npx skills add heygen-com/hyperframes --skill <name>` -> install just one
Files updated: README.md, CLAUDE.md, docs/guides/skills.mdx. Existing
docs/quickstart.mdx and docs/guides/prompting.mdx already used this
contract and are unchanged.
— Jerrai (https://claude.com/claude-code)
## What
Add 28 transition blocks from the Hyperframe Template Structure catalog, bringing the registry to 53 total items.
### Shader transitions (14 blocks, WebGL, 4s each)
`domain-warp-dissolve`, `ridged-burn`, `whip-pan`, `sdf-iris`, `ripple-waves`, `gravitational-lens`, `cinematic-zoom`, `chromatic-radial-split`, `glitch`, `swirl-vortex`, `thermal-distortion`, `flash-through-white`, `cross-warp-morph`, `light-leak`
### CSS transition showcases (14 blocks, various durations)
`transitions-3d`, `transitions-blur`, `transitions-cover`, `transitions-destruction`, `transitions-dissolve`, `transitions-distortion`, `transitions-grid`, `transitions-light`, `transitions-mechanical`, `transitions-other`, `transitions-push`, `transitions-radial`, `transitions-scale`, `transitions-shader`
## Why
Phase D content accumulation. Transitions are the most-requested category for the catalog.
## How
- Shader transitions extracted from `shader-showcase.zip`, each a standalone HTML with WebGL shaders
- CSS transitions extracted from `showcase-bundle.zip`, each a standalone showcase page
- All tagged with `transition` + `shader` or `showcase` for catalog grouping
- Preview thumbnails generated for all 28 blocks
- Catalog pages + index regenerated
## Test plan
- [x] All 28 blocks produce preview thumbnails
- [x] `registry-item.json` validates for all blocks
- [x] Catalog pages generated (45 total items in catalog-index.json)
- [x] `oxfmt --check` passes
* feat(skills): add hyperframes-cli skill for CLI workflow guidance
Adds a new skill that teaches AI agents how to use the HyperFrames CLI
(init, lint, dev, render, doctor). Previously, agents had no way to
discover the CLI — the compose-video skill only covered HTML authoring.
This led to agents searching for binaries, finding the monorepo, and
running bun run studio manually instead of using npx hyperframes dev.
Also registers the skill in init.ts so new projects get it bundled
alongside hyperframes-compose and hyperframes-captions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(cli): rename dev command to preview
The command starts a preview server — "preview" describes what users
are doing more accurately than "dev". Updates the command name, file
name, all CLI references, docs, skills, and template CLAUDE.md.
22 files updated across CLI source, docs, skills, and templates.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(skills): replace stale dev reference with preview in CLI skill
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(docs): catch remaining dev references missed in rename
- testing-local-changes.mdx: two inline command examples
- troubleshooting.mdx: anchor link #dev → #preview, "dev server" → "preview server"
- cli.mdx: "dev server" → "preview server"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Major improvements across all 18 pages:
- Use Mintlify components: <Steps> for tutorials, <Tabs> for alternatives,
<CodeGroup> for multi-platform commands, <Tree> for directory structures,
<AccordionGroup> for FAQ/scannable content, <Mermaid> for diagrams
- Add filename annotations to all code blocks (e.g., ```html index.html)
- Add numbered comments inside multi-step code examples
- Show expected terminal output after CLI commands
- Add "When to use" / "When NOT to use" sections to all package pages
- Add "Next Steps" CardGroup to every page (no dead-end pages)
- Cross-link between pages at point of curiosity (not just "see also" dumps)
- Expand thin pages (engine, studio) with architecture details and examples
- Add decision guides (rendering modes, template selection)
- Use <Warning> and <Note> sparingly (max 2-3 per page)
Also adds DOCS_GUIDELINES.md at repo root with writing standards.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ukimsanov