ADR-001 — Three.js r128 as 3D renderer
Status · Accepted Date · 2026-04-01 TA anchor · §stack · §constraints
Context
Four of the six screens require real-time 3D rendering in the browser. The solar system explorer, mission arc, and moon map all use Three.js. A version must be pinned to ensure consistent behaviour and avoid breaking changes.
Decision
Use Three.js r128, bundled locally in production. Not a newer version. Not a different WebGL library.
Rationale
r128 was the version used throughout prototype development. All prototype code is validated against r128. THREE.CapsuleGeometry does not exist in r128 — this constraint is already known and worked around in the prototypes. Upgrading to a later version requires auditing four 3D screens for breaking changes. That audit is out of scope for v1.
Alternatives considered
- Three.js r140+ — introduces new geometries and API changes; requires full audit of existing code. Not worth it for v1.
- Babylon.js — different API entirely; would require rewriting all 3D code from scratch.
- Raw WebGL — no value for this use case; Three.js is the right level of abstraction.
Consequences
Positive: all prototype code ports directly; no breaking changes to manage. Negative: r128 is several versions behind current; some newer Three.js features unavailable.
Implementation notes
Bundle via npm: three@0.128.0. Do not load from CDN in production (prototypes use CDN; production bundling is handled by Vite via SvelteKit per ADR-012).