76 lines
4.3 KiB
Markdown
76 lines
4.3 KiB
Markdown
# 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 `LineGrid3D` plane (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.
|