Add magic book catalog block

[MrSunOcean]

What

Adds magic-book, a cinematic 3D spellbook dissolve catalog block with glowing rings, magical dust, and GPGPU particle vapor

Why

This adds a production-style 3D/VFX template to the HyperFrames catalog so users can install it with:

npx hyperframes add magic-book

How

Implemented as a standalone registry block under registry/blocks/magic-book.

Notable details:

1.Fixed 1920x1080 composition with 8s duration.
2.Uses a paused GSAP timeline registered as window.__timelines["magic-book"].
3.Preserves deterministic particle placement with seeded randomness.
4.Uses the original GLTF spellbook model, shader dissolve, glowing rings, dust layers, and GPU-driven particles.
5.Waits for the GLTF and particle setup before render capture starts, so HyperFrames render does not capture an empty scene.
6.Adds catalog docs and registry metadata.

Test plan

How was this tested?

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

Manual validation:

• npx hyperframes lint output/magic-book-render-project --verbose
• npx hyperframes render output/magic-book-render-project --output output/magic-book-official-preview-fixed5.mp4 --quality draft --fps 24 --workers 1

Render output was checked locally to confirm the book, dissolve, glow, and particle effects appear in the captured video.

magic-book-preview.mp4

[miguel-heygen]

Cool 3D work — the dissolve + particle vapor effect is genuinely impressive. But based on the team discussion and reviewing the code, this needs structural changes before it fits the catalog.

Catalog fit: showcase vs reusable component

The team aligned on this in the thread: as-is, this is a showcase piece (specific spellbook model, specific magical theme). To be a catalog block — the "shadcn of video components" standard James described — it needs to be generic and model-swappable.

Suggested restructure:

1. Rename to 3d-dissolve (or three-dissolve) — the value is the dissolve effect, not the book
2. Use HyperFrames variables for the model path, dissolve speed, particle color, and background color. Users should be able to npx hyperframes add 3d-dissolve and point it at their own GLTF without editing the HTML
3. Remove the bundled GLTF/textures from the registry — they add ~2MB of binary assets to the repo. Instead, reference a remote URL or document how to bring your own model
4. Add instructions in the docs for swapping the model: "Replace scene.gltf with your own GLTF model. The dissolve effect adapts to any mesh geometry."

Technical issues

Async timeline construction

The entire composition builds inside an async IIFE (line 79). HyperFrames rule: "Never build timelines inside async/await, setTimeout, or Promises. The capture engine reads window.__timelines synchronously after page load."

The current workaround (register a proxy timeline first, then load GLTF) is fragile. The timeline's onUpdate calls renderAt() which depends on state (bookMesh, gpuCompute, etc.) that doesn't exist until the GLTF loads. If the capture engine seeks before the model loads, it renders an empty scene.

Consider using the Three.js runtime adapter (@hyperframes/three-adapter) which handles async model loading and seek properly. Or use window.__hyperframes_ready to signal when the composition is actually renderable.

Seeded random

The seededRandom() function (mulberry32 variant) is good — deterministic as required. But seed is a let at module scope — if this composition is loaded twice, the second instance shares the mutated seed state. Use a local seed per-instance.

Three.js version

Pinned to three@0.132.2 (2021). The current Three.js is ~0.170+. The legacy examples/js/ imports (GLTFLoader, EffectComposer, etc.) are deprecated in favor of ES module imports. Not blocking, but worth noting for maintainability.

Summary

The VFX quality is great. The path to merging:

1. Genericize: rename to 3d-dissolve, add variables for model/colors/speed
2. Remove bundled binary assets — document bring-your-own-model
3. Fix or document the async loading pattern (ideally use the Three.js adapter)
4. Verify model-swappability works (Vance's ask)

[vanceingalls]

First review at d194d1a7. CI status is mostly "skipping" (registry-only PR). Existing review: @miguel-heygen REQUEST_CHANGES on 2026-05-11 — and Miguel has since picked this up himself in #779 which restructures magic-book → generic three-dissolve with modelUrl variable, dropping the 14MB bundled assets in favor of CDN.

Audited

• File list (12 files: HTML composition + docs + registry metadata + 14MB of binary GLTF/textures)
• Miguel's prior REQUEST_CHANGES review (2026-05-11)
• registry/blocks/magic-book/registry-item.json (config + asset list)

Strengths

• The VFX work is genuinely impressive. Cinematic 3D spellbook dissolve with GPGPU particle vapor, glowing rings, and post-processing pipeline. The shaders + particle system are well-factored — Miguel called this out specifically in his review and carried the rendering pipeline through to #779 unchanged.
• Deterministic seeded particle placement. The let seed shared state was the only correctness issue in the original (since fixed in #779). The GLTF-load + particle-setup readiness wait is the right pattern.
• Catalog docs + registry-item.json follow the existing block conventions. Schema is clean.

Blocker — superseded by #779

The PR was reviewed by @miguel-heygen on 2026-05-11 with structural change requests around naming, asset packaging, and variable surface. Miguel picked the work up himself in #779 — feat(registry): add three-dissolve block — generic 3D dissolve effect which:

• Renames magic-book → three-dissolve (the value is the dissolve effect, not the spellbook model)
• Adds composition variables (modelUrl, dissolveStart, dissolveEnd, particleColor, bgColor)
• Removes the 14MB of bundled binary assets — default model URL points to static.heygen.ai CDN
• Auto-scales any GLTF model to fit the viewport via bounding-box normalization
• Fixes the seeded random closure scope + readiness signal bugs

#779's PR body explicitly says "Supersedes #712." The intent is to close this PR in favor of that one.

Recommendation

Close this PR. The block's value is preserved in #779; bundling 14MB of binary assets in the repo was the main structural concern in Miguel's review, and #779 addresses that by pointing at the CDN. Keep an eye on #779 (currently has a red Render catalog previews check that I've reviewed at 4cdd1472) — once that lands, this work ships.

Thanks for the original contribution — the VFX pipeline you wrote is the value, and it carries through.

Verdict

Verdict: COMMENT
Reasoning: Superseded by #779 (Miguel's restructured version that addresses his earlier review feedback). The VFX pipeline you authored is preserved there; this PR can be closed. No new blockers to flag here that aren't already covered by Miguel's prior review.

— Vai

[MrSunOcean]

Thanks for the detailed review. I understand the catalog fit concern.

I’m happy that the VFX pipeline is being preserved in #779 as the more generic three-dissolve block. I’ll close this PR in favor of #779.

Thanks again for reviewing and for carrying the effect forward.