docs(999.58-03): complete scene.C dialog cut-over plan (code+build); UAT pending

- Add 999.58-03-SUMMARY.md (dialog-free Scene; Scene-owned StereoScreenConfig;
  in-Scene applyStereoDefaults; demoTutorial repointed; all grep proofs pass)
- STATE.md: stopped_at/last_activity -> 999.58-03 at blocking checkpoint; P03
  metric row; Plan 03 decision entry
- ROADMAP.md: 999.58-03 marked [~] code+build complete, UAT pending, 999.53 unblocked
- VIEW-CLEAN-03 intentionally left PARTIAL (gated on the BLOCKING phase-level GUI render UAT)

Author: okohlbacher

.planning/ROADMAP.md

@@ -2549,7 +2549,7 @@ Plans:
 Plans:
 - [~] 999.58-01-PLAN.md — Material + Light config relocation onto the Inspector MaterialController/LightController; route applyPreferences material+light + the light-refresh sites off the dialogs (wave 1). **Code+build COMPLETE 2026-05-22** (MaterialController owns the full default-material field set incl. the 3 colors + `applyDefaultMaterial()`; LightController owns the full per-light list + `syncFromStage()`; scene.C `applyPreferences` + all 5 light-refresh sites routed through the controllers; no live MaterialSettings/LightSettings reach-throughs remain on Scene's render path; BALLView.app links clean BALL_UI_V2=ON). **BLOCKING running-BALLView render UAT PENDING** (lights + materials must still visibly drive the scene) — VIEW-CLEAN-03 stays incomplete (phase-spanning).
 - [~] 999.58-02-PLAN.md — Full non-stereo Stage render config relocation onto StageController (vertex buffers, downsampling, projection, FPS, preview, offscreen, renderer switch, etc.); route applyPreferences stage branch + getGLSettings off stage_settings_ (wave 2). **Code+build COMPLETE 2026-05-22** (StageController grew the full non-stereo render-config field set — projection / show-lights / animation-smoothness / offscreen+factor / capping / FPS / preview / vertex-buffers incl. rep-delete side effect / smooth-lines / downsampling / renderer-switch / mouse+wheel-sensitivity — applied through the same Scene/Stage/Camera/GLRenderer/ClippingPlane backend behind the re-entrancy shield + a new MainControl::isBusy() defer-guard; scene.C `applyPreferences` routed through a transient StageController; non-load-bearing `getGLSettings()` init readback removed; swap-side-by-side left to StereoController; BALLView.app links clean BALL_UI_V2=ON). **BLOCKING running-BALLView render UAT PENDING** (stage controls must still visibly drive the scene; no regression to background/fog/eye/focal) — VIEW-CLEAN-03 stays incomplete (phase-spanning).
-- [ ] 999.58-03-PLAN.md — Remove the 3 dialog constructions (scene.C:142/143/162) + Preferences-stack rewire; Scene-owned stereo-screen config for the deferred stereo bodies; in-Scene applyStereoDefaults; demoTutorial repoint; grep proof scene.C is dialog-free (wave 3).
+- [~] 999.58-03-PLAN.md — Remove the 3 dialog constructions (scene.C:142/143/162) + Preferences-stack rewire; Scene-owned stereo-screen config for the deferred stereo bodies; in-Scene applyStereoDefaults; demoTutorial repoint; grep proof scene.C is dialog-free (wave 3). **Code+build COMPLETE 2026-05-22** (scene.C constructs/registers none of LightSettings/MaterialSettings/StageSettings; members/forward-decls/getStageSettings()/getMaterialSettings() accessors removed from scene.h; the four guard-and-deferred stereo bodies read a Scene-owned `StereoScreenConfig` struct instead of `stage_settings_->get*` — guard-and-return preserved, stereo NOT re-enabled; `applyStereoDefaults` inlines the geometry math in-Scene; demoTutorialDialog repointed off all 6 dialog-accessor reach-throughs with the dormant RTfact Stage-setup logic preserved; unused dialog includes dropped from both consumers; BALLView.app links clean BALL_UI_V2=ON). VIEW-CLEAN-03 construction grep proof PASSES — **999.53 unblocked to delete the 3 dialog triples**. **BLOCKING running-BALLView render UAT PENDING** (materials/lights/stage must still visibly drive the scene; stereo menu must defer cleanly without crash) — VIEW-CLEAN-03 stays incomplete (phase-spanning).
 
 > **Deferred / blocked v1.7.x items (NOT promoted to phases):** v1.7.x-03 (Stereo checkbox) is **blocked** on the SEED-001 step-5 Renderer/RenderSurface stereo-mode boundary; v1.7.x-04 (Geometric/Dataset highlight) and v1.7.x-05 (macOS QSS overlay) are **dormant** pending a user re-file / concrete trigger. They stay in [`v1.7.x-PATCH-QUEUE.md`](v1.7.x-PATCH-QUEUE.md) with their gating conditions. v1.7.x-34 (www.ball-project.org outage) is external/Tübingen-side infra, not a code phase.
 

.planning/STATE.md

@@ -2,16 +2,16 @@
 gsd_state_version: 1.0
 milestone: v1.6.2
 milestone_name: · 2026-05-16)
-status: executing
-stopped_at: "999.58-02 at BLOCKING checkpoint:human-verify (stage non-stereo render-config render UAT pending; 999.58-01 lights+materials UAT also pending)"
-last_updated: "2026-05-22T08:10:00.000Z"
-last_activity: 2026-05-22 -- 999.58-02 code+build complete (StageController owns the full non-stereo stage render config; scene.C applyPreferences routed through it; getGLSettings init readback removed; BALLView links clean BALL_UI_V2=ON); GUI render UAT pending
+status: paused
+stopped_at: "999.58-03 at BLOCKING checkpoint:human-verify (FINAL scene.C dialog cut-over render UAT pending; 999.58-01/02 UATs also pending)"
+last_updated: "2026-05-22T00:00:00.000Z"
+last_activity: 2026-05-22 -- 999.58-03 FINAL scene.C dialog cut-over landed (scene.C constructs none of LightSettings/MaterialSettings/StageSettings; Preferences stack registers none of them; deferred stereo bodies read a Scene-owned StereoScreenConfig; applyStereoDefaults computes in-Scene; demoTutorialDialog repointed); BALLView.app links clean (BALL_UI_V2=ON); VIEW-CLEAN-03 construction grep proof passes; GUI render UAT pending — 999.53 unblocked to delete the dialog triples
 progress:
   total_phases: 73
-  completed_phases: 32
+  completed_phases: 33
   total_plans: 84
-  completed_plans: 81
-  percent: 44
+  completed_plans: 84
+  percent: 45
 ---
 
 # STATE: BALLView 1.6 Modernization
@@ -24,10 +24,10 @@ progress:
 
 ## Current Position
 
-Phase: 999.58 (scene-settings-stereo-cutover) — EXECUTING
-Plan: 2 of 3 (code+build done; BLOCKING GUI render UAT pending — 999.58-01 UAT also pending)
-Status: Executing Phase 999.58 — 999.58-02 paused at blocking checkpoint:human-verify
-Last activity: 2026-05-22 -- 999.58-02 Stage non-stereo render-config cut-over landed (StageController owns projection/downsampling/FPS/preview/offscreen/vertex-buffers/smooth-lines/show-lights/animation-smoothness/capping/renderer-switch + applyPreferences routes through it); BALLView.app links clean (BALL_UI_V2=ON); awaiting stage render verification
+Phase: 999.58 (scene-settings-stereo-cutover) — EXECUTING (all 3 plans code+build complete; phase-level GUI render UAT pending)
+Plan: 3 of 3 (FINAL — code+build done; BLOCKING GUI render UAT pending — 999.58-01/02 UATs also pending)
+Status: Executing Phase 999.58 — 999.58-03 paused at blocking checkpoint:human-verify
+Last activity: 2026-05-22 -- 999.58-03 FINAL scene.C dialog cut-over landed (scene.C constructs/registers none of LightSettings/MaterialSettings/StageSettings; deferred stereo bodies read a Scene-owned StereoScreenConfig; applyStereoDefaults computes in-Scene; demoTutorialDialog repointed; unused dialog includes dropped); BALLView.app links clean (BALL_UI_V2=ON); VIEW-CLEAN-03 construction grep proof passes; 999.53 unblocked
 
 ## Performance Metrics
 
@@ -97,11 +97,13 @@ Last activity: 2026-05-22 -- 999.58-02 Stage non-stereo render-config cut-over l
 | Phase 999.57 P03 | ~5min | 4 tasks | 6 files |
 | Phase 999.58 P01 | ~18min | 3 of 4 tasks (Task 4 blocking GUI human-verify) | 5 files |
 | Phase 999.58 P02 | ~22min | 2 of 3 tasks (Task 3 blocking GUI human-verify) | 3 files |
+| Phase 999.58 P03 | ~25min | 3 of 4 tasks (Task 4 blocking GUI human-verify) | 3 files |
 
 ## Accumulated Context
 
 ### Decisions
 
+- [Phase 999.58-scene-settings-stereo-cutover Plan 03 — FINAL]: scene.C is now dialog-free for the three settings dialogs. Removed the constructor constructions (`new LightSettings`/`new MaterialSettings`/`new StageSettings`), the Preferences-stack `insertEntry`/`removeEntry` of all three (EditSettings preserved), the `REMOVE_COORDINATE_SYSTEM` `stage_settings_->updateFromStage()` readback, the stale `if (light_settings_ == 0) return;` applyPreferences guard, and the members/forward-decls/`getStageSettings()`/`getMaterialSettings()` accessors from scene.h. Added a Scene-owned `StereoScreenConfig` struct (9 fields — 3 screen indices default -1, 2 default-empty QRect eye geometries, 2 renderer types default `OPENGL_RENDERER`, 1 stereo mode default `NO_STEREO`) so the four guard-and-deferred stereo bodies (`enterStereo`/`enterDualStereo`/`enterDualStereoDifferentDisplays`) compile without `stage_settings_->get*` — eye/focal/swap deliberately NOT mirrored (Stage/StereoController-owned, avoids T-99858-05). Each body's unconditional guard-and-return is unchanged — no stereo path re-enabled (T-99858-07). `applyStereoDefaults()` inlines `StageSettings::computeDefaultPressed()`'s geometry math in-Scene (dialog-only slider refreshes dropped; .ui distance defaults 150/6 inlined as constants; downsampling uses the live `downsampling_factor_`). `demoTutorialDialog.C` repointed off all 6 scene dialog-accessor reach-throughs (dormant `#ifdef BALL_HAS_RTFACT` Stage-setup logic + `applyPreferences()` preserved). Dropped the now-unused dialog header includes from both consumers (Rule 2, for the 999.53 deletion hand-off). Task commits `f1cb34ad28` (stereo config + applyStereoDefaults), `16a661a9b7` (constructions + Preferences stack), `8c702ddb46` (demoTutorial). BALLView.app links clean (BALL_UI_V2=ON). VIEW-CLEAN-03 construction grep proof PASSES; **999.53 unblocked to delete the dialog triples**. **VIEW-CLEAN-03 remains PARTIAL** — gated on the BLOCKING phase-level GUI render UAT (this plan's checkpoint + 999.58-01/02's), NOT marked complete.
 - [Phase 999.58-scene-settings-stereo-cutover Plan 02]: StageController (the 999.44 read-only-mirror exemplar) was grown to own the COMPLETE non-stereo stage render config the legacy `StageSettings::apply()` (stageSettings.C:233-309) wrote — projection mode, show-light-sources, animation smoothness, offscreen rendering (+factor), capping color, FPS, preview, vertex buffers (incl. the rep-delete-on-toggle side effect), smooth lines, downsampling, the OpenGL/RTfact renderer switch, and mouse/wheel sensitivity — on top of the already-migrated background/coord/fog/eye/focal. `apply()` drives each through the same Scene/Stage/Camera/GLRenderer/ClippingPlane/InteractionModeManager backend the dialog used, behind the existing `ControllerApplyGuard` re-entrancy shield PLUS a newly-added `MainControl::isBusy()` defer-guard (the renderer-switch + bulk rep-rebuild must not run mid-busy-cycle — T-99858-04). `scene.C::applyPreferences()` now applies the stage through a transient `StageController(stage_, this)` (revert + apply, the 999.58-01 pattern) instead of `stage_settings_->apply()`, and the non-load-bearing `getGLSettings()` init readback was removed from `initializePreferencesTab()`. Mouse/wheel sensitivity are write-only mirrors (InteractionModeManager has no getter) using an unset sentinel (`< 0`) so the controller-driven path never clobbers the live value. swap-side-by-side stays owned by StereoController (0 occurrences in stageController.C — avoids the double-write race T-99858-05). The `stage_settings_` construction (scene.C:169), Preferences-stack registration, and stereo accessors are UNTOUCHED — Plan 03 owns them. One remaining `stage_settings_->updateFromStage()` at scene.C:388 is a dialog-widget readback (no render mutation), out of this plan's scope, left intact and documented honestly. Task commits `b2f905941a` (controller), `d4aec20ff8` (scene.C). BALLView.app links clean (BALL_UI_V2=ON). **VIEW-CLEAN-03 remains PARTIAL** (phase-spanning 999.58-01/02/03; gated on the BLOCKING GUI render UAT — NOT marked complete).
 - [Phase 999.57-inspector-controller-cutover Plan 02]: Relocated `createColorProcessor` + its `applySettingsTo` override-application out of `ColoringSettingsDialog` into a headless `ColorProcessorFactory` (`include/BALL/VIEW/MODELS/colorProcessorFactory.{h,C}`), mirroring Plan 01's ModelProcessorFactory. `ColorProcessorFactory::create(ColoringMethod, const ColoringOverrides&)` constructs the per-method processor (which already loads its compiled default color map) then layers an explicit `ColoringOverrides` value object — zero Qt-widget dependency. `ColoringOverrides` carries the dialog's color tables (element/residue-name/chain/molecule as empty==no-override containers) + color-button/slider groups (residue-number/charge/distance/occupancy/secondary-structure/temperature-factor/force/residue-type, each gated by a `has_*` presence flag). CONFIG-01 invariant preserved: a default-constructed `ColoringOverrides` layers nothing → compiled-default processor, byte-equivalent to the molecule-load default-rep render. `ColoringSettingsDialog::createColorProcessor` thinned to `ColorProcessorFactory::create(method, buildColoringOverrides_())`; `applySettingsTo` kept INTACT (displayProperties.C:502 still calls it on the render path — Plan 03 repoints it). Render path (displayProperties.C:487 + coloringController.C:100) UNCHANGED this plan (verified via `git diff --name-only HEAD`). libVIEW builds clean (BALL_UI_V2=ON). Task commits `f414c3d572` (header), `d47e98f554` (impl+cmake), `fadbc571f9` (dialog delegation). **VIEW-CLEAN-02 remains PARTIAL** (phase-spanning; finishes in Plan 03 + GUI verify — NOT marked complete).
 - [Phase 999.52-inspector-transparency Plan 01]: The Inspector Material-tab Transparency control drives the **working** interactive-GL path — `Representation::setTransparency()` (0-255 per-vertex alpha) + `rep_->update(false)` — NOT `Stage::Material.transparency`, which only POVRay/RTfact read (RTfact disabled) and which GLRenderer::setMaterial_ never consumes. Writing the dead field is exactly the #527 bug; the negative-grep acceptance criterion (`material.transparency =` must NOT appear) enforces this. The Material control shares the SAME Representation transparency state as the existing Model-section slider (`revert()` reads `rep_->getTransparency()`), so they stay mutually consistent — a deliberate second entry point onto one backend, not a divergent duplicate. `rep_->update(false)` (cheap, no composite re-walk) chosen because the material intensities flow through the separate scene-material path; this is the Rule 3 build fix for the plan's argument-less `rep_->update()` (Representation::update(bool) has no default). MaterialController int `transparency` property mirrors ModelController exactly (Q_PROPERTY/getter/setTransparency slot/transparencyChanged signal/transparency_ member; setter guards-on-equal + emits). Legacy MaterialSettings dialog left untouched (Phase 999.53 deletes it). VIEW-INSP-03 implementation-complete; **BLOCKING GUI human-verify pending** (compile is necessary-but-not-sufficient for a GUI control). Task commits `ce4061a93d` (controller), `7374d42ae8` (section + build fix). libVIEW + BALLView.app built clean under BALL_UI_V2=ON (build-ui-on).