Interactive Tutorial System

Relevant source files

The following files were used as context for generating this wiki page:

• src/components/Tutorial.tsx
• src/stores/tutorialStore.ts
• src/lib/tutorial-visibility.ts
• src/context/TutorialContext.tsx
• src/tests/tutorialStore.test.ts
• src/App.tsx

The Interactive Tutorial System is a state-driven educational layer designed to guide players through the core mechanics of the Dreamcats card game. It utilizes a centralized store to track progression through various educational steps, ranging from basic goal explanations to complex game actions like peeking and special card usage.

The system is integrated into the main application lifecycle, appearing automatically for new users who have not yet completed the tutorial. It employs a "highlight and explain" approach, using DOM selectors to focus the user's attention on specific game elements (like the draw pile or player hand) while providing context-sensitive tips and instructions.

Core Architecture and State Management

The tutorial's logic is decoupled from the UI using a combination of a Zustand store for state management and a React Context provider for dependency injection.

Tutorial State Store

The useTutorialStore manages the TutorialStep state and provides actions for navigating the tutorial flow. It uses a predefined linear order for steps and persists completion status to local storage.

The diagram shows the sequential progression of tutorial steps as defined in the store.
Sources: src/stores/tutorialStore.ts:24-54, src/tests/tutorialStore.test.ts:133-162

Tutorial Visibility Logic

The visibility of the initial tutorial welcome dialog is determined by a utility function that checks authentication status, preference loading states, and previous completion flags.

Condition	Value	Result
tutorialCompleted	true	Do not show
step	NOT inactive	Do not show
isAuthenticated AND prefsLoading	true	Do not show
tutorialCompleted == false AND step == inactive	true	Show Welcome

Sources: src/lib/tutorial-visibility.ts:3-19, src/context/TutorialContext.tsx:34-44

Component implementation

The Tutorial Component

The Tutorial component is the primary UI layer, responsible for rendering dialogs, the highlight overlay, and the step instruction panel. It uses framer-motion for animations and transitions between steps.

• Highlighting Logic: Uses document.querySelector with data attributes (e.g., [data-tutorial-id="draw-pile"]) to calculate the bounding rectangle of target UI elements.
• Dynamic Positioning: The instruction panel automatically shifts its position (left, right, or center) based on the location of the highlighted element to avoid obscuring it.
• Game Integration: If the tutorial starts while the user is in the lobby, it can trigger a solo game automatically to ensure the relevant UI elements are available for highlighting.

Sources: src/components/Tutorial.tsx:103-142, src/components/Tutorial.tsx:162-171, src/components/Tutorial.tsx:238-251

Tutorial Flow Control

The system synchronizes with the active game state. For example, the tutorial will automatically advance from the peeking step once the game phase changes from peeking to something else.

This sequence illustrates how the tutorial store interacts with user input and the game phase.
Sources: src/components/Tutorial.tsx:145-157, src/stores/tutorialStore.ts:69-79

Tutorial Steps Configuration

The tutorial includes 9 specific educational steps following the welcome screen.

Step	Target Element (Selector)	Purpose
goal	scoreboard	Explains the objective of getting the lowest score.
hand	player-hand	Introduces the 4-card "Dream" layout.
peeking	player-hand	Explains the initial peeking phase.
deck	draw-pile	Explains drawing hidden cards.
discard	discard-pile	Explains taking visible cards.
drawing	piles	General drawing mechanics overview.
special_cards	N/A	Explains power cards like "Take 2" or "Swap".
pobudka	pobudka-button	Explains how to end the round.
scoring	N/A	Details the scoring and penalty logic.

Sources: src/components/Tutorial.tsx:31-90, src/stores/tutorialStore.ts:10-22

Integration with Main Application

The tutorial is mounted within the App.tsx file inside the TutorialProvider. It only renders if the user has "entered" the game (past the landing screen).

// src/App.tsx
<TutorialProvider>
  <main>
    <ConvexSync />
    {/* ... other components */}
    {hasEntered && <Tutorial />}
  </main>
</TutorialProvider>

Sources: src/App.tsx:174-205

The Interactive Tutorial System ensures that players understand the unique "Dreamcats" mechanics, such as the "Pobudka" call and the risk of penalties, by providing a managed, interactive walkthrough that bridges the gap between the lobby and active gameplay.

Sources: src/components/Tutorial.tsx:1-4060, src/stores/tutorialStore.ts:1-105