4.3 KiB
ADR 0052: Native Rerun grid navigation
Date: 2026-09-21 Status: implemented and installed; checks and manual acceptance bounds are in the navigation audit
Decision and authority
The owner accepted the restored recorded cloud quality, then explicitly asked to finish navigation: pan the pivot on the grid, orbit around that fixed pivot, and zoom independently of the route extent. OPS is updated only after completion.
This is a bounded amendment to ADR 0045's unmodified web viewer requirement. Rerun SDK, recording format, data, timeline, native renderer and single-viewer ownership remain unchanged. The web viewer stays on upstream 0.36.3, with one reproducible, hash-checked source patch. The archived 0.34.1 fork is not reactivated. No second camera/renderer, pointer injection or HTTP request per gesture is introduced.
Camera contract
- The native orbital pivot lies on the native
LineGrid3Dplane (XY in the product's world frame). Pan translates the whole camera rig along that plane; orbital rotation leaves the pivot fixed. Scene changes cannot choose a new pivot after operator navigation. The guide grid is not a measured terrain model. - Initial fallback height is projected before rendering, not at the start of the first rotation. Active interpolation stops on manual navigation.
- Zoom changes distance to the pivot. The scene-diagonal zoom-out cap is removed. Upstream's 0.02 m collision-with-pivot guard and a finite 1e17 arithmetic guard remain; these are not route-distance limits. Passing through the pivot would reverse orbital direction, so it is deliberately not implemented.
- Explicit tracking remains distinct from fixed-pivot inspection. While following, Rerun may move the target with the tracked entity. First-person movement keeps upstream behavior. Reset and plan/3D switches remain explicit preset actions.
- A read-only native snapshot supplies the last rendered eye to the existing iframe facade. The approximate DOM-input camera journal is removed. Snapshots cross the disposable iframe as copied primitive JSON only; no native handle or listener escapes its lifetime. With no rendered 3D frame, the snapshot is null.
- Display-only blueprint activation carries that actual native eye. Omitting eye fields resurrects the incoming store's startup camera, as reproduced in browser QA; stable view identity alone is insufficient. This is one snapshot per settings update, not a second input controller or HTTP per gesture.
- Mission Core admits one active spatial pane per iframe. The snapshot selects the last rendered spatial state of the active recording, ignoring retained states from earlier views. Multiple simultaneous 3D panes would require an explicit view-id argument before that product composition is admitted.
Build, upgrade and rollback
vendor/rerun-web-viewer-0.36.3/NODEDC_NAVIGATION.patch is applied to the pinned
upstream commit. scripts/build-rerun-navigation.sh runs in a bounded temporary
Worker006 container, not on the 18 GB operator Mac. It tests native camera math,
uses Rerun's own release/WebAssembly builder and matching JS transformation,
and emits the paired runtime and declarations. No scanner data enters the build.
navigation-build.json binds upstream, source patch, compiler image and artifact
hashes. The installer validates every input before modifying any package file,
and rejects an unfamiliar SDK version or wrapper. Fresh installs and production
builds use that same installer once the candidate is accepted.
An upgrade requires rebasing this patch, native tests, JS/WASM ABI checks, frontend contracts and real-browser navigation/regression QA. Do not copy the old WASM into a newer SDK. To roll back, disable the installer hooks and restore the exact official 0.36.3 package; the facade treats a missing native snapshot as unavailable, never fabricates an operator eye. Raw/corrected recordings do not need to be regenerated.
Acceptance
Required: plane/pan/orbit/zoom invariants, different grid plane, top-down and first-person regression; exact native snapshot and realm cleanup; normal and expanded product views, Escape, explicit reset, layers/point-size updates and follow transitions. A successful compile alone is not product acceptance.
The accepted full-fidelity cloud and 30-minute accumulation are outside this navigation patch and must not be reduced to make testing cheaper.