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

src/sim/ Simulation core

raylib-independent bodies, constants, Vec3d math, Newtonian acceleration, Verlet stepping, and scene factories.

Verification: C tests cover vector math, acceleration, body initialization, and time stepping.

src/app/ Application helpers

orbit camera state, body trails, labels, and other window-independent app helpers.

Verification: C tests exercise camera focus, zoom clamps, labels, and trail history.

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, and grid sizing.

src/main.c Runtime loop

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

Verification: Native build, web build, and smoke checks prove both loop targets compile.

tests/ Test binaries

focused C binaries for physics and app behavior without requiring a desktop window.

Verification: Run with make test.

docs/ Public site

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

Verification: Run npm run build --prefix docs and the docs route smoke checker.

web/shell.html Web shell

Emscripten HTML shell that hosts the C/raylib WebAssembly artifact.

Verification: Checked by tools/check_wasm_artifacts.py and live Pages smoke tests.

.github/workflows/ Automation

Build workflow for native and WASM gates, plus workflow-run Pages deployment.

Verification: GitHub Actions Build and Deploy Pages runs must pass for the pushed SHA.

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.

docs/, web/, tools/, and .github/workflows/ publish the public lab without changing the C simulation contract.