Speculative Assembly Explosion Rendering

[seveibar]

Adds a speculative core implementation of assembly.explosion.stage and assembly.explosion.move, plus a PoppyGL-rendered example that lifts an intact constrained cover, moves it aside, and then removes its cap in the displaced subassembly frame.

Approval required: this is a draft experiment. Do not merge this stack before API and implementation approval.

Dependencies:

• tscircuit/props#936: stage/move API, now draft and awaiting approval.
• tscircuit/poppygl#49: speculative depth-tested explosion guide lines.

The branch pins both PR previews so it can be installed and rendered today. Core's existing dependency-check deliberately blocks merging preview dependencies; after approval, release the upstream packages and replace these pins. That merge gate is preserved.

getAssemblyExplosion(circuit, { throughStageRef?, stageProgress? }) derives an immutable CAD view after normal assembly mounting constraints resolve. Stages use a stable topological sort with authored order as the fallback; references, cycles, duplicate stages, and invalid move targets produce named diagnostics. Parent movement carries descendant CAD and reference-surface centers. Repeated evaluation and backward scrubbing do not modify the assembled circuit or input props.

The render tests verify upright, inverted, and tilted mount frames against emitted reference directions, and guide endpoints against emitted GLTF node translations. Run bun scripts/render-assembly-explosion.tsx work/assembly-explosion-preview to export all four PNG/GLB/JSON states.

Limitations are explicit: this prototype supports mechanical CAD translations and rejects PCB/cable-containing targets. Swept-path collision verification is not implemented; returned views report collisionCheckStatus: "not_implemented". The diagrams do not certify assembly clearance.

Approval tracking and behavior are documented in docs/assembly-explosion.md.

Validation:

• Three new explosion tests pass, including two annotated PoppyGL visual regressions.
• Assembly and namespaced assembly regressions: 70 passed, 0 failed, using the pinned PR-preview packages.
• tsc --noEmit: passed.
• Changed TypeScript files pass Biome formatting; git diff --check passes.
• Standalone render export script produced all four states using the pinned PR-preview packages.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
tscircuit-core-benchmarks	Ready	Preview	Oct 14, 2026 8:18pm UTC