# Compass Shift — UX Flow and State Matrix v0.1 **Status:** provisional; paired with GDD v0.1 **Primary viewport/input:** 390x844 portrait, one-thumb tap **Parity:** mouse click and keyboard activation use the identical release transaction ## Entry contract Every Stage 2 visit and reload starts at FTUE step one with a fresh in-memory campaign. No FTUE, level, board, compass, undo, result, tuning, or progress state is read from or written to browser storage, cookies, URLs, a server, or analytics. The game shell is inert while the FTUE overlay is open. Skip is always available; How to Play replays the same teaching flow in the current visit. ## Primary flow `Launch -> FTUE -> Practice/Level 1 -> Playing -> Completion -> Next level or Map` Secondary routes: `Playing <-> How to Play`, `Playing <-> Map/Tools`, and `Playing -> Restart -> Playing`. ## FTUE The overlay uses three short steps and code-native diagrams: 1. **Goal:** remove every arrow from the fixed board. Show the large shared compass and one clear arrow ray. 2. **Core input:** tap an arrow on touch, click it with a mouse, or focus it and press Enter/Space. There is no second Release button. 3. **Consequence/recovery:** a legal arrow leaves, then the compass turns exactly one quarter-turn and all remaining directions change. A blocked tap removes nothing and turns nothing; use Undo/Restart after a successful ordering choice. Closing the overlay enters a practice-capable board. The only in-session FTUE completion trigger is the first real successful arrow release. Dismissing, skipping, opening Help, tapping a blocked arrow, or changing a setting does not complete it. Reload resets the teaching flow by design. ## Screen/state inventory | Screen/state | Required elements | Primary action | Back/recovery | |---|---|---|---| | FTUE | three steps, progress, Next/Back, Skip, inert background | read/dismiss into practice | dismiss returns focus to a board arrow | | Playing | level/tier label, board + shared bezel, arrows, walls/ports, Undo, Restart, How to Play, Tools/Map | tap/click/activate arrow | use visible controls | | Release resolving | selected ray and target aperture | automatic | pointer cancellation before activation changes nothing | | Arrow releasing | exactly one arrow slides out | automatic | input locked for short presentation interval | | Compass turning | bezel and remaining arrowheads turn 90 degrees | automatic | reduced motion swaps state under 100 ms | | Blocked feedback | first blocker/closed aperture emphasized; “compass unchanged” accessible status | choose another arrow | no loss, stack entry, or modal | | Completed | settled empty board, Next, Replay, Map, Technical review | Next | Replay restores authored level state | | Level Map | 50 buttons plus direct selector inside Tools | choose any prototype level | return to the chosen fresh in-memory board | | How to Play | replayable three-step FTUE plus controls legend | replay or close | return focus to the board; board state unchanged | | Tools | three presentation tuners, current solver evidence, technical-only outcome payload | adjust/record build readiness | no rule, persisted, deployment, smoke, or product-verdict change | ## Playing interaction sequence 1. A pointer tap/click or keyboard Enter/Space activates one arrow button. 2. `TapInput` forwards only its stable arrow ID to `GameController`. 3. `ReleaseResolver` returns `success` with ray/aperture or `blocked` with a reason. Presentation does not determine legality. 4. Blocked: emphasize the first blocking arrow/wall/closed aperture, announce that no arrow or compass state changed, then return to idle. 5. Success: draw the resolved ray, slide exactly one arrow off board, remove it, rotate the shared compass and all remaining effective arrowheads exactly 90 degrees, settle, test win. 6. If the activated arrow held focus when removed, focus moves to the first remaining native arrow button; otherwise the browser's native pointer focus behavior is left alone. Touch, mouse, and keyboard all execute steps 2-6. Hover may preview focus affordance but never reveals exclusive mechanic information. ## Compass and port communication - The compass bezel is integrated around the board, with one code-native phase label for assistive clarity and four visual tick groups. - Arrowheads render current effective directions, not base-direction debug data. - Phase windows show the one eligible phase through tick geometry and an accessible label. - Patterned ports show their two eligible phases through dot/dash marks and an accessible label. - Closed ports never look like valid empty space; plain exits remain visually distinct. ## Mobile layout - Use safe-area padding on every side and keep primary arrow targets at least 44 x 44 CSS pixels. - Board plus bezel uses the largest square fitting between the compact header and bottom controls. - Undo, Restart, How to Play, and Map stay in thumb reach; Tools may be secondary but visible. - No document scroll, browser gesture collision, clipped bezel, or control overlap at 390x844. - Portrait is the product default. A short landscape viewport (at most 650 CSS pixels high) uses a centered two-column layout; taller desktop windows keep the centered single-column instrument. Neither presentation changes rules or reduces control access. ## Desktop and keyboard parity - Mouse: click a token; no drag or hover is required. - Keyboard: Tab focuses native arrow-token and action buttons; Enter/Space activates the same handler. Escape closes the Tools sheet when it is open. - Undo, Restart, How to Play, Map, and Tools are native buttons with visible focus. - A polite status region announces release/new phase, blocked reason, Undo, and Restart. Completion is a focused modal dialog. ## Undo/restart/failure behavior - Undo is available after any success and may be repeated to the authored start. It atomically restores the removed arrow and previous compass phase. - Restart restores all arrows and the initial compass phase; presentation tuning remains in-memory. - A blocked tap does not enable Undo by itself and does not increment moves/losses. - If no legal release remains, the board stays visible with Undo/Restart; Stage 2 does not add a separate automatic dead-end banner. - Completion is deliberate: the empty board settles before the result panel appears. ## Accessibility and presentation - Direction uses silhouette; aperture schedule uses shape/pattern; state uses outline and text. - The browser's reduced-motion preference collapses presentation delays while preserving transaction order and feedback. - Stage 2 has no sound, haptics, high-contrast toggle, or settings panel. - Dynamic UI type may scale; gameplay tokens keep minimum target and arrowhead size. - Screen-reader labels announce arrow cell/effective bearing and compass/port state without exposing solver-only information. ## Empty, loading, error, and offline states - No saved progress is normal; every load intentionally begins fresh. - No network is required for the core prototype. A network failure cannot block play. - Campaign generation and validity are enforced before release by automatic tests; the shipped prototype performs no runtime content fetch and has no separate loading/error screen. - The last prototype level completes to Replay/Map; it never promises unavailable content. - Technical evidence and outcome JSON remain visible/selectable and in memory only. ## Truthful prototype state Built, registered, deployed, smoke-tested, and product-greenlit are distinct. Until a URL is confirmed and mobile smoke evidence is recorded, no Play/Live claim is made outside the local Stage 2 artifact. The Tools payload always keeps `decision` and `productDecision` null; only the separate Phase 07 record may report deployment/smoke truth or a later owner product verdict.