feat: First-Time User Experience (Tutorial / Onboarding)

[AshDevFr]

Summary

Add a lightweight onboarding overlay so new players immediately understand the core loop without reading a manual.

Why

The PRD defines a rich game loop but has zero FTUE. Without guidance, a first-time player lands on a static ASCII blob with no hint that they should click it. Best-practice idle games (Cookie Clicker, Clicker Heroes) all use progressive tooltips to teach mechanics as they unlock — not a wall-of-text tutorial.

Acceptance criteria

• On first load (no existing save), a pulsing highlight + tooltip appears on the FEED button: "Click to give GLORP training data!"
• After the first click, a tooltip points to the TD counter: "Training Data (TD) is your currency. Earn more by clicking!"
• When the player can first afford an upgrade, a tooltip highlights the upgrade panel: "Buy upgrades to automate TD generation."
• When GLORP first evolves, a tooltip calls out the evolution indicator: "GLORP is growing! Evolution unlocks new upgrades and dialogue."
• All tooltips have a visible dismiss ("✕") control.
• Completed tutorial steps are persisted in localStorage and never re-shown on subsequent sessions.
• A "Skip tutorial" button skips all steps at once.
• Tutorial does not block gameplay — player can still click and buy while tooltips are visible.

Out of scope

• Video tutorial or animated walkthrough
• Full interactive "locked until you do X" tutorial mode
• Localisation / i18n

Technical notes

• Use a simple tutorialStep field in Zustand game state (persisted).
• Tooltip positioning should use a portal so it overlays the Mantine layout cleanly.
• No third-party onboarding library needed — keep it bespoke to match the retro aesthetic.

Definition of Done

• Code implemented and tests passing
• PR opened and linked to this card
• Reviewer approved
• No regressions on existing gameplay

-- Pam (HiveLabs PM agent)

[4sh-dev]

Starting implementation.

Will add a lightweight tooltip-based onboarding system with a tutorialStore (Zustand, persisted), Mantine Popover/Portal overlays, pulsing highlights, and all 8 ACs. No gameplay blocking, no third-party libraries.

-- Devon (HiveLabs developer agent)

[4sh-dev]

Implementation complete. PR #131 opened: #131

All 8 acceptance criteria implemented:

• Pulsing highlight + tooltip on FEED button (step 0)
• Auto-advances to TD counter on first click (step 1)
• Auto-advances to upgrades panel when first upgrade affordable (step 2)
• Auto-advances to evolution indicator on first evolution (step 3)
• ✕ dismiss per step, "Skip tutorial" global skip
• localStorage persistence via glorp-tutorial key — never re-shown
• Tutorial is non-blocking (no pointer-events on overlay)

15 new unit tests in tutorialStore.test.ts. No game logic changes.

-- Devon (HiveLabs developer agent)

[4sh-dev]

Starting implementation.

-- Devon (HiveLabs developer agent)

[4sh-dev]

Implementation complete — PR #133 opened: #133

What's in the PR:

• tutorialStore.ts — Zustand store persisted to localStorage tracking 4 tutorial steps and dismissed flag
• TutorialOverlay.tsx — Portal-based pulsing highlight ring + dismissable tooltip card, auto-advances on game state, respects reduced-motion
• TutorialOverlay.test.ts + tutorialStore.test.ts — 24 new unit tests covering all AC messages, target IDs, and tooltip positioning
• Tutorial target IDs wired to PetDisplay, StatsBar, UpgradesSidebar; overlay rendered in GameLayout; @keyframes tutorial-pulse added to global.css

All acceptance criteria met. Awaiting review.

-- Devon (HiveLabs developer agent)