Report depth export readiness in CLI snapshots

docs/modernization/build-inventory.md

@@ -280,7 +280,10 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
   snapshots also feed the active frame through the shared `pp_paint_renderer`
   export-readiness report, reporting texture, transition, command, byte, and
   active-frame payload counts in `rendererUpload` JSON plus `facePngExport`
-  readiness, face count, byte count, and payload count. It is covered by
+  readiness, face count, byte count, and payload count. They also report
+  `depthExport` readiness from the tested paint-renderer depth plan: pending
+  snapshots keep it unavailable, and payload-complete snapshots expose the
+  1024x1024 draw/readback plan counts. It is covered by
   `pano_cli_plan_canvas_document_snapshot_smoke` plus the payload-bearing
   snapshot smoke.
 - Live equirectangular, layer, animation-frame, and cube-face export adapters

docs/modernization/debt.md

@@ -551,6 +551,13 @@ agent or engineer to remove them without reconstructing context from chat.
   document snapshot before retained `Canvas::export_depth` runs. The actual
   1024x1024 perspective/depth rendering, readback, worker-thread behavior, and
   the legacy `.png` path names carrying JPEG-encoded bytes remain open.
+- 2026-06-05: DEBT-0010/DEBT-0036 were narrowed again.
+  `pano_cli plan-canvas-document-snapshot` now emits the same depth export
+  render-plan readiness as the live adapter. Metadata-only snapshots report
+  depth export unavailable until renderer payload readback is captured;
+  payload-complete snapshots report the 1024x1024 merged-face and per-layer
+  depth draw counts while still marking final depth image readback as
+  renderer-owned.
 
 ## Open Debt
 

docs/modernization/roadmap.md

@@ -684,6 +684,11 @@ automation and live export adapters the same document/canvas-to-renderer
 readiness boundary before broader writer replacement. Live save writer
 replacement, export adoption, and renderer-owned readback remain under
 `DEBT-0010`/`DEBT-0013`/`DEBT-0036`.
+The same CLI snapshot report now emits `depthExport` readiness from
+`pp_paint_renderer::plan_document_depth_export_render`: metadata-only snapshots
+report pending renderer payload readback, while payload-complete snapshots
+report the legacy 1024x1024 depth-render draw plan and still flag the final
+3D view/depth image readback as renderer-owned.
 Live equirectangular, layer, animation-frame, and cube-face export adapters now
 prepare the same payload-bearing document snapshot and shared renderer export
 readiness report. Cube-face export writes those
@@ -2535,7 +2540,10 @@ Results:
   through `pp_paint_renderer::prepare_document_frame_export_readiness`, which
   records the renderer-neutral active-frame texture upload stream and encodes
   the composited active-frame cube faces as PNG bytes, so agents validate the
-  same document/canvas-to-renderer readiness report consumed by live export.
+  same document/canvas-to-renderer readiness report consumed by live export. It
+  also emits `depthExport` readiness from the paint-renderer depth plan, keeping
+  CLI automation aligned with the live depth export adapter while final renderer
+  readback remains retained.
 - Live image/collection/cube export adapters now prepare and log the same
   document/canvas plus shared renderer-upload and face-PNG export readiness
   reports. Cube-face export now writes the pure document/renderer PNG bytes to

tests/CMakeLists.txt

@@ -1480,13 +1480,13 @@ if(TARGET pano_cli)
         COMMAND pano_cli plan-canvas-document-snapshot --width 128 --height 64 --layers 3 --frames 2 --current-layer 2 --current-frame 1 --hidden-layer 0 --alpha-locked-layer 2 --opacity 0.5 --blend-mode 4 --pending-face-payloads-per-layer 6)
     set_tests_properties(pano_cli_plan_canvas_document_snapshot_smoke PROPERTIES
         LABELS "app;document;integration;desktop-fast"
-        PASS_REGULAR_EXPRESSION "\"command\":\"plan-canvas-document-snapshot\".*\"width\":128.*\"height\":64.*\"layers\":3.*\"frames\":2.*\"activeLayer\":2.*\"activeFrame\":1.*\"activeLayerName\":\"Layer 3\".*\"activeLayerOpacity\":0.5.*\"activeLayerBlend\":\"overlay\".*\"activeLayerAlphaLocked\":true.*\"pendingFacePayloads\":18.*\"metadataOnly\":true.*\"requiresRendererPayloadReadback\":true.*\"documentFacePayloads\":0.*\"saveReport\":\\{\"payloadComplete\":false,\"canExportPpi\":false\\}.*\"ppiExport\":\\{\"ready\":false,\"bytes\":0,\"dirtyFaces\":0\\}.*\"rendererUpload\":\\{\"ready\":false,\"textures\":0,\"bytes\":0,\"transitions\":0,\"facePayloads\":0,\"compositedLayerFaces\":0,\"commands\":0,\"uploadCommands\":0,\"transitionCommands\":0\\}.*\"facePngExport\":\\{\"ready\":false,\"faces\":0,\"bytes\":0,\"facePayloads\":0\\}")
+        PASS_REGULAR_EXPRESSION "\"command\":\"plan-canvas-document-snapshot\".*\"width\":128.*\"height\":64.*\"layers\":3.*\"frames\":2.*\"activeLayer\":2.*\"activeFrame\":1.*\"activeLayerName\":\"Layer 3\".*\"activeLayerOpacity\":0.5.*\"activeLayerBlend\":\"overlay\".*\"activeLayerAlphaLocked\":true.*\"pendingFacePayloads\":18.*\"metadataOnly\":true.*\"requiresRendererPayloadReadback\":true.*\"documentFacePayloads\":0.*\"saveReport\":\\{\"payloadComplete\":false,\"canExportPpi\":false\\}.*\"ppiExport\":\\{\"ready\":false,\"bytes\":0,\"dirtyFaces\":0\\}.*\"rendererUpload\":\\{\"ready\":false,\"textures\":0,\"bytes\":0,\"transitions\":0,\"facePayloads\":0,\"compositedLayerFaces\":0,\"commands\":0,\"uploadCommands\":0,\"transitionCommands\":0\\}.*\"facePngExport\":\\{\"ready\":false,\"faces\":0,\"bytes\":0,\"facePayloads\":0\\}.*\"depthExport\":\\{\"ready\":false,\"width\":0,\"height\":0,\"mergedFaceDraws\":0,\"layerDepthDraws\":0,\"visitedLayers\":0,\"visibleLayers\":0,\"facePayloads\":0,\"requiresRendererReadback\":true\\}")
 
     add_test(NAME pano_cli_plan_canvas_document_snapshot_payload_smoke
         COMMAND pano_cli plan-canvas-document-snapshot --width 128 --height 64 --layers 2 --frames 2 --current-layer 1 --current-frame 1 --pending-face-payloads-per-layer 2 --captured-face-payloads-per-layer 2)
     set_tests_properties(pano_cli_plan_canvas_document_snapshot_payload_smoke PROPERTIES
         LABELS "app;document;integration;desktop-fast"
-        PASS_REGULAR_EXPRESSION "\"command\":\"plan-canvas-document-snapshot\".*\"layers\":2.*\"frames\":2.*\"activeLayer\":1.*\"activeFrame\":1.*\"pendingFacePayloads\":4.*\"capturedFacePayloads\":4.*\"metadataOnly\":false.*\"requiresRendererPayloadReadback\":false.*\"documentFacePayloads\":4.*\"saveReport\":\\{\"payloadComplete\":true,\"canExportPpi\":true\\}.*\"ppiExport\":\\{\"ready\":true,\"bytes\":[1-9][0-9]*,\"dirtyFaces\":4\\}.*\"rendererUpload\":\\{\"ready\":true,\"textures\":6,\"bytes\":[1-9][0-9]*,\"transitions\":6,\"facePayloads\":2,\"compositedLayerFaces\":2,\"commands\":12,\"uploadCommands\":6,\"transitionCommands\":6\\}.*\"facePngExport\":\\{\"ready\":true,\"faces\":6,\"bytes\":[1-9][0-9]*,\"facePayloads\":2\\}")
+        PASS_REGULAR_EXPRESSION "\"command\":\"plan-canvas-document-snapshot\".*\"layers\":2.*\"frames\":2.*\"activeLayer\":1.*\"activeFrame\":1.*\"pendingFacePayloads\":4.*\"capturedFacePayloads\":4.*\"metadataOnly\":false.*\"requiresRendererPayloadReadback\":false.*\"documentFacePayloads\":4.*\"saveReport\":\\{\"payloadComplete\":true,\"canExportPpi\":true\\}.*\"ppiExport\":\\{\"ready\":true,\"bytes\":[1-9][0-9]*,\"dirtyFaces\":4\\}.*\"rendererUpload\":\\{\"ready\":true,\"textures\":6,\"bytes\":[1-9][0-9]*,\"transitions\":6,\"facePayloads\":2,\"compositedLayerFaces\":2,\"commands\":12,\"uploadCommands\":6,\"transitionCommands\":6\\}.*\"facePngExport\":\\{\"ready\":true,\"faces\":6,\"bytes\":[1-9][0-9]*,\"facePayloads\":2\\}.*\"depthExport\":\\{\"ready\":true,\"width\":1024,\"height\":1024,\"mergedFaceDraws\":6,\"layerDepthDraws\":2,\"visitedLayers\":2,\"visibleLayers\":1,\"facePayloads\":2,\"requiresRendererReadback\":true\\}")
 
     add_test(NAME pano_cli_plan_canvas_document_snapshot_no_canvas
         COMMAND pano_cli plan-canvas-document-snapshot --no-canvas)

tools/pano_cli/main.cpp

@@ -6011,6 +6011,15 @@ int plan_canvas_document_snapshot(int argc, char** argv)
     std::size_t face_png_export_faces = 0;
     std::uint64_t face_png_export_bytes = 0;
     std::size_t face_png_export_payloads = 0;
+    bool depth_export_ready = false;
+    std::uint32_t depth_export_width = 0;
+    std::uint32_t depth_export_height = 0;
+    std::size_t depth_export_merged_face_draws = 0;
+    std::size_t depth_export_layer_depth_draws = 0;
+    std::size_t depth_export_visited_layers = 0;
+    std::size_t depth_export_visible_layers = 0;
+    std::size_t depth_export_face_payloads = 0;
+    bool depth_export_requires_renderer_readback = value.requires_renderer_payload_readback;
     if (save_report.can_export_ppi) {
         const auto exported = pp::app::export_document_canvas_save_snapshot_to_ppi(value);
         if (!exported) {
@@ -6054,6 +6063,26 @@ int plan_canvas_document_snapshot(int argc, char** argv)
         face_png_export_faces = readiness.value().face_pngs.face_count;
         face_png_export_bytes = readiness.value().face_pngs.encoded_bytes;
         face_png_export_payloads = readiness.value().face_pngs.composite.face_payload_count;
+
+        const auto depth_plan = pp::paint_renderer::plan_document_depth_export_render(
+            pp::paint_renderer::DocumentDepthExportRenderPlanRequest {
+                .document = &document,
+                .frame_index = document.active_frame_index(),
+            });
+        if (!depth_plan) {
+            print_error("plan-canvas-document-snapshot", depth_plan.status().message);
+            return 2;
+        }
+
+        depth_export_ready = true;
+        depth_export_width = depth_plan.value().output_extent.width;
+        depth_export_height = depth_plan.value().output_extent.height;
+        depth_export_merged_face_draws = depth_plan.value().merged_face_draw_count;
+        depth_export_layer_depth_draws = depth_plan.value().layer_depth_draw_count;
+        depth_export_visited_layers = depth_plan.value().visited_layer_count;
+        depth_export_visible_layers = depth_plan.value().visible_layer_count;
+        depth_export_face_payloads = depth_plan.value().face_payload_count;
+        depth_export_requires_renderer_readback = depth_plan.value().requires_renderer_readback;
     }
 
     std::cout << "{\"ok\":true,\"command\":\"plan-canvas-document-snapshot\""
@@ -6098,6 +6127,15 @@ int plan_canvas_document_snapshot(int argc, char** argv)
               << ",\"faces\":" << face_png_export_faces
               << ",\"bytes\":" << face_png_export_bytes
               << ",\"facePayloads\":" << face_png_export_payloads
+              << "},\"depthExport\":{\"ready\":" << json_bool(depth_export_ready)
+              << ",\"width\":" << depth_export_width
+              << ",\"height\":" << depth_export_height
+              << ",\"mergedFaceDraws\":" << depth_export_merged_face_draws
+              << ",\"layerDepthDraws\":" << depth_export_layer_depth_draws
+              << ",\"visitedLayers\":" << depth_export_visited_layers
+              << ",\"visibleLayers\":" << depth_export_visible_layers
+              << ",\"facePayloads\":" << depth_export_face_payloads
+              << ",\"requiresRendererReadback\":" << json_bool(depth_export_requires_renderer_readback)
               << "}"
               << "}}\n";
     return 0;