R3 Workbench overview
Status: CANDIDATE. The R3 workbench is the interactive research surface of LunarTrace. It
replaces the single-page R2 story at /; the R2 page remains available at /r2 as a
historical surface.
What it is
Section titled “What it is”The workbench lets a researcher draw or select a region of interest (ROI) on a Cesium model
of the Moon, have Python evaluate the lunartrace.slope_quality/v1 method over that region,
and inspect, compare, export and reproduce the result. Every ROI result is labelled
METHOD_EXECUTED · NOT_ADMITTED. User ROIs are exploratory; the workbench does not imply
scientific admission, a DOI or an endorsement.
The surface is a single global bar over a Dockview desktop of instrument panels. Panels can be dragged, split, tabbed or closed. Scenes are starting layouts, not modes (see Scenes and instruments).
Run it
Section titled “Run it”Two processes are required: the Python sidecar and the Vite development server.
task workbench:py # Python sidecar on 127.0.0.1:4318; marimo Lab on 127.0.0.1:4319task dev:ion # Vite dev server; Cesium ion token injected by InfisicalVite proxies /py/* to the sidecar and strips the /py prefix, so the browser calls
/py/cell, /py/roi/evaluate and so on. The sidecar binds 127.0.0.1 only and refuses requests
whose Origin is not local (see Sidecar API).
If the sidecar is down, the global bar shows Python offline, and each instrument shows its own
problem state. Nothing in the UI falls back to numbers that the browser computed itself.
The sidecar also accepts --check, which loads the frozen Site once, prints the provenance
summary as JSON and exits. Its options are --manifest, --store, --lab-dir, --port and
--lab-port.
Architecture
Section titled “Architecture”| Layer | File | Role |
|---|---|---|
| Shell | web/r3/shell.tsx | Global bar (scene switch, Draw ROI, ROI, τ and sidecar status, Commands) over the Dockview desktop; owns the global hotkeys |
| Workspace | web/r3/workspace.ts | The five scenes as panel layouts; switching scenes keeps the Moon panel mounted |
| Registry | web/r3/registry.tsx | Static instrument manifest: id, title, icon, component (no plugin ABI) |
| Research context | web/r3/context.ts | Single store: site, ROI, evaluation, selected τ, linked cell, cell requests and saved runs |
| Commands | web/r3/commands.ts, web/r3/palette.tsx | Every user action is a ResearchCommand; the palette (Ctrl K), toolbars and hotkeys run the same commands |
| Sidecar client | web/r3/sidecar.ts | Typed fetch calls; every response is decoded with Effect Schema before it reaches research state |
| Moon render | web/moon/quality.ts, web/moon/scene.tsx | Display-cost profiles and the adaptive governor (see Render quality) |
| Design | web/r3/design/*, web/r3/ui/primitives.tsx | PandaCSS tokens, the Dockview theme and shared primitives |
| Sidecar | src/lunartrace/workbench/server.py | Starlette application; the only seam to scientific authority |
| ROI evaluation | src/lunartrace/workbench/roi.py | Ring projection, rasterisation, cell resolution, sampling |
| Presets and Lab | src/lunartrace/workbench/presets.py, lab.py | Editable Python presets; generated marimo notebooks |
| Figures | src/lunartrace/workbench/figures.py | Deterministic matplotlib Figures (SVG, PNG, PDF) |
Both brushing directions (Moon and Cells) run as ResearchCommands. ROI and τ changes, and
newer sample clicks, abort pending cell requests so that a late answer cannot replace the
current linked cell.
Python is the authority
Section titled “Python is the authority”The UI never thresholds, snaps or derives science values. Specifically:
- Inclusion, validity, the containing pixel, the cell centre and every statistic come from Python.
- Display rounding is labelled. Exact values sit in tooltips, in CSV exports and in the Python preset output.
- A missing value renders as
—(“missing (not zero)”). Non-finite source values serialise asnull, never as zero. - Cesium and Perspective are presentation layers. The Moon’s ROI is sent to Python as a lon/lat ring; Python decides whether a picked point lies inside it.
Verification boundary: the workbench and cell tests, the native localhost sidecar with the Effect decoder, the commands and a research-state smoke test pass without a Vite server. Cesium rendering and live browser appearance are not established by these checks. See Residuals.
Phones and small tablets
Section titled “Phones and small tablets”Below 768 CSS pixels the workbench switches to a compact layout. The research state is shared with the desktop layout, so crossing the breakpoint keeps the ROI, any draft vertices, , the linked cell and saved runs. Camera continuity across the breakpoint is not promised.
- Header. A scene menu and a condensed ROI, and Python status replace the desktop bar. Commands opens the full-width command palette, which has a touch close button.
- Bottom navigation. One tab per instrument in the scene’s order, including instruments that are inactive tabs on desktop. A command can open an extra instrument tab; switching scene clears the extras.
- One instrument at a time. The selected instrument fills the available height. The Moon stays mounted while hidden, so changing tab or scene does not recreate the Cesium viewer.
- Drawing by touch. Tap the Moon to add vertices, then use Close ROI, Undo vertex or Cancel drawing. These targets are at least 44 px. Double-tap does not zoom the page, because Cesium owns the canvas gestures. With an ROI selected, a tap resolves a cell through Python, as a click does on desktop.
- Wide tables. Rows scrolls on both axes inside its panel with sticky headers, and Perspective stays inside its panel, so the page itself never scrolls sideways.
- Safe areas. The shell uses the dynamic viewport height and safe-area insets, and the
page viewport sets
viewport-fit=cover.
The compact layout was checked in Chromium at 360 and 390 px widths with the real Python sidecar. The embedded marimo editor, ion terrain and reverse highlighting from Perspective to the Moon were not exercised on a phone layout.