# Foldwake UX Architecture

## Screen Inventory

- `SCR-ONBOARDING` (onboarding): a real two-cell `ENV-CHART`, single `E-BOAT`, matching `E-HARBOR`, ghost `UI-CREASE-RAIL`, Skip, accessibility shortcut, and one sentence: “Fold the boat onto its harbor.” No carousel.
- `SCR-HOME` (home): Foldwake mark, restored `ENV-ATLAS` page stack, Continue as `UI-PRIMARY`, chapter grid, settings, legal link, offline status only when relevant, and no store takeover.
- `SCR-GAMEPLAY` (gameplay): `UI-TOPBAR`, full chart, legal crease rails, lower instruction/commit zone, pause, optional rule hint, and no decorative overlays across cells.
- `SCR-PAUSE` (pause overlay): Resume, Restart, Settings, Home. It freezes input and preserves the exact preview or committed state.
- `SCR-SUCCESS` (success result): final compact chart, rescued-boat count, crease result, earned cosmetic stamps, Next as `UI-PRIMARY`, Replay, and Home.
- `SCR-FAILURE` (failure result): highlighted decisive cells, plain-language rule, Retry as `UI-PRIMARY`, Inspect, and Home. No purchase or ad prompt.
- `SCR-SETTINGS` (settings): music, ambience, effects, haptics, tutorial replay, restore purchases if applicable, accessibility route, legal route, and data controls.
- `SCR-ACCESSIBILITY` (accessibility): `A-COLOR` patterns, `A-MOTION` reduced motion, `A-TEXT` scale preview, `A-HAPTIC`, high-contrast crease, screen-reader labels, and reset.
- `SCR-LEGAL` (legal): privacy, terms, credits, licenses, support contact, age/consent detail, and locally cached text with last-updated label.

## State Inventory

- `ST-FRESH`: authored chart loaded, no fold committed, all legal rails visible after onboarding prompt.
- `ST-ACTIVE`: touch enabled; may be idle or showing `M-PREVIEW`; `UI-TOPBAR` reflects remaining boats and creases.
- `ST-PAUSED`: gameplay state serialized in memory, animation stopped, overlay focus trapped.
- `ST-SUCCESS`: no active `E-BOAT`; `V-SUCCESS` completes before result controls enable.
- `ST-FAILURE`: a precise rule violation or exhausted budget; `V-WRECK` and cell markers identify cause.
- `ST-ERROR`: corrupted/invalid level, save, entitlement, or optional network adapter failure; retains a safe local route and never fabricates progress.

Loading is an inline non-blocking chart skeleton, not a separate primary screen. Disabled controls use reduced opacity plus a lock/slash symbol and explanatory label. An OS interruption transitions active play to `ST-PAUSED` before backgrounding.

## Navigation and Back Behavior

First launch → `SCR-ONBOARDING` → first `ST-SUCCESS` → `SCR-HOME`. Returning launch → `SCR-HOME`. Home Continue → `SCR-GAMEPLAY` in `ST-FRESH`; first touch → `ST-ACTIVE`. Gameplay pause or Android back → `SCR-PAUSE`; Resume/back → gameplay; Restart → fresh level after confirmation only when progress exists; Home → save checkpoint then home. Gameplay success/failure → matching result screen; Next/Retry → gameplay. Settings, accessibility, and legal push onto a simple stack and return to their caller. Android back closes the top overlay before navigating; back from home opens a native exit confirmation.

## Transitions and Back Behavior

Screen transitions use 160 ms opacity plus 8 px vertical motion; `A-MOTION` removes translation. `M-PREVIEW` cancels if a modal opens. A committed `M-FOLD` finishes its 280 ms deterministic resolution before pause takes effect, except OS termination, where the prior stable state is restored. No navigation can authorize, simulate, or bypass the owner design lock.

## Overlays, Loading, and Errors

`SCR-PAUSE` and confirmations use `UI-MODAL`, a 68% indigo scrim, one title, one reason, and no more than four actions. Loading never covers a playable chart; levels are decoded before entering `ST-FRESH`. `ST-ERROR` shows a short error category, Retry, and Return Home. Offline failure for analytics/cloud is silent except an unobtrusive home badge. Entitlement uncertainty preserves already verified owned content and defers new purchase access until verification.

## Orientation and Safe Areas

Portrait is the only supported orientation. Logical canvas is 360×800. Top safe inset is max(device inset, 24); bottom is max(device inset, 20); side insets are max(device inset, 16). `UI-TOPBAR` occupies y=24–96, chart occupies y=112–628, and the thumb/action zone occupies y=648–780. At wider ratios the chart grows until cell size reaches 72; at taller ratios extra space divides above and below the chart. Rotation while open keeps portrait and does not rearrange the board.

## Touch and Reachability

All controls are at least 48×48 with 8 px separation. Crease rails extend 16 px beyond visible line art to make targeting forgiving. Drag begins only from a legal rail; the preview side changes after crossing 12 px past the crease to prevent jitter. `UI-PRIMARY` is centered in the lower thumb zone. Pause stays top-right but has a 56×56 target. No gameplay requires two fingers, long press, precise angle, or edge swipe.

## Accessibility Matrix

- `A-COLOR`: boats use lantern silhouettes and pair glyphs; harbors use ring docks and the same glyph; reefs use jagged silhouettes plus diagonal coral hatch; previews use arrowheads and moving-half dots. Color is redundant.
- `A-MOTION`: replace `V-FOLD` hinge rotation with a 100 ms before/after crossfade, remove storm drift, preserve static overlap arrows, and never flash.
- `A-TEXT`: 100%, 125%, 150% system; top bar may wrap to two rows but cannot cover `ENV-CHART`; essential failure text minimum 17 logical px at 100%.
- `A-HAPTIC`: independent toggle; preview tick, commit pulse, rescue light pulse, failure double pulse. Audio and visuals remain complete when off.
- Focus order follows heading → status → board summary → primary → secondary → navigation. Board cells expose row, column, occupant, target, hazard, and projected consequence to assistive technology.

## Accessibility and Recovery

Accessibility is reachable on onboarding and settings. Every modal returns focus to its opener. Tutorial can skip and replay. Save writes only stable pre- or post-fold states, never mid-hinge. On corrupted level data, `ST-ERROR` quarantines the level and offers home; on save corruption, keep the last checksum-valid snapshot and explain that newer local progress could not be restored.