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.
Labelled 56s, but the file I encoded and uploaded measures 47.6s - there are
several variants of that marketing film on disk and the 1920x1080 one I selected
is the shorter cut. Every other label matches its file to the nearest second.
The wall compiled but rendered zero tiles. Reading the page bundle showed why:
Mintlify keeps only the exported component out of a snippet file, so the CDN base
and the film list I had declared above it never made it into the compiled output -
`const FILMS` and `const CDN` appear zero times in the bundle while `FILMS.map` is
still there. The component threw on an undefined reference, React's error boundary
swallowed it, and the section rendered empty with no console error to point at it.
Both constants now live inside the component. Recorded the trap in AGENTS.md,
since a blank snippet with a clean console gives no clue on its own.
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.
Move all preview mp4/png/gif assets under docs/images/ out of the repo
and serve them from https://static.heygen.ai/hyperframes-oss/docs/images/
(backed by s3://heygen-public/hyperframes-oss/docs/images/, CloudFront).
Drops ~49MB from the working tree and, more importantly, ~49MB from every
future Mintlify build checkout. Combined with the (already-LFS-tracked)
producer snapshots, the remaining bloat in 'npx skills add heygen-com/
hyperframes' (see #300) is LFS smudge during clone — separate fix needed
in the skills CLI to pass GIT_LFS_SKIP_SMUDGE=1.
Changes:
- Delete docs/images/** (103 files, ~49MB). Files are uploaded to S3 already.
- Rewrite /images/* references in 44 MDX files, TemplateCard.jsx, and
catalog-index.json to absolute CDN URLs.
- Update README.md img src to CDN URL (renders correctly on GitHub).
- Add docs/images/ to .gitignore so regenerated previews aren't committed.
- Add scripts/upload-docs-images.sh to sync docs/images/ → S3 after running
the preview generators.
- Wire up bun run upload:docs-images and bun run generate:catalog-previews
scripts in package.json.
- Update generator script docstrings to point at the upload step.
External contributors can still regenerate previews locally (mintlify dev
reads the CDN URLs, so broken previews appear only for newly added items
pending a maintainer upload). Maintainers run:
bun run generate:catalog-previews --only <name>
bun run upload:docs-images
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## What
PR 5/17 of the catalog system rollout. Adds the `hyperframes add` verb for installing blocks and components from the registry into an existing project, plus the `hyperframes.json` project config that tells `add` which registry to use and where to drop files. Stacks on #255.
- **`packages/cli/src/commands/add.ts`** — new `hyperframes add <name>` command. Resolves an item, validates target paths, installs files in parallel, builds an include snippet, copies it to the clipboard. Exposes a testable `runAdd(opts)` function; the citty default wraps it with console output + exit handling
- **`packages/cli/src/utils/projectConfig.ts`** — read/write/normalize `hyperframes.json`. Tolerant to missing and partial configs
- **`packages/cli/src/utils/clipboard.ts`** — minimal cross-platform clipboard (pbcopy / clip.exe / wl-copy / xclip / xsel). Zero deps. Gracefully no-ops in headless environments
- **`packages/cli/src/commands/init.ts`** — write `hyperframes.json` during scaffold if not already present
- **`packages/cli/src/cli.ts`** + **`help.ts`** — register `add` under Getting Started (directly below `init`)
Design doc: [Hyperframes Catalog System](https://www.notion.so/heygen/Hyperframes-Catalog-System-Design-Plan-341449792c69813f899dcd53b4c0383a).
## UX
```bash
# Scaffold a project (now writes hyperframes.json too)
npx hyperframes init my-video --example blank
cd my-video
# Add a block — files land, snippet copied to clipboard
npx hyperframes add claude-code-window
# ✓ Added claude-code-window (hyperframes:block)
# compositions/claude-code-window.html
#
# Include snippet:
# <iframe src="compositions/claude-code-window.html" data-start="0" data-duration="6"></iframe>
#
# Copied to clipboard — paste into your host composition.
# Add a component effect
npx hyperframes add shader-wipe
# Headless / CI — no clipboard, JSON output for tooling
npx hyperframes add shader-wipe --no-clipboard --json
```
Running `hyperframes add warm-grain` (an example) errors clearly pointing to `init --example`.
## Docs (bundled in this PR per the tracker principle)
- `docs/packages/cli.mdx` — new `add` subsection under Commands (flags, examples, trigger rules) + new `hyperframes.json` section describing the config file shape
## Tests
- **`packages/cli/src/commands/add.test.ts`** — 11 tests:
- `remapTarget` / `buildSnippet` pure helpers (5 tests)
- `runAdd` integration against a mocked `fetch` registry: block install lands files + returns snippet, component install respects `paths.components` remap, example-typed names throw `AddError` with code `example-type`, unknown names throw `AddError` with code `unknown-item` (4 tests plus 2 covering block default path and non-default path preservation)
- **`packages/cli/src/utils/projectConfig.test.ts`** — 9 tests:
- Write/read round-trip, partial-config normalization, corrupt-file handling, absent-file fallback to defaults, custom paths preserved
- **CLI suite:** 92 passed (was 72 on #255, **+20**). Same 4 pre-existing failures unchanged
## Scope decisions
- **`init.ts` full port to new resolver deferred.** The original plan bundled a removal of the `packages/cli/src/templates/` compat shim. That's ~300 more lines and isn't required for `add` to work. The compat shim from #254 still functions; a separate cleanup PR handles it
- **No ajv runtime schema validation.** Manifests are trusted as schema-valid. Full validation lands when third-party registries arrive (PR 14/15). Path safety is still enforced by the installer's `assertSafeTarget` guard
- **Default project paths stay under `compositions/`.** Blocks → `compositions/<name>.html`; components → `compositions/components/<name>/<file>`. Users override via `hyperframes.json#paths`
## Breaking / migration
**None.** Pure additive — new command, new file types, no existing commands or flags change. `init.ts` now writes `hyperframes.json` but that's a new additional file, not a modification of existing output.
## Stacks on
#255 — base branch. When #255 merges, this rebases onto `main`.
## Next in stack
PR 6 — `feat(registry): seed block — claude-code-window`. First real registry item. Exercises the full `hyperframes add <name>` flow end-to-end against a committed item on `main`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* feat(docs): add template gallery page with visual previews
* fix(docs): remove invalid MDX heading anchors
* chore: retrigger CI
* feat(docs): merge gallery into templates page with hover-to-play video previews
- Consolidated gallery.mdx and templates.mdx into single templates.mdx
- Moved templates page to Getting Started section
- Added MP4 video previews rendered by hyperframes (hover to play)
- Custom JS for hover-to-play behavior (Mintlify strips JSX event handlers)
- 2-column grid for landscape, 3-column for portrait
- Remotion-style cards with gradient overlay labels
* fix(docs): update broken links after templates page move
* ci(regression): remove scripts/ from regression trigger paths
scripts/ contains dev utilities (lint, versioning, preview generation)
that don't affect the rendering engine.
ukimsanov