feat(registry): add 25 image carousel blocks

[miga-heygen]

What

Adds 25 image carousel blocks to the registry catalog across 5 families, each with 5 style variants:

• Orbit (1–5): image cards on a spinning 3D Fibonacci sphere, billboarded to camera
• Path (1–5): cards following animated CSS motion paths
• Circle (1–5): circular carousel layouts
• Vision (1–5): Apple Vision-style spatial carousel presentations
• Text Circle (1–5): circular carousels with text animation overlays

Each block ships a standalone 1920×1080 / 6s composition and a registry-item.json with 12–24 configurable image slots.

Their placeholder images are hosted on the CDN rather than committed, which needs one small addition to the registry format (below).

Why

The registry is served straight out of this repository — DEFAULT_REGISTRY_URL points at raw.githubusercontent.com — so every byte a block ships stays in the history forever. Compositions are text and cost nothing. Images are not.

These 25 blocks would have added 421 JPEGs: 27.7 MiB in a checkout, and a 472-file diff nobody can review. Only 23 of those images are distinct; the same 12–24 placeholders were copied into every block directory.

How

files[] entries gain an optional url. When set, the installer fetches the bytes from there instead of joining the registry base:

{
  "path": "assets/carousel-images/one.jpg",
  "url": "https://static.heygen.ai/hyperframes-oss/registry-assets/223d162eed10f08f.jpg",
  "target": "assets/carousel-images/one.jpg",
  "type": "hyperframes:asset"
}

Three decisions worth calling out:

path does not change. It still says where the file lands relative to the item, so composition HTML, target mirroring and hyperframes add all behave exactly as before. Only the source of the bytes moves. Users still get real local files, so rendering stays offline and deterministic.

Keys are content-addressed. The 396 manifest entries resolve to 23 objects, and a changed image gets a new URL rather than a stale one served from the edge — the objects are published immutable, max-age=31536000, so a re-upload under an old name would keep serving old bytes until the TTL expired. No invalidation step needed as a result.

The catalog preview renderer needed the same step. It copies an item's directory and renders it, and cpSync only carries what is committed. Without materialising hosted files first, the preview draws every card blank and reports success — worse than failing. Containment reuses the existing isContainedIn check, since manifests arrive from pull requests.

scripts/host-registry-assets.ts (bun run host:registry-assets <item>) does the upload and the manifest rewrite. Contributors without AWS access commit assets normally and a maintainer runs it before merge; docs/contributing/catalog.mdx documents this.

Also drops registry/catalog/, 25 hand-made thumbnails referenced by nothing — catalog previews are rendered by CI and served from docs/images/catalog.

Result: 472 files → 87, and zero binaries.

Catalog pages

These 25 blocks had no Catalog page. Every other item in the registry has one, so they shipped invisible: installable by name, unfindable by browsing.

Generating them naively undid the change above. The Catalog payload copies an item's assets into docs/public/, which is tracked, so the 396 images removed here came straight back as 43 MB one directory over, worse than the 3 MB they started as, because each block gets its own copy.

That copy exists because these compositions assemble img.src at run time from a variable value. There is no src="..." in the markup for the payload's asset scan to resolve, and an unpredictable path can only be satisfied by serving every file beside it.

An absolute URL needs no directory, since the scan already skips any https: reference. So on the payload path only, hosted files are left undownloaded and the composition's variable defaults are rewritten to their URLs. The preview renderer still downloads them: it paints real frames, and a missing file there is a blank card.

25 pages and 25 payloads, zero bytes of image added.

Test plan

• Unit tests added/updated
• Manual testing performed
• Documentation updated (if applicable)

Three new tests on assetSourceUrl covering the plain path, the hosted path, and rejection of a non-https:// URL. Verified non-vacuous: forcing the plain-path branch fails 2 of the 3.

• bun run --filter @hyperframes/cli test — 3068 passed, 1 skipped
• bun run --filter @hyperframes/core test — 2659 passed
• node scripts/lint-registry-items.mjs on one block per family — 0 errors

End-to-end, on real infrastructure:

• All 23 objects return HTTP 200 from the CDN, each one's sha256 matching its key.
• hyperframes add carousel-orbit-1 against a locally served registry installs 24 real JPEGs (file reports JPEG for all 24, 1.6 MB total).
• generate-catalog-previews.ts renders carousel-orbit-1, carousel-vision-1 and carousel-path-3 with the images present. Removing the fetch step renders blank white cards and still exits 0, which is the failure the step exists to prevent.
• A spike item declaring no assets at all, with nothing on disk, rendered its 24 covers from the CDN — that is what proves the variable-default path before it was built on.
• Payload generation for a carousel block writes no item directory and no shared asset; the payload references the CDN.
• mint validate and mint broken-links --check-redirects pass with the 25 new pages, and all 521 doc pages return 200 on a local mint dev.
• bun run test:scripts — 86 passed.

Not covered

• Only the carousel blocks move to the CDN here. A dry run found 213 more hostable files across the existing registry (including 66 in texture-mask-text and several font files); those are a follow-up, deliberately kept out of this diff.
• The placeholder images are album art. Hosting them elsewhere does not settle their licensing, and that question is unchanged by this PR.
• scripts/generate-catalog-pages.test.ts has one failing case, "still encodes the first load with encodeURIComponent". It fails identically on origin/main and no script in package.json runs that file, so CI has never reported it. Untouched here, and worth its own fix.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Sep 9, 2026, 1:23 AM

💡 Tip: Enable Automations to automatically generate PRs for you.