Validate snapshot face payloads

docs/modernization/build-inventory.md

@@ -93,9 +93,10 @@ Known local toolchain state:
   `pp_ui_core`, `pano_cli`, and their current headless test binaries,
   including foundation event/logging/task queue coverage, PNG metadata and
   decode, PPI header/layout, settings document, document
-  snapshot/per-layer-frame/move/duration/face-pixel/PPI export coverage, paint
+  snapshot/per-layer-frame/move/duration/face-pixel/PPI export coverage,
-  brush/stroke/stroke-script coverage, renderer shader descriptor and OpenGL
+  snapshot-embedded face-payload rejection, paint brush/stroke/stroke-script
-  capability coverage, UI color parsing, and layout XML parse coverage.
+  coverage, renderer shader descriptor and OpenGL capability coverage, UI
+  color parsing, and layout XML parse coverage.
 - `pano_cli inspect-image` reports PNG IHDR metadata as JSON and is covered by
   `pano_cli_inspect_png_metadata_smoke` with a tiny IHDR fixture.
 - `pp_assets_image_pixels_tests` decodes PNG payloads, encodes RGBA8 pixels to

docs/modernization/debt.md

@@ -28,7 +28,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | DEBT-0007 | Open | Modernization | `vcpkg.json` and `windows-msvc-vcpkg-headless` are validated for the headless Windows component matrix, but app targets still use vendored libraries and Android/Apple triplets are not proven | Dependency migration must stay incremental while SDK/patched/vendor dependencies remain in use | `$env:VCPKG_ROOT="C:\Program Files\Microsoft Visual Studio\2022\Community\VC\vcpkg"; cmake --preset windows-msvc-vcpkg-headless`; `ctest --preset desktop-fast-vcpkg --build-config Debug` | Component targets consume vcpkg packages where reliable and desktop app, Android, and Apple triplets are validated or explicitly documented as permanent vendor exceptions |
 | DEBT-0008 | Open | Modernization | `windows-msvc-default` preset is used for local validation because the VS 2026 generator is not installed here | The target VS 2026 preset must remain, but this machine configures with Visual Studio 17 2022 | `cmake --preset windows-msvc-default`; `ctest --preset desktop-fast --build-config Debug` | Validate `windows-vs2026-x64` on a machine with Visual Studio 2026 installed and make it the default Windows validation preset |
 | DEBT-0009 | Open | Modernization | Android root CMake validation currently builds headless targets only, not APK/package variants | Platform app entrypoints still live in legacy Gradle/CMake projects and need Phase 6 alignment | `powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64` | Android standard, Quest, and Focus/Wave package targets consume shared component targets and have package smoke commands |
-| DEBT-0010 | Open | Modernization | `pp_document` is a pure layer/frame/document/undo-history model with alpha-lock metadata, snapshot construction, per-layer frame metadata, renderer-free RGBA8 face payload storage, renderer-free alpha8 selection-mask storage, and PPI import/export helpers, but it is not yet wired to legacy `Canvas`, legacy save, or legacy action commands | Keep extraction incremental while preserving app behavior | `ctest --preset desktop-fast --build-config Debug`; `pano_cli create-document --width 64 --height 32 --layers 2`; `pano_cli load-project --path tests\data\projects\minimal-project.ppi`; `pp_document_ppi_import_tests`; `pp_document_ppi_export_tests`; `pano_cli_simulate_document_edits_smoke` | Legacy document behavior is represented by `pp_document` tests and the app consumes it through a boundary/facade |
+| DEBT-0010 | Open | Modernization | `pp_document` is a pure layer/frame/document/undo-history model with alpha-lock metadata, snapshot construction, per-layer frame metadata, renderer-free RGBA8 face payload storage, snapshot-embedded face-payload validation, renderer-free alpha8 selection-mask storage, and PPI import/export helpers, but it is not yet wired to legacy `Canvas`, legacy save, or legacy action commands | Keep extraction incremental while preserving app behavior | `ctest --preset desktop-fast --build-config Debug`; `pano_cli create-document --width 64 --height 32 --layers 2`; `pano_cli load-project --path tests\data\projects\minimal-project.ppi`; `pp_document_tests`; `pp_document_ppi_import_tests`; `pp_document_ppi_export_tests`; `pano_cli_simulate_document_edits_smoke` | Legacy document behavior is represented by `pp_document` tests and the app consumes it through a boundary/facade |
 | DEBT-0011 | Open | Modernization | `package-smoke` validates the Windows CMake app artifact only, not AppX/APK/Apple/WebGL package outputs | Platform package targets are not migrated to root CMake yet | `powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -Preset windows-msvc-default -Configuration Debug` | Package-smoke covers Windows AppX, Android APK variants, Apple bundles, and WebGL output where local toolchains are present |
 | DEBT-0012 | Open | Modernization | `pp_ui_core` uses vcpkg tinyxml2 on `windows-msvc-vcpkg-headless`, but retains `pp_vendor_tinyxml2` for default and unproven platform presets | Mobile/AppX/Apple triplets and app packaging still need validation before removing the vendored fallback | `ctest --preset desktop-fast-vcpkg --build-config Debug`; `ctest --preset desktop-fast --build-config Debug`; `powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64` | All supported presets consume vcpkg tinyxml2 or document a permanent vendored exception |
 | DEBT-0013 | Open | Modernization | `pp_assets`, `pp_document`, `pano_cli inspect-project`, `pano_cli load-project`, and `pano_cli save-project` validate the fixed PPI header, thumbnail/body byte layout, generated multi-layer/multi-frame PPI writing with explicit layer opacity/blend/alpha-lock/visibility metadata, per-layer frame durations, metadata-only and targeted dirty-face-payload save/load round-trips, layer/frame index, dirty-face descriptors, dirty-face PNG payload metadata, asset-level RGBA PNG payload decoding, pure document-to-PPI export, and decoded pixel attachment to `pp_document`, but full legacy PPI round-trip parity is not yet extracted | Full PPI save parity requires staged extraction of legacy `Canvas` serialization and image/layer payload handling | `ctest --preset desktop-fast --build-config Debug`; `pp_assets_image_pixels_tests`; `pp_assets_ppi_header_tests`; `pp_document_ppi_import_tests`; `pp_document_ppi_export_tests`; `pano_cli_inspect_project_layout_smoke`; `pano_cli_load_project_metadata_smoke`; `pano_cli_save_project_roundtrip_smoke`; `pano_cli_save_project_payload_roundtrip_smoke` | Full PPI load/save fixtures cover thumbnails, decoded layer face payloads attached to documents, frames, corrupt payloads, dirty-face payload saving, arbitrary legacy canvas payload/layout combinations, and legacy app round-trip compatibility |

docs/modernization/roadmap.md

@@ -325,7 +325,8 @@ started with a pure canvas/layer/frame model, alpha-lock metadata, snapshot
 construction, per-layer frame metadata, layer metadata operations, frame
 move/duration queries, renderer-free RGBA8 cube-face payload storage,
 renderer-free alpha8 selection-mask storage, PPI image import/export, and
-layer/frame/undo-redo history invariant tests.
+layer/frame/undo-redo history invariant tests. Snapshot construction validates
+embedded face-pixel payload bounds and byte counts.
 `pp_renderer_api` has started with renderer-neutral
 texture/readback descriptors and validation tests. `pp_paint_renderer` has
 started with deterministic CPU layer compositing over renderer extents using
@@ -693,7 +694,8 @@ Results:
 - `pp_paint_stroke_script_tests` passed.
 - `pp_document_tests` passed, including snapshot construction, alpha-lock
   metadata, per-layer frame metadata, frame move, duration, face-pixel payload
-  storage/replacement/rejection, and history invariants.
+  storage/replacement/rejection, snapshot-embedded face-payload rejection, and
+  history invariants.
 - `pp_document_ppi_import_tests` passed, including decoded PPI dirty-face
   payload attachment to `pp_document` layer/frame storage and out-of-range
   payload rejection.
@@ -812,6 +814,8 @@ Results:
 - `pp_document::export_ppi_project_document` exposes pure document-to-PPI byte
   export through CTest coverage; legacy Canvas save integration remains tracked
   by DEBT-0010/DEBT-0013.
+- Snapshot creation now rejects invalid embedded RGBA8 face payloads before
+  document export or history can persist malformed state.
 - PowerShell package-smoke wrapper validates the Windows CMake app executable
   and runtime `data/` copy.
 - Android arm64 configured with NDK 29.0.14206865 through the platform-build

src/document/document.cpp

@@ -232,6 +232,23 @@ namespace {
     return pp::foundation::Status::success();
 }
 
+[[nodiscard]] pp::foundation::Status validate_frame_face_pixels(
+    std::span<const AnimationFrame> frames,
+    std::uint32_t document_width,
+    std::uint32_t document_height) noexcept
+{
+    for (const auto& frame : frames) {
+        for (const auto& pixels : frame.face_pixels) {
+            const auto pixels_status = validate_face_pixels(pixels, document_width, document_height);
+            if (!pixels_status.ok()) {
+                return pixels_status;
+            }
+        }
+    }
+
+    return pp::foundation::Status::success();
+}
+
 }
 
 pp::foundation::Result<CanvasDocument> CanvasDocument::create(DocumentConfig config)
@@ -308,6 +325,11 @@ pp::foundation::Result<CanvasDocument> CanvasDocument::create_from_snapshot(Docu
                 pp::foundation::Status::out_of_range("document layer frame count exceeds the configured limit"));
         }
 
+        const auto face_pixels_status = validate_frame_face_pixels(layer_frames, config.width, config.height);
+        if (!face_pixels_status.ok()) {
+            return pp::foundation::Result<CanvasDocument>::failure(face_pixels_status);
+        }
+
         for (const auto& frame_config : layer_frames) {
             const auto duration_status = validate_frame_duration(frame_config.duration_ms);
             if (!duration_status.ok()) {
@@ -333,6 +355,14 @@ pp::foundation::Result<CanvasDocument> CanvasDocument::create_from_snapshot(Docu
             return pp::foundation::Result<CanvasDocument>::failure(duration_status);
         }
 
+        const auto face_pixels_status = validate_frame_face_pixels(
+            std::span<const AnimationFrame>(&frame_config, 1),
+            config.width,
+            config.height);
+        if (!face_pixels_status.ok()) {
+            return pp::foundation::Result<CanvasDocument>::failure(face_pixels_status);
+        }
+
         document.frames_.push_back(frame_config);
     }
 

tests/document/document_tests.cpp

@@ -311,6 +311,88 @@ void rejects_invalid_snapshot_metadata(pp::tests::Harness& h)
     PP_EXPECT(h, bad_layer_frame.status().code == StatusCode::invalid_argument);
 }
 
+void rejects_invalid_snapshot_face_pixels(pp::tests::Harness& h)
+{
+    const AnimationFrame frames[] { { .duration_ms = 100, .face_pixels = {} } };
+    const AnimationFrame bad_byte_count_frames[] {
+        {
+            .duration_ms = 100,
+            .face_pixels = {
+                LayerFacePixels {
+                    .face_index = 0,
+                    .x = 0,
+                    .y = 0,
+                    .width = 1,
+                    .height = 1,
+                    .rgba8 = {},
+                },
+            },
+        },
+    };
+    const AnimationFrame outside_frames[] {
+        {
+            .duration_ms = 100,
+            .face_pixels = {
+                LayerFacePixels {
+                    .face_index = 0,
+                    .x = 63,
+                    .y = 0,
+                    .width = 2,
+                    .height = 1,
+                    .rgba8 = { 1, 2, 3, 4, 5, 6, 7, 8 },
+                },
+            },
+        },
+    };
+    const DocumentLayerConfig bad_byte_count_layers[] {
+        {
+            .name = "Ink",
+            .frames = bad_byte_count_frames,
+        },
+    };
+    const DocumentLayerConfig outside_layers[] {
+        {
+            .name = "Ink",
+            .frames = outside_frames,
+        },
+    };
+    const DocumentLayerConfig layers[] {
+        {
+            .name = "Ink",
+            .frames = {},
+        },
+    };
+
+    const auto bad_layer_payload = CanvasDocument::create_from_snapshot(DocumentSnapshotConfig {
+        .width = 64,
+        .height = 64,
+        .layers = bad_byte_count_layers,
+        .frames = frames,
+        .selection_masks = {},
+    });
+    const auto outside_layer_payload = CanvasDocument::create_from_snapshot(DocumentSnapshotConfig {
+        .width = 64,
+        .height = 64,
+        .layers = outside_layers,
+        .frames = frames,
+        .selection_masks = {},
+    });
+    const auto bad_root_payload = CanvasDocument::create_from_snapshot(DocumentSnapshotConfig {
+        .width = 64,
+        .height = 64,
+        .layers = layers,
+        .frames = bad_byte_count_frames,
+        .selection_masks = {},
+    });
+
+    PP_EXPECT(h, !bad_layer_payload.ok());
+    PP_EXPECT(h, bad_layer_payload.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !outside_layer_payload.ok());
+    PP_EXPECT(h, outside_layer_payload.status().code == StatusCode::out_of_range);
+    PP_EXPECT(h, !bad_root_payload.ok());
+    PP_EXPECT(h, bad_root_payload.status().code == StatusCode::invalid_argument);
+}
+
 void manages_animation_frames_and_duration(pp::tests::Harness& h)
 {
     auto document_result = CanvasDocument::create(
@@ -744,6 +826,7 @@ int main()
     harness.run("creates_document_from_snapshot_metadata", creates_document_from_snapshot_metadata);
     harness.run("preserves_per_layer_snapshot_timelines", preserves_per_layer_snapshot_timelines);
     harness.run("rejects_invalid_snapshot_metadata", rejects_invalid_snapshot_metadata);
+    harness.run("rejects_invalid_snapshot_face_pixels", rejects_invalid_snapshot_face_pixels);
     harness.run("manages_animation_frames_and_duration", manages_animation_frames_and_duration);
     harness.run("moves_frames_and_preserves_active_frame_identity", moves_frames_and_preserves_active_frame_identity);
     harness.run("rejects_invalid_animation_frame_operations", rejects_invalid_animation_frame_operations);

tests/document/ppi_export_tests.cpp

@@ -122,7 +122,7 @@ void exports_document_metadata_and_face_payloads(pp::tests::Harness& h)
     PP_EXPECT(h, imported.value().face_pixel_payload_count() == 2U);
 }
 
-void rejects_export_when_document_payload_cannot_encode(pp::tests::Harness& h)
+void rejects_snapshot_payload_that_cannot_export(pp::tests::Harness& h)
 {
     const AnimationFrame root_frames[] {
         { .duration_ms = 100, .face_pixels = {} },
@@ -161,12 +161,8 @@ void rejects_export_when_document_payload_cannot_encode(pp::tests::Harness& h)
         .selection_masks = {},
     });
 
-    PP_EXPECT(h, document.ok());
+    PP_EXPECT(h, !document.ok());
-
+    PP_EXPECT(h, document.status().code == StatusCode::invalid_argument);
-    const auto exported = export_ppi_project_document(document.value());
-
-    PP_EXPECT(h, !exported.ok());
-    PP_EXPECT(h, exported.status().code == StatusCode::invalid_argument);
 }
 
 }
@@ -175,6 +171,6 @@ int main()
 {
     pp::tests::Harness harness;
     harness.run("exports_document_metadata_and_face_payloads", exports_document_metadata_and_face_payloads);
-    harness.run("rejects_export_when_document_payload_cannot_encode", rejects_export_when_document_payload_cannot_encode);
+    harness.run("rejects_snapshot_payload_that_cannot_export", rejects_snapshot_payload_that_cannot_export);
     return harness.finish();
 }