developer/scrabble-game
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat(ui): first-run onboarding coachmarks #147

Merged
developer merged 1 commits from feature/onboarding-coachmarks into development 2026-06-30 20:09:33 +00:00
Conversation 1 Commits 1 Files Changed 16
+809 -14
developer commented 2026-06-30 19:49:38 +00:00
Owner
Copy Link
Copy Source

What

First-run onboarding coachmarks across all platforms. A light dimmed overlay points one hint bubble at a time at a real control (tap anywhere → next; gone for good after the last hint). Two independent series:

  • Lobby (first lobby entry): ⚙️ settings, ✏️ stats, 🎲 new game.
  • Game (first game board): scoreboard header (history/chat/word-check), 🔄 pass/exchange, 🛟 hints, 🔀 shuffle, rack.

How

  • One Coachmark.svelte overlay at App level; each target carries a data-coach attribute, so a single positioning engine (lib/coachmark.ts, unit-tested) anchors bubbles in portrait and landscape, re-measuring each frame until the geometry settles (route slide, hidden-banner reflow, fonts).
  • Per-device persisted flags (session.ts onboarding), marked done only after the last hint, so an interrupted run replays from the start. A deep-link into Settings → Friends still triggers the lobby series on the first trip back.
  • The promo banner hides while the overlay is up (app.coachActive); a hidden DebugPanel Reset visited control replays the walk-through.
  • Off by default in the mock build (Playwright smoke unaffected); ?coach forces it on for the dedicated e2e.

Tests

  • pnpm check (0 errors), pnpm test:unit (356, incl. coachmark.test.ts + i18n parity), pnpm build, pnpm test:e2e (160 pass / 4 pre-existing skips, incl. new onboarding.spec.ts on Chromium + WebKit, portrait + landscape).
  • Verified visually via Playwright screenshots (light + dark, portrait + landscape, every step); dim (~0.32) + accent bubble signed off.

Docs

FUNCTIONAL (+ru) onboarding story; UI_DESIGN coachmark section.

## What First-run onboarding coachmarks across all platforms. A light dimmed overlay points one hint bubble at a time at a real control (tap anywhere → next; gone for good after the last hint). Two independent series: - **Lobby** (first lobby entry): ⚙️ settings, ✏️ stats, 🎲 new game. - **Game** (first game board): scoreboard header (history/chat/word-check), 🔄 pass/exchange, 🛟 hints, 🔀 shuffle, rack. ## How - One `Coachmark.svelte` overlay at App level; each target carries a `data-coach` attribute, so a single positioning engine (`lib/coachmark.ts`, unit-tested) anchors bubbles in **portrait and landscape**, re-measuring each frame until the geometry settles (route slide, hidden-banner reflow, fonts). - Per-device persisted flags (`session.ts` `onboarding`), marked done only after the **last** hint, so an interrupted run replays from the start. A deep-link into Settings → Friends still triggers the lobby series on the first trip back. - The promo banner hides while the overlay is up (`app.coachActive`); a hidden DebugPanel **Reset visited** control replays the walk-through. - Off by default in the mock build (Playwright smoke unaffected); `?coach` forces it on for the dedicated e2e. ## Tests - `pnpm check` (0 errors), `pnpm test:unit` (356, incl. `coachmark.test.ts` + i18n parity), `pnpm build`, `pnpm test:e2e` (160 pass / 4 pre-existing skips, incl. new `onboarding.spec.ts` on Chromium + WebKit, portrait + landscape). - Verified visually via Playwright screenshots (light + dark, portrait + landscape, every step); dim (~0.32) + accent bubble signed off. ## Docs FUNCTIONAL (+ru) onboarding story; UI_DESIGN coachmark section.
developer added 1 commit 2026-06-30 19:49:38 +00:00
feat(ui): first-run onboarding coachmarks
CI / changes (pull_request) Successful in 3s
Details
CI / unit (pull_request) Has been skipped
Details
CI / integration (pull_request) Has been skipped
Details
CI / ui (pull_request) Successful in 57s
Details
CI / gate (pull_request) Successful in 0s
Details
CI / deploy (pull_request) Successful in 1m20s
Details
6636d7c309 
A one-time coachmark overlay walks a new player through the lobby and their
first game board: a light dimmed layer draws one tail-pointed hint bubble at a
time, advancing on a tap anywhere and removing itself for good after the last
hint. Two independent series (lobby: settings/stats/new game; game:
header/pass-exchange/hints/shuffle/rack), gated by a per-device persisted flag
and marked done only after the last hint, so an interrupted run replays from
the start. A deep-link into Settings -> Friends still triggers the lobby series
on the first trip back to the lobby.

Targets carry a data-coach attribute, so one positioning engine anchors the
bubble in both portrait and landscape, re-measuring each frame until the
geometry settles (route slide, hidden-banner reflow, fonts). The promo banner
hides while the overlay is up (app.coachActive); a hidden DebugPanel "Reset
visited" control replays the walk-through. Off by default in the mock build so
the Playwright smoke is unaffected; ?coach forces it on for the dedicated e2e.

Pure geometry (step lists, nextVisibleStep, placeBubble) in lib/coachmark.ts
(unit-tested); Coachmark.svelte renders. Docs: FUNCTIONAL(+ru) onboarding
story, UI_DESIGN coachmark section.
owner approved these changes 2026-06-30 20:09:16 +00:00
developer merged commit adf7c55695 into development 2026-06-30 20:09:33 +00:00
developer deleted branch feature/onboarding-coachmarks 2026-06-30 20:09:33 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
owner
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
owner (Ilia) developer
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: developer/scrabble-game#147
Delete Branch "feature/onboarding-coachmarks"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?