feat(registry): add path-traced-3d example with raster preview and path-traced export - #7219

What

Adds path-traced-3d, an opt-in Three.js starter. It previews with raster rendering and exports with a path tracer, from the same scene file. It also adds a skill reference (skills/hyperframes/references/path-tracing.md) and a docs guide (docs/guides/path-tracing.mdx).

• The renderer variable is raster (the default, for fast preview) or path (for export). samples and bounces are also variables.

• three 0.180.0, three-gpu-pathtracer 0.0.24 and three-mesh-bvh 0.9.5 ship as one local ES module, with:

  • their licences;
  • a note with the versions and the bundle's hash;
  • a pinned rebuild recipe in source/.

  There are no CDN imports, and 2D projects never load the tracer.

Why

Path tracing in HyperFrames already works with existing APIs: window.__hf.buildReady, hf-seek with waitUntil, and composition variables. But it's easy to get wrong:

• Setup that waits on an animation frame or the clock never finishes during a render.
• A setup loop that polls with scheduler.yield() never finishes anywhere. Yield continuations run ahead of timers, so the loop starves the setTimeout that Three's compileAsync polls with. Plain headless Chrome 152 hangs on a ten-line page that does this.
• Unseeded randomness changes the grain between page loads and render workers. The tracer's noise textures and Three's object ids, which set the order lights are sampled in, both come from Math.random.

This starter and recipe show a deterministic, verified version of each.

Related work

• Refs fix(engine): report a pending setup as a setup timeout, not zero duration #7211, which gives a setup timeout its own message ("Composition setup did not finish") instead of "Composition has zero duration".
• fix(producer): let buildReady setup that awaits a frame finish #7213 was the alternative of letting animation frames run before the first seek. We closed it to keep the render clock strict, so this recipe is where the safe pattern lives.

How

• assets/scene.js builds the scene, and poseAt(t) is the only code that moves anything.
• assets/render.js:
  • Setup is one buildReady promise. It awaits renderer.compileAsync (raster), or the tracer's compile promise behind isCompiling (path), in one commented helper. It draws one throwaway frame, because a renderer's first frame differs from later ones, then reads one pixel back.
  • Frames are drawn only in the hf-seek listener, registered with waitUntil. Each new time restarts accumulation and traces exactly samples passes.
  • Settings that depend on elapsed time are off: renderDelay and fadeDuration are 0, and dynamicLowRes is off.
  • The scene and the tracer are built under a fixed Math.random seed.
  • Nothing uses timers, animation frames, the clock or scheduler.yield(), and nothing starts a render loop.
• source/ holds the repo-only files, which aren't installed:
  • pinned package.json and lockfile, plus build.mjs (a rebuild produces the same hash);
  • path-traced-3d.test.mjs (in test:scripts), which checks the manifest, local-only imports, the bundle hash and pins, that render.js uses no timers, animation frames or clock, and that a pose depends only on its time;
  • verify-render.mjs, the render check.

Test plan

• Unit tests added/updated: path-traced-3d.test.mjs (5 tests) passes. The skill lint, core-skills and catalog-source-PR checks pass (64 tests).
• Manual testing performed: verify-render.mjs, run on a machine without a hardware GPU (software WebGL), at 320x180 and 2 samples per pixel in path mode:
  • hyperframes check passes in path mode, so the async setup resolves.
  • Snapshots at 4 s, 0 s, then 4 s again: the two 4 s PNGs are byte-identical, in both raster and path mode. A fresh page draws the same 4 s path still (same hash).
  • Exported frames decoded with ffmpeg: raster, 1 s at 30 fps (30 frames); path, 0.8 s at 10 fps on 2 workers (8 frames). No frame is blank, the clip moves, and there's no jump where the two workers' frames meet.
  • Software wall times: path setup about 55 s (mostly the first shader run), path render 66 s, raster render 6.8 s.
• Documentation updated (if applicable): new guide and skill reference, linked from frame-adapters.mdx, types/3d.md and runtimes.md.
• Comments follow CONTRIBUTING.md "Comments".

Notes

• hyperframes init --example path-traced-3d starts working once the catalog publication PR adds the example to registry/registry.json.
• A catalog PR may not edit docs/docs.json, so the guide is linked from the frame-adapters page instead of the sidebar. A small follow-up can add the sidebar entry.
• Without a hardware GPU, the tracer's first shader run takes about a minute, which is longer than the default 45 s readiness wait. The guide says to raise --timeout or --player-ready-timeout.
• The cost figures in the guide (8 s 720p clip: 10.8 s raster vs 810.5 s path traced, at 32 samples per pixel and 6 bounces, on an Apple M4 Max) come from the study this starter is based on. A hardware-GPU benchmark is running, and I'll update the figures if it disagrees.

🤖 Generated with Claude Code