feat(player): animate authoritative hedge breakthroughs

PLANS.md

@@ -2905,7 +2905,7 @@ unchanged.
 
 ## Milestone 026 — Optional help overlay at match start
 
-**Status:** `IN_PROGRESS`
+**Status:** `COMPLETE`
 
 ### Objective
 
@@ -2939,4 +2939,190 @@ without automatically opening the optional player help overlay.
 
 ### Evidence
 
-- Implementation and verification are pending.
+- On 2026-09-12, `renderSnapshot()` was changed to dismiss the countdown
+  modal after an active player projection without invoking `showOnboarding()`.
+  The existing `onboarding-replay` button and the skip and final-step close
+  paths remain unchanged.
+- On 2026-09-12, `node --test test/web/test_player_app.js
+  test/web/test_hedge_svg.js` passed all 26 tests. The new countdown-completion
+  test verifies direct match-screen activation and enabled controls, no
+  automatic help opening, and the preserved optional open and close paths.
+- On 2026-09-12, `bash scripts/run_host_tests.sh` passed, and `python3
+  scripts/verify_web_assets.py` passed with a deterministic 29,984 /
+  1,572,864 byte compressed web payload.
+- On 2026-09-12, `/home/sasa/.platformio/penv/bin/pio run --target buildfs`
+  succeeded with the LittleFS image using 2,031,616 / 2,031,616 bytes.
+- In-app browser verification is pending because the current in-app browser
+  connection is unavailable.
+- On 2026-09-12, the project owner checked the optional help overlay and
+  confirmed that it is not shown automatically when a game starts. This
+  supplies the missing visual acceptance evidence for Milestone 026.
+
+## Milestone 027 — Playful breakthrough movement and prominent hedge gaps
+
+**Status:** `IN_PROGRESS`
+
+### Objective
+
+Make a successful perseverance breakthrough feel exciting and immediately
+understandable to children by synchronizing the player's movement through the
+wall with a short playful vegetation effect, and by enlarging and sharpening
+the permanent opening so it is as easy to recognize as an ordinary maze
+passage on supported mobile and desktop screens.
+
+### Scope
+
+- Do not start implementation until every preceding milestone is `COMPLETE`.
+  Milestone 026 is still `IN_PROGRESS` when this plan is created, so this
+  milestone must remain `NOT_STARTED` until its visual acceptance is recorded.
+- Preserve the Milestone 022 authoritative rule: the ESP opens the wall and
+  moves the player on the fifth qualifying impact. The browser may animate
+  only a received server-approved breakthrough and must never predict an
+  opening, delay the authoritative position, or change collision behavior.
+- Reconcile the breakthrough presentation in `docs/UI_STYLE.md`,
+  `docs/PLAYER_UI.md`, and `ARCHITECTURE.md` before changing runtime assets.
+- Replace the understated fifth-impact transition with one short,
+  child-friendly sequence: the hedge compresses away from the impact point,
+  the player performs a readable squash-and-stretch hop or energetic dash
+  through the opening, and a small bounded burst of leaves and soft sparkle
+  shapes follows the motion. Keep the effect cheerful rather than violent,
+  alarming, or realistic.
+- Synchronize the effect with the authoritative origin and destination cells.
+  The player must begin at the old visible position, cross the exact opened
+  edge, and settle at the new server-approved position without teleport-like
+  flicker, duplicate avatars, or a frame spent on top of a closed hedge.
+- Keep the complete breakthrough sequence brief enough not to slow repeated
+  play, target approximately 350--550 ms in normal-motion mode, and do not
+  block directional input longer than required to reconcile the authoritative
+  snapshot. Later snapshots must safely supersede an unfinished animation.
+- Increase the clear center of every permanent breached-hedge variant. At the
+  minimum supported cell size, the visible gap must occupy at least 60% of the
+  traversable edge span, with the remaining foliage pulled into two distinct
+  side clusters rather than forming a faint interruption in an otherwise
+  continuous wall.
+- Give breached edges an unmistakable top-down silhouette using bent branches,
+  displaced leaves, and a subtle trampled-ground or scattered-leaf cue on both
+  sides of the opening. Do not add a bright line, rectangular floor grid,
+  arrow, warning text, or color-only marker.
+- Ensure the enlarged decoration reads as open space from either direction and
+  in horizontal and vertical orientations. It must not resemble a thin closed
+  wall, cover the passage center, overlap the player, key, artifact, exit, or
+  door, or make adjacent closed edges ambiguous.
+- Keep authoritative maze geometry, pathfinding, visibility, hit testing,
+  object interactions, and protocol contents unchanged unless a documented
+  contract gap proves that an existing breakthrough event cannot identify the
+  required visible edge and movement transition.
+- Reuse the local SVG hedge family where practical. Any new SVG shapes must be
+  editable, script-free, raster-free, locally packaged, and consistent with
+  the approved top-down leaves, twigs, outlines, and palette.
+- Bound all temporary leaves, sparkles, DOM nodes, timers, and animation state.
+  Coalesce or replace repeated effects and clear them on projection loss,
+  screen change, pause, disconnect, result, reset, and reduced-motion changes.
+- In reduced-motion mode, immediately place the player at the authoritative
+  destination and switch to the enlarged permanent gap with a brief static
+  emphasis only. Do not require translation, shake, squash, flying leaves,
+  sparkle motion, sound, vibration, or color to communicate success.
+- Apply the improved permanent gap to player and observer maps. The observer
+  does not need player travel animation but must see the same clear opened-edge
+  silhouette at overview and inspection zoom levels.
+- Preserve supported mobile layouts, directional controls, player focal-point
+  positioning, Russian player-facing copy, offline operation, and firmware and
+  LittleFS budgets.
+
+### Deliverables
+
+- Updated breakthrough motion, permanent-gap, layering, timing, cleanup, and
+  reduced-motion contracts in canonical and supporting documentation.
+- Revised horizontal and vertical permanent-breach SVG variants with a larger
+  clear center and distinct displaced-foliage silhouettes.
+- A bounded, server-triggered player breakthrough animation with synchronized
+  hedge compression, player movement, and playful leaf and sparkle accents.
+- Player and observer renderer updates that use the more prominent permanent
+  breach without changing authoritative maze geometry.
+- Deterministic browser tests, web-asset validation, host regression results,
+  size evidence, and representative mobile, desktop, observer, reduced-motion,
+  and physical-device visual verification.
+
+### Acceptance criteria
+
+1. A fifth qualifying impact still causes exactly one server-authoritative wall
+   opening and movement. The browser starts the effect only from the matching
+   authoritative breakthrough response and never predicts, repeats, or delays
+   gameplay state.
+2. In normal-motion mode, the player visibly travels from the authoritative
+   origin cell through the exact breached edge to the authoritative destination
+   in one coherent 350--550 ms sequence, without teleport flicker, duplicate
+   avatars, stale positions, or overlap with an apparently closed wall.
+3. The sequence includes a cheerful and visually coherent hedge compression or
+   parting action, player squash-and-stretch hop or dash, and a bounded leaf and
+   sparkle accent. Its meaning remains clear with sound and vibration disabled.
+4. At 34, 40, and 46 CSS-pixel cell sizes, the clear center of each permanent
+   breached variant spans at least 60% of the traversable edge and is visibly
+   wider than the pre-milestone breach. Automated geometry checks cover every
+   horizontal and vertical variant.
+5. Every permanent breach reads as an open passage at a glance from both sides
+   and in all orientations. Its two separated foliage clusters, bent branches,
+   and restrained ground debris remain distinguishable from an intact wall in
+   normal color, grayscale, and representative color-vision checks.
+6. The enlarged gap does not obscure or overlap the player, keys, artifacts,
+   doors, exits, controls, neighboring passage centers, or closed-edge
+   silhouettes, and it introduces no map-shell or page overflow.
+7. Unrelated successful movement retains its existing behavior. The special
+   travel effect is used only for a confirmed fifth-impact breakthrough and
+   cannot replay from duplicate, delayed, reordered, or stale events.
+8. A newer authoritative snapshot safely completes, replaces, or cancels an
+   unfinished visual transition while leaving exactly one player at the latest
+   approved cell and the correct current projected topology.
+9. The implementation documents and tests fixed upper bounds for temporary
+   nodes, particles, timers, and queued effects. Pause, disconnect, result,
+   reset, screen change, and projection loss leave no stale transforms,
+   decorations, classes, or animation state.
+10. Reduced-motion mode performs no travel, shake, squash, flying-leaf, or
+    sparkle animation. It immediately shows the authoritative destination and
+    the same prominent permanent gap with a non-motion, non-color-only cue.
+11. Player and observer maps render the same deterministic breached-edge
+    family. Observer pan and zoom remain responsive, and openings stay legible
+    at overview and inspection scales without changing observer read-only
+    behavior.
+12. Browser tests cover authoritative triggering, timing, origin-to-destination
+    alignment, all breach variants and orientations, the minimum 60% gap,
+    deduplication, interrupted transitions, cleanup, reduced motion, supported
+    mobile and desktop viewports, observer rendering, layering, and overflow.
+13. All host and browser tests pass; SVG and compressed-web-asset validation
+    passes; the payload remains within the 1.5 MiB web budget and LittleFS
+    partition; and firmware remains within the factory partition.
+14. Physical-device testing confirms stable two-player play during repeated
+    and simultaneous breakthroughs, with no input lockup, stale avatar, lost
+    projection, accumulated effects, or visible performance regression.
+15. The project owner confirms on a representative mobile browser that the
+    breakthrough effect is fun and understandable for children, the movement
+    feels connected to breaking the bushes, and the resulting passage is
+    immediately obvious and at least as readable as an ordinary open route, or
+    explicitly approves a documented evidence deviation.
+
+### Evidence
+
+- On 2026-09-12, the project owner reported that the current permanent breach
+  is too small and visually weak, and requested a larger, sharper gap plus a
+  child-friendly special effect for player movement through a broken hedge.
+- Planning-time inspection of the active mobile game at
+  `http://192.168.1.50/` confirmed that the small interruption and remaining
+  near-continuous foliage silhouette make the breach difficult to distinguish
+  from an intact hedge at gameplay scale.
+- On 2026-09-12, implementation began after Milestone 026 was completed. The
+  player renderer now recognizes only a newly opened current-projection edge
+  paired with an adjacent authoritative self move, uses a single replaceable
+  480 ms runner with four decorative accents, and clears it on newer views,
+  control reset, screen change, and reduced motion. Permanent breach symbols
+  now reserve a 96 / 160 (60%) clear centre.
+- On 2026-09-12, `node --test test/web/test_player_app.js
+  test/web/test_hedge_svg.js` passed all 30 tests, including authoritative
+  opening detection, fixed 480 ms travel, four-accent bounds, reduced-motion
+  cleanup, and all three 60%-centre breach variants.
+- On 2026-09-12, `bash scripts/run_host_tests.sh` passed all portable and
+  bundled browser tests. `python3 scripts/verify_web_assets.py` passed with a
+  deterministic 31,071 / 1,572,864 byte compressed web payload, and
+  `/home/sasa/.platformio/penv/bin/pio run --target buildfs` succeeded with a
+  2,031,616 / 2,031,616 byte LittleFS image.
+- Mobile, desktop, observer, reduced-motion, and physical-device visual
+  acceptance remain required before this milestone can be marked `COMPLETE`.