@thegeem/protocol 0.1.38 → 0.1.41

package/dist/index.d.cts

@@ -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 };