Extract shared HUD layer into core engine and adopt across games

[SorraTheOrc]

Headline

Extract a shared HUD layer abstraction into core engine and migrate all example games to use it for help, settings, game-over, and end-round overlays.

Problem statement

HUD/sidebar/overlay layering is implemented inconsistently across games, with Main Street currently driving a targeted HUD-layer fix. Without a shared core abstraction, layering behavior and maintenance costs diverge across scenes.

Users

• Players: need overlay/sidebar UI (help, settings, game-over, end-round) to consistently render above gameplay content.
• QA: need deterministic and reusable layering behavior across all games for regression verification.
• Developers: need one core-engine HUD-layer pattern to avoid per-game ad hoc depth/container logic.

Success criteria

• A reusable HUD layer abstraction exists in core engine and is exposed via shared APIs used by game scenes.
• All games under example-games/ are migrated to use the shared HUD layer for help, settings, game-over, and end-round overlays where present.
• No migrated game has overlay/sidebar UI rendering behind gameplay/card layers in normal play and end-state flows.
• Automated tests are added or updated to validate overlay/sidebar layering behavior on representative game scenes, including end-round overlays where applicable.
• All related documentation is updated to reflect the changes, including code comments, README, and any relevant wiki or docs site entries.
• Full project test suite must pass with the new changes.

Constraints

• This work item is dependent on Main Street: move overlay and sidebar UI to shared HUD layer (CG-0MP1TAZU5008OTJY).
• Migration scope is all games in example-games/.
• Required migration depth includes help, settings, game-over, and end-round overlays when a game provides them.
• Do not keep a temporary backward-compatibility path in @ui; update call sites directly to the new shared abstraction.
• Do not change game rules, scoring, or non-layering gameplay behavior.

Existing state

• CardGameScene currently initializes HelpPanel and SettingsPanel directly (src/ui/CardGameScene.ts).
• Overlay primitives exist (src/ui/Overlay.ts, src/ui/OverlayManager.ts), but there is no single shared HUD layer contract adopted by all games.
• Main Street has an in-flight dependency focused on consolidating overlay/sidebar surfaces into a HUD layer (CG-0MP1TAZU5008OTJY).
• Multiple games still manage overlays independently in game-specific managers under example-games/*/scenes/*OverlayManager.ts.

Desired change

• Extract and document a core-engine HUD-layer abstraction that provides a consistent top-layer container/ownership model for overlay/sidebar UI.
• Integrate the abstraction into shared scene foundations (@ui / CardGameScene) so help and settings attach consistently.
• Migrate all example games to use the shared HUD layer for modal and sidebar surfaces, including end-round overlays when those exist.
• Update/add tests and docs to validate and explain the new cross-game HUD-layer contract.

Related work

• Main Street: move overlay and sidebar UI to shared HUD layer (CG-0MP1TAZU5008OTJY) — prerequisite dependency and source implementation intent.
• Extract MainStreetOverlayManager (CG-0MP0B51RK002C0EV) — prior modularization of Main Street overlays.
• src/ui/CardGameScene.ts — common scene entry point for HelpPanel/SettingsPanel initialization.
• src/ui/HelpPanel.ts and src/ui/SettingsPanel.ts — reusable sidebar components that must adopt shared HUD layer semantics.
• src/ui/Overlay.ts and src/ui/OverlayManager.ts — existing shared overlay utilities to align with the extracted HUD layer.

Related work (automated report)

• CG-0MP1TAZU5008OTJY defines game-level HUD-layer consolidation in Main Street and is the direct precursor for promoting the pattern into shared engine modules.
• src/ui/CardGameScene.ts is the highest-leverage integration point because it already centralizes help/settings initialization for many games.
• Existing overlay helpers (src/ui/Overlay.ts, src/ui/OverlayManager.ts) suggest the codebase already favors reusable UI primitives; this item extends that approach to container/layer ownership.
• Game-specific overlay managers across example-games/*/scenes indicate migration breadth and justify explicit acceptance criteria covering all games.

Risks & assumptions

• Risk: broad migration across all games can introduce regressions in input order, focus behavior, and overlay dismissal flow. Mitigation: require representative automated coverage and full-suite validation.
• Risk: some games may have scene-specific overlay timing/depth assumptions that conflict with a single abstraction. Mitigation: document game-specific deviations as linked follow-up work items instead of expanding this item’s scope.
• Risk: scope creep into non-layering refactors while touching many scenes. Mitigation: record additional opportunities as linked work items and keep this item focused on HUD-layer extraction/adoption.
• Assumption: CG-0MP1TAZU5008OTJY will provide a usable reference implementation pattern.
• Assumption: all target games can be migrated without introducing a temporary compatibility layer.

Appendix: Clarifying questions & answers

• Q: "Scope of 'all games use it': A) all games currently under example-games/, B) only actively maintained games, C) other?" — Answer (user): "A". Source: interactive reply. Final: yes.
• Q: "Required migration depth: A) Help + Settings + end-game/modal overlays, B) Help + Settings only, C) overlay primitives only?" — Answer (user): "A + end round overlays if they exist". Source: interactive reply. Final: yes.
• Q: "Backward compatibility for game scenes: A) no compatibility layer; update call sites now, B) temporary compatibility path, C) no preference" — Answer (user): "A". Source: interactive reply. Final: yes.
• Q: "Should this new issue be dependent on CG-0MP1TAZU5008OTJY?" — Answer (user seed intent): "Ensure this new issue is dependent upon CG-0MP1TAZU5008OTJY." Source: seed context. Final: yes.