Validate PPI face payload metadata

docs/modernization/build-inventory.md

@@ -96,8 +96,8 @@ Known local toolchain state:
   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.
-- `pano_cli inspect-project` reports validated PPI thumbnail/body byte layout
+- `pano_cli inspect-project` reports validated PPI thumbnail/body byte layout,
-  plus body summary fields, and is covered by
+  body summary fields, and dirty-face PNG payload metadata, and is covered by
   `pano_cli_inspect_project_layout_smoke` with a minimal PPI fixture.
 - `pano_cli create-document` supports `--frames` and `--frame-duration-ms` and
   is covered by `pano_cli_create_animation_document_smoke`.

docs/modernization/debt.md

@@ -31,7 +31,7 @@ agent or engineer to remove them without reconstructing context from chat.
 | DEBT-0010 | Open | Modernization | `pp_document` is a pure layer/frame/document/undo-history model but is not yet wired to legacy `Canvas`, PPI load/save, selection masks, 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` | 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` and `pano_cli inspect-project` validate the fixed PPI header, thumbnail/body byte layout, and body summary, but do not yet deserialize layer face PNG payloads into document/layer/frame pixel data | Full PPI parsing requires staged extraction of legacy `Canvas` serialization and image/layer payload handling | `ctest --preset desktop-fast --build-config Debug`; `pp_assets_ppi_header_tests`; `pano_cli_inspect_project_layout_smoke` | Full PPI load/save fixtures cover thumbnail, decoded layer face payloads, frames, metadata, corrupt payloads, and round-trip compatibility |
+| DEBT-0013 | Open | Modernization | `pp_assets` and `pano_cli inspect-project` validate the fixed PPI header, thumbnail/body byte layout, body summary, and dirty-face PNG payload metadata, but do not yet deserialize layer face PNG pixels into document/layer/frame data | Full PPI parsing requires staged extraction of legacy `Canvas` serialization and image/layer payload handling | `ctest --preset desktop-fast --build-config Debug`; `pp_assets_ppi_header_tests`; `pano_cli_inspect_project_layout_smoke` | Full PPI load/save fixtures cover thumbnail, decoded layer face payloads, frames, metadata, corrupt payloads, and round-trip compatibility |
 | DEBT-0014 | Open | Modernization | `windows-clangcl-asan` now configures as a headless Ninja/clang-cl preset and uses the release MSVC runtime required by ASan, but local builds still fail because installed clang-cl 18.1.8 is paired with VS 2026-preview STL headers that require Clang 20 or newer | Sanitizer validation should be local and repeatable, but this machine's compiler/header pairing is incompatible | `cmake --fresh --preset windows-clangcl-asan`; `cmake --build --preset windows-clangcl-asan --target pp_foundation` | Install/use Clang 20+ with the VS 2026 STL, or point the preset at a compatible VS 2022 toolchain, then make `platform-build.ps1 -Presets windows-clangcl-asan` pass for the headless matrix |
 
 ## Closed Debt

docs/modernization/roadmap.md

@@ -313,7 +313,8 @@ task queue, and deterministic `TraceRecorder` now record
 component/name/thread/frame/stroke metadata with filtering, capacity, and
 invalid-end tests. `pp_assets` has started with PNG/JPEG signature detection,
 PNG IHDR metadata parsing, PPI header/project byte-layout/body-summary
-recognition, and a pure typed settings document model, with
+recognition, dirty-face PNG payload metadata validation, and a pure typed
+settings document model, with
 corrupt/truncated/unsupported, extreme-dimension, and key/value limit tests.
 `pp_paint` has started with pure brush parameter validation/stamp evaluation,
 CPU reference math for the five current shader blend modes, and deterministic
@@ -328,8 +329,8 @@ the paint blend reference. `pp_ui_core` has started with XML-layout-facing
 length parsing, color parsing, tinyxml-backed layout XML parsing, and invalid
 input tests.
 `pano_cli inspect-image` exposes PNG IHDR metadata as JSON,
-`pano_cli inspect-project` reports validated PPI thumbnail/body byte layout and
+`pano_cli inspect-project` reports validated PPI thumbnail/body byte layout,
-body summary, and
+body summary, and dirty-face PNG payload metadata, and
 `pano_cli create-document` can create simple animation documents with explicit
 frame count/duration, and `pano_cli simulate-stroke` exercises the pure stroke
 sampler for scripted-stroke automation. `pano_cli simulate-stroke-script`
@@ -568,8 +569,8 @@ Results:
 - `pp_foundation_trace_tests` passed.
 - `pp_assets_image_format_tests` passed.
 - `pp_assets_image_metadata_tests` passed.
-- `pp_assets_ppi_header_tests` passed, including PPI thumbnail/body layout and
+- `pp_assets_ppi_header_tests` passed, including PPI thumbnail/body layout,
-  body summary validation.
+  body summary validation, and dirty-face PNG payload metadata validation.
 - `pp_assets_settings_document_tests` passed.
 - `pp_paint_brush_tests` passed.
 - `pp_paint_blend_tests` passed.
@@ -590,7 +591,8 @@ Results:
 - `pano_cli_inspect_png_metadata_smoke` passed and reports PNG metadata JSON
   for the tiny IHDR fixture.
 - `pano_cli_inspect_project_layout_smoke` passed and reports PPI
-  thumbnail/body byte layout and body summary JSON.
+  thumbnail/body byte layout, body summary, and dirty-face PNG payload metadata
+  JSON.
 - `pano_cli_parse_layout_smoke` passed.
 - `pano_cli_simulate_stroke_smoke` passed and reports deterministic stroke
   sample counts/distances.

src/assets/ppi_header.cpp

@@ -1,5 +1,6 @@
 #include "assets/ppi_header.h"
 
+#include "assets/image_metadata.h"
 #include "foundation/binary_stream.h"
 
 #include <bit>
@@ -77,6 +78,28 @@ namespace {
     return pp::foundation::Status::success();
 }
 
+[[nodiscard]] pp::foundation::Status validate_face_png_payload(
+    std::span<const std::byte> payload,
+    std::uint32_t width,
+    std::uint32_t height) noexcept
+{
+    const auto metadata = parse_png_metadata(payload);
+    if (!metadata) {
+        return metadata.status();
+    }
+
+    if (metadata.value().width != width || metadata.value().height != height) {
+        return pp::foundation::Status::invalid_argument("PPI face PNG dimensions do not match the dirty box");
+    }
+
+    if (metadata.value().bit_depth != 8U || metadata.value().components != 4U
+        || metadata.value().color_type != ImageColorType::rgba) {
+        return pp::foundation::Status::invalid_argument("PPI face PNG payload must be 8-bit RGBA");
+    }
+
+    return pp::foundation::Status::success();
+}
+
 }
 
 pp::foundation::Result<PpiHeaderInfo> parse_ppi_header(std::span<const std::byte> bytes) noexcept
@@ -356,15 +379,25 @@ pp::foundation::Result<PpiBodySummary> parse_ppi_body_summary(
                         pp::foundation::Status::invalid_argument("PPI compressed face payload must not be empty"));
                 }
 
-                const auto payload_status = add_payload_bytes(summary, data_size.value());
+                const auto byte_status = add_payload_bytes(summary, data_size.value());
-                if (!payload_status.ok()) {
+                if (!byte_status.ok()) {
-                    return pp::foundation::Result<PpiBodySummary>::failure(payload_status);
+                    return pp::foundation::Result<PpiBodySummary>::failure(byte_status);
                 }
 
-                const auto skip_status = skip_bytes(reader, data_size.value());
+                const auto payload = reader.read_bytes(data_size.value());
-                if (!skip_status.ok()) {
+                if (!payload) {
-                    return pp::foundation::Result<PpiBodySummary>::failure(skip_status);
+                    return pp::foundation::Result<PpiBodySummary>::failure(payload.status());
                 }
+
+                const auto png_status = validate_face_png_payload(
+                    payload.value(),
+                    x1.value() - x0.value(),
+                    y1.value() - y0.value());
+                if (!png_status.ok()) {
+                    return pp::foundation::Result<PpiBodySummary>::failure(png_status);
+                }
+
+                ++summary.rgba_face_payload_count;
             }
         }
     }

src/assets/ppi_header.h

@@ -54,6 +54,7 @@ struct PpiBodySummary {
     std::uint32_t declared_frame_count = 0;
     std::uint32_t total_layer_frames = 0;
     std::uint32_t dirty_face_count = 0;
+    std::uint32_t rgba_face_payload_count = 0;
     std::uint64_t compressed_face_bytes = 0;
     std::uint32_t info_bytes = 0;
 };

tests/CMakeLists.txt

@@ -234,7 +234,7 @@ if(TARGET pano_cli)
         COMMAND pano_cli inspect-project --path "${CMAKE_CURRENT_SOURCE_DIR}/data/projects/minimal-project.ppi")
     set_tests_properties(pano_cli_inspect_project_layout_smoke PROPERTIES
         LABELS "assets;integration;desktop-fast"
-        PASS_REGULAR_EXPRESSION "\"thumbnail\":\\{\"width\":128,\"height\":128,\"components\":4,\"bytes\":65536\\}.*\"body\":\\{\"offset\":65576,\"bytes\":73,\"width\":64,\"height\":32,\"layers\":1,\"frames\":1,\"dirtyFaces\":0,\"compressedBytes\":0,\"infoBytes\":0\\}")
+        PASS_REGULAR_EXPRESSION "\"thumbnail\":\\{\"width\":128,\"height\":128,\"components\":4,\"bytes\":65536\\}.*\"body\":\\{\"offset\":65576,\"bytes\":73,\"width\":64,\"height\":32,\"layers\":1,\"frames\":1,\"dirtyFaces\":0,\"rgbaFacePayloads\":0,\"compressedBytes\":0,\"infoBytes\":0\\}")
 
     add_test(NAME pano_cli_parse_layout_smoke
         COMMAND pano_cli parse-layout --path "${CMAKE_CURRENT_SOURCE_DIR}/data/layouts/simple-layout.xml")

tests/assets/ppi_header_tests.cpp

@@ -25,6 +25,14 @@ void append_u32(std::vector<std::byte>& bytes, std::uint32_t value)
     bytes.push_back(static_cast<std::byte>((value >> 24U) & 0xffU));
 }
 
+void append_u32_be(std::vector<std::byte>& bytes, std::uint32_t value)
+{
+    bytes.push_back(static_cast<std::byte>((value >> 24U) & 0xffU));
+    bytes.push_back(static_cast<std::byte>((value >> 16U) & 0xffU));
+    bytes.push_back(static_cast<std::byte>((value >> 8U) & 0xffU));
+    bytes.push_back(static_cast<std::byte>(value & 0xffU));
+}
+
 void append_f32(std::vector<std::byte>& bytes, float value)
 {
     append_u32(bytes, std::bit_cast<std::uint32_t>(value));
@@ -78,6 +86,38 @@ void append_minimal_body(std::vector<std::byte>& bytes)
     append_u32(bytes, 0);
 }
 
+std::vector<std::byte> png_ihdr_payload(
+    std::uint32_t width,
+    std::uint32_t height,
+    std::uint8_t bit_depth = 8U,
+    std::uint8_t color_type = 6U)
+{
+    std::vector<std::byte> bytes {
+        std::byte { 0x89 },
+        std::byte { 0x50 },
+        std::byte { 0x4e },
+        std::byte { 0x47 },
+        std::byte { 0x0d },
+        std::byte { 0x0a },
+        std::byte { 0x1a },
+        std::byte { 0x0a },
+    };
+    append_u32_be(bytes, 13);
+    bytes.push_back(std::byte { 'I' });
+    bytes.push_back(std::byte { 'H' });
+    bytes.push_back(std::byte { 'D' });
+    bytes.push_back(std::byte { 'R' });
+    append_u32_be(bytes, width);
+    append_u32_be(bytes, height);
+    bytes.push_back(static_cast<std::byte>(bit_depth));
+    bytes.push_back(static_cast<std::byte>(color_type));
+    bytes.push_back(std::byte { 0 });
+    bytes.push_back(std::byte { 0 });
+    bytes.push_back(std::byte { 0 });
+    append_u32_be(bytes, 0);
+    return bytes;
+}
+
 std::vector<std::byte> minimal_project()
 {
     auto bytes = valid_header();
@@ -86,6 +126,40 @@ std::vector<std::byte> minimal_project()
     return bytes;
 }
 
+std::vector<std::byte> project_with_single_face_payload(std::vector<std::byte> payload)
+{
+    auto bytes = valid_header();
+    bytes.resize(ppi_header_size + (128U * 128U * 4U), std::byte { 0 });
+
+    append_u32(bytes, 64);
+    append_u32(bytes, 32);
+    append_u32(bytes, 1);
+    append_u32(bytes, 1);
+    append_u32(bytes, 0);
+    append_f32(bytes, 1.0F);
+    append_u32(bytes, 3);
+    append_ascii(bytes, "Ink");
+    append_u32(bytes, 0);
+    bytes.push_back(std::byte { 0 });
+    bytes.push_back(std::byte { 1 });
+    append_u32(bytes, 1);
+    append_u32(bytes, 100);
+
+    append_u32(bytes, 1);
+    append_u32(bytes, 2);
+    append_u32(bytes, 3);
+    append_u32(bytes, 10);
+    append_u32(bytes, 7);
+    append_u32(bytes, static_cast<std::uint32_t>(payload.size()));
+    bytes.insert(bytes.end(), payload.begin(), payload.end());
+
+    for (std::uint32_t i = 1; i < 6U; ++i) {
+        append_u32(bytes, 0);
+    }
+    append_u32(bytes, 0);
+    return bytes;
+}
+
 void parses_legacy_ppi_header(pp::tests::Harness& h)
 {
     const auto bytes = valid_header();
@@ -178,10 +252,42 @@ void parses_minimal_project_body_summary(pp::tests::Harness& h)
     PP_EXPECT(h, summary.value().body.declared_frame_count == 1U);
     PP_EXPECT(h, summary.value().body.total_layer_frames == 1U);
     PP_EXPECT(h, summary.value().body.dirty_face_count == 0U);
+    PP_EXPECT(h, summary.value().body.rgba_face_payload_count == 0U);
     PP_EXPECT(h, summary.value().body.compressed_face_bytes == 0U);
     PP_EXPECT(h, summary.value().body.info_bytes == 0U);
 }
 
+void validates_dirty_face_png_payload_metadata(pp::tests::Harness& h)
+{
+    const auto project = project_with_single_face_payload(png_ihdr_payload(8, 4));
+    const auto summary = parse_ppi_project_summary(project);
+
+    PP_EXPECT(h, summary.ok());
+    PP_EXPECT(h, summary.value().body.dirty_face_count == 1U);
+    PP_EXPECT(h, summary.value().body.rgba_face_payload_count == 1U);
+    PP_EXPECT(h, summary.value().body.compressed_face_bytes == 33U);
+}
+
+void rejects_invalid_dirty_face_png_payloads(pp::tests::Harness& h)
+{
+    auto mismatched_dimensions = project_with_single_face_payload(png_ihdr_payload(7, 4));
+    auto non_rgba = project_with_single_face_payload(png_ihdr_payload(8, 4, 8, 2));
+    auto bad_signature_payload = png_ihdr_payload(8, 4);
+    bad_signature_payload[0] = std::byte { 0 };
+    auto bad_signature = project_with_single_face_payload(bad_signature_payload);
+
+    const auto mismatched_result = parse_ppi_project_summary(mismatched_dimensions);
+    const auto non_rgba_result = parse_ppi_project_summary(non_rgba);
+    const auto bad_signature_result = parse_ppi_project_summary(bad_signature);
+
+    PP_EXPECT(h, !mismatched_result.ok());
+    PP_EXPECT(h, mismatched_result.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !non_rgba_result.ok());
+    PP_EXPECT(h, non_rgba_result.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !bad_signature_result.ok());
+    PP_EXPECT(h, bad_signature_result.status().code == StatusCode::invalid_argument);
+}
+
 void rejects_invalid_project_body_summaries(pp::tests::Harness& h)
 {
     auto truncated = minimal_project();
@@ -216,6 +322,8 @@ int main()
     harness.run("parses_project_layout_with_thumbnail_and_body", parses_project_layout_with_thumbnail_and_body);
     harness.run("rejects_project_layout_with_truncated_thumbnail", rejects_project_layout_with_truncated_thumbnail);
     harness.run("parses_minimal_project_body_summary", parses_minimal_project_body_summary);
+    harness.run("validates_dirty_face_png_payload_metadata", validates_dirty_face_png_payload_metadata);
+    harness.run("rejects_invalid_dirty_face_png_payloads", rejects_invalid_dirty_face_png_payloads);
     harness.run("rejects_invalid_project_body_summaries", rejects_invalid_project_body_summaries);
     return harness.finish();
 }

tools/pano_cli/main.cpp

@@ -311,6 +311,7 @@ int inspect_project(int argc, char** argv)
               << ",\"layers\":" << summary.value().body.layer_count
               << ",\"frames\":" << summary.value().body.declared_frame_count
               << ",\"dirtyFaces\":" << summary.value().body.dirty_face_count
+              << ",\"rgbaFacePayloads\":" << summary.value().body.rgba_face_payload_count
               << ",\"compressedBytes\":" << summary.value().body.compressed_face_bytes
               << ",\"infoBytes\":" << summary.value().body.info_bytes
               << "}}\n";