NODEDC_MISSION_CORE/docs/audits/2026-09-20-planning-scene-camera-and-tools.md

Spatial scene: camera ownership and modeless tools

Follow-up, 2026-09-21: the owner reported native hover/picking of world/grid. The data-geometry grid introduced here is selectable; this is an open presentation regression, not covered by the acceptance below. The complete planning upgrade inventory and pending grid check are recorded in 2026-09-21-rerun-planning-customizations.md. No fix is claimed in this report.

Scope

Presentation-only change for the planning profile in the shared spatial scene. No registration, tracking thresholds, recording, source data or device commands were changed. Existing unrelated working-tree changes were retained.

Reproduced cause

PlanningLiveScene already kept its native viewer/channel mounted. The reset was server-side: any changed presentation option requested a full geometry refresh, and log_base sent a new blueprint with a generated view and initial EyeControls3D. Clipping, layers, point size and grid therefore replaced the operator's native camera. Discarded responses and transport failures also discarded the cursor, conflating a geometry repair with first admission.

Implementation

• Separate log_base (data entities) from log_view (camera blueprint).
• Cursor carries [mode, reset] as the admitted camera intent. Only first admission or a changed explicit view/reset intent sends a camera blueprint.
• Preserve the last admitted cursor on errors and superseded responses; needsBase independently requests a complete geometry repair. Expired live evidence is still rejected. No stale response gains localization authority.
• Send reset generation through the HTTP API instead of dropping it in the client. Explicit reset and top/3D presets remain functional.
• Grid visibility is now an ordinary Rerun LineStrips3D display entity, so it needs no blueprint activation or approximate camera-input journal. It is a reference-bound XY guide with 80 m padding; guide spacing adapts to large reference extents. This is display geometry, not inferred ground, clearance or a source-distance limit. Native grid is disabled in the initial blueprint.
• Remove duplicate planning navigation and engine action from the spatial toolbar. Preserve the optional source action for separate existing consumers.
• Use the canonical WorkspaceWindow, like planner settings, for layers and display controls. It is inline, draggable/resizable, modeless, bounded by the scene and supports maximize/restore and Escape. Switching tools retains the open window's position. Its lifecycle is independent from the renderer.
• Height clipping still defaults to the full 80 m range and has no outline.

Acceptance

• Application architecture tests: 4 passed.
• Full frontend typecheck: passed.
• Full frontend suite, serialized: 875 passed, 0 failures.
• Production build: passed. Existing large-chunk warning remains.
• Focused backend display/API tests: 8 passed. New tests cover all presentation toggles, geometry repair, display epoch changes and explicit camera intents.
• Frontend stream tests cover stale responses and recovery retaining the last admitted camera cursor; reset intent reaches the server.
• Unit tests verify modeless bounded tools and removal of duplicate actions.
• Full-suite output contained a Vite dependency-scanner teardown warning; all test assertions and process exit passed. No watcher was retained.

Browser QA on canonical 8000

Used the existing in-app tab and real saved ja-sun-018-80m-offset-back scene. No synthetic viewer, new application server, scan or device action was used.

Rotated and zoomed the cloud away from its preset, dragged the tools window, changed height from 80 to 3 m, hid trajectories, switched tools, increased point size and hid the grid. The cloud changed without returning the native camera to its preset. Tested top/3D and explicit reset separately.

Verified cloud expansion, clipping while expanded, Escape restoration, ordinary and expanded application-panel layouts, tool maximize/restore and close/Escape. DOM measurement of maximized tool and its scene matched exactly (504 × 376.03125 CSS px); aria-modal=false. Browser checking verifies visible behavior, not a numerical measurement of native camera coordinates.

Returned the scene to 3D, 80 m clip, visible grid/trajectories and closed tools. The canonical service was updated through its hash-fenced LaunchAgent workflow after proving acquisition absent and control idle. Health accepted; one backend on 8000 remains running. K1 live-stream behavior was not physically retested.