@thegeem/protocol 0.1.38 → 0.1.41

package/dist/index.d.ts

@@ -36,7 +36,7 @@ declare const LIMITS: {
  *    `seedha`/`snag`). Raise the floor SLOWLY to retire ancient builds. Unversioned clients (no `pv`,
  *    e.g. the legacy web harness) are treated as the floor and never rejected.
  */
-declare const PROTOCOL_VERSION = 4;
+declare const PROTOCOL_VERSION = 7;
 declare const MIN_SUPPORTED_PV = 1;
 /**
  * Geem is a PLATFORM of GAMES (jackbox-style). The trivia board split (D-023) into TWO player-facing
@@ -45,7 +45,7 @@ declare const MIN_SUPPORTED_PV = 1;
  * pre-pv2 clients (they never saw seedha/snag), and what old clients send on startGame. Every room
  * runs one game, identified by `gameId`.
  */
-declare const GAME_IDS: readonly ["seedha", "snag", "trivia", "dama", "ersimha"];
+declare const GAME_IDS: readonly ["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"];
 type GameId = (typeof GAME_IDS)[number];
 /**
  * The GAME REGISTRY — player-facing games + the version gating (D-024/D-025). A client renders a tile
@@ -60,6 +60,56 @@ interface GameInfo {
 }
 declare const GAMES: readonly GameInfo[];
 /** Games to OFFER a client of version `pv` (tiles). Excludes the deprecated alias + anything too new. */
+/**
+ * ⚠️ THE OUTBOUND ADAPTER FOR `hostActivity`, AND IT PREVENTS A FROZEN LOBBY — not a wrong banner.
+ *
+ * The generated Swift type is `enum Activity: String, Codable` — a STRICT enum. A build that predates
+ * `options` has only `configuring` and `idle` in it, so receiving `"options"` makes the decode THROW,
+ * and because `hostActivity` sits inside the lobby struct **the entire lobby frame is dropped**. Every
+ * old joiner in the room stops updating: no new players, no team changes, no category picks. Nothing
+ * errors on either side.
+ *
+ * That is not a hypothetical — it is the same «one unknown key drops the whole frame» failure the iOS
+ * desk described for `SebaqStateView`, arriving through an enum instead of a missing field.
+ *
+ * ⚠️ SO IT IS DOWN-MAPPED PER RECIPIENT, and the alternative was worse: without this, the Options page
+ * could not ship until an App Store release carrying a lenient decoder had reached every player —
+ * and frozen app-store builds never fully do. This is [[D-025]]'s adapt-within-a-window applied to a
+ * second field: the server speaks each client's dialect on the way out.
+ *
+ * `configuring` and not `idle`, deliberately: the host IS busy setting up. An old joiner reads
+ * «… يختار الفئات» a step early, which is slightly wrong and completely harmless — where `idle` would
+ * say «nothing is happening» while the host configures, which is the wrong sentence.
+ */
+declare const hostActivityForPv: (activity: "options" | "configuring" | "idle", pv?: number) => "options" | "configuring" | "idle";
+/**
+ * The pv at which a client can decode the `comebackBonus` effect. Below this it is WITHHELD, never
+ * down-mapped: there is nothing older to translate it into, and the alternative is worse than useless.
+ *
+ * ⚠️ THE FAILURE IT PREVENTS IS NOT «the card does not show». quicktype emits `Effect` as a strict
+ * Swift enum, so a build that predates this variant throws on decode — and because effects travel as
+ * an ARRAY inside one `fx` frame, the whole frame is dropped. Sounds, reveals, celebrations and score
+ * pops in the same batch die with it, silently, for the rest of that game. **One new variant can stop
+ * an old client updating at all.**
+ *
+ * So an old build gets the +100 (the score is in the state it already renders) and no card. That is
+ * the honest degradation: the game stays correct, the animation is missing.
+ */
+declare const COMEBACK_BONUS_MIN_PV = 7;
+/**
+ * The effects safe to send a client of version `pv`.
+ *
+ * ⚠️ WITHHOLDING IS THE ONLY OPTION FOR AN EFFECT, and it is why this is a filter rather than a
+ * mapper like `hostActivityForPv`. An unknown `hostActivity` string could be down-mapped to an older
+ * word that means nearly the same thing; an unknown effect VARIANT has no older equivalent, and
+ * inventing one (sending `scorePop` instead) would make the client animate a normal score change for
+ * an event that is not one.
+ */
+/** Every comeback effect, as ONE list. ⚠️ Exported because the relay's `CLIENT_FX` allow-list must be
+ *  built from it rather than re-typed: I re-typed it, listed one of the three, and shipped a feature
+ *  whose refusal rendered as silence on prod. A hand-list that fails by OMISSION errors nowhere. */
+declare const COMEBACK_EFFECTS: readonly ["comebackOffer", "comebackBonus", "comebackDeclined"];
+declare const effectsForPv: (effects: Effect[], pv: number | undefined) => Effect[];
 declare const gamesForPv: (pv: number) => GameInfo[];
 /** The gameId to SEND a client of version `pv`: new games need pv >= their minPv; older clients see 'trivia'. */
 declare const gameIdForPv: (gameId: GameId, pv: number | undefined) => GameId;
@@ -134,11 +184,12 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
         emoji: string;
         color: string;
     }>>;
-    game: z.ZodOptional<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha"]>>;
+    game: z.ZodOptional<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"]>>;
     character: z.ZodOptional<z.ZodEnum<["m", "f"]>>;
     pv: z.ZodOptional<z.ZodNumber>;
     idToken: z.ZodOptional<z.ZodString>;
     platform: z.ZodOptional<z.ZodEnum<["web", "ios", "android", "tv"]>>;
+    games: z.ZodOptional<z.ZodArray<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"]>, "many">>;
     appVersion: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     t: "createRoom";
@@ -147,11 +198,12 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
         emoji: string;
         color: string;
     } | undefined;
-    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | undefined;
+    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq" | undefined;
     character?: "m" | "f" | undefined;
     pv?: number | undefined;
     idToken?: string | undefined;
     platform?: "web" | "ios" | "android" | "tv" | undefined;
+    games?: ("seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq")[] | undefined;
     appVersion?: string | undefined;
 }, {
     t: "createRoom";
@@ -160,11 +212,12 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
         emoji: string;
         color: string;
     } | undefined;
-    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | undefined;
+    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq" | undefined;
     character?: "m" | "f" | undefined;
     pv?: number | undefined;
     idToken?: string | undefined;
     platform?: "web" | "ios" | "android" | "tv" | undefined;
+    games?: ("seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq")[] | undefined;
     appVersion?: string | undefined;
 }>, z.ZodObject<{
     t: z.ZodLiteral<"renameHost">;
@@ -223,6 +276,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     pv: z.ZodOptional<z.ZodNumber>;
     idToken: z.ZodOptional<z.ZodString>;
     platform: z.ZodOptional<z.ZodEnum<["web", "ios", "android", "tv"]>>;
+    games: z.ZodOptional<z.ZodArray<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"]>, "many">>;
     appVersion: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     code: string;
@@ -236,6 +290,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     pv?: number | undefined;
     idToken?: string | undefined;
     platform?: "web" | "ios" | "android" | "tv" | undefined;
+    games?: ("seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq")[] | undefined;
     appVersion?: string | undefined;
 }, {
     code: string;
@@ -249,6 +304,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     pv?: number | undefined;
     idToken?: string | undefined;
     platform?: "web" | "ios" | "android" | "tv" | undefined;
+    games?: ("seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq")[] | undefined;
     appVersion?: string | undefined;
 }>, z.ZodObject<{
     t: z.ZodLiteral<"resume">;
@@ -268,6 +324,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     pv: z.ZodOptional<z.ZodNumber>;
     idToken: z.ZodOptional<z.ZodString>;
     platform: z.ZodOptional<z.ZodEnum<["web", "ios", "android", "tv"]>>;
+    games: z.ZodOptional<z.ZodArray<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"]>, "many">>;
     appVersion: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     code: string;
@@ -281,6 +338,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     pv?: number | undefined;
     idToken?: string | undefined;
     platform?: "web" | "ios" | "android" | "tv" | undefined;
+    games?: ("seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq")[] | undefined;
     appVersion?: string | undefined;
 }, {
     code: string;
@@ -294,6 +352,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     pv?: number | undefined;
     idToken?: string | undefined;
     platform?: "web" | "ios" | "android" | "tv" | undefined;
+    games?: ("seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq")[] | undefined;
     appVersion?: string | undefined;
 }>, z.ZodObject<{
     t: z.ZodLiteral<"setPlaying">;
@@ -340,6 +399,15 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
 }, {
     t: "kick";
     playerId: string;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"comebackDecide">;
+    grant: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    t: "comebackDecide";
+    grant: boolean;
+}, {
+    t: "comebackDecide";
+    grant: boolean;
 }>, z.ZodObject<{
     t: z.ZodLiteral<"setCategories">;
     categoryIds: z.ZodArray<z.ZodString, "many">;
@@ -367,30 +435,51 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
 }, {
     t: "pickTeam";
     teamIndex: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"sebaqAnswer">;
+    optionIndex: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    t: "sebaqAnswer";
+    optionIndex: number;
+}, {
+    t: "sebaqAnswer";
+    optionIndex: number;
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"sebaqRetry">;
+}, "strip", z.ZodTypeAny, {
+    t: "sebaqRetry";
+}, {
+    t: "sebaqRetry";
+}>, z.ZodObject<{
+    t: z.ZodLiteral<"sebaqSkip">;
+}, "strip", z.ZodTypeAny, {
+    t: "sebaqSkip";
+}, {
+    t: "sebaqSkip";
 }>, z.ZodObject<{
     t: z.ZodLiteral<"setMode">;
-    game: z.ZodOptional<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha"]>>;
+    game: z.ZodOptional<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"]>>;
     modeId: z.ZodOptional<z.ZodEnum<["solo", "oneDevice", "snag", "multiplayer"]>>;
 }, "strip", z.ZodTypeAny, {
     t: "setMode";
-    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | undefined;
+    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq" | undefined;
     modeId?: "snag" | "solo" | "oneDevice" | "multiplayer" | undefined;
 }, {
     t: "setMode";
-    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | undefined;
+    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq" | undefined;
     modeId?: "snag" | "solo" | "oneDevice" | "multiplayer" | undefined;
 }>, z.ZodObject<{
     t: z.ZodLiteral<"hostActivity">;
-    activity: z.ZodEnum<["configuring", "idle"]>;
+    activity: z.ZodEnum<["options", "configuring", "idle"]>;
 }, "strip", z.ZodTypeAny, {
     t: "hostActivity";
-    activity: "configuring" | "idle";
+    activity: "options" | "configuring" | "idle";
 }, {
     t: "hostActivity";
-    activity: "configuring" | "idle";
+    activity: "options" | "configuring" | "idle";
 }>, z.ZodObject<{
     t: z.ZodLiteral<"startGame">;
-    game: z.ZodOptional<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha"]>>;
+    game: z.ZodOptional<z.ZodEnum<["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"]>>;
     totalRounds: z.ZodNumber;
     categoryIds: z.ZodArray<z.ZodString, "many">;
     hostPlays: z.ZodOptional<z.ZodBoolean>;
@@ -409,7 +498,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     t: "startGame";
     categoryIds: string[];
     totalRounds: number;
-    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | undefined;
+    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq" | undefined;
     modeId?: "snag" | "solo" | "oneDevice" | "multiplayer" | undefined;
     hostPlays?: boolean | undefined;
     players?: string[] | undefined;
@@ -422,7 +511,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     t: "startGame";
     categoryIds: string[];
     totalRounds: number;
-    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | undefined;
+    game?: "seedha" | "snag" | "trivia" | "dama" | "ersimha" | "sebaq" | undefined;
     modeId?: "snag" | "solo" | "oneDevice" | "multiplayer" | undefined;
     hostPlays?: boolean | undefined;
     players?: string[] | undefined;
@@ -901,6 +990,26 @@ interface GameStateView {
      *  paused (e.g. steal intro), or after time-up. Present ⇒ animate a countdown from
      *  it; the server remains the authority on actual time-up. */
     timerRemainingMs?: number;
+    /**
+     * A comeback bonus awaiting the host's verdict (gs#123), or ABSENT when there is none.
+     *
+     * ⚠️ IT IS STATE, NOT ONLY AN EFFECT, AND THE DIFFERENCE IS A WEDGE. `comebackOffer` arrives as an
+     * `fx` — and `fx` is transient and never replayed. So a host who reconnects between the offer and
+     * their verdict would come back to a state with no mention of it: no card, no buttons, and no way
+     * to resolve. The server would still hold the pending offer, and a pending offer BLOCKS the next
+     * one, so the feature would be permanently dead for the rest of that game with nothing in any log.
+     *
+     * Found by the iOS desk asking «a resume snapshot after the accept carries the new score only,
+     * yes?» — a question about the happy path, whose answer exposed the unhappy one.
+     *
+     * ABSENT rather than null when there is no offer: the card is either on screen or it is not, and an
+     * optional key is the shape a client already has to handle for `timerRemainingMs`.
+     */
+    comebackOffer?: {
+        teamId: string;
+        questionText: string;
+        scoreGapBeforeBonus: number;
+    };
 }
 /** Transient presentation effects the relay emits; clients play them once. */
 type Effect = {
@@ -931,6 +1040,21 @@ type Effect = {
     t: 'scorePop';
     amount: number;
     streakBonus: number;
+} | {
+    t: 'comebackBonus';
+    teamId: string;
+    points: number;
+    previousScore: number;
+    newScore: number;
+    scoreGapBeforeBonus: number;
+} | {
+    t: 'comebackOffer';
+    teamId: string;
+    questionText: string;
+    scoreGapBeforeBonus: number;
+} | {
+    t: 'comebackDeclined';
+    teamId: string;
 } | {
     t: 'chargeCredit';
 } | {
@@ -989,6 +1113,73 @@ interface DamaStateView {
     moveCount: number;
     black?: string;
     white?: string;
+    /**
+     * When the side to move runs out of time, as absolute epoch ms — render it as a countdown.
+     *
+     * دامة is strictly 1v1, so ONE absent player stops the board completely: every other engine bounded
+     * its equivalent and this one did not, which left a stalled game sitting until the 30-minute room
+     * reaper. On expiry the game ends with NO winner and NO rating change — the same ruling as a
+     * mid-game kick (2026-08-08): counting an abandonment as a win would let someone farm ELO by
+     * walking away from a losing board.
+     *
+     * ADDITIVE and optional: absent while a bot is to move, after the game is over, and from any older
+     * relay. A client that ignores it is correct, just less kind — it simply sees the game end.
+     */
+    moveDeadlineMs?: number;
+}
+/**
+ * سباق — the race. Everyone runs the SAME questions, in the SAME order, privately, at their own speed.
+ *
+ * ⚠️ WHY THIS IS A RELAY GAME AND NOT A LOCAL ONE, in one sentence from the iOS desk: **timing cannot
+ * be client-reported or the player with the best connection wins.** Every advance is stamped by the
+ * server, the question set is dealt by the server, and a client never asks for a question — that last
+ * one is how two players would otherwise end up racing different sets.
+ *
+ * The rules, all the owner's:
+ *   1. same questions, same order, for every player — it is what makes «who finished first» mean anything
+ *   2. right on the first tap → FULL points
+ *   3. wrong → the player CHOOSES: try again for HALF, or move on. The cost of a retry is TIME, which
+ *      is why it needs no extra penalty and why the choice changes depending on whether you are ahead
+ *   4. wrong twice → 0 for that question, next question. ⚠️ TWO TIERS ONLY — full → half → gone is
+ *      something a child can hold; a third tier turns it into arithmetic. Do not add one.
+ *   5. finishing faster → BONUS points
+ *   6. 🔴 HIGHEST SCORE WINS. SPEED ADDS, IT NEVER OVERRIDES. A player who mashes through in 30
+ *      seconds finishes first and still loses — that is the intended outcome and it is load-bearing.
+ *   7. live standings visible during play
+ *   8. the host races too
+ *
+ * ⚠️ QUESTION COUNT IS NOT FIXED: it is the selected categories × 6 levels (owner, 2026-08-25 —
+ * «Questions are as players selected categories»). «3 categories» was his example, not the rule.
+ */
+interface SebaqStandingRow {
+    playerId: string;
+    /** How many questions this player has FINISHED (not the one they are on). */
+    done: number;
+    score: number;
+    /** Set only when they have finished the whole set — the bonus is not knowable before then. */
+    speedBonus?: number;
+    finished: boolean;
+}
+interface SebaqStateView {
+    /** Total questions in this race = categories × 6. Every player runs all of them. */
+    total: number;
+    /** Live standings for everyone, always visible (rule 7). Ordered by the server, best first. */
+    standings: SebaqStandingRow[];
+    /** Set when every racer has finished. Ties on total score break on base score, then on time. */
+    winnerId?: string | null;
+    /** ⚠️ YOUR question only, and only the one you are ON. Never another player's, never the next one —
+     *  a client that could see ahead could pre-read while others cannot, which is the whole race. */
+    you?: {
+        index: number;
+        /** ⚠️ The SAME anti-cheat boundary as trivia's: `correctAnswerIndex` is null while the question is
+         *  live and set only on reveal. In a race the temptation is stronger — every player holds a live
+         *  question at the same moment, so a leaked answer index is a leak to everyone at once. */
+        question: QuestionView;
+        /** true once you have answered wrong ONCE on this question: the half-or-skip choice is live. */
+        retryOffered: boolean;
+        score: number;
+        finished: boolean;
+    };
 }
 /**
  * The authoritative Ersimha round state. Anti-cheat boundary (D-030): `word` is set ONLY in the
@@ -1065,7 +1256,7 @@ type ServerMsg = {
     packs?: PackView[];
     selectedCategoryIds: string[];
     teams: TeamSlotView[];
-    hostActivity: 'configuring' | 'idle';
+    hostActivity: 'options' | 'configuring' | 'idle';
     tally?: {
         [playerId: string]: number;
     };
@@ -1087,6 +1278,12 @@ type ServerMsg = {
     view: DamaStateView;
     you: YouContext;
     roster?: RosterEntry[];
+} | {
+    t: 'sebaqState';
+    gameId: 'sebaq';
+    view: SebaqStateView;
+    you: YouContext;
+    roster?: RosterEntry[];
 } | {
     t: 'ersimhaState';
     gameId: 'ersimha';
@@ -1165,4 +1362,4 @@ interface MyQuestionRow {
     };
 }
 
-export { type AvatarView, type BuzzerGameMode, CHARACTER_IDS, type CategoryView, type CharacterId, ClientMsg, type DamaMoveView, type DamaPieceView, type DamaStateView, EMOTE_IDS, type Effect, type EmoteId, type ErsimhaStateView, GAMES, GAME_IDS, type GameId, type GameInfo, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MIN_SUPPORTED_PV, MODES, MODE_IDS, type ModeId, type ModeInfo, type MyQuestionRow, PROTOCOL_VERSION, type PackView, type QuestionView, REJECT_REASONS, ROOM_ALPHABET, type RejectReason, type RosterEntry, SUBMISSION_KINDS, SUBMISSION_STATUSES, type ServerMsg, type SoundName, type StrokePointView, type SubmissionKind, type SubmissionStatus, type TeamSlotView, type TeamView, type YouContext, gameIdForPv, gamesForPv, modesForGame, normalizeWesternDigits, sanitizeName };
+export { type AvatarView, type BuzzerGameMode, CHARACTER_IDS, COMEBACK_BONUS_MIN_PV, COMEBACK_EFFECTS, type CategoryView, type CharacterId, ClientMsg, type DamaMoveView, type DamaPieceView, type DamaStateView, EMOTE_IDS, type Effect, type EmoteId, type ErsimhaStateView, GAMES, GAME_IDS, type GameId, type GameInfo, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MIN_SUPPORTED_PV, MODES, MODE_IDS, type ModeId, type ModeInfo, type MyQuestionRow, PROTOCOL_VERSION, type PackView, type QuestionView, REJECT_REASONS, ROOM_ALPHABET, type RejectReason, type RosterEntry, SUBMISSION_KINDS, SUBMISSION_STATUSES, type SebaqStandingRow, type SebaqStateView, type ServerMsg, type SoundName, type StrokePointView, type SubmissionKind, type SubmissionStatus, type TeamSlotView, type TeamView, type YouContext, effectsForPv, gameIdForPv, gamesForPv, hostActivityForPv, modesForGame, normalizeWesternDigits, sanitizeName };

package/dist/index.js

@@ -9,9 +9,9 @@ var LIMITS = {
    *  Clients batch pen points to stay under this — ~150ms batching lands at ~7/sec. */
   STROKE_BATCH_PER_SEC: 20
 };
-var PROTOCOL_VERSION = 4;
+var PROTOCOL_VERSION = 7;
 var MIN_SUPPORTED_PV = 1;
-var GAME_IDS = ["seedha", "snag", "trivia", "dama", "ersimha"];
+var GAME_IDS = ["seedha", "snag", "trivia", "dama", "ersimha", "sebaq"];
 var GAMES = [
   { id: "seedha", label: "Seedha", minPv: 2 },
   { id: "snag", label: "Snag", minPv: 2 },
@@ -19,8 +19,31 @@ var GAMES = [
   // engine #2 (D-027) — offered only to pv≥3 clients
   { id: "ersimha", label: "Ersimha", minPv: 4 },
   // engine #3 (D-030) draw-and-guess — offered only to pv≥4 clients
+  // ⚠️ A NEW GAME, NOT A MODE OF SNAG, AND THE NAME COLLISION IS WHY IT HAD TO BE. `buzzerMode: 'race'`
+  // ALREADY MEANS ديوانية's buzz-race — everyone racing to buzz for ONE shared question. Sebaq is the
+  // opposite: no shared question, no buzzer, no turns. Every player runs the same set privately, at
+  // their own speed. Putting a mode called `race` beside a buzzerMode called `race`, meaning opposite
+  // things, one string apart on the wire, is the worst naming available here.
+  //
+  // It is also the wrong SHAPE for a mode: every MODES row is a way of playing seedha's turn loop —
+  // one question, one board, a shared clock. Sebaq uses none of it. A mode that shares no mechanic
+  // with its game is a game.
+  //
+  // ✅ NAME RULED BY THE OWNER, 2026-08-25: «سباق sebaq». Renamed from the provisional `sabag` before
+  // any client had shipped the string — which was the entire reason for saying it was provisional.
+  //
+  // ⚠️ `q` IS ق, AND IT IS NOT AN EXCEPTION TO THE BRAND RULE — I filed it as one and the owner
+  // corrected me. `CLAUDE.md`'s «Najdi ق = g» is about how ق SOUNDS in قييم; `q` is what the LETTER
+  // is. Two different questions, and `sebaq` answers the second. **Do not "fix" this to `sebag`.**
+  { id: "sebaq", label: "Sebaq", minPv: 5 },
+  // سباق — the race tile, offered only to pv≥5 clients
   { id: "trivia", label: "Trivia", minPv: 1, deprecated: true }
 ];
+var hostActivityForPv = (activity, pv) => activity === "options" && (pv ?? MIN_SUPPORTED_PV) < 6 ? "configuring" : activity;
+var COMEBACK_BONUS_MIN_PV = 7;
+var COMEBACK_EFFECTS = ["comebackOffer", "comebackBonus", "comebackDeclined"];
+var COMEBACK_EFFECT_SET = new Set(COMEBACK_EFFECTS);
+var effectsForPv = (effects, pv) => (pv ?? MIN_SUPPORTED_PV) >= COMEBACK_BONUS_MIN_PV ? effects : effects.filter((e) => !COMEBACK_EFFECT_SET.has(e.t));
 var gamesForPv = (pv) => GAMES.filter((g) => !g.deprecated && g.minPv <= pv);
 var gameIdForPv = (gameId, pv) => {
   const g = GAMES.find((x) => x.id === gameId);
@@ -55,6 +78,7 @@ var HelpType = z.enum([
 var Pv = z.number().int().min(1).max(1e6).optional();
 var IdToken = z.string().max(4096).optional();
 var Platform = z.enum(["web", "ios", "android", "tv"]).optional();
+var Games = z.array(z.enum(GAME_IDS)).max(GAME_IDS.length).optional();
 var AppVersion = z.string().trim().max(24).regex(/^[0-9]+(\.[0-9]+){0,3}([-+][0-9A-Za-z.-]+)?$/, "bad app version").optional();
 var Avatar = z.object({
   emoji: z.string().min(1).max(16).transform((s) => s.replace(UNSAFE_CHARS, "")).refine((s) => s.length >= 1, "empty emoji"),
@@ -63,7 +87,7 @@ var Avatar = z.object({
 var Character = z.enum(CHARACTER_IDS);
 var ClientMsg = z.discriminatedUnion("t", [
   // room / lobby
-  z.object({ t: z.literal("createRoom"), name: DisplayName.optional(), avatar: Avatar.optional(), game: z.enum(GAME_IDS).optional(), character: Character.optional(), pv: Pv, idToken: IdToken, platform: Platform, appVersion: AppVersion }),
+  z.object({ t: z.literal("createRoom"), name: DisplayName.optional(), avatar: Avatar.optional(), game: z.enum(GAME_IDS).optional(), character: Character.optional(), pv: Pv, idToken: IdToken, platform: Platform, games: Games, appVersion: AppVersion }),
   // Host sets/changes their display name AFTER createRoom (for anonymous one-tap
   // hosts who started nameless). Host-only; the relay re-broadcasts the lobby.
   // SUPERSEDED by setProfile (kept working for shipped builds).
@@ -77,8 +101,8 @@ var ClientMsg = z.discriminatedUnion("t", [
   // view carries names+avatars so it updates live; dama/ersimha views are id-keyed (clients
   // map ids→names from the lobby roster), so a change there lands on the next lobby.
   z.object({ t: z.literal("setProfile"), name: DisplayName.optional(), avatar: Avatar.optional(), character: Character.optional() }),
-  z.object({ t: z.literal("joinRoom"), code: RoomCode, name: DisplayName, avatar: Avatar.optional(), character: Character.optional(), pv: Pv, idToken: IdToken, platform: Platform, appVersion: AppVersion }),
-  z.object({ t: z.literal("resume"), code: RoomCode, token: z.string().max(120), avatar: Avatar.optional(), character: Character.optional(), pv: Pv, idToken: IdToken, platform: Platform, appVersion: AppVersion }),
+  z.object({ t: z.literal("joinRoom"), code: RoomCode, name: DisplayName, avatar: Avatar.optional(), character: Character.optional(), pv: Pv, idToken: IdToken, platform: Platform, games: Games, appVersion: AppVersion }),
+  z.object({ t: z.literal("resume"), code: RoomCode, token: z.string().max(120), avatar: Avatar.optional(), character: Character.optional(), pv: Pv, idToken: IdToken, platform: Platform, games: Games, appVersion: AppVersion }),
   // `tally` (gs#46) = wins per PLAYER across every game this room has played tonight — «نتيجة الليلة».
   // Keyed by playerId, NOT by team: team names are recycled each game, so a per-team count means nothing
   // across a night. Survives playAgain. A One Device game credits nobody (its team slots hold no players).
@@ -97,6 +121,42 @@ var ClientMsg = z.discriminatedUnion("t", [
   z.object({ t: z.literal("kick"), playerId: PlayerId }),
   // Host's IN-PROGRESS category selection in the lobby — a live preview for waiting
   // players. Distinct from startGame.categoryIds, which COMMITS the board. Empty = cleared.
+  // ⚠️ AN EMPTY `categoryIds` IS A MEANINGFUL MESSAGE — DO NOT ADD `.min(1)`.
+  //
+  // The host sends `setCategories([])` the moment they press «التالي», before picking anything.
+  //
+  // ⚠️ THE THREE-STATE READING RECORDED IN a33f305 IS NOT DELIVERABLE ON THIS WIRE, AND A CLIENT
+  // WRITTEN TO IT WILL BE «FIXED» IN THE WRONG DIRECTION. It said:
+  //     absent            → still in the lobby
+  //     present but EMPTY → the host is choosing
+  //     non-empty         → the picks card
+  // The first state does not exist. `socket.ts` creates every room with `selectedCategoryIds: []`
+  // and `rooms.ts` serialises it on EVERY lobby frame, so a joiner's very first frame already carries
+  // `[]` — byte-identical to the host having pressed «التالي». QA measured it on prod (room J7UY,
+  // raw frames in geem-qa `findings/sebaq/race2.jsonl`): the joiner's lobby before and after the
+  // host's empty `setCategories` differ in nothing on this field. On iOS the visible result is that
+  // joiners read «يختار الفئات» the moment they land. (geem-server#118.)
+  //
+  // ⚠️ `hostActivity` IS THE CARRIER FOR «THE HOST IS CHOOSING» — it is the field built for this exact
+  // question and it distinguishes the state this one cannot: `'options'` (the host is on the settings
+  // surface) vs `'configuring'` vs `'idle'`. Read THAT for the waiting-screen line; read
+  // `selectedCategoryIds` only for WHICH categories, never for WHETHER the host has begun.
+  //
+  // What stays true from a33f305, and is still worth its test: an empty array must PARSE. Adding
+  // `.min(1)` would reject a message the client is right to send.
+  //
+  // Without it, joiners sat on «ناطرين … يبدأ اللعبة» for as long as the host browsed and only learned
+  // anything had happened when the FIRST pick landed (owner, 2026-08-26; fixed by the iOS desk).
+  //
+  // ⚠️ THE FAILURE IF SOMEONE TIGHTENS THIS IS SILENT AND LOOKS LIKE A CLIENT BUG. Nothing crashes:
+  // every joiner in every category game just goes back to «waiting to start» until the first pick.
+  // The relay would be rejecting a message the client is right to send, and the search would start on
+  // the client. Applies to صيدها, بالدور and سباق alike — they share one lobby.
+  // The host's verdict on a comeback offer (owner ruling 2026-08-27). `grant: false` is a real and
+  // expected outcome — «if he refuse then he will not get it» — and closes the offer with nothing.
+  // ⚠️ HOST-ONLY, and the relay enforces it. A trailing team that could grant its own bonus is not a
+  // bonus, it is a button that says «+100».
+  z.object({ t: z.literal("comebackDecide"), grant: z.boolean() }),
   z.object({ t: z.literal("setCategories"), categoryIds: z.array(z.string().max(60)).max(12) }),
   // Host defines the lobby teams players can join (0–12; empty = disband back to the
   // one-team-per-player default). Resets picks that fall out of range.
@@ -113,10 +173,32 @@ var ClientMsg = z.discriminatedUnion("t", [
   // `modeId` alone still works (pre-gs#49 clients); `game` is what lets a host announce a tile with
   // no modes (dama/ersimha), which `modeId` could never express. An incoherent pair (a mode that
   // doesn't belong to the game) is rejected with `bad_mode` rather than silently resolved.
+  // ── Sebaq slice (gameId 'sebaq', the RACE tile) ──
+  // ⚠️ THE SERVER JUDGES AND THE SERVER TIMES. The client sends which option was tapped and nothing
+  // else — no «correct», no elapsed ms. A client-reported time makes the best connection win, and a
+  // client-reported verdict makes the race unwinnable honestly.
+  z.object({ t: z.literal("sebaqAnswer"), optionIndex: z.number().int().min(0).max(5) }),
+  // Rule 3: after ONE wrong answer the player chooses. `sebaqRetry` re-opens the SAME question for
+  // half points; `sebaqSkip` takes 0 and moves on. Two tiers only (rule 4) — a second wrong answer
+  // needs no message, it just ends the question.
+  z.object({ t: z.literal("sebaqRetry") }),
+  z.object({ t: z.literal("sebaqSkip") }),
   z.object({ t: z.literal("setMode"), game: z.enum(GAME_IDS).optional(), modeId: z.enum(MODE_IDS).optional() }),
   // Host signals it's busy configuring the game (categories/rounds/mode) so waiting players can show
   // a "host is setting up…" state instead of a frozen-looking lobby. 'idle' when the settings close.
-  z.object({ t: z.literal("hostActivity"), activity: z.enum(["configuring", "idle"]) }),
+  // ⚠️ THREE VALUES SINCE 2026-08-26 (Options page, geem-coordination#24). The host's pre-game
+  // journey is Lobby → Options → Categories, and joiners route on this:
+  //     idle        → the lobby
+  //     options     → «how we play» — the per-game settings page, read-only for joiners
+  //     configuring → «… يختار الفئات» — the category picker
+  //
+  // ⚠️ THE RELAY MUST ACCEPT `options` BEFORE ANY CLIENT SENDS IT, which is why this ships ahead of
+  // the page: a new client sending it to an old relay is a `bad_message`, the activity stays whatever
+  // it was, and every joiner shows the wrong banner with nothing erroring.
+  z.object({ t: z.literal("hostActivity"), activity: z.enum(["options", "configuring", "idle"]) }),
+  // ⚠️ AND IT IS ADAPTED ON THE WAY OUT (D-025), which is what makes it shippable without a
+  // coordinated release. `hostActivityForPv` below down-maps `options` → `configuring` for any client
+  // below pv6 — see there for the failure it prevents.
   // host game actions
   z.object({
     t: z.literal("startGame"),
@@ -234,6 +316,8 @@ var SUBMISSION_KINDS = ["new", "edit"];
 var REJECT_REASONS = ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
 export {
   CHARACTER_IDS,
+  COMEBACK_BONUS_MIN_PV,
+  COMEBACK_EFFECTS,
   ClientMsg,
   EMOTE_IDS,
   GAMES,
@@ -247,8 +331,10 @@ export {
   ROOM_ALPHABET,
   SUBMISSION_KINDS,
   SUBMISSION_STATUSES,
+  effectsForPv,
   gameIdForPv,
   gamesForPv,
+  hostActivityForPv,
   modesForGame,
   normalizeWesternDigits,
   sanitizeName

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thegeem/protocol",
-  "version": "0.1.38",
+  "version": "0.1.41",
   "description": "Geem's wire protocol — shared zod schemas + TypeScript types for talking to the Geem game server over Socket.IO. The source of truth all clients implement against.",
   "license": "UNLICENSED",
   "homepage": "https://geem.tv",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "copy-rules.json"
   ],
   "publishConfig": {
     "access": "public"