feat(registry): add Apple Terminal theme code snippet blocks

[miguel-heygen]

Summary

• Adds 12 Apple Terminal built-in profile blocks to the Code Snippets catalog section, following the VS Code theme pattern from feat(registry): add code snippet blocks with VS Code workbench #1113
• Each block is a self-contained 1920×1080 composition: macOS Terminal.app window in the matching profile colors, per-character GSAP typing animation, window.__timelines contract
• Profiles: Basic, Clear Dark, Clear Light, Grass, Homebrew, Man Page, Novel, Ocean, Pro, Red Sands, Silver Aerogel, Solid Colors
• Install individually: npx hyperframes add code-snippet-apple-terminal-basic
• Install all at once: npx hyperframes add apple-terminal

Files

• registry/blocks/code-snippet-apple-terminal-*/ — 12 new block directories (HTML + registry-item.json each)
• docs/catalog/blocks/code-snippet-apple-terminal-*.mdx — 12 new catalog doc pages
• docs/docs.json — Apple Terminal entries added to Code Snippets group (alphabetically before VS Code entries)

Notes

• Video preview URLs (static.heygen.ai/hyperframes-oss/...) are placeholders — need to be populated once videos are uploaded to CDN (Jake shared rendered MP4s for basic, clear-light, grass, man-page in Slack)
• Theme colors sourced from macOS Terminal.app built-in profile defaults

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jun 2, 2026, 3:35 PM

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

[jrusso1020]

Reviewed at bc492626. Structure looks right (registry/blocks/ + docs/catalog/ + docs.json — same shape hf#1113 settled on); 12 themes × 3 files plus the index update = 37 files. One real concern worth raising before merge: 8 of the 12 video URLs aren't actually live on the CDN yet, and the PR ships them anyway. Smaller observations after.

Live CDN check — 4 of 12 videos resolve, 8 return HTTP 403

I just hit each preview URL:

Theme	Status
basic, clear-light, grass, man-page	✅ 200
clear-dark, homebrew, novel, ocean, pro, red-sands, silver-aerogel, solid-colors	✗ 403

The 403s (not 404s) suggest S3 is returning unauthorized rather than not-found — same UX result either way: the HTML5 <video> element can't load the source. The PR body acknowledges the URLs are placeholders pending render uploads, but the user-facing behavior at merge time is: a Code Snippets catalog page with 8 broken video tiles.

The <video> element here:

<video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800"
       src="..."
       poster="..." ... />

…will fall back to the poster image when the video src fails. But those poster .png URLs presumably also 403 (same upload bottleneck) — same problem. Net effect: 8 themes show the bg-zinc-100 dark:bg-zinc-800 gray fallback box.

Four options to resolve, ordered by cleanliness:

1. Split the PR — land the 4 working themes now (basic, clear-light, grass, man-page), file the other 8 as a follow-up that lands once renders are uploaded. Catalog stays clean from day one.
2. Render + upload the 8 missing previews before merging — if the bottleneck is "Jake hasn't rendered the other 8 yet," that's a known scope; ~1 hr per theme via the same pipeline Jake used for the first 4.
3. Hide the 8 placeholders from the catalog index via a published: false flag in their registry-item.json + a docs.json filter, until their previews are live. Keeps the comp files in the repo, hides them from end-users.
4. Ship as-is + accept the 8 broken tiles — worst UX, would recommend against.

I'd push for option 1 or 2; option 3 is the soft-defer if the rendering bottleneck is non-trivial.

Naming consistency — worth a sanity check

The 12 theme names look right at a glance (Basic, Clear Dark, Clear Light, Grass, Homebrew, Man Page, Novel, Ocean, Pro, Red Sands, Silver Aerogel, Solid Colors). Two worth double-checking against Apple's canonical Terminal.app > Preferences > Profiles source list:

• "Clear Dark" / "Clear Light" — older macOS Terminal versions didn't ship "Clear" as a built-in profile name. If these are coming from a recent macOS, fine; if they were inferred or named to match a system-mode preference, flag the source.
• "Solid Colors" — Apple's canonical profile is just Solid Colors (no qualifier), but it's a category, not a specific theme. Worth confirming the colors in this block match a specific solid-color preset rather than being ambiguous.

The PR body says "Theme colors sourced from macOS Terminal.app built-in profile defaults" — taking that at face value but worth a spot-check against Apple's source if you have a recent macOS handy.

Registry path follows hf#1113's resolution

Files land at registry/blocks/code-snippet-apple-terminal-*/ (the published artifact path), not the older example/ location that hf#1113 fixed. Good — the lesson from that PR carried over. ✓

Smaller observations

• "Install all at once" command: npx hyperframes add apple-terminal — this implies prefix matching or a meta-entry in the registry. Worth confirming the CLI actually supports the all-at-once pattern, or whether it falls back to per-block. Not in the diff explicitly.
• Authorship clarification: PR is opened by Miguel (per user.login), not Magi. PR body footer says "🤖 Generated with Claude Code" — content-generation by AI tooling is consistent with the team's pattern but the PR-author bot constraint doesn't apply since the GH author is a human. Standard review event types are valid.
• Composition file naming: each comp lives at compositions/code-snippet-apple-terminal-<theme>.html (per target in registry-item.json) when installed. Long names but consistent with the prior catalog pattern. Fine.
• Tags consistency: every block has ["code", "developer", "showcase", "terminal", "apple"] — uniform across all 12. ✓ Future search/filter work will benefit from the consistency.

Verdict

Materially LGTM on the structure + registry shape + naming-pattern consistency. Real concern: 8 of 12 preview URLs aren't live, which means shipping this as-is gives users a catalog with 8 broken tiles. Option 1 (split) or option 2 (render before merge) closes it. Stamp held — James gates.

— Rames Jusso (hyperframes)

[jrusso1020]

Re-reviewed at 1c7c5f36. 3 commits since my prior round; both blocking items addressed.

Prior concern	Status at 1c7c5f36
8 of 12 preview URLs returned 403 on CDN	✅ resolved — re-curled all 12, every URL returns 200
npx hyperframes add apple-terminal all-at-once command implies prefix matching or meta-entry	✅ resolved — apple-terminal tag now in every registry-item's tags[]

CDN verification — all 12 live

basic: 200          clear-dark: 200      homebrew: 200
clear-light: 200    novel: 200           ocean: 200
grass: 200          pro: 200             red-sands: 200
man-page: 200       silver-aerogel: 200  solid-colors: 200

Picked option 2 from my prior review (render + upload before merge) — the strongest of the four. ✓

Tag-based all-at-once install

Verified one of the previously-unrendered ones (code-snippet-apple-terminal-homebrew/registry-item.json):

"tags": ["code", "developer", "showcase", "terminal", "apple", "apple-terminal"]

apple-terminal is now a distinct tag (the prior apple tag wouldn't have been specific enough to filter from non-Terminal Apple-related blocks). All 12 registry items got the addition. npx hyperframes add apple-terminal will now match by tag.

Smaller observation that didn't make it into a commit

My prior soft-flag on naming canonical-ness ("Clear Dark"/"Clear Light"/"Solid Colors" vs Apple Terminal's actual Preferences > Profiles list) wasn't addressed in the commits. Not a blocker — the colors and naming look reasonable and the PR body cites Apple's defaults — but worth a final sanity check on a recent macOS if there's any doubt. Easy to drop a comment if the names match exactly; nothing more to do.

Verdict

LGTM. Both blocking items closed cleanly via the cleanest route. Stamp held — James gates.

— Rames Jusso (hyperframes)

[vanceingalls]

My initial pass found two blockers — both now fixed:

1. Format CI — oxfmt was failing on all 12 HTML files; Preflight (lint + format) now passes across all 37 checks. ✓
2. Tag mismatch — apple-terminal tag is now in all 12 registry items alongside apple; npx hyperframes add apple-terminal will resolve correctly. ✓

All 12 CDN URLs confirmed 200 (Rames re-curled after the render uploads). ✓

One nit to be aware of (non-blocking): all 12 new blocks carry the "code" tag, matching the 12 existing VS Code blocks. npx hyperframes add code currently installs 12 VS Code blocks; after this PR it installs 24. If that's intentional (unified "all code snippet blocks" install), it's fine — just a silent expansion of a documented command.

LGTM.

— Vai