Code boundaries

Architecture keeps physics testable.

The repository is intentionally plain C around a small set of boundaries: simulation owns truth, app helpers own reusable runtime state, and raylib stays at the presentation edge.

Responsibility map

docs/public/catalog/ + data/planet_epoch.json Small-body atlas and source epoch

Pinned shard/index/density inventory, physical-data supplements in data/, and planetary vectors for bounded selected-body experiments. Provenance lives in data/README.md and data/SMALL_BODIES.md.

Verification: Offline tools/small_body_catalog.py --check and tools/planet_epoch.py --check; conic/experiment C tests and catalog-worker tests.

data/jovian_moons.json Jovian satellite catalog

Versioned source elements, stable JPL codes, physical-data quality and references for all 115 Jupiter moons; shared with C and Astro.

Verification: Offline tools/jovian_catalog.py --check, C satellite/geometry tests, and full-scene convergence.

SPEC.md Project spec

Current goals, constraints, interfaces, invariants, tasks, and bug history.

Verification: Review before an implementation task; check drift after verification.

src/sim/ Simulation core

raylib-independent SI bodies, Newtonian forces, Verlet/Euler stepping, diagnostics, lessons, opt-in head-on contact, conic propagation, and scene factories.

Verification: make test-core covers initial states, orbital references, convergence, conservation, collisions, and source-catalog contracts without raylib.

src/app/ Application helpers

C-owned sessions, fixed-step playback, physical inspection, camera, synchronized bounded trails, shared SI CSV writer, versioned lesson descriptors, and matched A/B comparison checkpoints.

Verification: C tests exercise reset/step, inspection, camera framing, 100-day accuracy, trail retention, descriptor validation, and comparison timing/identity.

src/render/ Rendering boundary

raylib conversion from SI-unit simulation state into readable 3D drawing policies.

Verification: Renderer helper tests guard scale conversion, visual radius policy, family framing, and grid sizing.

src/main.c Runtime loop

native window loop, Emscripten callback loop, input handling, simulation stepping, and draw orchestration.

Verification: Native and WebAssembly builds compile both loop targets; artifact checks validate generated files.

src/headless.c + src/lab_web.c Headless and comparison entrypoints

The raylib-free solar-lab CLI and the C-only comparison WASM module share sessions, descriptors, measurements, and CSV export. examples/ holds replayable .solar inputs.

Verification: make test-cli; tools/test_learning_wasm.mjs compares matching native/WASM experiments.

tests/ Test binaries

Focused C binaries plus Python CLI, build-graph, catalog-import, and artifact-validation tests; no desktop window is required.

Verification: make test test-build test-cli test-validators; make test-sanitize for address/undefined-behavior checks.

docs/ Public site

Astro Pages site, documentation routes, public lab shell, and source-backed explanatory content.

Verification: npm test --prefix docs, npm run check --prefix docs, npm run build --prefix docs, and make docs-check; docs/browser-tests/ covers browser interaction.

tools/ Catalog and delivery tools

Explicit source refresh/import, offline audits, C/WASM parity checks, runtime artifact provenance/staging, generated-route validation, and the loopback site server.

Verification: make test-build test-validators, offline catalog checks, WASM checks, and make docs-check.

docs/src/pages/simulator.astro Browser runtime

Shared Astro layout, controls, and canvas; simulator.ts sends commands to C and presents live physical readouts and errors.

Verification: Runtime integration tests, generated route checks, and headless browser verification.

.github/workflows/ Automation

Read-only Build gates produce a checked Pages tree; trusted workflow-run deployment publishes that exact artifact. CodeQL separately analyzes C/C++, JavaScript/TypeScript, and Actions.

Verification: Inspect Build/CodeQL for the revision and, on eligible main delivery, Deploy Pages plus the public runtime manifest.

Why the split matters

src/sim/ has no raylib dependency, which means gravity, vectors, body initialization, and Verlet stepping can be tested without opening a window.

src/main.c owns orchestration for native and WebAssembly loops, while src/render/ translates the same physical state into readable 3D drawings.

src/app/simulation_session.c owns playback, selection, reset, and parent-relative inspection. Native shortcuts and Astro buttons enter the same command handler in src/main.c.

docs/, tools/, and .github/workflows/ publish the public lab. The web layer sends commands to C and formats physical measurements; it does not integrate orbits.