Route paint UI clear state through GL backend

docs/modernization/build-inventory.md

@@ -385,17 +385,20 @@ Known local toolchain state:
   consume backend-owned error codes, state queries, framebuffer targets,
   texture binding targets, and active texture units.
   `NodeStrokePreview` brush preview rendering also consumes backend-owned
-  depth/scissor/blend state, viewport/clear-color queries, active texture
-  unit execution, fallback 2D texture unbinds, 2D texture targets, copy
-  targets, and sampler filters/wraps. Its live stroke-mixer and brush-preview
-  viewport, scissor, and depth/blend state changes now execute through tested
-  `pp_renderer_gl` dispatch with only local OpenGL adapter endpoints retained.
+  depth/scissor/blend state, tested viewport/clear-color query dispatch,
+  clear-color restore, active texture unit execution, fallback 2D texture
+  unbinds, 2D texture targets, copy targets, and sampler filters/wraps. Its
+  live stroke-mixer and brush-preview viewport, scissor, and depth/blend state
+  changes now execute through tested `pp_renderer_gl` dispatch with only local
+  OpenGL adapter endpoints retained.
   Retained `Canvas` stroke/thumbnail/object/export paths and `NodeCanvas`
   panorama rendering use the same tested active-texture dispatch for
   texture-unit switches, and their live viewport, scissor, and generic
   depth/blend/scissor capability changes now route through the same backend
-  dispatch contracts. Retained desktop HMD eye rendering also routes viewport
-  execution through tested backend dispatch.
+  dispatch contracts. `NodeCanvas` saved viewport/clear-color query,
+  density/offscreen color clear, and clear-color restore paths also use tested
+  `pp_renderer_gl` dispatch helpers. Retained desktop HMD eye rendering also
+  routes viewport execution through tested backend dispatch.
   Legacy `Texture2D`, `TextureManager`, `Sampler`, and `RTT` public headers no
   longer expose raw OpenGL enum defaults; default texture formats, sampler
   filters/wraps, and render-target formats resolve through backend-owned
@@ -431,9 +434,10 @@ Known local toolchain state:
   the retained canvas-tip pick readback remains direct legacy OpenGL until the
   readback boundary is finished under DEBT-0036.
   `NodeCanvas` panorama UI rendering also consumes backend-owned sampler
-  defaults, viewport/clear-state queries, blend/depth/scissor state, color
-  clear masks, active texture units, fallback 2D texture unbind targets, copy
-  targets, and RGBA8 render-target formats.
+  defaults, tested viewport/clear-color query dispatch, blend/depth/scissor
+  state, color-buffer clear dispatch, clear-color restore, active texture
+  units, fallback 2D texture unbind targets, copy targets, and RGBA8
+  render-target formats.
   Canvas resource setup also consumes backend-owned stroke-buffer
   RGBA8/RGBA16F/RGBA32F formats, flood-fill texture upload format/type,
   brush/stencil/mix sampler filters and wraps, and image channel-count texture
@@ -653,6 +657,8 @@ Known local toolchain state:
   NodeStrokePreview texture-unit switches,
   tested viewport/scissor/capability dispatch consumed by retained Canvas,
   NodeCanvas, NodeStrokePreview, and HMD render-state paths,
+  tested viewport query, clear-color query, and clear-color restore dispatch
+  consumed by retained `NodeCanvas` and `NodeStrokePreview` draw-state paths,
   tested color-write-mask dispatch consumed by retained `NodePanelGrid`
   transparent heightmap rendering,
   tested pixel-buffer allocation/readback/map/unmap/delete dispatch

docs/modernization/debt.md

@@ -53,7 +53,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | DEBT-0033 | Open | Modernization | Tools menu planning and direct command execution dispatch now consume pure `pp_app_core` through `App::init_menu_tools`, `pano_cli plan-tools-menu`, `pano_cli plan-tools-panel`, and the `ToolsMenuServices` boundary, and direct command execution is centralized in `src/legacy_app_shell_services.*`; SonarPen availability/startup now routes through `PlatformServices`, but live adapters still construct legacy `NodePanelFloating` panels, mutate legacy panel nodes, clear `CanvasModeGrid`, reset `NodeCanvas` camera state, open legacy shortcuts UI, and rely on the legacy platform adapter for the retained iOS SonarPen bridge | Preserve current Tools menu behavior while UI shell actions move toward app/UI/platform services | `pp_app_core_tools_menu_tests`; `pp_platform_api_tests`; `pano_cli plan-tools-menu --command shortcuts`; `pano_cli plan-tools-panel --panel layers`; `pano_cli plan-tools-panel --panel animation --already-visible`; `ctest --preset desktop-fast --build-config Debug` | Tools panel creation, submenu routing, grid clear, camera reset, shortcuts dialog, and SonarPen dispatch are owned by injected app/UI/platform services with `App::init_menu_tools` acting only as a UI adapter and no legacy Tools adapter |
 | DEBT-0034 | Open | Modernization | About menu command planning and execution dispatch now consume pure `pp_app_core` through `App::init_menu_about`, `pano_cli plan-about-menu`, and the `AboutMenuServices` boundary, and live execution is centralized in `src/legacy_app_shell_services.*`, but the bridge still opens legacy About/manual/what's-new dialogs, invokes the injected crash hook, and runs the legacy Canvas stroke performance test directly | Preserve About menu behavior while dialogs and diagnostics move toward app/UI/platform services | `pp_app_core_about_menu_tests`; `pano_cli plan-about-menu --command news --version-major 2 --version-minor 5 --version-fix 7`; `pano_cli plan-about-menu --command performance --no-canvas`; `ctest --preset desktop-fast --build-config Debug` | About/manual/what's-new dialog dispatch, crash-test dispatch, and performance-test execution are owned by injected app/UI/platform services with `App::init_menu_about` acting only as a UI adapter and no legacy About adapter |
 | DEBT-0035 | Open | Modernization | Main toolbar/status command planning and execution dispatch now consume pure `pp_app_core` through `App::init_toolbar_main`, `pano_cli plan-main-toolbar`, and the `MainToolbarServices` boundary, history/canvas commands now hand off through `HistoryUiServices` and `DocumentCanvasClearServices`, and live execution is centralized in `src/legacy_app_shell_services.*`, but the bridge still opens legacy open/save/settings/message-box dialogs and delegates to legacy history/canvas adapters | Preserve reachable toolbar/status behavior while app shell commands move toward app/document/UI services | `pp_app_core_main_toolbar_tests`; `pano_cli plan-main-toolbar --command undo --undo-count 2`; `pano_cli plan-main-toolbar --command clear-canvas --no-canvas`; `ctest --preset desktop-fast --build-config Debug` | Open/save/settings/message-box routing, undo/redo/clear-history execution, and canvas-clear execution are owned by injected app/document/UI services with `App::init_toolbar_main` acting only as a UI adapter and no legacy toolbar adapter |
-| DEBT-0036 | Open | Modernization | `pp_renderer_api`, `pp_paint_renderer`, `pano_cli plan-paint-feedback`, and `pano_cli plan-stroke-composite` can choose backend-neutral complex paint feedback strategies for fixed-function blending, framebuffer-fetch-capable renderers, or ping-pong render targets. OpenGL extension detection now stores `pp::renderer::RenderDeviceFeatures` through `ShaderManager`, using `pp_renderer_gl::query_opengl_capability_detection`, `detect_opengl_feature_state`, and `render_device_features` as the backend conversion point; that feature snapshot now includes float32-linear filtering, so canvas stroke texture format selection, renderer diagnostics, grid lightmap render planning, and grid bake target selection no longer read `ShaderManager::ext_*` flags directly. `pp_paint_renderer::plan_canvas_blend_gate` owns the compatibility mapping from persisted layer/brush blend indices to the extracted stroke-composite planner, and live `Canvas::draw_merge` plus `NodeCanvas` panorama rendering both call it with the stored renderer-neutral feature set for their existing shader-blend gates and destination-copy versus framebuffer-fetch decisions. `pp_paint_renderer::plan_canvas_stroke_feedback` also owns the current destination-feedback decision, and live `Canvas::stroke_draw`, thumbnail layer blending, and `NodeStrokePreview` brush-preview rendering use it for framebuffer-fetch versus destination-copy decisions. The retained `copy_framebuffer_to_texture_2d` utility bridge now routes 2D framebuffer-to-texture copies through tested `pp_renderer_gl` dispatch, retained `RTT::create`/`RTT::destroy` render-target texture parameter setup, optional depth renderbuffer allocation, framebuffer allocation/attachment/status checks, binding restore, and resource deletion now route through tested `pp_renderer_gl` dispatch, retained RTT clear, masked clear with color-write-mask restore, and texture bind/unbind now route through tested `pp_renderer_gl` dispatch, retained Canvas, NodeCanvas, and NodeStrokePreview texture-unit switches now route through tested active-texture dispatch, retained Canvas, NodeCanvas, NodeStrokePreview, and desktop HMD viewport/scissor/capability execution now route through tested `pp_renderer_gl` dispatch adapters, CanvasLayer cube/equirect generation plus frame clears now route blend state, active texture units, viewport execution, color clears, and cube-face framebuffer-to-texture copies through tested `pp_renderer_gl` dispatch adapters, `NodePanelGrid` live heightmap draw and bake setup now route depth/blend state, depth clears, color-write-mask toggles, active texture selection, and bake viewport execution through tested `pp_renderer_gl` dispatch adapters, retained CanvasMode overlay/mask/transform paths now route active texture, depth/blend state, and transform/cut viewport execution through tested `pp_renderer_gl` dispatch adapters while the retained canvas-tip pick readback remains direct legacy OpenGL, and retained simple UI draw paths now share `legacy_ui_gl_dispatch` for blend-state execution, fallback 2D texture unbinds, `NodeViewport` viewport query/restore, color-buffer clears, and clear-color restore, but actual live stroke rasterization, dual-brush compositing, pattern feedback math, thumbnail layer compositing, brush-preview compositing, and the retained `ShaderManager::ext_*` compatibility fields still use legacy OpenGL canvas/UI execution | Preserve current painting behavior while the renderer boundary matures for OpenGL parity and later Vulkan/Metal experiments | `pp_renderer_api_tests`; `pp_renderer_gl_capabilities_tests`; `pp_paint_renderer_compositor_tests`; `pano_cli plan-paint-feedback --framebuffer-fetch --explicit-transitions --render-only`; `pano_cli plan-paint-feedback --texture-copy`; `pano_cli plan-stroke-composite --stroke-blend 10 --framebuffer-fetch --explicit-transitions --render-only`; `pano_cli plan-stroke-composite --layer-blend 4 --dual-blend --texture-copy`; `ctest --preset desktop-fast --build-config Debug`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter` | Live stroke/layer compositing chooses its feedback path through `pp_paint_renderer` and renderer services, with OpenGL golden parity and Vulkan/Metal lab tests covering framebuffer-fetch and ping-pong behavior |
+| DEBT-0036 | Open | Modernization | `pp_renderer_api`, `pp_paint_renderer`, `pano_cli plan-paint-feedback`, and `pano_cli plan-stroke-composite` can choose backend-neutral complex paint feedback strategies for fixed-function blending, framebuffer-fetch-capable renderers, or ping-pong render targets. OpenGL extension detection now stores `pp::renderer::RenderDeviceFeatures` through `ShaderManager`, using `pp_renderer_gl::query_opengl_capability_detection`, `detect_opengl_feature_state`, and `render_device_features` as the backend conversion point; that feature snapshot now includes float32-linear filtering, so canvas stroke texture format selection, renderer diagnostics, grid lightmap render planning, and grid bake target selection no longer read `ShaderManager::ext_*` flags directly. `pp_paint_renderer::plan_canvas_blend_gate` owns the compatibility mapping from persisted layer/brush blend indices to the extracted stroke-composite planner, and live `Canvas::draw_merge` plus `NodeCanvas` panorama rendering both call it with the stored renderer-neutral feature set for their existing shader-blend gates and destination-copy versus framebuffer-fetch decisions. `pp_paint_renderer::plan_canvas_stroke_feedback` also owns the current destination-feedback decision, and live `Canvas::stroke_draw`, thumbnail layer blending, and `NodeStrokePreview` brush-preview rendering use it for framebuffer-fetch versus destination-copy decisions. The retained `copy_framebuffer_to_texture_2d` utility bridge now routes 2D framebuffer-to-texture copies through tested `pp_renderer_gl` dispatch, retained `RTT::create`/`RTT::destroy` render-target texture parameter setup, optional depth renderbuffer allocation, framebuffer allocation/attachment/status checks, binding restore, and resource deletion now route through tested `pp_renderer_gl` dispatch, retained RTT clear, masked clear with color-write-mask restore, and texture bind/unbind now route through tested `pp_renderer_gl` dispatch, retained Canvas, NodeCanvas, and NodeStrokePreview texture-unit switches now route through tested active-texture dispatch, retained Canvas, NodeCanvas, NodeStrokePreview, and desktop HMD viewport/scissor/capability execution now route through tested `pp_renderer_gl` dispatch adapters, CanvasLayer cube/equirect generation plus frame clears now route blend state, active texture units, viewport execution, color clears, and cube-face framebuffer-to-texture copies through tested `pp_renderer_gl` dispatch adapters, `NodePanelGrid` live heightmap draw and bake setup now route depth/blend state, depth clears, color-write-mask toggles, active texture selection, and bake viewport execution through tested `pp_renderer_gl` dispatch adapters, retained CanvasMode overlay/mask/transform paths now route active texture, depth/blend state, and transform/cut viewport execution through tested `pp_renderer_gl` dispatch adapters while the retained canvas-tip pick readback remains direct legacy OpenGL, retained simple UI draw paths now share `legacy_ui_gl_dispatch` for blend-state execution, fallback 2D texture unbinds, `NodeViewport` viewport query/restore, color-buffer clears, and clear-color restore, and retained `NodeCanvas` plus `NodeStrokePreview` draw-state paths now route viewport query, clear-color query, color-buffer clear, and clear-color restore through tested `pp_renderer_gl` dispatch helpers, but actual live stroke rasterization, dual-brush compositing, pattern feedback math, thumbnail layer compositing, brush-preview compositing, and the retained `ShaderManager::ext_*` compatibility fields still use legacy OpenGL canvas/UI execution | Preserve current painting behavior while the renderer boundary matures for OpenGL parity and later Vulkan/Metal experiments | `pp_renderer_api_tests`; `pp_renderer_gl_capabilities_tests`; `pp_paint_renderer_compositor_tests`; `pano_cli plan-paint-feedback --framebuffer-fetch --explicit-transitions --render-only`; `pano_cli plan-paint-feedback --texture-copy`; `pano_cli plan-stroke-composite --stroke-blend 10 --framebuffer-fetch --explicit-transitions --render-only`; `pano_cli plan-stroke-composite --layer-blend 4 --dual-blend --texture-copy`; `ctest --preset desktop-fast --build-config Debug`; `cmake --build --preset windows-msvc-default --config Debug --target PanoPainter` | Live stroke/layer compositing chooses its feedback path through `pp_paint_renderer` and renderer services, with OpenGL golden parity and Vulkan/Metal lab tests covering framebuffer-fetch and ping-pong behavior |
 | DEBT-0037 | Open | Modernization | Recording lifecycle/export planning and execution dispatch now consume pure `pp_app_core` through `App::rec_start`, `App::rec_stop`, `App::rec_clear`, `App::rec_export`, `pano_cli plan-recording-session`, and the `RecordingServices` boundary; live execution is centralized in `src/legacy_recording_services.*`, and retained `PBO` allocation/readback/map/unmap/delete operations now route through tested `pp_renderer_gl` dispatch, but the bridge still owns legacy recording thread startup/shutdown, platform recorded-file cleanup, progress UI, retained `App::rec_loop` readback call sites, and `MP4Encoder::write_mp4` execution | Preserve current timelapse/MP4 behavior while recording moves toward app/document/renderer/video services | `pp_app_core_document_recording_tests`; `pp_renderer_gl_capabilities_tests`; `pano_cli plan-recording-session --running --frame-count 12`; `pano_cli plan-recording-session --platform-clears-files`; `ctest --preset desktop-fast --build-config Debug` | Recording thread lifecycle, frame readback scheduling, platform cleanup, progress reporting, and MP4 writing are owned by injected app/renderer/video services with `App` methods acting only as adapters |
 | DEBT-0038 | Open | Modernization | Cloud upload/browse/bulk planning and execution dispatch now consume pure `pp_app_core` through `App::cloud_upload`, `App::cloud_upload_all`, `App::cloud_browse`, `pano_cli plan-cloud-upload`, `pano_cli plan-cloud-upload-all`, `pano_cli plan-cloud-browse`, and the `CloudServices` boundary; live execution is centralized in `src/legacy_cloud_services.*`, the app-owned `upload`/`download`/license curl helpers now ask `PlatformServices` for the Android TLS-verification bypass policy, and retained `Asset::open_url`, `LogRemote::net_init`, and `NodeDialogCloud::load_thumbs_thread` curl sites consume the `pp_platform_api` default TLS policy helper instead of spelling Android branches locally, but the bridge still uses legacy save-before-upload, app-owned curl helpers instead of an injected network service, progress/message UI, OpenGL context guarding, `NodeDialogCloud`, `Canvas` project open, layer refresh, and `ActionManager` reset | Preserve current cloud behavior while cloud/network/document import flows move toward app/document/platform services | `pp_app_core_document_cloud_tests`; `pp_platform_api_tests`; `pano_cli plan-cloud-upload --new-document --unsaved`; `pano_cli plan-cloud-browse --selected-file demo.ppi`; `pano_cli plan-cloud-upload-all --file-count 3`; `ctest --preset desktop-fast --build-config Debug` | Cloud upload/download, TLS policy, save-before-upload, progress reporting, cloud browse dialog, downloaded project opening, layer refresh, OpenGL context ownership, and action-history reset are owned by injected app/document/network/platform/renderer services with `App` methods acting only as adapters |
 | DEBT-0039 | Open | Modernization | Document-open planning and execution dispatch now consume pure `pp_app_core` through `App::open_document`, `pano_cli plan-open-route`, `DocumentOpenServices`, and `src/legacy_document_open_services.*`, but the bridge still opens ABR/PPBR import prompts before delegating import execution to `src/legacy_brush_package_import_services.*`, applies unsaved-project discard prompts, calls legacy project-open execution, refreshes layer UI, updates the app title, and clears legacy history directly | Preserve current file-open/import behavior while document loading and brush import move toward app/document/asset/UI services | `pp_app_core_document_route_tests`; `pp_app_core_document_session_tests`; `pano_cli plan-open-route --path D:/Paint/Scenes/demo.ppi --unsaved`; `pano_cli plan-open-route --path D:/Paint/Brushes/clouds.ABR --unsaved`; `ctest --preset desktop-fast --build-config Debug` | Brush import prompting, project-open execution, unsaved-project discard prompting, layer refresh, title updates, and history clearing are owned by injected app/document/asset/UI services with `App::open_document` acting only as an adapter |

docs/modernization/roadmap.md

@@ -1110,17 +1110,20 @@ Legacy `util.cpp` OpenGL error naming and `gl_state` save/restore now delegate
 error codes, state queries, framebuffer targets, texture binding targets, and
 active texture units to `pp_renderer_gl`.
 `NodeStrokePreview` brush preview rendering now delegates depth/scissor/blend
-state, viewport/clear-color queries, active texture unit execution, fallback
-2D texture unbinds, 2D texture targets, copy targets, sampler filters/wraps,
-and destination-feedback copy/fetch decisions to `pp_renderer_gl` and
-`pp_paint_renderer`. Its live stroke-mixer and brush-preview viewport,
-scissor, and depth/blend state changes now also execute through tested
-`pp_renderer_gl` dispatch with only local OpenGL adapter endpoints retained.
+state, tested viewport/clear-color query dispatch, clear-color restore, active
+texture unit execution, fallback 2D texture unbinds, 2D texture targets, copy
+targets, sampler filters/wraps, and destination-feedback copy/fetch decisions
+to `pp_renderer_gl` and `pp_paint_renderer`. Its live stroke-mixer and
+brush-preview viewport, scissor, and depth/blend state changes now also
+execute through tested `pp_renderer_gl` dispatch with only local OpenGL adapter
+endpoints retained.
 Retained `Canvas` stroke/thumbnail/object/export paths and `NodeCanvas`
 panorama rendering use the same tested active-texture dispatch for their
 texture-unit switches, and their live viewport, scissor, and generic
 depth/blend/scissor capability changes now route through the same backend
-dispatch contracts.
+dispatch contracts. `NodeCanvas` saved viewport/clear-color query, density
+target color clear, and clear-color restore paths also use tested
+`pp_renderer_gl` dispatch helpers.
 Desktop HMD eye rendering now routes eye framebuffer viewport changes through
 the tested `pp_renderer_gl` viewport dispatch while platform VR SDK bridges
 remain isolated for later platform-shell extraction.
@@ -2027,11 +2030,13 @@ Results:
   renderer GL backend mapping. The retained canvas-tip pick readback remains
   direct legacy OpenGL until the readback boundary is finished under DEBT-0036.
 - `NodeCanvas` panorama UI rendering now routes sampler defaults, saved
-  viewport/clear/blend/depth/scissor state, color clears, active texture units,
+  viewport/clear/blend/depth/scissor state, tested viewport and clear-color
+  query dispatch, color clears, clear-color restore, active texture units,
   fallback 2D texture unbinds, 2D framebuffer-to-texture copy dispatch, and
   RGBA8 render-target formats through the renderer GL backend mapping.
-  Its live viewport and generic blend/depth/scissor capability changes now
-  execute through tested `pp_renderer_gl` dispatch adapters.
+  Its live viewport, generic blend/depth/scissor capability changes, and
+  density/offscreen color-buffer clears now execute through tested
+  `pp_renderer_gl` dispatch adapters.
 - Canvas resource setup now routes stroke-buffer RGBA8/RGBA16F/RGBA32F
   formats, flood-fill texture upload format/type, brush/stencil/mix sampler
   filters and wraps, and cube-strip import channel formats through the renderer
@@ -2066,6 +2071,10 @@ Results:
   `NodeBorder`, `NodeImage`, `NodeImageTexture`, `NodeColorWheel`,
   `NodeAnimationTimeline`, `NodeScroll`, `NodeText`, `NodeTextInput`, and
   `NodeViewport` without changing their legacy draw ordering.
+- Retained paint UI surface paths now use tested `pp_renderer_gl` viewport
+  query, clear-color query, clear-color restore, and color-buffer clear helpers
+  in `NodeCanvas` and `NodeStrokePreview`, removing direct query/clear calls
+  from those draw bodies while keeping their legacy compositing order.
 - Canvas draw-merge shader-blend selection now consumes the extracted
   `pp_paint_renderer` stroke composite planner for current layer and primary
   brush blend modes, while preserving legacy OpenGL compositing execution under