Files
aetherbound-guild/docs/plans/M47_UNIFIED_UI_MVP.md
T

165 lines
6.9 KiB
Markdown

# M47 Unified UI MVP
## Status
- Plan: `M47_UNIFIED_UI_MVP`
- Status: `COMPLETE`
- Activated: 2026-09-05
- Baseline: `4d342c4` (`M46_MVP_UI_CONSISTENCY_PASS` closure)
- Owner request: produce a directly playable MVP proving that Market,
Readiness and Battle Result belong to one authored game.
## Objective
Create a small, playable presentation MVP that repairs the information
architecture and page grammar of the three highest-signal screens. Keep the
existing gameplay, controllers, services, Save/Receipt behavior, routing,
static masters and accepted Japanese 2D hand-drawn art unchanged.
## Player-visible stopping point
- The player can complete the existing first-cycle route while Market,
Readiness and Battle Result share one recognizable shell, type scale,
spacing rhythm, surface treatment and command hierarchy.
- Each target page exposes one primary action, two or three primary facts, and
secondary detail only when it helps a decision.
- Debug hashes, internal IDs and implementation-oriented copy are hidden from
normal presentation.
- Body text remains readable at `760x360`, `844x390` and `1280x720` in both
supported locales; primary commands retain at least 48 logical pixels.
- The MVP is runnable locally from the existing Godot project and can be
handed to the Owner for an uncoached first-cycle tryout.
## UI system contract
### Tokens
All target pages use `ABGUI_Tokens` for type roles (`title`, `heading`,
`body`, `label`, `micro`), spacing, command heights, semantic colors,
surface radii and notice severities. Page code may choose geometry but may not
invent a competing token vocabulary.
### Page shell
Each target page follows this shared grammar:
1. full-bleed hand-drawn world/master;
2. compact top rail for page identity and one resource/state fact;
3. one focal work surface;
4. one attached context/notice surface;
5. one bottom command rail with primary, secondary and utility semantics.
The shell is a grammar, not a forced identical layout. Market remains a desk,
Readiness remains a formation review, and Result remains a post-battle
outcome surface.
### Component entry points
Target pages must use `ABGUIFactory`/`ABGPageView` helpers for labels,
commands, icons, notices and flat surfaces. Direct `Button.new()`, ad-hoc
`StyleBoxFlat.new()` and raw page color literals are forbidden in new or
rewritten target-page code. Existing static masters and authored portraits are
reused.
### Information budget
- Market: selected offer, profession/trait/price, coin and one next action.
- Readiness: committed line, pressure/risk, one warning summary and one next
action.
- Result: outcome, reward delta, knockout/recovery fact, causal summary and
one continuation action.
## Ordered steps
### M47-A — Contract and baseline (`COMPLETE`)
- Freeze this contract and the source-bound baseline captures.
- Record the issue register and exact acceptance checks.
- Update `CURRENT_CHECKPOINT.md` and the development ledger.
- No runtime product code changes in this step.
Acceptance: exactly one active plan/step; baseline is `4d342c4`; no tracked
runtime changes; existing M46 evidence remains intact.
Closure: M47-A closes at source `1d3a526`. The unified-shell contract,
information budget, frozen scope and three-page stopping point are recorded;
no runtime product code changed in activation.
### M47-B — Shared MVP shell (`COMPLETE`)
- Add presentation-only shell/surface helpers and target-page layout helpers.
- Extend token roles only where the three pages require them.
- Add focused foundation tests for shell geometry, type minimums, command
variants and hidden-debug-field policy.
Closure: M47-B closes at source `57fbd67`. `ABGPageView` now mounts the
shared MVP shell over each target page, `ABGUI_Tokens` owns the shell surfaces,
and `ABG_M47_UNIFIED_UI_MVP_OK` passes with shell, surface, typography and
input assertions.
### M47-C — Three-page migration (`COMPLETE`)
- Recompose Market, Readiness and Battle Result around the shared shell while
preserving stable node names, intents, focus order and controller snapshots.
- Remove normal-view Board hash/internal diagnostics and reduce competing
status blocks.
- Keep all domain/application/controller code and static art masters unchanged.
Closure: M47-C closes at source `f911095`. Market, Readiness and Battle Result
now mount the shared shell, present player-facing status copy instead of
internal hashes/IDs, use a readable small-screen text floor, and preserve all
existing node names, intents and controller snapshots. Focused Market,
Readiness and Result View contracts pass.
### M47-D — Playable verification and handoff (`COMPLETE`)
- Run focused View tests plus the existing first-cycle candidate/audit through
`tools/run_test_attempt.py` with strict diagnostics, exact markers, parsed
touch/restart and owned cleanup.
- Capture `760x360`, `844x390`, `1280x720` in `zh_CN` and `en`; inspect for
clipping, overlap, hierarchy, minimum text and primary-action clarity.
- Record the visual audit and provide the local run/tryout command.
Closure: M47-D closes at source `1a08127`. The source-bound full first-cycle
audit passes with marker `ABG_MVP_FIRST_CYCLE_AUDIT_OK`, 34 focused checks,
128 normal `100%` captures across `760x360`, `844x390` and `1280x720` in
`zh_CN`/`en`, strict diagnostics `0`, parsed touch/restart and owned cleanup.
Evidence archive:
`/private/tmp/aetherbound-guild-test-evidence/m47-mvp-audit-long/20260905T170957Z-89658`
(SHA-256 `693e90ede44d35621d518a979a88c5af24334f677ba50aed68584f8755daf7fb`).
## Acceptance checks
- New marker: `ABG_M47_UNIFIED_UI_MVP_OK` exactly once.
- Existing first-cycle markers and Save/Receipt regressions remain green.
- Strict Godot diagnostics remain `0`; no unowned evidence/cache roots remain.
- No changes to gameplay, economy, content identities, routing, Save schema,
localization semantics or static-master assets.
- Target pages contain no direct `Button.new()` or raw command `StyleBoxFlat`
construction after migration; shared factories provide command state/icon
styling.
- Normal captures show one shared visual grammar without flattening the
page-specific art compositions.
## Frozen scope
- No new professions, regions, bosses, contracts or economy systems.
- No battle-rule, controller, Save, audio, packaging, device or release work.
- No pixel-art conversion, post-process pixelation or static-master repaint.
- No mass rewrite of `entry_shell.gd` or Router extraction.
- Do not delete or stage `.uid`, `.import` or `prototype_incremental/`.
## Commit boundaries
- `M47-A`: plan/checkpoint/ledger activation.
- `M47-B`: shared MVP shell and focused foundation test.
- `M47-C`: Market, Readiness and Battle Result migration.
- `M47-D`: verification, visual audit and handoff.
Each boundary must be committed and pushed before the next step becomes
`IN_PROGRESS`. A failed check keeps the same step active.
## Final handoff
`ABG M47 UNIFIED UI MVP READY FOR OWNER TRYOUT`