feat(player-ui): add pre-reader controls and onboarding

docs/PRE_READER_USABILITY.md

@@ -0,0 +1,38 @@
+# Pre-reader usability observation guide
+
+## Purpose
+
+Use this short, consent-based observation to verify the player interface with
+a child who does not rely on reading. It is an acceptance activity for
+Milestone 015, not a source of analytics. Do not record names, images, audio,
+contact details, or any other identifying information.
+
+## Setup
+
+- Use the player screen at a `412 x 916` CSS-pixel viewport with sound enabled.
+- Start a normal two-player match with the observer screen hidden.
+- An adult may read a prompt once but must not point to the answer or operate
+  the child's device.
+
+## Prompts
+
+Ask the child to demonstrate each task. Mark it as completed only when the
+child succeeds without reading the Russian support text.
+
+| Task | Expected non-reading cue |
+| --- | --- |
+| Move the hero | circular joystick and character movement |
+| Find and pick up a key | key shape and pickup feedback |
+| Recognize farther vision | eye symbol and map expansion |
+| Follow the compass | arrow direction and compass icon |
+| Find the exit | outlined exit shape and owner character shape |
+| Recognize a wall | wall shape plus rejection feedback |
+| Recognize the result | result icon/overlay plus local feedback |
+
+## Record
+
+Record only the date, viewport, browser, whether Russian labels were read,
+and the seven task outcomes. Summarize unclear cues and any adult assistance.
+If no representative child observation is feasible, the project owner may
+approve a documented deviation instead; include the reason and the remaining
+risk in the active milestone evidence.

docs/UI_STYLE.md

@@ -49,11 +49,13 @@ are not MVP requirements.
 - Use frequent but purposeful animation for screen transitions, movement,
   pickups, game events, and humorous feedback.
 - Pending controls blink until their command is resolved.
-- A reduced-motion mode is not required for the MVP.
+- A visible reduced-motion toggle is required in player mode. It must suppress
+  non-essential animation without changing gameplay feedback or authority.
 - Sound and vibration are enabled by default. They begin only after the first
   user interaction when required by the browser, and are used only when the
   browser and device support them.
-- Dedicated sound and vibration toggles are not required for the MVP.
+- A visible mute toggle is required in player mode. It disables local sound and
+  vibration feedback only; it must never change protocol behavior.
 
 ## 5. Shared controls
 
@@ -62,10 +64,14 @@ are not MVP requirements.
 - Visible keyboard-focus outlines are not required for the MVP.
 - On computers, movement works from the keyboard and from an on-screen
   directional control cluster fixed in the lower-right corner.
-- On tablets, an on-screen directional control cluster is fixed in the
-  lower-right corner for right-handed use. Touch swipes remain supported.
-- On phones, movement uses directional swipes and no on-screen directional
-  buttons are shown.
+- On touch devices, movement uses an always-visible circular joystick at least
+  160 by 160 CSS pixels. Its drag stays within the control, returns to center
+  on release, cancellation, pause, disconnect, and browser blur, and sends
+  only cardinal movement intentions.
+- The joystick has a dead zone and directional hysteresis. Its locally
+  scheduled repeat interval is bounded and never faster than the server's
+  movement cooldown. Touch swipes remain supported. Phones do not show a
+  directional-button cluster.
 - The always-visible key-drop control is labelled `OK`, includes a key icon,
   and is positioned closer to the upper edge of the screen than the
   directional controls. Dropping does not require confirmation.
@@ -78,6 +84,9 @@ are not MVP requirements.
 - A fixed status panel occupies the top of the screen.
 - The persistent player status shows the player name, carried key when one is
   held, active vision effect, and match state.
+- The player identity is represented by a distinct character shape, not `P1`
+  or `P2`. Object, blocked-move, pause, and result feedback must pair a shape
+  or icon with its color.
 - Connection details and the Wi-Fi settings link belong in a secondary panel,
   not in the persistent status row.
 - Countdown, pause, and result states appear as modal overlays above the map.
@@ -93,9 +102,10 @@ are not MVP requirements.
   boundaries prevent it.
 - Render unknown space as a solid background. Never infer, retain, animate, or
   decorate maze geometry outside the server-provided visible projection.
-- Use a nominal cell size of 20 CSS pixels on phones and 40 CSS pixels on
-  tablets and computers. Minor adjustment is allowed to fit browser chrome and
-  safe areas without making the map unusable.
+- Compute cell size from the current server projection and available map area.
+  At the minimum supported phone viewport a common 7 by 7 projection must use
+  at least 46 CSS-pixel cells, while smaller projections may grow to 72 pixels.
+  Do not alter, retain, or infer hidden maze cells to fill spare space.
 - Player zoom and pan controls are not part of the MVP.
 - Use different colors plus labels, outlines, shapes, or icons to distinguish
   player ownership and object types.
@@ -108,6 +118,9 @@ are not MVP requirements.
 - Support both portrait and landscape orientations. Suggest landscape when it
   materially improves play, but do not block portrait play.
 - Respect display safe areas and keep essential status and controls visible.
+- At `412 x 916`, the map is the dominant visual region; controls overlay it
+  instead of creating an empty lower region. Status remains icon-first and
+  readable without requiring reading as the normal interaction path.
 - Scale icons and controls up on tablets and computers while preserving map
   priority and fixed panel placement.
 - Validate the MVP against the current stable releases of Chrome, Safari,
@@ -143,3 +156,19 @@ are not MVP requirements.
   message, and semantic color role manually and through focused browser tests
   where practical.
 - Golden-image or screenshot-regression tests are not required for the MVP.
+
+## 12. Pre-reader onboarding and usability
+
+- On a player's first active projection, show an eight-step, wordless-first
+  walkthrough for joystick drag and release, walls, key, vision, compass,
+  exit, and meeting the other player. Each step uses a large icon; short
+  Russian text is secondary support for an adult.
+- The walkthrough provides a replay button and an explicit Russian skip button
+  for adults. It is browser-local UI only and never changes server state.
+- A child must be able to distinguish their character, the other character,
+  key, vision, compass, exit, blocked movement, and results through at least
+  two channels such as shape/icon, position, motion, outline, color, sound, or
+  haptic feedback.
+- Before release, record a representative pre-reader observation using
+  `docs/PRE_READER_USABILITY.md`, or record a project-owner-approved deviation
+  with its reason and impact.