panopainter/AGENTS.md

AGENTS.md

This file is the quick-start map for agents working in this repository. Keep it small and point to the live docs instead of duplicating the whole plan.

Current Modernization Goal

PanoPainter is being incrementally modernized into independently testable C++23 components while preserving current behavior. OpenGL remains the working backend until the renderer boundary is proven; Vulkan/Metal/WebGPU work waits behind that boundary.

Read these first:

• docs/modernization/roadmap.md - live phase roadmap, recent results, and next work queue.
• docs/modernization/debt.md - required debt log. Every temporary adapter, retained legacy dependency, skipped platform, fallback, or shortcut needs an entry with validation and removal conditions.
• docs/modernization/capability-map.md - behavior that must be preserved.
• docs/modernization/build-inventory.md - current build/component inventory.
• docs/adr/0001-modernization-boundaries.md - component boundary decisions.

Working Rules

• Work on codex/modernization-cmake-foundation unless the user says otherwise.
• Commit and push each verified successful progress slice.
• Prefer larger coherent slices over tiny checkpoints, but keep docs/debt updated with each slice.
• Do not revert user changes. Unrelated untracked notes, such as docs/human-review-notes.md, should be left alone unless explicitly requested.
• Use CMake as the source of truth. Legacy Visual Studio project files are not the modernization path.
• Use apply_patch for manual source/doc edits.

Build And Test

Primary Windows configure/build:

cmake --preset windows-msvc-default
cmake --build --preset windows-msvc-default --config Debug --target PanoPainter pano_cli

Focused fast validation:

ctest --preset desktop-fast --build-config Debug --output-on-failure

Useful targeted pattern:

ctest --preset desktop-fast --build-config Debug -R "pp_app_core|pano_cli_plan" --output-on-failure

If MSVC reports corrupt debug information or stale PDB/object errors, clean the generated build tree target before judging source changes:

cmake --build --preset windows-msvc-default --config Debug --target clean

Current Architecture Direction

The desired component split is documented in the roadmap. Current extracted or in-progress boundaries include:

• pp_foundation
• pp_assets
• pp_paint
• pp_document
• pp_renderer_api
• pp_renderer_gl
• pp_paint_renderer
• pp_app_core
• pp_panopainter_ui
• pp_platform_*
• panopainter_app

Legacy UI/app code still exists and is being reduced through pure planners, service interfaces, CLI automation, and CTest coverage. When moving behavior out of a legacy node, preserve current behavior first, add focused tests, document remaining shortcuts in docs/modernization/debt.md, then wire the live adapter.

Legacy Context

PanoPainter started as a flat C++17 OpenGL panoramic painting app centered on singletons such as App::I, Canvas::I, Settings, and WacomTablet::I. Rendering uses GLAD/OpenGL and shaders in data/shaders/. UI is XML/Yoga based with many Node* subclasses. Project files are PPI, brush packages are PPBR, and Photoshop brushes import through ABR support.

Exceptions are disabled in app code. Public modernization APIs should return explicit status/result objects.