Expose document history through pano cli

docs/modernization/build-inventory.md

@@ -113,6 +113,9 @@ Known local toolchain state:
   `pano_cli_load_project_metadata_smoke`.
 - `pano_cli create-document` supports `--frames` and `--frame-duration-ms` and
   is covered by `pano_cli_create_animation_document_smoke`.
+- `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-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
@@ -246,6 +249,9 @@ Known local toolchain state:
   window or GL context.
 - `pano_cli record-render` exposes the recording renderer through JSON
   automation and is covered by `pano_cli_record_render_smoke`.
+- `pano_cli simulate-document-history` exposes `pp_document::DocumentHistory`
+  apply/undo/redo state through JSON automation and is covered by
+  `pano_cli_simulate_document_history_smoke`.
 - `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

@@ -339,8 +339,10 @@ asset-level decode coverage, and
 counts, durations, and decoded face-pixel payload attachment when PPI image
 payloads are present.
 `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`
+frame count/duration. `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
+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
 expanding document behavior toward legacy Canvas parity and then port OpenGL
@@ -685,6 +687,8 @@ Results:
 - `pano_cli_create_document_smoke` passed.
 - `pano_cli_create_animation_document_smoke` passed and reports animation
   duration JSON.
+- `pano_cli_simulate_document_history_smoke` passed and reports real
+  `pp_document::DocumentHistory` apply/undo/redo 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
@@ -746,6 +750,9 @@ Results:
 - `pano_cli record-render` exercises that headless recording renderer and emits
   JSON command counts, target dimensions, backend name, and trace/draw summary
   for agent automation.
+- `pano_cli simulate-document-history` exercises pure document history
+  apply/undo/redo behavior and emits JSON layer/frame/history state for agent
+  automation.
 - 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

@@ -285,6 +285,12 @@ if(TARGET pano_cli)
         LABELS "renderer;integration;desktop-fast"
         PASS_REGULAR_EXPRESSION "\"backend\":\"recording\".*\"width\":32.*\"height\":16.*\"commands\":7.*\"drawCommands\":1")
 
+    add_test(NAME pano_cli_simulate_document_history_smoke
+        COMMAND pano_cli simulate-document-history --width 64 --height 32 --history 4)
+    set_tests_properties(pano_cli_simulate_document_history_smoke PROPERTIES
+        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_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

@@ -53,6 +53,12 @@ struct SimulateStrokeScriptArgs {
     std::string path;
 };
 
+struct SimulateDocumentHistoryArgs {
+    std::uint32_t width = 64;
+    std::uint32_t height = 32;
+    std::uint32_t history_entries = 4;
+};
+
 struct RecordRenderArgs {
     std::uint32_t width = 64;
     std::uint32_t height = 32;
@@ -116,6 +122,7 @@ void print_help()
         << "  load-project --path FILE\n"
         << "  parse-layout --path FILE\n"
         << "  record-render [--width N] [--height N]\n"
+        << "  simulate-document-history [--width N] [--height N] [--history N]\n"
         << "  simulate-stroke --x1 N --y1 N --x2 N --y2 N [--spacing N]\n"
         << "  simulate-stroke-script --path FILE\n"
         << "  --help\n";
@@ -631,6 +638,135 @@ int simulate_stroke_script(int argc, char** argv)
     return 0;
 }
 
+pp::foundation::Status parse_simulate_document_history_args(
+    int argc,
+    char** argv,
+    SimulateDocumentHistoryArgs& args)
+{
+    for (int i = 2; i < argc; ++i) {
+        const std::string_view key(argv[i]);
+        if (key == "--width" || key == "--height" || key == "--history") {
+            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 if (key == "--height") {
+                args.height = value.value();
+            } else {
+                args.history_entries = 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_document_history(int argc, char** argv)
+{
+    SimulateDocumentHistoryArgs args;
+    const auto status = parse_simulate_document_history_args(argc, argv, args);
+    if (!status.ok()) {
+        print_error("simulate-document-history", 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-document-history", document_result.status().message);
+        return 2;
+    }
+
+    auto history_result = pp::document::DocumentHistory::create(
+        document_result.value(),
+        static_cast<std::size_t>(args.history_entries));
+    if (!history_result) {
+        print_error("simulate-document-history", history_result.status().message);
+        return 2;
+    }
+
+    auto history = history_result.value();
+    auto with_layer = history.current();
+    const auto layer_result = with_layer.add_layer("Paint");
+    if (!layer_result) {
+        print_error("simulate-document-history", layer_result.status().message);
+        return 2;
+    }
+
+    auto apply_status = history.apply(with_layer);
+    if (!apply_status.ok()) {
+        print_error("simulate-document-history", apply_status.message);
+        return 2;
+    }
+
+    auto with_frame = history.current();
+    const auto frame_result = with_frame.add_frame(250);
+    if (!frame_result) {
+        print_error("simulate-document-history", frame_result.status().message);
+        return 2;
+    }
+
+    apply_status = history.apply(with_frame);
+    if (!apply_status.ok()) {
+        print_error("simulate-document-history", apply_status.message);
+        return 2;
+    }
+
+    const auto undo_status = history.undo();
+    if (!undo_status.ok()) {
+        print_error("simulate-document-history", undo_status.message);
+        return 2;
+    }
+
+    const auto undo_layers = history.current().layers().size();
+    const auto undo_frames = history.current().frames().size();
+    const auto undo_can_redo = history.can_redo();
+    const auto undo_index = history.current_index();
+
+    const auto redo_status = history.redo();
+    if (!redo_status.ok()) {
+        print_error("simulate-document-history", redo_status.message);
+        return 2;
+    }
+
+    const auto& current = history.current();
+    std::cout << "{\"ok\":true,\"command\":\"simulate-document-history\""
+              << ",\"history\":{\"size\":" << history.size()
+              << ",\"currentIndex\":" << history.current_index()
+              << ",\"canUndo\":" << (history.can_undo() ? "true" : "false")
+              << ",\"canRedo\":" << (history.can_redo() ? "true" : "false")
+              << "},\"undo\":{\"layers\":" << undo_layers
+              << ",\"frames\":" << undo_frames
+              << ",\"currentIndex\":" << undo_index
+              << ",\"canRedo\":" << (undo_can_redo ? "true" : "false")
+              << "},\"current\":{\"width\":" << current.width()
+              << ",\"height\":" << current.height()
+              << ",\"layers\":" << current.layers().size()
+              << ",\"frames\":" << current.frames().size()
+              << ",\"activeLayer\":" << current.active_layer_index()
+              << ",\"activeFrame\":" << current.active_frame_index()
+              << ",\"animationDurationMs\":" << current.animation_duration_ms()
+              << "}}\n";
+    return 0;
+}
+
 pp::foundation::Status parse_record_render_args(int argc, char** argv, RecordRenderArgs& args)
 {
     for (int i = 2; i < argc; ++i) {
@@ -839,6 +975,10 @@ int main(int argc, char** argv)
         return simulate_stroke_script(argc, argv);
     }
 
+    if (command == "simulate-document-history") {
+        return simulate_document_history(argc, argv);
+    }
+
     if (command == "parse-layout") {
         return parse_layout(argc, argv);
     }