feat(rooms): real server-side private games with friend invites (no bot swap)

Private rooms were 100% client-simulated (the "friend" auto-accepted then bots
filled invited seats). Now they're server-authoritative over SignalR:

Server (GameManager.PrivateRooms + GameHub):
- Room registry with create/invite/accept/decline/addBot/clearSeat/start/leave.
- Invite pushes a `roomInvite` to that user (Clients.User); the seat stays
  "invited" (a pending guest with their real profile, resolved server-side) — it
  is NEVER replaced by a bot.
- StartPrivate refuses while any invite is pending; only EMPTY seats fill with
  bots. Then it spins up a live GameRoom and matchFound → both devices enter.
- Host leave / disconnect closes the room (roomClosed); members free their seat.

Client:
- signalr-service implements the room methods over the hub (+ room/roomInvite/
  roomClosed events, room mapping, onRoomInvite); mock keeps offline no-ops.
- online-store accept/declineInvite; RoomScreen blocks "Start" while an invite
  is pending and auto-enters the live game on matchFound (host + friend).
- New global InviteModal (accept/decline) + i18n (invite.*, room.waitAccept).

Addresses: (1) no bot replacement, (2) game waits for acceptance, (3) invited
friend shown as a pending guest with their name/avatar.

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

src/app/page.tsx

@@ -22,6 +22,7 @@ import { ResumeGameBar } from "@/components/online/ResumeGameBar";
 import { CelebrationOverlay } from "@/components/online/CelebrationOverlay";
 import { ErrorBoundary } from "@/components/ErrorBoundary";
 import { PublicProfileModal } from "@/components/online/PublicProfileModal";
+import { InviteModal } from "@/components/online/InviteModal";
 import { CapacitorBack } from "@/components/CapacitorBack";
 import { useSessionStore } from "@/lib/session-store";
 import { useGameStore } from "@/lib/game-store";
@@ -209,6 +210,7 @@ export default function Page() {
         <ResumeGameBar />
         <CelebrationOverlay />
         <PublicProfileModal />
+        <InviteModal />
       </ErrorBoundary>
       <CapacitorBack />
       {loading && null}

src/components/online/InviteModal.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { AnimatePresence, motion } from "framer-motion";
+import { Coins, Users } from "lucide-react";
+import { useEffect, useState } from "react";
+import { getService } from "@/lib/online/service";
+import { useOnlineStore } from "@/lib/online-store";
+import { useUIStore } from "@/lib/ui-store";
+import { useI18n } from "@/lib/i18n";
+import { sound } from "@/lib/sound";
+import type { RoomInvite } from "@/lib/online/types";
+
+/**
+ * Global incoming private-room invite. When a friend invites you, this pops up
+ * with accept/decline. Accepting joins their room (you appear as a real guest,
+ * never a bot) and opens the room screen.
+ */
+export function InviteModal() {
+  const { t } = useI18n();
+  const acceptInvite = useOnlineStore((s) => s.acceptInvite);
+  const declineInvite = useOnlineStore((s) => s.declineInvite);
+  const go = useUIStore((s) => s.go);
+  const [invite, setInvite] = useState<RoomInvite | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    const unsub = getService().onRoomInvite((i) => {
+      setInvite(i);
+      if (i) sound.play("notify");
+    });
+    return unsub;
+  }, []);
+
+  if (!invite) return null;
+
+  const accept = async () => {
+    if (busy) return;
+    setBusy(true);
+    try {
+      await acceptInvite();
+      go("room");
+    } finally {
+      setBusy(false);
+      setInvite(null);
+    }
+  };
+  const decline = async () => {
+    if (busy) return;
+    setBusy(true);
+    try {
+      await declineInvite();
+    } finally {
+      setBusy(false);
+      setInvite(null);
+    }
+  };
+
+  return (
+    <AnimatePresence>
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        exit={{ opacity: 0 }}
+        className="fixed inset-0 z-[80] flex items-center justify-center bg-navy-950/85 backdrop-blur-sm p-5"
+      >
+        <motion.div
+          initial={{ scale: 0.9, y: 20 }}
+          animate={{ scale: 1, y: 0 }}
+          transition={{ type: "spring", stiffness: 240, damping: 22 }}
+          className="glass rounded-3xl p-6 w-full max-w-xs text-center"
+        >
+          <div className="mx-auto grid size-14 place-items-center rounded-2xl btn-gold mb-3">
+            <Users className="size-6" />
+          </div>
+          <h2 className="gold-text text-lg font-black">{t("invite.title")}</h2>
+          <p className="text-cream/75 text-sm mt-2">{t("invite.body").replace("{name}", invite.hostName)}</p>
+          {invite.stake > 0 && (
+            <p className="mt-2 inline-flex items-center gap-1 text-gold-300 text-xs font-bold">
+              {invite.stake.toLocaleString()} <Coins className="size-3.5" />
+            </p>
+          )}
+          <div className="flex gap-2 mt-5">
+            <button onClick={decline} disabled={busy} className="flex-1 glass rounded-xl py-3 text-cream/70 disabled:opacity-60">
+              {t("invite.decline")}
+            </button>
+            <button onClick={accept} disabled={busy} className="flex-1 btn-gold rounded-xl py-3 font-bold disabled:opacity-60">
+              {t("invite.accept")}
+            </button>
+          </div>
+        </motion.div>
+      </motion.div>
+    </AnimatePresence>
+  );
+}

src/components/screens/RoomScreen.tsx

@@ -8,6 +8,7 @@ import { useGameStore } from "@/lib/game-store";
 import { useOnlineStore } from "@/lib/online-store";
 import { useUIStore } from "@/lib/ui-store";
 import { useI18n } from "@/lib/i18n";
+import { getService } from "@/lib/online/service";
 import { Friend, PresenceStatus, RoomSeat, avatarEmoji } from "@/lib/online/types";
 import { cn } from "@/lib/cn";
 
@@ -31,6 +32,7 @@ export function RoomScreen() {
   const startRoom = useOnlineStore((s) => s.startRoom);
   const leaveRoom = useOnlineStore((s) => s.leaveRoom);
   const newOnlineMatch = useGameStore((s) => s.newOnlineMatch);
+  const enterServerMatch = useGameStore((s) => s.enterServerMatch);
   const goGame = useUIStore((s) => s.goGame);
   const go = useUIStore((s) => s.go);
 
@@ -41,7 +43,22 @@ export function RoomScreen() {
     loadFriends();
   }, [loadFriends]);
 
+  // Live: when the host starts, the server sends matchFound to every human seat
+  // (host + accepted friends) → each device auto-enters the server-run game.
+  useEffect(() => {
+    const svc = getService();
+    if (!svc.live) return;
+    const unsub = svc.onMatchmaking((s) => {
+      if (s.phase === "ready") {
+        enterServerMatch(svc);
+        goGame("home");
+      }
+    });
+    return unsub;
+  }, [enterServerMatch, goGame]);
+
   if (!room) return null;
+  const hasPending = room.seats.some((s) => s.kind === "invited");
   const seat = (n: number) => room.seats.find((s) => s.seat === n)!;
   const statusLabel = (s: PresenceStatus) =>
     s === "online" ? t("friends.online") : s === "in-game" ? t("friends.inGame") : t("friends.offline");
@@ -64,6 +81,13 @@ export function RoomScreen() {
   };
 
   const start = async () => {
+    if (hasPending) return; // never start while a friend's invite is still pending
+    if (getService().live) {
+      // Server runs the match; it pushes matchFound → the effect above enters it.
+      await startRoom();
+      return;
+    }
+    // Offline mock: build a client-run match from the (bot-filled) seats.
     await startRoom();
     const r = useOnlineStore.getState().room!;
     const players = r.seats
@@ -136,11 +160,18 @@ export function RoomScreen() {
         </div>
       </div>
 
+      {hasPending && (
+        <p className="text-center text-[11px] text-gold-300/80 mt-5 -mb-2">{t("room.waitAccept")}</p>
+      )}
       <div className="flex gap-3 mt-7">
         <button onClick={leave} className="glass rounded-xl px-5 py-3 text-cream/70 hover:text-cream">
           {t("room.leave")}
         </button>
-        <button onClick={start} className="btn-gold flex-1 rounded-xl py-3 text-lg">
+        <button
+          onClick={start}
+          disabled={hasPending}
+          className="btn-gold flex-1 rounded-xl py-3 text-lg disabled:opacity-50 disabled:cursor-not-allowed"
+        >
           {t("room.start")}
         </button>
       </div>

src/lib/i18n.tsx

@@ -239,6 +239,11 @@ const fa: Dict = {
   "room.addBot": "ربات",
   "room.empty": "خالی",
   "room.waiting": "در انتظار پذیرش…",
+  "room.waitAccept": "تا وقتی دوستت دعوت را نپذیرد بازی شروع نمی‌شود",
+  "invite.title": "دعوت به بازی",
+  "invite.body": "{name} شما را به یک بازی خصوصی دعوت کرد",
+  "invite.accept": "بپذیر",
+  "invite.decline": "رد",
   "room.cancelInvite": "لغو دعوت",
   "room.start": "شروع بازی",
   "room.stake": "سکه ورودی",
@@ -620,6 +625,11 @@ const en: Dict = {
   "room.addBot": "Bot",
   "room.empty": "Empty",
   "room.waiting": "Waiting to accept…",
+  "room.waitAccept": "The game won't start until your friend accepts",
+  "invite.title": "Game invite",
+  "invite.body": "{name} invited you to a private game",
+  "invite.accept": "Accept",
+  "invite.decline": "Decline",
   "room.cancelInvite": "Cancel invite",
   "room.start": "Start game",
   "room.stake": "Entry coins",

src/lib/online-store.ts

@@ -32,6 +32,8 @@ interface OnlineStore {
   clearSeat: (seat: 1 | 2 | 3) => Promise<void>;
   startRoom: () => Promise<void>;
   leaveRoom: () => Promise<void>;
+  acceptInvite: () => Promise<void>;
+  declineInvite: () => Promise<void>;
 
   startMatchmaking: (opts: MatchmakingOptions) => Promise<void>;
   cancelMatchmaking: () => Promise<void>;
@@ -133,6 +135,15 @@ export const useOnlineStore = create<OnlineStore>((set, get) => ({
     }
     set({ room: null });
   },
+  acceptInvite: async () => {
+    const svc = getService();
+    if (roomUnsub) roomUnsub();
+    roomUnsub = svc.onRoom((r) => set({ room: { ...r } })); // subscribe first so we catch the room push
+    await svc.acceptInvite();
+  },
+  declineInvite: async () => {
+    await getService().declineInvite();
+  },
 
   startMatchmaking: async (opts) => {
     const svc = getService();

src/lib/online/mock-service.ts

@@ -868,6 +868,13 @@ export class MockOnlineService implements OnlineService {
     return () => this.roomCbs.delete(cb);
   }
 
+  // Offline mock has no real cross-device invites — these are inert.
+  async acceptInvite() {}
+  async declineInvite() {}
+  onRoomInvite(): Unsubscribe {
+    return () => {};
+  }
+
   /* --------------------------- matchmaking --------------------------- */
 
   async startMatchmaking(opts: MatchmakingOptions) {

src/lib/online/service.ts

@@ -17,6 +17,7 @@ import {
   PlayerSummary,
   PublicProfile,
   ReportReason,
+  RoomInvite,
   MatchSummary,
   MatchmakingState,
   RewardResult,
@@ -122,6 +123,11 @@ export interface OnlineService {
   startRoom(roomId: string): Promise<Room>;
   leaveRoom(roomId: string): Promise<void>;
   onRoom(cb: (room: Room) => void): Unsubscribe;
+  /** Respond to an incoming room invite (join their room / decline). */
+  acceptInvite(): Promise<void>;
+  declineInvite(): Promise<void>;
+  /** An invite arrived (or null when it was cancelled). */
+  onRoomInvite(cb: (invite: RoomInvite | null) => void): Unsubscribe;
 
   /* ----- matchmaking ----- */
   startMatchmaking(opts: MatchmakingOptions): Promise<void>;

src/lib/online/signalr-service.ts

@@ -27,6 +27,7 @@ import {
   MatchmakingState,
   RewardResult,
   Room,
+  RoomInvite,
   ServerGameState,
   ShopItem,
   UserProfile,
@@ -35,6 +36,22 @@ import {
 const SERVER = process.env.NEXT_PUBLIC_SERVER_URL || "http://localhost:5005";
 const LS_SESSION = "hokm.session";
 
+/** Raw private-room shape pushed by the server (kind: empty|invited|bot|human). */
+interface ServerRoom {
+  id: string;
+  code: string;
+  hostId: string;
+  status: string;
+  targetScore: number;
+  stake: number;
+  ranked: boolean;
+  seats: { seat: number; kind: string; player?: { id: string; displayName: string; avatar: string; level: number } }[];
+}
+
+const EMPTY_ROOM: Room = {
+  id: "", code: "", hostId: "", status: "open", seats: [], targetScore: 7, stake: 0, ranked: false,
+};
+
 /**
  * Talks to the .NET SignalR backend for auth, matchmaking, live game state and
  * reactions. Everything not yet server-backed (profile, friends, shop, daily,
@@ -61,6 +78,10 @@ export class SignalrService implements OnlineService {
   private chatCbs = new Set<(id: string, m: ChatMessage[]) => void>();
   private typingCbs = new Set<(fromId: string) => void>();
   private forfeitCbs = new Set<(r: ForfeitRequest | null) => void>();
+  private roomCbs = new Set<(r: Room) => void>();
+  private roomInviteCbs = new Set<(i: RoomInvite | null) => void>();
+  private roomWaiters: ((r: Room) => void)[] = [];
+  private lastRoom: Room | null = null;
   private cachedProfile: UserProfile | null = null;
 
   constructor() {
@@ -133,6 +154,18 @@ export class SignalrService implements OnlineService {
       this.reactionCbs.forEach((cb) => cb(r.seat, r.reaction)));
     conn.on("typing", (m: { from: string }) =>
       this.typingCbs.forEach((cb) => cb(m.from)));
+    conn.on("room", (r: ServerRoom) => {
+      const room = this.mapRoom(r);
+      this.lastRoom = room;
+      this.roomWaiters.splice(0).forEach((w) => w(room));
+      this.roomCbs.forEach((cb) => cb(room));
+    });
+    conn.on("roomInvite", (i: RoomInvite) => this.roomInviteCbs.forEach((cb) => cb(i)));
+    conn.on("roomInviteCancelled", () => this.roomInviteCbs.forEach((cb) => cb(null)));
+    conn.on("roomClosed", () => {
+      this.lastRoom = null;
+      this.roomInviteCbs.forEach((cb) => cb(null));
+    });
     conn.on("notification", (n: AppNotification) =>
       this.notifCbs.forEach((cb) => cb(n)));
     conn.on("profile", (p: UserProfile) =>
@@ -399,14 +432,65 @@ export class SignalrService implements OnlineService {
   }
   onFriends(cb: (f: Friend[]) => void) { this.friendCbs.add(cb); return () => this.friendCbs.delete(cb); }
 
-  createRoom(o: CreateRoomOptions) { return this.mock.createRoom(o); }
-  setPartner(roomId: string, friendId: string | null) { return this.mock.setPartner(roomId, friendId); }
-  inviteToSeat(roomId: string, seat: 1 | 3, friendId: string) { return this.mock.inviteToSeat(roomId, seat, friendId); }
-  addBot(roomId: string, seat: 1 | 2 | 3) { return this.mock.addBot(roomId, seat); }
-  clearSeat(roomId: string, seat: 1 | 2 | 3) { return this.mock.clearSeat(roomId, seat); }
-  startRoom(roomId: string) { return this.mock.startRoom(roomId); }
-  leaveRoom(roomId: string) { return this.mock.leaveRoom(roomId); }
-  onRoom(cb: (r: Room) => void) { return this.mock.onRoom(cb); }
+  // --- private rooms (server-authoritative, real friend invites) ---
+  private mapRoom(r: ServerRoom): Room {
+    const myId = this.session?.userId;
+    return {
+      id: r.id, code: r.code, hostId: r.hostId, status: "open",
+      targetScore: r.targetScore, stake: r.stake, ranked: r.ranked,
+      seats: r.seats.map((s) => ({
+        seat: s.seat as 0 | 1 | 2 | 3,
+        kind:
+          s.kind === "empty" ? "empty"
+          : s.kind === "bot" ? "bot"
+          : s.kind === "invited" ? "invited"
+          : s.player?.id === myId ? "you" : "friend",
+        player: s.player,
+      })),
+    };
+  }
+  private waitRoom(): Promise<Room> {
+    return new Promise((resolve) => {
+      this.roomWaiters.push(resolve);
+      setTimeout(() => {
+        const i = this.roomWaiters.indexOf(resolve);
+        if (i >= 0) { this.roomWaiters.splice(i, 1); resolve(this.lastRoom ?? EMPTY_ROOM); }
+      }, 5000);
+    });
+  }
+  async createRoom(o: CreateRoomOptions) {
+    await this.connect();
+    const p = this.cachedProfile ?? (await this.getProfile().catch(() => this.mock.getProfile()));
+    await this.conn?.invoke("CreatePrivateRoom",
+      { name: p.displayName, avatar: p.avatar, level: p.level, plan: p.plan }, o.stake, o.targetScore);
+    return this.waitRoom();
+  }
+  async setPartner(_roomId: string, friendId: string | null) {
+    if (friendId) await this.conn?.invoke("InvitePrivate", 2, friendId);
+    else await this.conn?.invoke("ClearPrivateSeat", 2);
+    return this.lastRoom ?? EMPTY_ROOM;
+  }
+  async inviteToSeat(_roomId: string, seat: 1 | 3, friendId: string) {
+    await this.conn?.invoke("InvitePrivate", seat, friendId);
+    return this.lastRoom ?? EMPTY_ROOM;
+  }
+  async addBot(_roomId: string, seat: 1 | 2 | 3) {
+    await this.conn?.invoke("AddPrivateBot", seat);
+    return this.lastRoom ?? EMPTY_ROOM;
+  }
+  async clearSeat(_roomId: string, seat: 1 | 2 | 3) {
+    await this.conn?.invoke("ClearPrivateSeat", seat);
+    return this.lastRoom ?? EMPTY_ROOM;
+  }
+  async startRoom(_roomId: string) {
+    await this.conn?.invoke("StartPrivate");
+    return this.lastRoom ?? EMPTY_ROOM;
+  }
+  async leaveRoom(_roomId: string) { await this.conn?.invoke("LeavePrivate"); }
+  onRoom(cb: (r: Room) => void) { this.roomCbs.add(cb); return () => this.roomCbs.delete(cb); }
+  async acceptInvite() { await this.connect(); await this.conn?.invoke("AcceptPrivate"); }
+  async declineInvite() { await this.conn?.invoke("DeclinePrivate"); }
+  onRoomInvite(cb: (i: RoomInvite | null) => void) { this.roomInviteCbs.add(cb); return () => this.roomInviteCbs.delete(cb); }
 
   listConversations(): Promise<Conversation[]> { return this.getJson<Conversation[]>("/api/chat"); }
   getMessages(id: string): Promise<ChatMessage[]> {

src/lib/online/types.ts

@@ -356,6 +356,14 @@ export interface Room {
   ranked: boolean;
 }
 
+/** An incoming invitation to someone else's private room. */
+export interface RoomInvite {
+  roomId: string;
+  code: string;
+  hostName: string;
+  stake: number;
+}
+
 /* --------------------------- Matchmaking ----------------------------- */
 
 export type MatchmakingPhase =