Orbit lab window: themed lib/ui front-end over the physics core (rung 1, slice 1)

[InauguralPhysicist]

First slice of dynamics#20 rung 1 (fleet UI ladder, hq/proposals/fleet-ui-expansion.md — approved 2026-08-02). The issue stays open: this is slice 1, not the whole rung (bifurcation sweeps, pan/zoom, and the chart-widget consumption land in later slices).

What this is

A run() front-end over the unmodified physics.eigs damped-oscillator core (the repo's best-documented system; analytic equilibrium at the origin, marked red on the plot):

• orbit.eigs — the lab window: live phase portrait (x, v) on a ui.canvas, world grid + axes, teal trail, amber current-state head; a zeta slider (0..2), pause/resume (button + Space), and the observer's live regime forecasts for energy and displacement (report of — the observer is the instrument).
• orbit_theme.eigs — named palette mapped onto lib/ui theme keys with the DeslanStudio in-place field-by-field apply, called before widget construction (never set_theme wholesale — it nulls the sizing keys). The canvas plot surface reads its colours from the same module, so chrome and plot are themed together.
• orbit_main.eigs — standalone launcher (eigenscript orbit_main.eigs, gfx build).

The oracle (non-negotiable, and green)

tests/test_orbit_oracle.sh: a headless run and a UI-stepped run (real window, real per-frame draw through the same tick path an interactive session uses) of the same system/zeta/frames must dump byte-identical trajectories — the UI is a pure reader of the simulation. Both paths advance through the one frame_advance (SUB unobserved substeps of the core's step, the specimen's own cadence) and format through the one traj_line.

PASS: headless and UI-stepped trajectories are byte-identical (201 lines)
PASS: planted fault (zeta=0.16) is caught by the checker

The checker is validated with a planted fault (a zeta=0.16 headless run must NOT compare equal). The script exits 2 on a non-gfx runtime — a skip is a failure in CI, so the UI oracle can never be silently dropped from a gfx-capable environment. Verified locally on both the gfx and release builds (trajectories byte-identical across builds too).

CI

The devcontainer now builds the gfx variant and ships SDL2 + Xvfb (the Tidepool pattern; SDL2 is dlopen'd so no -dev headers). test.yml runs the oracle alongside the existing smoke/lab suites — all three green locally against the v0.34.0 pin.

Gap ledger (FINDINGS.md, for upstream filing)

• F-DYN-8 — import physics silently resolves to the stdlib's lib/physics.eigs (formula library), shadowing the repo's physics.eigs; members read null and the first symptom is a downstream type error. Worked with load_file (path-explicit); candidate upstream: shadowing warning or cwd-first resolution.
• F-DYN-9 — lib/ui has no x-y parametric plot widget: chart is strictly y-vs-index. The phase portrait is canvas-drawn in this slice; third consumer (with eigen-sheet#26, EigenMiniSat#76) now forcing the chart/plot widget.
• F-DYN-10 — viz widget surfaces (_render_chart/_render_bar_chart/_render_waveform_view) hardcode their background/grid colours instead of reading theme keys — a themed app cannot restyle exactly the surfaces a data app is made of.

Screenshot evidence from a driven session on the real desktop (slider drag and pause toggle verified by pixels) is in docs/orbit-lab.png.

🤖 Generated with Claude Code