Route app frame decisions through app core

docs/modernization/build-inventory.md

@@ -241,6 +241,11 @@ Known local toolchain state:
   retained shader loading, asset initialization, layout creation, title updates,
   UI render-target creation, recording startup, VR-controller state mutation,
   settings writes, and license-warning dialogs remain legacy execution.
+- `src/app_core/app_frame.h` owns the current initial surface, update-gating,
+  and draw-pass decisions consumed by `App::create`, `App::update`,
+  `App::draw`, and `pano_cli plan-app-frame`; retained layout traversal,
+  toolbar widget writes, canvas stroke drawing, VR UI render-target drawing,
+  main target binding, and OpenGL/UI drawing remain in the legacy app.
 - `src/legacy_app_preference_services.*` is the current app-shell bridge for
   options-menu preference execution. It keeps UI scale, viewport scale, RTL,
   VR mode, VR-controller, auto-timelapse, and canvas cursor-mode callbacks on
@@ -824,6 +829,9 @@ Known local toolchain state:
   planning, optional auto-timelapse/license/VR-controller decisions, negative
   and overflow run-counter rejection, stable full startup dispatch ordering,
   split persistence/runtime dispatch, and malformed startup-plan rejection.
+- `pp_app_core_app_frame_tests` covers the legacy initial surface default,
+  idle/redraw/animation update gating, canvas-stroke draw eligibility, VR UI
+  visibility, main UI suppression in VR-only mode, and redraw reset planning.
 - `pp_platform_api_tests` covers service dispatch for clipboard read/write,
   empty clipboard writes, cursor visibility, virtual-keyboard visibility,
   external file display, file sharing, VR lifecycle, layout/asset file load

docs/modernization/debt.md

@@ -20,7 +20,7 @@ agent or engineer to remove them without reconstructing context from chat.
 
 - 2026-06-04: DEBT-0009 was narrowed. `platform-build.ps1` and
   `platform-build.sh` now include the current headless component/test matrix,
-  including brush-package coverage and the app-core startup/file/document/
+  including brush-package coverage and the app-core startup/frame/file/document/
   brush/canvas/history/grid/toolbar/tools/about/preferences/status automation
   tests, and `panopainter_platform_build_target_matrix_self_test` now verifies
   the wrapper defaults against the current CMake test executables. On
@@ -91,6 +91,12 @@ agent or engineer to remove them without reconstructing context from chat.
   the retained OpenGL startup task in place, then delegates startup resources
   and runtime side effects through the startup bridge. `pano_cli
   plan-app-startup-resources` exposes the resource path for automation.
+- 2026-06-05: DEBT-0003 was narrowed. Initial surface sizing, redraw/animation
+  update gating, canvas-stroke draw eligibility, VR UI pass selection, main UI
+  pass selection, and redraw reset are now tested `pp_app_core` frame plans
+  consumed by `App::create`, `App::update`, `App::draw`, and
+  `pano_cli plan-app-frame`; retained layout traversal, toolbar widget writes,
+  and OpenGL/UI drawing remain in the legacy app.
 - 2026-06-04: DEBT-0036 was narrowed again. Canvas stroke commit,
   thumbnail, and object-draw history paths now query saved blend state through
   tested `pp_renderer_gl` capability-state dispatch; CanvasLayer equirect

docs/modernization/roadmap.md

@@ -198,6 +198,11 @@ and floating-point render targets; `App::title_update`,
 `App::update_memory_usage`, `App::update_rec_frames`, resolution helpers,
 `App::initLayout`, and `pano_cli plan-app-status` consume those contracts while
 legacy UI nodes still render the strings and status lights.
+Frame-level app decisions for the initial surface size, redraw/animation update
+gating, canvas-stroke drawing, VR UI drawing, main UI drawing, and redraw reset
+now live in `pp_app_core`; `App::create`, `App::update`, `App::draw`, and
+`pano_cli plan-app-frame` consume those plans while retained layout traversal
+and OpenGL/UI drawing stay in the legacy app.
 `panopainter_app` is now a real static target that owns app orchestration
 sources, app version metadata, and version-header generation.
 `pp_panopainter_ui` now owns app-specific modal, dialog, panel, canvas,
@@ -1286,7 +1291,7 @@ standard x64/arm64, Android Quest arm64, Android Focus/Wave arm64,
 Emscripten/WebGL, macOS, iOS device, and iOS simulator. `platform-build`
 automation now builds the current headless component matrix, including
 `pp_platform_api`, `pp_app_core`, platform API tests, brush-package tests, and
-the current app-core startup/file/document/brush/canvas/history/grid/toolbar/
+the current app-core startup/frame/file/document/brush/canvas/history/grid/toolbar/
 tools/about/preferences/status automation tests. The PowerShell wrapper also
 normalizes comma-separated `-Presets` and `-Targets` values for reliable
 machine-driven partial matrix checks. `panopainter_platform_build_target_matrix_self_test`
@@ -1643,6 +1648,11 @@ Results:
   `pano_cli_plan_app_startup_rejects_negative_counter`, with startup resource
   sequencing also covered by `pano_cli_plan_app_startup_resources_smoke` and
   `pano_cli_plan_app_startup_resources_rejects_bad_size`.
+- `PanoPainter`, `pp_app_core_app_frame_tests`, and `pano_cli` built after
+  app frame surface/update/draw-pass decisions moved into `pp_app_core`.
+- Focused frame CTest coverage passed for `pp_app_core_app_frame_tests`,
+  `pano_cli_plan_app_frame_vr_smoke`, and
+  `pano_cli_plan_app_frame_idle_missing_canvas_smoke`.
 - `PanoPainter`, `pp_app_core_brush_package_export_tests`, and `pano_cli` built
   after PPBR brush package export request validation and dispatch moved behind
   app-core brush package services.