aetherbound-guild/docs/plans/M15_RUNTIME_FOUNDATION.md

# M15 Runtime Foundation & Shared UI

## Status

- Plan: `M15_RUNTIME_FOUNDATION`
- Status: `IN_PROGRESS`
- Activated: 2026-08-25
- Baseline: `0d7dcce` (`MVP_FIRST_CYCLE_COMPLETE`, repository cleanup closed)
- Owner authorization: explicit instruction to begin the runtime architecture
  refactor and establish shared game-wide services/components.

## Objective

Create the smallest reusable Runtime Foundation that can support future pages
without forcing every page through the current `main.gd` / `entry_shell.gd`
coupling. The first stopping point is an additive, tested foundation and a
Settings integration boundary; the accepted MVP player flow must remain
behaviorally unchanged.

## Player/System Stopping Point

At the end of this plan's first boundary:

- the existing first-cycle route still launches and completes unchanged;
- settings data has one explicit service/repository boundary;
- shared UI primitives have no dependency on `facade`, `current_screen`, or
  page-specific domain state;
- a screen-stack/route context can represent the caller and return focus for
  Settings without copying settings logic into every page;
- the new foundation is available for the next page migration, but accepted
  pages are not mass-rewritten in this milestone.

## Architecture Contract

### Dependency direction

```text
AppRoot / FlowRouter
  -> Page Controllers and Page Views
  -> Application Commands / Use Cases
  -> Domain Services
  -> Repositories / persistence

Page Views -> Shared UI primitives
Shared UI primitives -X-> facade, current_screen, domain services, Save files
Domain Services -X-> Control, Label, TextureRect, page nodes
```

### Shared ownership classes

1. **Global services**: Settings, localization, audio, input/focus, save and
   screen navigation. One owner and one public boundary.
2. **Shared UI primitives**: tokens, theme, button states, rails, notices,
   dialogs and common icons. They receive view data and emit user intent.
3. **Page patterns**: optional shells such as a settings workspace or action
   dock. They may be configured by a page context, but do not own game rules.
4. **Page-specific composition**: world art, battle field, market board,
   risk relic and other authored layouts remain owned by their page module.

## Ordered Steps

### M15-A — Foundation contract and inventory (`COMPLETE`)

- Record the baseline, forbidden scope and ownership rules in this plan.
- Inventory current shared candidates (`entry_chrome.gd`, `settings_store.gd`,
  localization/font/assets and screen-return branches).
- Add the checkpoint pointer to this plan before product code changes.

Acceptance:

- this plan is the only active implementation plan;
- the current MVP and historical adapters are explicitly frozen;
- no `.uid`, `.import`, cache or `prototype_incremental/` cleanup is included.

### M15-B — Additive foundation types (`IN_PROGRESS`)

Add only the minimum new code under `runtime/foundation/` and
`runtime/ui/shared/`:

- `app_services.gd` — explicit service bundle, no global page lookups;
- `screen_context.gd` — caller/return-route/focus context;
- `ui_tokens.gd` — shared visual and layout constants;
- `shared_button.gd` — semantic button state/variant boundary;
- `screen_stack.gd` — route/overlay stack contract without replacing the
  current entry flow yet.

The additive layer must compile independently and have focused unit checks.

### M15-C — Settings integration pilot (`PENDING`)

- Wrap the existing validated `ABGEntrySettingsStore` behind a foundation
  `SettingsService` boundary without changing the JSON schema or migration
  behavior.
- Pass a `ScreenContext` to Settings entry/return paths.
- Keep the existing Settings visuals and semantics until a later page-specific
  reconstruction step; this is an ownership refactor, not a visual redesign.

Acceptance:

- defaults, v1 migration, validation, atomic save and corrupt-file rejection
  remain covered;
- Title/Guild/Battle callers return to the correct screen and focus context;
- no page writes the settings file directly.

### M15-D — Focused verification and migration boundary (`PENDING`)

- Run foundation-focused tests and the existing DEV-1 settings/entry checks.
- Run a normal 100% launch/settings/return smoke path at the current required
  fixtures; 130% remains non-blocking for this milestone.
- Run the MVP first-cycle audit to prove no route regression.
- Record the migration boundary and commit the smallest focused change.

## Frozen Scope

- No mass rewrite of `entry_shell.gd` or `main.gd`.
- No changes to Company, Contract, Battle, reward, recovery or Save-v11
  gameplay semantics.
- No new page visual redesign or asset generation.
- No iOS/export/package/signing work.
- No deletion of historical runtime, `.uid`, `.import` or provenance files.

## Required Evidence

- Godot parse/import diagnostics: strict zero.
- Focused foundation tests and settings regression marker.
- Normal-render settings open/apply/discard/return evidence.
- Existing `ABG_MVP_FIRST_CYCLE_AUDIT_OK` remains green.
- Focused commit pushed before activating the next step.

## Issue Register

- `M15-ISSUE-01` — current `entry_shell.gd` owns both page composition and
  settings return logic. Resolved only when Settings has an explicit context
  boundary; visual extraction remains a later step.
- `M15-ISSUE-02` — `entry_chrome.gd` contains multiple visual families in one
  class. It is retained as provenance/compatibility until shared variants are
  extracted and individually verified.

## Commit Boundaries

- `M15-A`: plan/checkpoint activation commit.
- `M15-B`: additive foundation compile/test commit.
- `M15-C`: Settings integration commit.
- `M15-D`: focused evidence and closure commit.

Each boundary must pass its focused checks before the next step becomes active.