Build Hokm card game: offline vs-AI + online social/gamification (mock backend)

- Pure-TS Hokm engine (deal, hakem, trump, tricks, scoring, Kot) + AI bots
- Persian-luxury RTL UI (Next 16 / React 19 / Tailwind v4 / Framer Motion / Zustand)
- Online platform behind OnlineService seam (mock now, .NET SignalR later):
  auth (phone OTP + email/Google), profiles, friends, private rooms with
  partner pick, ranked matchmaking, leaderboard, shop
- Gamification: ranks/leagues, coins, XP/levels, daily rewards, achievements
- i18n fa/en, PWA manifest, engine + gamification sims

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/lib/game-store.ts

@@ -0,0 +1,228 @@
+"use client";
+
+import { create } from "zustand";
+import { chooseCardAI, chooseTrumpAI } from "./hokm/ai";
+import {
+  advanceAfterTrick,
+  chooseTrump as engineChooseTrump,
+  createInitialState,
+  dealForTrump,
+  playCard,
+  selectHakem,
+  startNextRound,
+} from "./hokm/engine";
+import { Card, GameState, RoundResult, Suit } from "./hokm/types";
+import { avatarEmoji } from "./online/types";
+
+const KOT_POINTS = 2;
+
+// Animation/pacing timings (ms) — UI matches these.
+export const TIMING = {
+  hakemDraw: 1500,
+  aiTrump: 1000,
+  aiPlay: 850,
+  trickPause: 1150,
+  roundPause: 2600,
+} as const;
+
+export type GameMode = "ai" | "online";
+
+export interface SeatPlayer {
+  name: string;
+  avatar: string; // emoji
+  level: number;
+}
+
+export interface GameSettings {
+  names: [string, string, string, string];
+  targetScore: number;
+}
+
+export interface OnlineMatchConfig {
+  players: { displayName: string; avatar: string; level: number }[]; // index = seat
+  targetScore: number;
+  stake: number;
+  ranked: boolean;
+}
+
+interface MatchTally {
+  tricksTeam0: number;
+  kotFor: boolean; // your team kot'd opponents at least once
+  kotAgainst: boolean;
+}
+
+interface GameStore {
+  game: GameState;
+  started: boolean;
+  mode: GameMode;
+  seatPlayers: SeatPlayer[];
+  matchMeta: { ranked: boolean; stake: number };
+  tally: MatchTally;
+
+  newMatch: (settings: GameSettings) => void;
+  newOnlineMatch: (cfg: OnlineMatchConfig) => void;
+  chooseTrump: (suit: Suit) => void;
+  playHuman: (card: Card) => void;
+  reset: () => void;
+}
+
+const AI_AVATARS = ["🦊", "🦁", "🦉", "🐯"];
+
+let pending: ReturnType<typeof setTimeout> | null = null;
+function clearPending() {
+  if (pending) {
+    clearTimeout(pending);
+    pending = null;
+  }
+}
+
+function freshTally(): MatchTally {
+  return { tricksTeam0: 0, kotFor: false, kotAgainst: false };
+}
+
+export const useGameStore = create<GameStore>((set, get) => {
+  function recordRound(result: RoundResult | null) {
+    if (!result) return;
+    const t = get().tally;
+    set({
+      tally: {
+        tricksTeam0: t.tricksTeam0 + result.tricks[0],
+        kotFor: t.kotFor || (result.winningTeam === 0 && result.kot),
+        kotAgainst: t.kotAgainst || (result.winningTeam === 1 && result.kot),
+      },
+    });
+  }
+
+  function scheduleAuto() {
+    clearPending();
+    const g = get().game;
+
+    switch (g.phase) {
+      case "selecting-hakem":
+        pending = setTimeout(() => {
+          set({ game: dealForTrump(get().game) });
+          scheduleAuto();
+        }, TIMING.hakemDraw);
+        break;
+
+      case "choosing-trump": {
+        const hakem = g.hakem!;
+        if (!g.players[hakem].isHuman) {
+          pending = setTimeout(() => {
+            const cur = get().game;
+            const suit = chooseTrumpAI(cur.players[cur.hakem!].hand);
+            set({ game: engineChooseTrump(cur, suit) });
+            scheduleAuto();
+          }, TIMING.aiTrump);
+        }
+        break;
+      }
+
+      case "playing": {
+        const seat = g.turn!;
+        if (!g.players[seat].isHuman) {
+          pending = setTimeout(() => {
+            const cur = get().game;
+            const s = cur.turn!;
+            const card = chooseCardAI(cur, s);
+            set({ game: playCard(cur, s, card) });
+            scheduleAuto();
+          }, TIMING.aiPlay);
+        }
+        break;
+      }
+
+      case "trick-complete":
+        pending = setTimeout(() => {
+          const next = advanceAfterTrick(get().game, KOT_POINTS);
+          set({ game: next });
+          // record the round once when it finalizes into match-over
+          if (next.phase === "match-over") recordRound(next.lastRoundResult);
+          scheduleAuto();
+        }, TIMING.trickPause);
+        break;
+
+      case "round-over":
+        pending = setTimeout(() => {
+          recordRound(get().game.lastRoundResult);
+          set({ game: startNextRound(get().game) });
+          scheduleAuto();
+        }, TIMING.roundPause);
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  return {
+    game: createInitialState({ names: ["", "", "", ""], targetScore: 7 }),
+    started: false,
+    mode: "ai",
+    seatPlayers: [],
+    matchMeta: { ranked: false, stake: 0 },
+    tally: freshTally(),
+
+    newMatch: (settings) => {
+      clearPending();
+      const initial = createInitialState(settings);
+      set({
+        game: selectHakem(initial),
+        started: true,
+        mode: "ai",
+        matchMeta: { ranked: false, stake: 0 },
+        tally: freshTally(),
+        seatPlayers: settings.names.map((name, i) => ({
+          name,
+          avatar: AI_AVATARS[i],
+          level: 0,
+        })),
+      });
+      scheduleAuto();
+    },
+
+    newOnlineMatch: (cfg) => {
+      clearPending();
+      const names = cfg.players.map((p) => p.displayName) as GameSettings["names"];
+      const initial = createInitialState({ names, targetScore: cfg.targetScore });
+      set({
+        game: selectHakem(initial),
+        started: true,
+        mode: "online",
+        matchMeta: { ranked: cfg.ranked, stake: cfg.stake },
+        tally: freshTally(),
+        seatPlayers: cfg.players.map((p) => ({
+          name: p.displayName,
+          avatar: avatarEmoji(p.avatar),
+          level: p.level,
+        })),
+      });
+      scheduleAuto();
+    },
+
+    chooseTrump: (suit) => {
+      const g = get().game;
+      if (g.phase !== "choosing-trump") return;
+      set({ game: engineChooseTrump(g, suit) });
+      scheduleAuto();
+    },
+
+    playHuman: (card) => {
+      const g = get().game;
+      if (g.phase !== "playing" || g.turn !== 0) return;
+      set({ game: playCard(g, 0, card) });
+      scheduleAuto();
+    },
+
+    reset: () => {
+      clearPending();
+      set({
+        game: createInitialState({ names: ["", "", "", ""], targetScore: 7 }),
+        started: false,
+        mode: "ai",
+        seatPlayers: [],
+        tally: freshTally(),
+      });
+    },
+  };
+});