Initial interactive SolarSystem architecture

[kevinatlee]

Summary

• implement the React/TypeScript/Three.js Solar System explorer with simplified, lineup, and educational Keplerian modes
• add deterministic simulation time, selection, body details, one-shot camera focus, visual scaling, and generic parent-child orbits
• add focused math/clock tests, production nginx Docker packaging, Compose, and project/architecture/handoff documentation
• address pre-merge review findings for JPL element-rate propagation, simplified mean-longitude phase, long-frame timing, camera focus release, bidirectional speed presets, and JPL validity-range warning

Verification

• npm test: 15/15 tests passed
• npm run typecheck: passed
• npm run build: passed (existing Three.js bundle-size warning)
• browser smoke test: passed across rendering, mode switching, selection/details, pause, reverse/forward speed presets, out-of-range warning, and camera focus with no runtime errors
• production preview: root and direct /explore/earth navigation returned HTTP 200
• Docker execution unavailable on the Codex host because Docker is not installed; Dockerfile, Compose, nginx health endpoint, and SPA fallback were inspected but container-level verification remains outstanding
• GitHub: no configured PR checks

Notes

• JPL approximate orbital elements/rates support the educational two-body model; this is intentionally not an authoritative ephemeris
• JPL Table 1 is treated as fitted for 1800–2050 and the UI warns outside that interval
• preferred eventual merge strategy is squash merge after hands-on interaction review

[kevinatlee]

Pre-merge architecture review — please address these focused issues without broad redesign:

1. JPL orbital-rate correctness. ratesPerJulianCentury.meanAnomalyRad is populated from JPL data but keplerianPositionAtJulianDate() ignores it and advances mean anomaly from a fixed orbitalPeriodDays. For bodies with JPL element rates, derive mean anomaly consistently from the supplied rate (with the existing period-based path as the fallback for bodies such as the Moon). Add a regression test proving element-rate propagation.

2. Simplified-mode orbital phase. The circular provider currently uses meanAnomalyAtEpochRad as the absolute ecliptic phase. That omits periapsis/node orientation and gives planets significantly wrong relative angular positions. For the coplanar circular approximation, use the appropriate mean-longitude phase (M + ω + Ω, with rate handling where available) so the simplified mode is a defensible approximation of current planetary arrangement. Add a test that would catch this distinction.

3. Simulation clock frame independence. useSimulationClock clamps real frame deltas to 250 ms. A throttled/background tab or low frame rate therefore loses simulated time, contrary to the frame-rate-independent/continuous-loop contract. Remove the silent loss of elapsed time or redesign the clock so elapsed real time is preserved. Add a test for a long frame gap at a non-1x simulation rate.

4. Camera focus behavior. After the first focus request, focusRequest > 0 remains true and useFrame() continuously lerps the camera toward desiredCamera, fighting subsequent user orbit/zoom input. Make Focus a one-shot transition that releases camera control after convergence (persistent body-follow can remain a future feature unless it is clean to add separately).

5. Reverse-speed UI consistency. The reverse button can create rates such as -3600 or -31557600, but those values are absent from the <select>, leaving its selected value inconsistent. Make direction and speed magnitude coherent so every forward preset can be reversed without putting the selector into an invalid/unrepresented state.

6. Keplerian validity visibility. The planetary JPL table is documented as valid for 1800–2050, while the date picker permits arbitrary dates. In Keplerian mode, surface a lightweight warning when the selected date is outside the supported range; do not needlessly block exploration.

Please keep the current module/provider architecture. Run tests, typecheck, and production build after the changes; update docs/HANDOFF.md; push to this same PR and report the new HEAD. Do not merge.

[kevinatlee]

Targeted re-review of HEAD 6669a78a251314c047567d1d208e9c2bb45161c8: all six requested pre-merge corrections are present and the implementation remains within the existing architecture. No additional code changes requested from this review. Remaining gate is hands-on interaction review; Docker execution is still unverified because the Codex host has no Docker runtime. Leave PR open pending that user test.

[kevinatlee]

Hands-on visual review feedback — please address these as a focused polish pass on the existing PR, without changing the established dark aesthetic or broad architecture:

1. Lineup lighting: In Size Lineup, some planets show awkward/uneven lighting even though the purpose is direct visual comparison. Give lineup mode neutral, presentation-style lighting independent of the orbital scene's Sun point light. Bodies should remain shaded/3D, but no planet should appear oddly dark simply because of where it sits in the lineup. Keep the dark-space background/aesthetic.

2. True-distance body-size interference: In 3D Orbits + True Distance Ratio, the current exaggerated display radii are large enough to overlap/interfere with nearby orbits/bodies (especially the Sun/Mercury region). Preserve the architecture rule that distance scaling and body-size scaling are independent. Add/complete a body-size presentation strategy so True Distance remains readable without the Sun swallowing inner-orbit geometry. Prefer an explicit, understandable body-size control or well-documented mode-dependent radius policy rather than silently corrupting true distance. Keep a clearly visible/exaggerated option because true physical body sizes would be nearly invisible.

3. Orbit display selector: Replace the current binary Orbits toggle with a three-state selector:

   • Off
   • Unified colour
   • Body colours (each orbit uses the associated body's visual colour)
     Preserve the existing subdued unified style as one option; coloured mode should remain tasteful against the dark aesthetic, not neon/overbright.

4. Orbital inclination readability: Do NOT falsify the accurate Keplerian geometry just to make inclinations obvious. Most major-planet inclinations to the ecliptic are genuinely small, so near-coplanarity is expected. Instead, make the 3D nature legible through presentation: choose/retain an angled default camera, ensure the ecliptic/grid reference does not visually flatten the scene, and consider a subtle reference treatment or optional clearly-labelled educational vertical/inclination exaggeration only if it can be kept separate from the accurate mode. Mercury's ~7° inclination should be visually detectable when inspected from a suitable camera angle. Do not exaggerate Z by default in the accurate 3D model.

After changes: run tests, typecheck, production build, and browser smoke testing specifically for lineup lighting, True Distance inner planets, all three orbit-display states, and visible 3D inclination from an angled camera. Update docs/HANDOFF.md and report the new HEAD. Leave PR #1 open and unmerged.

[kevinatlee]

Targeted re-review of the latest visual-polish pass found one remaining regression; please fix only this issue and avoid broader redesign:

True-distance Moon/body-size collision. In toDisplayPositions, Keplerian + true-distance now preserves the Moon's real parent-relative offset (~0.00257 AU), while sceneRadiusForBody(..., 'compact') renders Earth at roughly 0.032 scene units and the Moon at 0.018. This places the Moon's center well inside the exaggerated Earth sphere. The compact policy is therefore not actually orbit-safe for parent/child systems.

Keep simulation/orbital truth unchanged. Resolve this at the visualization layer. A good design is to preserve true heliocentric/planetary distance ratios while applying a documented minimum display separation for child satellites whenever exaggerated body radii would cause overlap, analogous to the existing educational Moon exaggeration but derived from rendered radii rather than a hard-coded arbitrary value. Alternatively, if you have a cleaner visualization-only solution, use it. Do not silently alter the Moon's physical/orbital data.

Add a regression test proving that under Keplerian + true-distance + compact rendering, Earth and Moon display spheres do not intersect (include a small visual gap), while the underlying localPositionAu remains physically correct. Update docs/HANDOFF wording so we do not claim the displayed Moon separation is physically true when body exaggeration forces a visualization adjustment.

Run tests, typecheck, and production build; push to the same PR; report new HEAD. Do not merge. All other items from the latest visual pass look structurally sound and should remain unchanged.

[kevinatlee]

Additional hands-on feedback to incorporate into the existing PR without broad redesign:

1. Add Pluto as a first-class dwarf planet. Use the existing dwarf-planet category and generic orbit/body architecture. Pluto should appear in Overview, Size Lineup, and 3D Keplerian modes, be selectable, have an info panel, label, rotation, and orbit-path support just like the existing bodies. Use an authoritative NASA/JPL source for its physical/orbital data. NASA/NSSDC publishes J2000 mean orbital elements for Pluto (a≈39.4817 AU, e≈0.2488, inclination≈17.14°); unlike the eight planets' JPL 1800–2050 fitted element rates, treat Pluto's fixed J2000 elements as an educational approximation with period-based phase propagation and document that distinction. Do not mislabel Pluto as one of the eight planets.

2. Size Lineup Moon placement. The Moon currently sits at the far end of the lineup and visually interferes with another body. Place the Moon immediately beside Earth as an Earth/Moon comparison pair, with enough display spacing to prevent overlap. Preserve the existing nonlinear size-comparison policy and neutral lineup lighting.

3. Do not exaggerate orbital eccentricity. The current round-looking planetary paths are broadly physically plausible; Mercury's e≈0.206 and even Pluto's e≈0.249 still produce ellipses whose minor axes are only a few percent shorter than their major axes. Preserve true Keplerian geometry. If helpful, make the Sun-at-focus/off-center relationship visually legible, but do not stretch the orbital shapes merely to make them look more oval.

4. Preserve the dark aesthetic and all prior visual-polish changes. Keep the outstanding True Distance Earth/Moon collision correction from the preceding review in scope if it has not yet been addressed.

Add/adjust regression tests where appropriate, update docs/HANDOFF.md and architecture/data-source notes, run tests/typecheck/build, push to this same PR, and report the new HEAD. Do not merge.

[kevinatlee]

Additional hands-on requirement before this next Codex pass:

Active Model transparency. Expand the Active Model panel so it explicitly states any intentional visual inaccuracies currently applied for readability/viewability. This should be dynamic to the active mode/settings rather than one generic disclaimer.

Examples of what it should communicate when applicable:

• Simplified Overview: circular/coplanar orbits, compressed orbital spacing, exaggerated body sizes, Moon orbit enlarged for visibility.
• Size Lineup: orbital positions/distances intentionally ignored; bodies are arranged side-by-side; radius scaling is nonlinear/compressed if that remains the implementation.
• 3D Educational Model: Keplerian geometry is used, but body sizes may be exaggerated/compact according to the selected body-size policy; compressed distance alters displayed spacing when selected; True Distance preserves orbital-distance ratios; Moon display orbit may be adjusted only where necessary for visibility and that adjustment should be stated.
• JPL accuracy limitation: the eight-planet fitted element model is educational/approximate and valid for its documented interval; Pluto should describe its own element/source limitations if different.

Keep this concise and readable in the existing dark UI. The goal is that a user can look at the Active Model box and immediately know which parts of the current view are physically faithful and which are intentionally distorted.

Do not replace the existing general footer warning; this is mode-specific transparency in addition to it.