Add document export CLI automation

This commit is contained in:
2026-06-02 11:18:19 +02:00
parent 7b14c356db
commit 99b2eeb99d
5 changed files with 224 additions and 2 deletions

View File

@@ -120,6 +120,9 @@ Known local toolchain state:
- `pp_document_ppi_export_tests` exports pure `pp_document` metadata,
per-layer frame durations, and RGBA8 face payloads to PPI bytes through
`pp_assets`, then decodes and reimports them for round-trip coverage.
- `pano_cli simulate-document-export` exposes the same pure document-to-PPI
export, asset-level decode, and document reimport path through JSON
automation and is covered by `pano_cli_simulate_document_export_smoke`.
- `pano_cli load-project` creates a `pp_document` projection with per-layer
frame counts, durations, and decoded face-pixel payloads when present; the
metadata-only minimal fixture remains covered by
@@ -301,6 +304,8 @@ Known local toolchain state:
- `pp_document::export_ppi_project_document` exposes pure document-to-PPI byte
export through CTest coverage; legacy Canvas save integration remains a
future DEBT-0010/DEBT-0013 task.
- `pano_cli simulate-document-export` exposes document export round-trip state
through JSON automation for agent-driven checks.
- `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.

View File

@@ -28,10 +28,10 @@ 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, 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-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`; `pano_cli_simulate_document_export_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 |
| 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, CLI document export automation, 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`; `pano_cli_simulate_document_export_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 |
| 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

View File

@@ -352,6 +352,9 @@ exposes the generated writer for metadata-only and test dirty-face-payload
round-trips through `load-project`.
`pp_document::export_ppi_project_document` converts pure documents into PPI
bytes using that writer, including PNG-encoded layer/frame face payloads.
`pano_cli simulate-document-export` exercises that pure document export path,
decodes the generated PPI bytes, reimports them, and emits JSON round-trip
metadata.
`pano_cli create-document` can create simple animation documents with explicit
frame count/duration. `pano_cli simulate-document-edits` exercises pure
layer metadata, frame reordering, active-index preservation, tiny face-payload
@@ -359,6 +362,8 @@ attachment, and selection-mask attachment. `pano_cli simulate-document-history`
pure `pp_document::DocumentHistory` apply/undo/redo path and emits JSON state
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-document-export` exercises pure document-to-PPI export,
asset-level PPI image decode, and document reimport in one automation command.
`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
@@ -716,6 +721,9 @@ 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_document_export_smoke` passed and reports pure
`pp_document` export to PPI bytes, asset-level decode, and document reimport
round-trip 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
@@ -814,6 +822,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.
- `pano_cli simulate-document-export` exposes the same export path through JSON
automation for agents.
- 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

View File

@@ -352,6 +352,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_document_export_smoke
COMMAND pano_cli simulate-document-export --width 64 --height 32)
set_tests_properties(pano_cli_simulate_document_export_smoke PROPERTIES
LABELS "assets;document;integration;desktop-fast"
PASS_REGULAR_EXPRESSION "\"command\":\"simulate-document-export\".*\"source\":\\{\"width\":64,\"height\":32,\"layers\":2,\"frames\":2,\"facePayloads\":2\\}.*\"export\":\\{\"bytes\":[0-9]+,\"dirtyFaces\":2,\"rgbaFacePayloads\":2,\"compressedBytes\":[0-9]+\\}.*\"roundtrip\":\\{\"layers\":2,\"frames\":2,\"facePayloads\":2,\"layerNames\":\\[\"Base\",\"Paint\"\\],\"layerFrameCounts\":\\[2,1\\],\"layerDurationsMs\":\\[350,333\\]\\}.*\"payloads\":\\[\\{\"layer\":0,\"frame\":0,\"face\":0,\"x\":2,\"y\":3,\"bytes\":4,\"alpha\":255\\},\\{\"layer\":1,\"frame\":0,\"face\":5,\"x\":4,\"y\":5,\"bytes\":4,\"alpha\":128\\}\\]")
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

View File

@@ -3,6 +3,7 @@
#include "assets/image_pixels.h"
#include "assets/ppi_header.h"
#include "document/document.h"
#include "document/ppi_export.h"
#include "document/ppi_import.h"
#include "foundation/parse.h"
#include "foundation/result.h"
@@ -99,6 +100,11 @@ struct SimulateImageImportArgs {
std::uint32_t height = 32;
};
struct SimulateDocumentExportArgs {
std::uint32_t width = 64;
std::uint32_t height = 32;
};
struct SimulateDocumentHistoryArgs {
std::uint32_t width = 64;
std::uint32_t height = 32;
@@ -210,6 +216,7 @@ void print_help()
<< " record-render [--width N] [--height N]\n"
<< " save-project --path FILE --width N --height N [--layer-name NAME] [--layer-opacity N] [--blend-mode N] [--alpha-locked] [--hidden] [--layers N] [--frames N] [--frame-duration-ms N] [--include-test-face-payload] [--payload-layer N] [--payload-frame N]\n"
<< " simulate-document-edits [--width N] [--height N]\n"
<< " simulate-document-export [--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"
@@ -1464,6 +1471,196 @@ int simulate_image_import(int argc, char** argv)
return 0;
}
pp::foundation::Status parse_simulate_document_export_args(
int argc,
char** argv,
SimulateDocumentExportArgs& 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");
}
if (args.width < 8 || args.height < 8) {
return pp::foundation::Status::out_of_range("width and height must be at least 8 for export simulation");
}
return pp::foundation::Status::success();
}
int simulate_document_export(int argc, char** argv)
{
SimulateDocumentExportArgs args;
const auto status = parse_simulate_document_export_args(argc, argv, args);
if (!status.ok()) {
print_error("simulate-document-export", status.message);
return 2;
}
const std::vector<std::uint8_t> red_pixel { 255, 0, 0, 255 };
const std::vector<std::uint8_t> blue_pixel { 0, 0, 255, 128 };
const pp::document::AnimationFrame root_frames[] {
{ .duration_ms = 100, .face_pixels = {} },
{ .duration_ms = 250, .face_pixels = {} },
};
const pp::document::AnimationFrame base_frames[] {
{
.duration_ms = 100,
.face_pixels = {
pp::document::LayerFacePixels {
.face_index = 0,
.x = 2,
.y = 3,
.width = 1,
.height = 1,
.rgba8 = red_pixel,
},
},
},
{ .duration_ms = 250, .face_pixels = {} },
};
const pp::document::AnimationFrame paint_frames[] {
{
.duration_ms = 333,
.face_pixels = {
pp::document::LayerFacePixels {
.face_index = 5,
.x = 4,
.y = 5,
.width = 1,
.height = 1,
.rgba8 = blue_pixel,
},
},
},
};
const pp::document::DocumentLayerConfig layers[] {
{
.name = "Base",
.visible = true,
.alpha_locked = false,
.opacity = 1.0F,
.blend_mode = pp::paint::BlendMode::normal,
.frames = std::span<const pp::document::AnimationFrame>(base_frames, 2),
},
{
.name = "Paint",
.visible = false,
.alpha_locked = true,
.opacity = 0.5F,
.blend_mode = pp::paint::BlendMode::overlay,
.frames = std::span<const pp::document::AnimationFrame>(paint_frames, 1),
},
};
const auto document_result = pp::document::CanvasDocument::create_from_snapshot(
pp::document::DocumentSnapshotConfig {
.width = args.width,
.height = args.height,
.layers = std::span<const pp::document::DocumentLayerConfig>(layers, 2),
.frames = std::span<const pp::document::AnimationFrame>(root_frames, 2),
.selection_masks = {},
});
if (!document_result) {
print_error("simulate-document-export", document_result.status().message);
return 2;
}
const auto exported = pp::document::export_ppi_project_document(document_result.value());
if (!exported) {
print_error("simulate-document-export", exported.status().message);
return 2;
}
const auto decoded = pp::assets::decode_ppi_project_images(exported.value());
if (!decoded) {
print_error("simulate-document-export", decoded.status().message);
return 2;
}
const auto imported = pp::document::import_ppi_project_document(decoded.value());
if (!imported) {
print_error("simulate-document-export", imported.status().message);
return 2;
}
const auto& source = document_result.value();
const auto& roundtrip = imported.value();
std::cout << "{\"ok\":true,\"command\":\"simulate-document-export\""
<< ",\"source\":{\"width\":" << source.width()
<< ",\"height\":" << source.height()
<< ",\"layers\":" << source.layers().size()
<< ",\"frames\":" << source.frames().size()
<< ",\"facePayloads\":" << source.face_pixel_payload_count()
<< "},\"export\":{\"bytes\":" << exported.value().size()
<< ",\"dirtyFaces\":" << decoded.value().project.body.summary.dirty_face_count
<< ",\"rgbaFacePayloads\":" << decoded.value().project.body.summary.rgba_face_payload_count
<< ",\"compressedBytes\":" << decoded.value().project.body.summary.compressed_face_bytes
<< "},\"roundtrip\":{\"layers\":" << roundtrip.layers().size()
<< ",\"frames\":" << roundtrip.frames().size()
<< ",\"facePayloads\":" << roundtrip.face_pixel_payload_count()
<< ",\"layerNames\":[";
for (std::size_t layer_index = 0; layer_index < roundtrip.layers().size(); ++layer_index) {
if (layer_index != 0U) {
std::cout << ",";
}
std::cout << "\"" << json_escape(roundtrip.layers()[layer_index].name) << "\"";
}
std::cout << "],\"layerFrameCounts\":[";
for (std::size_t layer_index = 0; layer_index < roundtrip.layers().size(); ++layer_index) {
if (layer_index != 0U) {
std::cout << ",";
}
std::cout << roundtrip.layers()[layer_index].frames.size();
}
std::cout << "],\"layerDurationsMs\":[";
for (std::size_t layer_index = 0; layer_index < roundtrip.layers().size(); ++layer_index) {
if (layer_index != 0U) {
std::cout << ",";
}
const auto duration = roundtrip.layer_animation_duration_ms(layer_index);
std::cout << (duration ? duration.value() : 0U);
}
std::cout << "]},\"payloads\":[";
for (std::size_t payload_index = 0; payload_index < decoded.value().faces.size(); ++payload_index) {
const auto& payload = decoded.value().faces[payload_index];
if (payload_index != 0U) {
std::cout << ",";
}
std::cout << "{\"layer\":" << payload.layer_index
<< ",\"frame\":" << payload.frame_index
<< ",\"face\":" << payload.face_index
<< ",\"x\":" << payload.descriptor.x0
<< ",\"y\":" << payload.descriptor.y0
<< ",\"bytes\":" << payload.image.pixels.size()
<< ",\"alpha\":" << static_cast<int>(payload.image.pixels[3])
<< "}";
}
std::cout << "]}\n";
return 0;
}
pp::foundation::Status parse_simulate_document_history_args(
int argc,
char** argv,
@@ -1813,6 +2010,10 @@ int main(int argc, char** argv)
return simulate_document_edits(argc, argv);
}
if (command == "simulate-document-export") {
return simulate_document_export(argc, argv);
}
if (command == "simulate-document-history") {
return simulate_document_history(argc, argv);
}