aetherbound-guild/docs/plans/M41_MARKET_PAGE_VIEW_REFACTOR.md

M41 Market Page View Refactor

Status

• Plan: M41_MARKET_PAGE_VIEW_REFACTOR
• Status: COMPLETE
• Activated: 2026-08-26
• Baseline: 8d377f0 (M40_RECRUIT_REVIEW_PAGE_VIEW_COMPLETE)
• Owner authorization: the Owner asked to continue decomposing Entry pages into the layered Passive View + Presenter/ViewData + Domain/Application Service architecture. Market is the next bounded extraction in the M32 migration map after Recruit Review.

Objective

Extract the accepted SHP-001 Market page from entry_shell.gd into a passive, UI-only ABGMarketPageView while preserving the approved Japanese 2D hand-drawn market master, Company/Line/Coin facts, stable board hash, three category rails, inspect-only offer selection, selected-offer context, Recruit Review and Equipment Review boundaries, route-inspect-only behavior, Back to Guild, Settings hit area, focus order, touch surfaces and normal 100% output.

This is a structural View migration, not a Market/economy, hire, contract, Save, localization or visual redesign.

Target boundary

EntryShell / composition root
  -> MarketPageController.snapshot()
  -> presentation-ready ViewData
  -> ABGMarketPageView.render(ViewData)
  -> explicit View intents
  -> EntryShell application command boundary
  -> existing selection / review / route / Settings commands

Ownership rules

1. ABGMarketPageView owns only Godot nodes, the matte/normalized 16:9 canvas, SHP-001 static master, engine text/values, offer/category command surfaces, focus and explicit intent emission. It must not add a second card wall or alter the accepted master geometry.
2. The View does not import or call GuildContractService, Save, RuntimeContentRegistry, the compatibility facade, current_screen or EntryShell globals. It receives copied ViewData only.
3. ABGMarketPageController remains the authority for categories, copied offers, stable offer identity, available IDs, selected offer, review state, Company/Contract facts and localization-ready content.
4. EntryShell remains the composition root and translates only deferred category, select_offer, recruit_review, equipment_review, route, back and settings intents through existing application boundaries.
5. Existing Market selection is inspect-only. Recruit Review keeps the same source_offer_id; Equipment Review and route inspection do not spend, refresh, lock, reorder, commit Risk or start Battle.

Player-visible stopping point

• The player sees the same SHP-001 static field, Company/Line/Coin/status rails, board hash, three category buttons, offer figures/trays, selected context and command rail as the M09-accepted page.
• Selecting an offer updates only the existing Market selection state and preserves stable kind/ID identity.
• Recruit Review opens only from the selected Recruit and returns to the same offer; Equipment Review remains the existing inspect boundary; battle routes remain explicitly inspect-only.
• Back returns to Guild and Settings preserves the existing caller/return context (market / MarketSettings).
• Invalid supplied ViewData renders a deterministic non-interactive boundary.

Ordered steps

M41-A — Architecture contract and inventory (COMPLETE)

• Freeze the SHP-001 stopping point, dependency direction and forbidden imports before product code changes.
• Inventory the matte, normalized 16:9 canvas, static master, MarketLayout wrapper, Company/Contract/board facts, category mode buttons, Recruit / Equipment / Battle offer nodes, selected context/review boundary, Back and Settings hit areas, exact node names and focus order.
• Record the M09 normal-capture equivalence target at 760x360/zh_CN, 844x390/en, 1280x720/zh_CN and 1280x720/en with text scale 100%; 130% is explicitly non-blocking.
• The accepted static master is runtime/assets/entry/shp_001_market/market-static-master.png (2048x1152, contained 16:9); dynamic-regions.png remains audit-only. MarketMasterMatte, MarketMasterCanvas, MarketStaticMaster, MarketLayout, MarketOfferList, MarketContextSurface, MarketCategoryEquipment, MarketCategoryBattle, MarketReviewRecruit/MarketReviewEquipment/MarketReviewRoute, MarketBackGuild and MarketSettings are the frozen semantic nodes.
• The normalized hit/focus contract is the M09 v002 package: company rail [0.02,0.02,0.38,0.18], three Recruit regions [0.15,0.30,0.16,0.49], [0.31,0.28,0.22,0.51], [0.53,0.30,0.24,0.49], equipment tray mode, battle mode, review context, Back and Settings; focus order starts at Settings and ends at Back.
• Commit and push this activation/inventory boundary before Runtime product changes.

Closure: source ef29bdc records the activation and inventory boundary in this plan, CURRENT_CHECKPOINT.md and docs/06_DEVELOPMENT_AND_REVIEW.md. M41-B became the sole IN_PROGRESS step.

M41-B — Passive View extraction (COMPLETE)

• Add runtime/entry/views/market_page_view.gd and the isolated View contract test.
• Reuse the accepted static master and normalized canvas geometry without changing text/value semantics or adding visible chrome.
• Mount the View from EntryShell and translate only the explicit intents.
• Remove only Market UI builders/helpers from EntryShell; retain Controller, GuildContractService, selection state, review handoffs, route semantics and Settings context.

Closure: source 9a440b3 adds ABGMarketPageView, extends the controller snapshot with presentation-only offer fields, mounts the passive View from EntryShell, removes the former SHP-001 UI builders and wires deferred category/selection/review/route/back/settings intents. The isolated View, M17 controller, M09 Runtime, M10 Recruit Review, DEV-3 Market and Hire checks pass with strict diagnostics 0.

M41-C — Focused verification (COMPLETE)

• Run the View contract, Market controller, M09 Market, M10 Recruit Review, hire and route regressions through tools/run_test_attempt.py with strict diagnostics and exact-once markers.
• Run the DEV-3 candidate and full MVP first-cycle audit.
• Compare normal Market captures with the M09 baseline at all four required fixtures/locales and confirm byte-equivalence for the visible page.

Closure: source b88b211508e5f72b350835872119692e2324859c passes the isolated View contract, Market/Recruit Review controller and runtime regressions, Hire and downstream route checks, the DEV-3 candidate and the full MVP first-cycle audit with strict diagnostics 0 and exact-once markers. The M41 Market capture set and an immutable baseline capture set are both green; all four normal 100% fixtures are byte-identical with zero decoded-pixel differences. Evidence is recorded in docs/runtime/M41_MARKET_PAGE_VIEW_VISUAL_AUDIT.md.

M41-D — Handoff (COMPLETE)

• Record source-bound evidence and visual equivalence in docs/runtime/M41_MARKET_PAGE_VIEW_VISUAL_AUDIT.md.
• Close only Market. Contract Choice, Guild, Battle, Economy, Save, packaging and release remain outside this plan.
• Update the checkpoint and development ledger, then push the focused closure.

Closure: M41 closes at source b88b211 after the source-bound audit and four-fixture visual-equivalence record. No later View migration is activated; any further extraction requires a new Owner-authorized durable plan.

Frozen scope

• No GuildContractService, Market/economy, Company, Contract, Hire, Battle, Save or localization semantic changes.
• No visible visual redesign, asset generation, static-master editing or 130% scope.
• No mass rewrite of entry_shell.gd and no global event bus/binding layer.
• No deletion of compatibility/history files, .uid, .import or prototype_incremental/.
• No packaging, iOS export, signing, deployment, store or release work.

Acceptance checks

• ABG_M41_MARKET_VIEW_CONTRACT_OK exactly once.
• Existing Market controller/M09, Recruit Review/M10, Hire and downstream route regressions remain green; DEV-3 candidate and ABG_MVP_FIRST_CYCLE_AUDIT_OK remain green.
• Extracted View has no forbidden service/content/route imports and emits only the documented category/selection/review/route/back/settings intents.
• Market normal 100% captures remain visually equivalent to the M09 baseline at all four required fixtures/locales; the Settings hit area does not alter pixels.
• Focused source is committed, pushed and tracked files are clean.

Commit boundaries

• M41-A: plan/checkpoint/ledger activation.
• M41-B: View and EntryShell integration.
• M41-C: focused verification/evidence.
• M41-D: handoff/closure.

Each boundary must pass its narrowest focused checks and be pushed before the next step becomes IN_PROGRESS; a failed check keeps the current step active.

Final handoff

ABG M41 MARKET VIEW PILOT COMPLETE