Interaction Gating
Relevant source files
The following files were used as context for generating this wiki page:
Interaction Gating in the DreamCats project refers to the systematic control and restriction of user interface interactions based on the application's state, specifically during the onboarding and tutorial phases. Its primary purpose is to ensure that users are guided through the game mechanics without accidental interference or navigation errors while learning the rules.
This system functions by overlaying specific UI states (like the tutorial steps) and preventing standard application flow (such as form submissions or page navigation) when certain conditions are met. It ensures that the user remains focused on the current instructional context before being allowed full agency within the game environment.
Sources: src/components/Tutorial.tsx:165-185, src/App.tsx:135-180
Core Implementation Mechanisms
The interaction gating system is implemented through a combination of React components, state management via Zustand, and DOM-level event listeners.
Tutorial State Management
The system relies on a central tutorialStore to track the current step of interaction. The state can range from inactive to specific instructional steps like goal, peeking, or pobudka. Gating logic is triggered whenever the state is not inactive.
UI Overlays and Cutouts
A key technical feature of the interaction gating is the use of a radial gradient overlay that creates a "cutout" effect. This visually focuses the user on a specific interactive element while the rest of the screen is darkened and its interactions are inhibited.
| Component | Function | Implementation Detail |
|---|---|---|
| Dark Overlay | Blocks background clicks | Uses a radial-gradient calculated from highlightRect |
| Highlight Ring | Visual focus | Positioned fixed based on getBoundingClientRect() of target |
| Step Panel | Controlled navigation | Provides "Back", "Next", and "Finish" buttons |
Sources: src/components/Tutorial.tsx:210-245, src/components/Tutorial.tsx:265-275
Navigation and Event Gating
To maintain the integrity of the application state during sensitive phases (like the landing page or during active gameplay), the project implements several low-level guards.
Form and Click Interception
In App.tsx, specific event listeners are attached to the document to prevent accidental navigation. This is particularly crucial on the landing screen where third-party scripts or unexpected form submissions could disrupt the user's entry into the game.
Sources: src/App.tsx:142-175
Phase-Based Visibility Gating
The system determines whether to show onboarding elements based on a set of visibility rules. This prevents the "Interaction Gate" (the tutorial welcome) from appearing if the user is already authenticated, preferences are still loading, or the tutorial is already completed.
| Condition | Tutorial Welcome Visibility |
|---|---|
Tutorial Completed = true | Hidden |
Auth Preferences Loading = true | Hidden |
Tutorial Step != inactive | Hidden |
Tutorial Completed = false AND Step = inactive | Visible |
Sources: src/tests/tutorial-visibility.test.ts:4-40
Implementation Details
Highlight Selector Logic
The system uses data attributes (e.g., data-tutorial-id) to identify elements that should be "ungated" or highlighted during specific tutorial steps.
// Example of identifying a gated target
highlightSelector: '[data-tutorial-id="player-hand"]'
The Tutorial.tsx component polls for these elements and updates the visual cutout position dynamically using window.addEventListener('resize', updateHighlight).
Sources: src/components/Tutorial.tsx:43-50, src/components/Tutorial.tsx:112-130
Session Persistence and Rejoin Gating
Interaction is also gated by the user's session history. If an active session exists, the UI forces a choice between "Rejoin Game" and "Start Fresh," preventing the user from entering a new game state while an old one is unresolved.
Sources: src/components/LandingPage.tsx:90-120, src/App.tsx:64-70
Summary
Interaction Gating in DreamCats is a multi-layered system that combines visual overlays with event-level blocking. By leveraging Zustand for state tracking and direct DOM event interception, it ensures that instructional flows and critical navigation points are protected from user error and external script interference.