Route PBO readbacks through GL backend

docs/modernization/build-inventory.md

@@ -278,8 +278,9 @@ Known local toolchain state:
   invalid channel counts rejected by `Texture2D::create(Image)`, renderer API
   texture-format to OpenGL internal/pixel/component token mapping including
   depth-stencil formats, RGBA8/RGBA32F
-  readback formats, checked byte-count math, and PBO pixel-buffer target/usage/access
-  mapping used by `RTT` and `PBO` readbacks, and framebuffer status naming
+  readback formats, checked byte-count math, PBO pixel-buffer target/usage/access
+  mapping, and PBO allocation/readback/map/unmap/delete dispatch sequences used
+  by retained `PBO` recording readbacks, and framebuffer status naming
   used by `RTT` and `Texture2D` diagnostics. It also owns the 2D texture target,
   framebuffer setup, readback format, mipmap target, and update component-type
   tokens used by `Texture2D`, plus cube-map binding and allocation face targets
@@ -541,11 +542,13 @@ Known local toolchain state:
 - `pano_cli plan-recording-session` exposes `pp_app_core` recording start,
   stop, clear, platform cleanup, frame-count reset, and export progress-total
   planning as JSON; the live recording controls consume those contracts before
-  reaching legacy recording threads, PBO readback, and MP4 encoder execution.
+  reaching legacy recording threads, retained PBO readback call sites, and MP4
+  encoder execution.
 - `src/legacy_recording_services.*` is the current app-shell bridge for
   recording start/stop/clear and MP4 export execution. It keeps those live paths
-  on the `pp_app_core` contracts while legacy recording thread ownership, PBO
-  readback, progress UI, platform cleanup, and `MP4Encoder` execution remain
+  on the `pp_app_core` contracts while legacy recording thread ownership,
+  retained PBO readback call sites, progress UI, platform cleanup, and
+  `MP4Encoder` execution remain
   tracked by `DEBT-0037`.
 - `pano_cli plan-share-file` exposes `pp_app_core` share availability planning
   as JSON for unsaved and saved document paths; the live platform share command
@@ -623,8 +626,9 @@ Known local toolchain state:
   consumed by the retained `gl_state` utility, tested texture lifecycle/readback dispatch consumed by
   the retained `Texture2D` utility, tested framebuffer blit/readback dispatch
   consumed by retained `RTT` resize/copy/readback and RGBA8 region-readback
-  paths, tested framebuffer-to-texture 2D copy dispatch consumed by retained
-  canvas/UI paint paths, tested framebuffer
+  paths, tested pixel-buffer allocation/readback/map/unmap/delete dispatch
+  consumed by retained `PBO` recording readbacks, tested framebuffer-to-texture
+  2D copy dispatch consumed by retained canvas/UI paint paths, tested framebuffer
   bind/restore dispatch consumed by retained `RTT` render-target pass entry
   and exit paths, tested depth renderbuffer allocation/delete and framebuffer
   depth attach/detach dispatch consumed by canvas object-drawing helpers,

docs/modernization/debt.md

@@ -54,7 +54,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | 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, but actual live stroke rasterization, dual-brush compositing, pattern feedback math, thumbnail layer compositing, brush-preview compositing, the retained cube-map framebuffer copy, 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.*`, but the bridge still owns legacy recording thread startup/shutdown, platform recorded-file cleanup, progress UI, PBO readback through `App::rec_loop`, 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`; `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, platform cleanup, progress reporting, and MP4 writing are owned by injected app/renderer/video services with `App` methods acting only as adapters |
+| 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 |
 | DEBT-0040 | Open | Modernization | Close request, document save, and save-before-workflow planning/execution dispatch now consume pure `pp_app_core` through `App::request_close`, `App::save_document`, `App::continue_document_workflow_after_optional_save`, `pano_cli simulate-app-session`, `DocumentSaveServices`, `CloseRequestServices`, `DocumentWorkflowServices`, and `src/legacy_document_session_services.*`; Save dialog working-directory picker visibility/path formatting now dispatches through `PlatformServices`, but the bridge still opens legacy message boxes/save dialogs, calls `Canvas::I->project_save`, mutates the unsaved flag on close confirmation, invokes native app close, and routes save-version through the retained legacy dialog | Preserve current close/save/dirty-workflow behavior while document session execution moves toward app/document/UI/platform services | `pp_app_core_document_session_tests`; `pp_platform_api_tests`; `pano_cli simulate-app-session --unsaved --save-intent save-dirty-version`; `pano_cli simulate-app-session --no-canvas`; `pano_cli plan-document-file --work-dir D:/Paint --name demo --target-exists`; `pano_cli plan-document-version --directory D:/Paint --doc-name demo.01 --existing-path D:/Paint/demo.02.ppi`; `ctest --preset desktop-fast --build-config Debug` | Close prompt execution, native close requests, dirty-workflow save prompts, existing-project saves, save dialogs, save-version execution, and unsaved-flag mutation are owned by injected app/document/UI/platform services with `App` methods acting only as adapters |

docs/modernization/roadmap.md

@@ -814,6 +814,10 @@ Legacy `RTT` also exposes an RGBA8 region-readback helper that uses the same
 backend framebuffer readback dispatch; canvas pick/history/snapshot and
 transform history paths now call that helper instead of binding an RTT and
 calling `glReadPixels` directly.
+Retained `PBO` recording readbacks now route pixel-buffer allocation,
+framebuffer readback, map, unmap, and deletion through tested
+`pp_renderer_gl` dispatch helpers; recording thread ownership, progress UI, and
+MP4 execution remain tracked by DEBT-0037.
 Legacy `RTT::bindFramebuffer` and `RTT::unbindFramebuffer` now use tested
 `pp_renderer_gl` draw/read framebuffer binding snapshot and restore contracts,
 moving render-target pass entry/exit state management behind the backend.
@@ -995,9 +999,10 @@ for future backend texture objects. `Texture2D` 2D texture binding, upload,
 mipmap generation, framebuffer readback setup, and update component-type tokens
 now delegate to `pp_renderer_gl`. `TextureCube` cube-map binding, allocation
 face targets, RGBA allocation format, and unsigned-byte component type also
-delegate to `pp_renderer_gl`. RGBA8/RGBA32F readback formats, checked byte-count math, and PBO
-pixel-buffer target/usage/access tokens used by `RTT` and `PBO` readbacks now
-live in `pp_renderer_gl`. The framebuffer blit color mask and linear/nearest
+delegate to `pp_renderer_gl`. RGBA8/RGBA32F readback formats, checked byte-count math, PBO
+pixel-buffer target/usage/access tokens, and PBO allocation/readback/map/unmap/delete
+dispatch sequences used by retained recording readbacks now live in
+`pp_renderer_gl`. The framebuffer blit color mask and linear/nearest
 filter tokens used by `RTT::resize` and `RTT::copy`, renderer API blit-filter
 to OpenGL token mapping, plus the default
 render-target texture parameters, texture/renderbuffer targets, depth format,