State Management & Stores

dicechess-analytics-ui uses Svelte 5 Runes ($state, $derived, $effect) to implement reactive, class-based global stores.

Instead of traditional Svelte 3/4 writeable stores (writable()), all state is grouped into TypeScript classes exposing $state properties and getter-based $derived computations.

---

1. Active Game Store (ActiveGameStore)

The activeGameStore coordinates game playback, turn transitions, and board visual navigation.

Key States

• selectedGameId: The UUID of the current active game.
• gameDetail: High-level game details (metadata, players, Elo, result).
• states: An array of MoveHistoryState representing the sequential positions reconstructed from the game.
• currentMoveIndex: The pointer to the currently rendered position on the chessboard.
• isPlaying: Boolean flag tracking whether auto-playback is active.

Reactive Computations

// Computes active board FEN for the current pointer
get currentBoardFen(): string | null {
    return this.currentState?.fen ?? null;
}

// Determines if the board should be flipped (shows higher-rated player at the bottom)
get boardOrientation(): 'white' | 'black' {
    const wRating = this.gameDetail?.white_rating || 0;
    const bRating = this.gameDetail?.black_rating || 0;
    return bRating > wRating ? 'black' : 'white';
}

---

2. Game List Store (GameListStore)

The gameListStore manages the query, filtering, sorting, and pagination of the game browser.

URL-Driven Filter Sync

To support shareable links and back-button history navigation, the URL’s query parameters act as the single source of truth for the game list filters.

• Deserializer: filtersFromSearchParams(params) parses and whitelists URL search query variables (e.g. ?player=...&min_turns=...&page=...).
• Serializer: filtersToSearchParams(filters) formats active filters back to a clean query string.
• Concurrency Guard: A monotonic loadSequence counter is used during asynchronous fetch requests. If a user changes filters rapidly, any late HTTP responses from preceding, superseded page loads are discarded.

---

3. Curator Store (CuratorStore)

The curatorStore handles position bookmarking and favorite recommendations.

• Authentication: Accesses and stores the dc-curator-token via localStorage.
• Favorite caching: Fetches and maps the recommended move list for a rolled dice combination at a given FEN.
• Optimistic Updates: Mutates the favorite map instantly when bookmarking is toggled, and syncs via background API requests (PUT / DELETE).