SolarSystem Web

The key insight was that SceneKit and Three.js share the same rendering model: a scene graph with meshes, materials, lights, and a camera. Every concept has a direct equivalent. The only real difference is the gesture system — iOS has structured UIGestureRecognizer classes, while the web has raw mouse/touch events that need manual state tracking.

The port was made possible by the iOS project's meticulous CLAUDE.md documentation. Every constant, every formula, every design decision was recorded — making it possible to reproduce the entire rendering pipeline in a different language and framework without guesswork.

This is the most common pitfall when developing web apps with ES modules. The file:// protocol has an opaque origin, so the browser treats every file as a different origin. A local HTTP server makes everything same-origin. Any static server works — Python, Node's npx serve, VS Code's Live Server extension, etc.

Three.js's physically correct mode (renderer.useLegacyLights was removed in r155) means light intensity is measured in candela, not arbitrary units. Combined with ACES tone mapping, the rendered image maps HDR lighting values to the display's SDR range in a way that mimics film exposure curves — highlights compress gradually instead of clipping.

Using depthWrite: false on the sprite materials prevents the transparent parts from writing to the depth buffer, which would create invisible rectangular occluders. The sprites are child objects of the Sun mesh, so they move and scale with it automatically.

Touch gesture disambiguation required a 5px dead zone: without it, every tap would start a pan. The double-click/tap detector uses a 350ms timeout to distinguish single from double. When a two-finger gesture ends with one finger still down, the controller transitions to one-finger pan mode without jumping. These subtleties don't exist in iOS's UIGestureRecognizer system, which handles them automatically.

This is a classic state synchronisation bug. The zoom slider, camera distance, scroll wheel, and pinch gesture all modify the same underlying value (cameraController.distance). Every entry point that changes the distance must also update the UI. The iOS app solved this identically — ensuring all zoom controls clamp to the same 0.5–250 range and calling syncZoomFromCamera() after programmatic changes.

The overlay uses backdrop-filter: blur(10px) at z-index 50 (above all other UI). The panel scrolls independently (max-height: 80vh; overflow-y: auto) for smaller screens. Three event listeners handle dismissal: the X button, clicking the backdrop (checking e.target === overlay), and the Escape key would be a natural future addition.

The thumbnails use flex: 1 within the toolbar to distribute evenly across the available width. The planet strip takes whatever space remains after the playback controls. Saturn's ring is a pure CSS effect — a border-radius: 50% div with transform: translate(-50%, -50%) rotateX(65deg), positioned absolutely over the planet circle.

The onTap() pattern fires on touchend with preventDefault() (no 300ms delay), and falls back to click for mouse input. A touchFired flag prevents the click from re-firing when both events are synthesized. This is now used for every interactive element in the app — 20+ bindings in total. Desktop mouse behaviour is completely unaffected.

The aspect-ratio correction is applied in focusCamera(), not in CSS. The camera's field of view is fixed at 60°, so the constraining dimension on portrait screens is width, not height. Without the correction, a planet at the "right" distance for a 16:9 desktop would appear at roughly half its intended visual size on a 9:16 phone — the multiplier drops to ~78% on a typical phone, bringing the camera closer to compensate.

The multipliers (2.2× with moons, 6.0× without) were tuned empirically. The underlying formula is cameraDistance = max(extent × multiplier, 0.5), where extent is the maximum of the planet radius and the outermost moon's orbit distance plus its own radius. The 0.5 floor prevents the camera from going inside the body.

The most valuable asset in the port wasn't the code — it was the documentation. The iOS app's CLAUDE.md contained every formula, every constant, every design decision with its rationale. This turned a complex reverse-engineering task into a straightforward transcription. The lesson: invest in documentation not just for future developers, but for future platforms.

The hardest problem was distance compression. The pow(ratio, 0.4) formula that makes the solar system visible squashes the 10,600 km between the Moon and the flyby point to 0.01 scene units — invisible. Flyby waypoints had to be slightly exaggerated so the trajectory visibly loops around the Moon. CatmullRom curves created kinks when waypoint coordinates reversed direction; keeping values monotonic within each leg solved this. Two further issues emerged through iterative tuning: the Z-component amplification problem, where constant out-of-plane values made the trajectory appear to pass over the Moon’s pole instead of behind the far side (fixed by reducing Z to near-zero at closest approach), and the flyby speed symmetry problem, where hand-crafted post-flyby waypoints initially showed 2.5x the approach speed. In a free-return trajectory, approach and departure speeds should be roughly symmetric — spacing the post-flyby waypoints wider in time and closer in distance corrected this. The multi-vehicle architecture was designed with Apollo 11 in mind — CSM and LM separating at the Moon will use the same vehicles array with diverging waypoints. Later refinements made missions look beautiful by default: the camera azimuth is set ~31° off the Sun direction (0.55 radians) so Earth and Moon appear two-thirds illuminated — a dramatic cinematic framing that required adding optional azimuth/elevation parameters to setCamera(). Event labels were changed from always-visible to timed (~3% of mission duration around each event), keeping the view clean during playback. The bounding box calculation was made robust by computing trajectory extent at both Earth’s start and end positions, preventing drift as Earth moves through its orbit.

The anchorBody system solved a subtle but critical problem: interplanetary waypoints defined with approximate coordinates (e.g. Jupiter at x=5.2 AU) wouldn’t match the actual computed planet position at the encounter date, because Keplerian elements shift over centuries. A Voyager trajectory passing “near” Jupiter but missing by 0.3 AU in the scene looks wrong. By importing the same heliocentricPosition() function used for rendering planets, each anchored waypoint snaps exactly to the planet’s rendered position at the flyby timestamp. The autoTrajectory generator then fills in smooth transfer arcs between these anchor points using elliptical interpolation, avoiding the need to manually plot hundreds of intermediate positions. The timeline slider presented a different challenge: when the simulation is paused, the normal animation loop doesn’t run — but scrubbing needs to update everything. The solution overrides the simulation date during scrub and forces a complete render pass (positions, telemetry, labels, banners) even while paused, so the scene always reflects the slider position. A third scale problem arose with Apollo 11’s LEM descent: the real 45 km descent path compresses to just 0.035 scene units — completely invisible. The flyby exaggeration approach (inflating distances by 10–15%) doesn’t work here because the vehicle needs to arrive at the Moon, not pass near it. The solution was runtime interpolation via the moonLanding vehicle property: during descent, the marker lerps from its orbital position to the Moon’s actual computed scene position (via moonPosition() each frame), creating clear visible separation from the orbiting CSM. During surface operations it tracks the Moon exactly, and during ascent it lerps back. Interplanetary speed consistency required a general principle: always add transition waypoints ~1,000–2,000 hours before and after anchored points to prevent speed spikes. This was applied across Cassini, New Horizons, and both Voyagers. A new anchorMoon system (the geocentric equivalent of anchorBody) resolves waypoints to the Moon’s actual ecliptic position, used for Apollo 11’s departure waypoints. The mission camera evolved through several iterations into a lazy-follow system: on selection, the camera snaps to Earth’s position + the trajectory’s local center (using tight localRadius bounds from getMissionBounds() rather than the wide start+end bounding box). During playback, the camera target lerps toward Earth’s current position each frame at lerp(0.02), keeping the trajectory centered while Earth drifts through space. User interaction breaks the follow by clearing activeMissionId.