@thegeem/protocol 0.1.37 → 0.1.40

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,43 @@ 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;
+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;
@@ -112,6 +149,14 @@ declare const ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
  * Letters are never touched; this maps exactly twenty codepoints.
  */
 declare const normalizeWesternDigits: (s: string) => string;
+/**
+ * THE definition of "a safe player-supplied string": strip the unsafe class, normalise digits.
+ * Exported because it was being hand-copied — the relay's HTTP gates (account PATCH, question
+ * submissions) each grew their own copy of this exact body, and one of those copies stored the
+ * bidi characters LITERALLY in source, where any formatter or copy-paste could silently change
+ * what it matches. A rule that can be edited by accident is not a rule.
+ */
+declare const sanitizeName: (s: string) => string;
 declare const HelpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
 declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     t: z.ZodLiteral<"createRoom">;
@@ -126,7 +171,7 @@ 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>;
@@ -139,7 +184,7 @@ 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;
@@ -152,7 +197,7 @@ 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;
@@ -332,6 +377,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">;
@@ -359,30 +413,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>;
@@ -401,7 +476,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;
@@ -414,7 +489,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;
@@ -833,6 +908,20 @@ interface TeamView {
     avatar?: AvatarView;
 }
 interface QuestionView {
+    /** The category this question came from (gs#94 follow-up, geem-site#54). NOT reveal-gated: the
+     *  category is already on the board tile the player picked, so it gives nothing away — unlike the
+     *  id, which is a handle into the bank. It exists so «اقترح سؤال مشابه» can preset the category
+     *  instead of asking the player to re-pick it; without it a client either asks again or INFERS one,
+     *  and inferring files somebody's question under the wrong category. Optional: pre-gs#94 servers
+     *  omit it and clients must cope. */
+    categoryId?: string;
+    /** The question's id — present ONLY once revealed (gs#90). It exists so a player can say «عدّل
+     *  السؤال» about a specific question: text is neither unique (template-shaped questions collide on
+     *  wording) nor stable, so an edit identified only by its text is not reliably applicable. Kept off
+     *  the wire while the question is LIVE for the same reason `correctAnswerIndex` is — the bank is
+     *  server-side and an id is a handle into it. Optional on the wire: shipped clients ignore it, and
+     *  a client that wants it must tolerate its absence pre-reveal. */
+    id?: string;
     text: string;
     options: string[];
     hiddenOptionIndices: number[];
@@ -840,6 +929,10 @@ interface QuestionView {
     selectedAnswerIndex: number | null;
     /** Only present once revealed (anti-cheat). Null while the question is live. */
     correctAnswerIndex: number | null;
+    /** «سؤال من: …» — community submitter credit (owner ruling 2026-08-14). Present ONLY on
+     *  questions promoted from community submissions; official questions never carry it. NOT
+     *  reveal-gated — a name leaks nothing — so place it wherever it reads best. */
+    submittedBy?: string;
     /** «معلومة» — optional explanation shown AFTER the reveal. Null while the question is live (it
      *  usually names the answer — same anti-cheat gate as correctAnswerIndex) and null when the
      *  question simply has none, which is most of the bank: render the card only when non-null. */
@@ -875,6 +968,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 = {
@@ -905,6 +1018,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';
 } | {
@@ -963,6 +1091,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
@@ -1039,7 +1234,7 @@ type ServerMsg = {
     packs?: PackView[];
     selectedCategoryIds: string[];
     teams: TeamSlotView[];
-    hostActivity: 'configuring' | 'idle';
+    hostActivity: 'options' | 'configuring' | 'idle';
     tally?: {
         [playerId: string]: number;
     };
@@ -1061,6 +1256,12 @@ type ServerMsg = {
     view: DamaStateView;
     you: YouContext;
     roster?: RosterEntry[];
+} | {
+    t: 'sebaqState';
+    gameId: 'sebaq';
+    view: SebaqStateView;
+    you: YouContext;
+    roster?: RosterEntry[];
 } | {
     t: 'ersimhaState';
     gameId: 'ersimha';
@@ -1103,5 +1304,40 @@ type ServerMsg = {
     message: string;
     reason?: string;
 };
+/** Review states for a community submission. ⚠️ `approved` is NOT here: it is a DEPRECATED alias
+ *  written by an older geem-admin, mapped to `accepted` by the relay and permitted by 0031's CHECK
+ *  only until that write is switched. It must never become a fourth state. */
+declare const SUBMISSION_STATUSES: readonly ["pending", "accepted", "rejected"];
+type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number];
+/** A brand-new question vs a correction to one already in the bank. */
+declare const SUBMISSION_KINDS: readonly ["new", "edit"];
+type SubmissionKind = (typeof SUBMISSION_KINDS)[number];
+/** Why a submission was turned down. Blame-free by construction — the closest to "you did badly" is
+ *  `duplicate`, which is about the BANK, not the writer. Clients translate these and must fall back
+ *  to `other` on anything unrecognised, which is exactly what makes adding a seventh survivable for a
+ *  build that shipped last month and will never be updated. */
+declare const REJECT_REASONS: readonly ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
+type RejectReason = (typeof REJECT_REASONS)[number];
+/** One row of «أسئلتي». Exists as a named type so the native generator EMITS the three unions above
+ *  — quicktype only reaches what a root references, and hand-typed constants are the whole bug. */
+interface MyQuestionRow {
+    id: string;
+    status: SubmissionStatus;
+    kind: SubmissionKind;
+    text: string;
+    options: string[];
+    correctIndex: number;
+    explain: string | null;
+    createdAt: string;
+    accepted?: {
+        plays: number;
+        firstPlayedAt: string | null;
+        coins: number;
+    };
+    rejected?: {
+        reason: RejectReason;
+        canResubmit: boolean;
+    };
+}
 
-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, PROTOCOL_VERSION, type PackView, type QuestionView, ROOM_ALPHABET, type RosterEntry, type ServerMsg, type SoundName, type StrokePointView, type TeamSlotView, type TeamView, type YouContext, gameIdForPv, gamesForPv, modesForGame, normalizeWesternDigits };
+export { type AvatarView, type BuzzerGameMode, CHARACTER_IDS, COMEBACK_BONUS_MIN_PV, 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,30 @@ 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 = /* @__PURE__ */ new Set(["comebackBonus", "comebackOffer", "comebackDeclined"]);
+var effectsForPv = (effects, pv) => (pv ?? MIN_SUPPORTED_PV) >= COMEBACK_BONUS_MIN_PV ? effects : effects.filter((e) => !COMEBACK_EFFECTS.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);
@@ -39,7 +61,8 @@ var CHARACTER_IDS = ["m", "f"];
 var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 var UNSAFE_CHARS = /[\p{Cc}\u202A-\u202E\u2066-\u2069<>]/gu;
 var normalizeWesternDigits = (s) => s.replace(/[٠-٩۰-۹]/g, (d) => String("\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) >= 0 ? "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669".indexOf(d) : "\u06F0\u06F1\u06F2\u06F3\u06F4\u06F5\u06F6\u06F7\u06F8\u06F9".indexOf(d)));
-var DisplayName = z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim()).refine((s) => s.length >= 1, "name is empty after sanitizing");
+var sanitizeName = (s) => normalizeWesternDigits(s.replace(UNSAFE_CHARS, "")).trim();
+var DisplayName = z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform(sanitizeName).refine((s) => s.length >= 1, "name is empty after sanitizing");
 var RoomCode = z.string().trim().toUpperCase().regex(new RegExp(`^[${ROOM_ALPHABET}]{${LIMITS.ROOM_CODE_LEN}}$`), "bad room code");
 var PlayerId = z.string().max(40);
 var HelpType = z.enum([
@@ -96,6 +119,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.
@@ -112,10 +171,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"),
@@ -228,8 +309,12 @@ var ClientMsg = z.discriminatedUnion("t", [
   // Drawer passes on the served word (capped per draw-turn; relay serves a fresh one).
   z.object({ t: z.literal("skipWord") })
 ]);
+var SUBMISSION_STATUSES = ["pending", "accepted", "rejected"];
+var SUBMISSION_KINDS = ["new", "edit"];
+var REJECT_REASONS = ["duplicate", "unclear_answer", "not_family", "inaccurate", "too_narrow", "other"];
 export {
   CHARACTER_IDS,
+  COMEBACK_BONUS_MIN_PV,
   ClientMsg,
   EMOTE_IDS,
   GAMES,
@@ -239,9 +324,15 @@ export {
   MODES,
   MODE_IDS,
   PROTOCOL_VERSION,
+  REJECT_REASONS,
   ROOM_ALPHABET,
+  SUBMISSION_KINDS,
+  SUBMISSION_STATUSES,
+  effectsForPv,
   gameIdForPv,
   gamesForPv,
+  hostActivityForPv,
   modesForGame,
-  normalizeWesternDigits
+  normalizeWesternDigits,
+  sanitizeName
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thegeem/protocol",
-  "version": "0.1.37",
+  "version": "0.1.40",
   "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"