diff --git a/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i-ordered-composition.md b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i-ordered-composition.md index 01f67226..02f595aa 100644 --- a/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i-ordered-composition.md +++ b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i-ordered-composition.md @@ -271,8 +271,10 @@ ledger only after the complete pipeline is live. tests / 3 intentional skips; the complete Release suite passes 7,745 tests / 5 intentional skips. Production App builds with zero warnings/errors; the solution retains only the 17 warnings tracked by #228. -- I.6 (retained UI plus live-presentation composition) is next. Checkpoint I - remains active until I.9 closes the complete nine-phase pipeline. +- I.6 (retained UI plus live-presentation composition) is active. Its detailed + two-commit ownership and failure-test plan is + [`2026-07-22-gamewindow-slice-8-checkpoint-i6-ui-live-presentation.md`](2026-07-22-gamewindow-slice-8-checkpoint-i6-ui-live-presentation.md). + Checkpoint I remains active until I.9 closes the complete nine-phase pipeline. ## 6. Automated acceptance diff --git a/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i6-ui-live-presentation.md b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i6-ui-live-presentation.md new file mode 100644 index 00000000..633fcf11 --- /dev/null +++ b/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-i6-ui-live-presentation.md @@ -0,0 +1,200 @@ +# GameWindow Slice 8 — Checkpoint I.6 UI and Live Presentation + +**Status:** Active + +**Parent:** `2026-07-22-gamewindow-slice-8-checkpoint-i-ordered-composition.md` + +**Scope:** Ordered-composition phases 5 and 6 only + +## 1. Outcome + +Remove the interaction, retained gameplay UI, live-entity presentation, and +landblock-publication construction bodies from `GameWindow.OnLoad`. The window +remains a write-only publication surface and runtime coordinator; it does not +remain an implicit service locator for callbacks created during startup. + +I.6 lands as two independently buildable commits: + +1. **I.6a — interaction and retained UI composition.** +2. **I.6b — live presentation and landblock publication composition.** + +Neither commit changes retail behavior, rendering order, input priority, +network messages, selection policy, DAT lookup, or resource quality. This is a +structural ownership move, so it does not add a divergence-register row. + +## 2. I.6a — interaction and retained UI + +### 2.1 Owned construction + +`InteractionRetainedUiCompositionPhase` constructs, in the existing order: + +1. combat attack controller; +2. combat target controller; +3. external-container lifecycle; +4. item interaction controller; +5. optional retained UI host; +6. cursor feedback and retail cursor resources; +7. character-sheet and magic runtimes; +8. retained mouse and keyboard bindings; +9. chrome/icon/font assets; +10. chat, radar, persistence, and optional probe owners; +11. uninitialized retained UI runtime mount. + +The non-UI combat and item owners exist even when retail UI is disabled. The +disabled path acquires no UI host, input callback, font, cursor, probe, or +runtime resource. + +### 2.2 Focused authorities + +Callbacks that formerly captured `GameWindow` resolve through typed owners: + +- `DeferredLiveSessionUiAuthority` exposes the current session, command bus, + link facts, character account, and the exact outbound operations needed by + interaction/UI. It binds to the Phase-7 `LiveSessionController` with an + expected-owner token and safely supplies disconnected/no-op values before + that bind. +- `DeferredSelectionUiAuthority` exposes world picking, use/pickup dispatch, + closest-target selection, range/health classification, vivid-target facts, + and camera facts. Phase 6 binds its exact query/controller pair. +- `DeferredRadarSnapshotSource` returns an empty-but-valid snapshot until + Phase 6 publishes the canonical `LiveEntityRuntime`/`GpuWorldState` view. It + must never retain the pre-runtime placeholder world. +- `DeferredWorldLifecycleAutomationSource` lets the optional UI probe mount in + Phase 5 while Phase 7 supplies reveal/resource facts later. +- the already focused local-player identity, controller, mode, external- + container, settings, and input-dispatch sources replace raw host fields. +- a shared `DeferredRenderFrameDiagnosticsSource` exists regardless of whether + developer tools are enabled; Phase 6 binds the diagnostics owner once. + +Every deferred bind returns or is paired with an expected-owner unbind. A stale +release can neither clear a newer owner nor make retry report “already bound”. +Deactivation makes all callbacks inert before runtime teardown. + +### 2.3 Ownership and publication + +`InteractionRetainedUiResult` carries the stable owners required by later +phases. `InteractionRetainedUiCompositionOwner` owns optional retained-UI +input/runtime resources and the late authorities. Construction uses +`CompositionAcquisitionScope`; the owner is published only after all mandatory +interaction resources and every enabled retained-UI resource are complete. + +`IGameWindowInteractionRetainedUiPublication` publishes exact field identities +needed by existing steady-state and reset code. Publication is write-only and +rejects replacement. + +Normal shutdown and construction rollback share these stages: + +1. deactivate late sources and retained input; +2. detach retained UI device callbacks; +3. dispose mounted runtime; +4. dispose host/assets/probe resources; +5. dispose item/external-container/combat owners. + +The existing retained UI lease remains the sole host/runtime owner until its +full lifecycle is migrated; the phase owner controls it but never duplicates +its resources. + +### 2.4 I.6a automated gates + +- exact success order and disabled-UI acquisition trace; +- injected failure after every construction, attach, mount, and publication + edge; +- reverse rollback, retry after partial cleanup, and no replay; +- late authority default behavior, exact-owner unbind, stale-token rejection, + deactivation, and rebind after rollback; +- session operations preserve the former outbound message selection; +- radar cannot observe a pre-runtime `GpuWorldState` placeholder; +- retained mouse-before-keyboard wiring and input capture are unchanged; +- publication identity and replacement rejection; +- App Release build/tests, then full solution Release build/tests; +- three independent self-review passes: retail behavior, architecture and + ownership, adversarial failure/reentrancy. + +## 3. I.6b — live presentation and landblock publication + +### 3.1 Owned construction + +`LivePresentationCompositionPhase` constructs, in existing order: + +1. deferred live-component lifecycle; +2. landblock and entity spawn adapters; +3. static animation/script activation owners; +4. canonical `GpuWorldState`; +5. `LiveEntityRuntime`, followed immediately by canonical slot bind; +6. motion, projectile, withdrawal, light, animation, equipped-child, effect, + presentation, and remote-teleport owners; +7. WB dispatcher and retail selection scene/query/controller; +8. optional paperdoll renderer/presenter; +9. EnvCell/portal/clip/tunnel/sky/particle render resources; +10. landblock render/physics/static publishers and presentation pipeline; +11. render diagnostics and canonical late-source bindings. + +The phase consumes immutable Phase-4 terrain/build inputs. It does not read +mutable `GameWindow` terrain fields. + +### 3.2 Named reversible edges + +Replace anonymous subscriptions with named lease owners: + +- live projection visibility → WB presentation residency; +- live projection visibility → particle presentation visibility; +- equipped-child projection pose → live-entity lights. + +Each lease stores the exact delegate and publisher, detaches once, supports +retry if a later release fails, and is inert before dependent teardown. +Phase-7 entity-ready and appearance-applied subscriptions are deliberately +handled in I.7, where both publishers exist. + +### 3.3 Canonical publication and late binding + +The result publishes one canonical world/runtime identity. Phase 5 radar and +selection authorities bind only after those identities exist. The live-runtime +slot binds immediately after runtime construction and receives an exact-owner +unbind token for rollback. + +Landblock-loaded hydration uses a deferred sink owned by the result. Phase 7 +binds it to `LiveEntityHydrationController`; no Phase-6 callback captures a +future nullable controller. + +Portal tunnel ownership remains: + +```text +fallback slot acquire -> prepared transfer -> final frame owner +``` + +The fallback slot and final owner never co-own the tunnel. + +### 3.4 I.6b automated gates + +- exact production construction order and canonical slot-bind position; +- failure at every construction/subscription/bind/publication edge; +- canonical runtime/world identity through radar, selection, devtools, and + frame diagnostics sources; +- loaded, pending, rebucketed, hidden, and deleted live records retain the + existing presentation behavior; +- event leases detach exact delegates once and survive callback reentrancy; +- no duplicate mesh, particle, light, script, selection, or collision owner; +- portal fallback acquire/prepare/transfer failure matrix; +- landblock publisher ordering and retirement symmetry; +- App Release build/tests, full Release build/tests, divergence/source audit; +- three independent self-review passes as in I.6a. + +## 4. Production cutover rules + +- Each subcommit leaves `OnLoad` calling the new phase and leaves later phases + consuming the typed result; no duplicate inline construction remains. +- Existing steady-state code may temporarily read published fields until I.8, + but new phase code cannot capture the window. +- I.6a may bind its selection/session/diagnostic authorities at the existing + Phase-6/7 construction sites. I.6b moves the Phase-6 binds into its result; + I.7 moves the remaining Phase-7 binds into the session/streaming phase. +- No broad interface exposes the window. Dependencies are explicit records of + stable owners and focused sources. +- No behavior change is accepted merely to simplify composition. + +## 5. Exit evidence + +I.6 is complete only when both production phase bodies have moved, the old +inline blocks and host callback wrappers are deleted, the late-source and +failure matrices pass, full Release gates are green, documentation/memory +reflect the new boundary, and both commits are individually buildable.