@thegeem/protocol 0.1.37 → 0.1.40

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