Expose image import simulation through pano cli

docs/modernization/build-inventory.md

@@ -118,6 +118,9 @@ Known local toolchain state:
 - `pano_cli simulate-document-history` exercises pure document history
   apply/undo/redo behavior and is covered by
   `pano_cli_simulate_document_history_smoke`.
+- `pano_cli simulate-image-import` decodes an embedded tiny PNG through
+  `pp_assets`, attaches it to `pp_document`, and is covered by
+  `pano_cli_simulate_image_import_smoke`.
 - `pano_cli simulate-stroke` exposes the pure stroke sampler for scripted
   automation and is covered by `pano_cli_simulate_stroke_smoke`.
 - `pano_cli simulate-stroke-script` loads a text stroke script fixture and is
@@ -257,6 +260,10 @@ Known local toolchain state:
 - `pano_cli simulate-document-edits` exposes `pp_document` layer metadata,
   frame order, active-index, and tiny face-payload state through JSON
   automation and is covered by `pano_cli_simulate_document_edits_smoke`.
+- `pano_cli simulate-image-import` exposes embedded PNG decode and document
+  face-payload attachment through JSON automation and is covered by
+  `pano_cli_simulate_image_import_smoke`; full file import/export remains a
+  future CLI automation task.
 - `pp_ui_core` consumes vcpkg tinyxml2 only when `PP_USE_VCPKG_TINYXML2=ON`
   through the vcpkg preset; default and Android validation still use the
   retained vendored fallback tracked by DEBT-0012.

docs/modernization/roadmap.md

@@ -343,7 +343,9 @@ frame count/duration. `pano_cli simulate-document-edits` exercises pure
 layer metadata, frame reordering, active-index preservation, and tiny
 face-payload attachment. `pano_cli simulate-document-history` exercises the
 pure `pp_document::DocumentHistory` apply/undo/redo path and emits JSON state
-summaries. `pano_cli simulate-stroke` exercises the pure stroke sampler for
+summaries. `pano_cli simulate-image-import` decodes an embedded tiny PNG
+through `pp_assets` and attaches the resulting RGBA8 payload to `pp_document`.
+`pano_cli simulate-stroke` exercises the pure stroke sampler for
 scripted-stroke automation. `pano_cli simulate-stroke-script`
 loads stroke script fixtures, parses them through `pp_paint`, and samples every
 stroke. `pano_cli parse-layout` exercises the XML layout path. Continue
@@ -694,6 +696,8 @@ Results:
   state as JSON.
 - `pano_cli_simulate_document_history_smoke` passed and reports real
   `pp_document::DocumentHistory` apply/undo/redo state as JSON.
+- `pano_cli_simulate_image_import_smoke` passed and reports embedded PNG decode
+  plus `pp_document` face-payload attachment state as JSON.
 - `pano_cli_inspect_image_rejects_unsupported` passed as an expected failure
   test.
 - `pano_cli_inspect_png_metadata_smoke` passed and reports PNG metadata JSON
@@ -761,6 +765,9 @@ Results:
 - `pano_cli simulate-document-edits` exercises pure document layer/frame edit
   operations and emits JSON metadata, frame order, and face-payload state for
   agent automation.
+- `pano_cli simulate-image-import` exercises embedded PNG decode through
+  `pp_assets` and `pp_document` face-payload attachment through JSON
+  automation. Full file import/export remains a future `pano_cli` task.
 - 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

tests/CMakeLists.txt

@@ -297,6 +297,12 @@ if(TARGET pano_cli)
         LABELS "document;integration;desktop-fast"
         PASS_REGULAR_EXPRESSION "\"command\":\"simulate-document-history\".*\"history\":\\{\"size\":3,\"currentIndex\":2,\"canUndo\":true,\"canRedo\":false\\}.*\"undo\":\\{\"layers\":2,\"frames\":1,\"currentIndex\":1,\"canRedo\":true\\}.*\"current\":\\{\"width\":64,\"height\":32,\"layers\":2,\"frames\":2,\"activeLayer\":1,\"activeFrame\":1,\"animationDurationMs\":350\\}")
 
+    add_test(NAME pano_cli_simulate_image_import_smoke
+        COMMAND pano_cli simulate-image-import --width 64 --height 32)
+    set_tests_properties(pano_cli_simulate_image_import_smoke PROPERTIES
+        LABELS "assets;document;integration;desktop-fast"
+        PASS_REGULAR_EXPRESSION "\"command\":\"simulate-image-import\".*\"image\":\\{\"format\":\"png\",\"width\":1,\"height\":1,\"bytes\":4,\"alpha\":0\\}.*\"document\":\\{\"width\":64,\"height\":32,\"layers\":1,\"frames\":1,\"facePayloads\":1\\}.*\"payload\":\\{\"face\":0,\"x\":0,\"y\":0,\"width\":1,\"height\":1,\"bytes\":4\\}")
+
     add_test(NAME pano_cli_simulate_stroke_smoke
         COMMAND pano_cli simulate-stroke --x1 0 --y1 0 --x2 10 --y2 0 --spacing 2)
     set_tests_properties(pano_cli_simulate_stroke_smoke PROPERTIES

tools/pano_cli/main.cpp

@@ -1,5 +1,6 @@
 #include "assets/image_format.h"
 #include "assets/image_metadata.h"
+#include "assets/image_pixels.h"
 #include "assets/ppi_header.h"
 #include "document/document.h"
 #include "document/ppi_import.h"
@@ -10,6 +11,7 @@
 #include "renderer_api/recording_renderer.h"
 #include "ui_core/layout_xml.h"
 
+#include <array>
 #include <cstdint>
 #include <fstream>
 #include <iostream>
@@ -58,6 +60,11 @@ struct SimulateDocumentEditsArgs {
     std::uint32_t height = 64;
 };
 
+struct SimulateImageImportArgs {
+    std::uint32_t width = 64;
+    std::uint32_t height = 32;
+};
+
 struct SimulateDocumentHistoryArgs {
     std::uint32_t width = 64;
     std::uint32_t height = 32;
@@ -129,6 +136,7 @@ void print_help()
         << "  record-render [--width N] [--height N]\n"
         << "  simulate-document-edits [--width N] [--height N]\n"
         << "  simulate-document-history [--width N] [--height N] [--history N]\n"
+        << "  simulate-image-import [--width N] [--height N]\n"
         << "  simulate-stroke --x1 N --y1 N --x2 N --y2 N [--spacing N]\n"
         << "  simulate-stroke-script --path FILE\n"
         << "  --help\n";
@@ -820,6 +828,125 @@ int simulate_document_edits(int argc, char** argv)
     return 0;
 }
 
+pp::foundation::Status parse_simulate_image_import_args(
+    int argc,
+    char** argv,
+    SimulateImageImportArgs& args)
+{
+    for (int i = 2; i < argc; ++i) {
+        const std::string_view key(argv[i]);
+        if (key == "--width" || key == "--height") {
+            if (i + 1 >= argc) {
+                return pp::foundation::Status::invalid_argument("missing value for option");
+            }
+
+            const auto value = pp::foundation::parse_u32(argv[++i]);
+            if (!value) {
+                return value.status();
+            }
+
+            if (key == "--width") {
+                args.width = value.value();
+            } else {
+                args.height = value.value();
+            }
+        } else {
+            return pp::foundation::Status::invalid_argument("unknown option");
+        }
+    }
+
+    if (args.width == 0 || args.height == 0) {
+        return pp::foundation::Status::invalid_argument("width and height must be greater than zero");
+    }
+
+    return pp::foundation::Status::success();
+}
+
+int simulate_image_import(int argc, char** argv)
+{
+    static constexpr std::array<std::byte, 68> transparent_png_1x1 {
+        std::byte { 0x89 }, std::byte { 0x50 }, std::byte { 0x4e }, std::byte { 0x47 },
+        std::byte { 0x0d }, std::byte { 0x0a }, std::byte { 0x1a }, std::byte { 0x0a },
+        std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x0d },
+        std::byte { 0x49 }, std::byte { 0x48 }, std::byte { 0x44 }, std::byte { 0x52 },
+        std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x01 },
+        std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x01 },
+        std::byte { 0x08 }, std::byte { 0x06 }, std::byte { 0x00 }, std::byte { 0x00 },
+        std::byte { 0x00 }, std::byte { 0x1f }, std::byte { 0x15 }, std::byte { 0xc4 },
+        std::byte { 0x89 }, std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x00 },
+        std::byte { 0x0b }, std::byte { 0x49 }, std::byte { 0x44 }, std::byte { 0x41 },
+        std::byte { 0x54 }, std::byte { 0x78 }, std::byte { 0x9c }, std::byte { 0x63 },
+        std::byte { 0x60 }, std::byte { 0x00 }, std::byte { 0x02 }, std::byte { 0x00 },
+        std::byte { 0x00 }, std::byte { 0x05 }, std::byte { 0x00 }, std::byte { 0x01 },
+        std::byte { 0x7a }, std::byte { 0x5e }, std::byte { 0xab }, std::byte { 0x3f },
+        std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x00 }, std::byte { 0x00 },
+        std::byte { 0x49 }, std::byte { 0x45 }, std::byte { 0x4e }, std::byte { 0x44 },
+        std::byte { 0xae }, std::byte { 0x42 }, std::byte { 0x60 }, std::byte { 0x82 },
+    };
+
+    SimulateImageImportArgs args;
+    const auto status = parse_simulate_image_import_args(argc, argv, args);
+    if (!status.ok()) {
+        print_error("simulate-image-import", status.message);
+        return 2;
+    }
+
+    const auto image_result = pp::assets::decode_png_rgba8(transparent_png_1x1);
+    if (!image_result) {
+        print_error("simulate-image-import", image_result.status().message);
+        return 2;
+    }
+
+    const auto document_result = pp::document::CanvasDocument::create(
+        pp::document::DocumentConfig {
+            .width = args.width,
+            .height = args.height,
+            .layer_count = 1,
+        });
+    if (!document_result) {
+        print_error("simulate-image-import", document_result.status().message);
+        return 2;
+    }
+
+    const auto& image = image_result.value();
+    auto document = document_result.value();
+    const auto import_status = document.set_layer_frame_face_pixels(
+        0,
+        0,
+        pp::document::LayerFacePixels {
+            .face_index = 0,
+            .x = 0,
+            .y = 0,
+            .width = image.width,
+            .height = image.height,
+            .rgba8 = image.pixels,
+        });
+    if (!import_status.ok()) {
+        print_error("simulate-image-import", import_status.message);
+        return 2;
+    }
+
+    const auto& payload = document.layers()[0].frames[0].face_pixels[0];
+    std::cout << "{\"ok\":true,\"command\":\"simulate-image-import\""
+              << ",\"image\":{\"format\":\"png\",\"width\":" << image.width
+              << ",\"height\":" << image.height
+              << ",\"bytes\":" << image.pixels.size()
+              << ",\"alpha\":" << static_cast<int>(image.pixels[3])
+              << "},\"document\":{\"width\":" << document.width()
+              << ",\"height\":" << document.height()
+              << ",\"layers\":" << document.layers().size()
+              << ",\"frames\":" << document.frames().size()
+              << ",\"facePayloads\":" << document.face_pixel_payload_count()
+              << "},\"payload\":{\"face\":" << payload.face_index
+              << ",\"x\":" << payload.x
+              << ",\"y\":" << payload.y
+              << ",\"width\":" << payload.width
+              << ",\"height\":" << payload.height
+              << ",\"bytes\":" << payload.rgba8.size()
+              << "}}\n";
+    return 0;
+}
+
 pp::foundation::Status parse_simulate_document_history_args(
     int argc,
     char** argv,
@@ -1165,6 +1292,10 @@ int main(int argc, char** argv)
         return simulate_document_history(argc, argv);
     }
 
+    if (command == "simulate-image-import") {
+        return simulate_image_import(argc, argv);
+    }
+
     if (command == "parse-layout") {
         return parse_layout(argc, argv);
     }