@thegeem/protocol 0.1.9 → 0.1.10

package/dist/index.cjs

@@ -23,8 +23,11 @@ __export(index_exports, {
   ClientMsg: () => ClientMsg,
   GAME_IDS: () => GAME_IDS,
   LIMITS: () => LIMITS,
+  MODES: () => MODES,
+  MODE_IDS: () => MODE_IDS,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
-  ROOM_ALPHABET: () => ROOM_ALPHABET
+  ROOM_ALPHABET: () => ROOM_ALPHABET,
+  modesForGame: () => modesForGame
 });
 module.exports = __toCommonJS(index_exports);
 var import_zod = require("zod");
@@ -36,6 +39,14 @@ var LIMITS = {
 };
 var PROTOCOL_VERSION = 1;
 var GAME_IDS = ["trivia"];
+var MODE_IDS = ["solo", "oneDevice", "snag", "multiplayer"];
+var MODES = [
+  { id: "solo", gameId: "trivia", label: "Solo", onlineEligible: false },
+  { id: "oneDevice", gameId: "trivia", label: "One Device", onlineEligible: false },
+  { id: "snag", gameId: "trivia", label: "Snag", onlineEligible: true },
+  { id: "multiplayer", gameId: "trivia", label: "Multiplayer", onlineEligible: true }
+];
+var modesForGame = (gameId) => MODES.filter((m) => m.gameId === gameId);
 var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 var UNSAFE_CHARS = /[\p{Cc}<>]/gu;
 var DisplayName = import_zod.z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => s.replace(UNSAFE_CHARS, "").trim()).refine((s) => s.length >= 1, "name is empty after sanitizing");
@@ -85,6 +96,10 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
     // which game to play; defaults to 'trivia'
     totalRounds: import_zod.z.number().int().min(1).max(50),
     categoryIds: import_zod.z.array(import_zod.z.string().max(60)).min(1).max(12),
+    // PREFERRED: pick a mode from the registry (see MODES). The server maps it to the engine
+    // rules. Send this and omit buzzerMode/noHost. Falls back to the legacy flags below if omitted.
+    modeId: import_zod.z.enum(MODE_IDS).optional(),
+    // LEGACY (pre-modeId clients) — the raw engine flags. Ignored when modeId is present.
     // How to play (maps to the engine). Omit → controller (each player answers from
     // their own device). 'off' = one device drives (Me-Controller); pair with noHost.
     //   solo=Solo · race=Snag/buzz · controller=each-player-from-device · off=Me-Controller
@@ -120,6 +135,9 @@ var ClientMsg = import_zod.z.discriminatedUnion("t", [
   ClientMsg,
   GAME_IDS,
   LIMITS,
+  MODES,
+  MODE_IDS,
   PROTOCOL_VERSION,
-  ROOM_ALPHABET
+  ROOM_ALPHABET,
+  modesForGame
 });

package/dist/index.d.cts

@@ -37,6 +37,26 @@ declare const PROTOCOL_VERSION = 1;
  */
 declare const GAME_IDS: readonly ["trivia"];
 type GameId = (typeof GAME_IDS)[number];
+/**
+ * The MODE REGISTRY — the list of ways to play each game. A client renders its mode picker from this
+ * and sends the chosen `modeId` on `startGame`; the SERVER owns the modeId → engine-rules mapping (the
+ * flags are an internal relay detail, not the client's job). Adding a mode = one entry here. Game #2
+ * gets its own `gameId` rows. `label` is a short English label — clients may localize by `id` (Arabic
+ * UI is Kuwaiti). `onlineEligible` = a finished game in this mode counts toward the global leaderboard
+ * (only server-arbitrated, multi-device modes; single-device/solo are local-only — the host controls
+ * input, so the server can't trust the score).
+ */
+declare const MODE_IDS: readonly ["solo", "oneDevice", "snag", "multiplayer"];
+type ModeId = (typeof MODE_IDS)[number];
+interface ModeInfo {
+    id: ModeId;
+    gameId: GameId;
+    label: string;
+    onlineEligible: boolean;
+}
+declare const MODES: readonly ModeInfo[];
+/** The modes available for a given game (for a client's mode picker). */
+declare const modesForGame: (gameId: GameId) => ModeInfo[];
 /** Unambiguous room-code alphabet — no 0/O, 1/I/L. */
 declare const ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 declare const HelpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
@@ -228,6 +248,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     game: z.ZodOptional<z.ZodEnum<["trivia"]>>;
     totalRounds: z.ZodNumber;
     categoryIds: z.ZodArray<z.ZodString, "many">;
+    modeId: z.ZodOptional<z.ZodEnum<["solo", "oneDevice", "snag", "multiplayer"]>>;
     buzzerMode: z.ZodOptional<z.ZodEnum<["off", "solo", "race", "controller"]>>;
     noHost: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
@@ -235,14 +256,16 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     categoryIds: string[];
     totalRounds: number;
     game?: "trivia" | undefined;
-    buzzerMode?: "off" | "solo" | "race" | "controller" | undefined;
+    modeId?: "solo" | "oneDevice" | "snag" | "multiplayer" | undefined;
+    buzzerMode?: "solo" | "off" | "race" | "controller" | undefined;
     noHost?: boolean | undefined;
 }, {
     t: "startGame";
     categoryIds: string[];
     totalRounds: number;
     game?: "trivia" | undefined;
-    buzzerMode?: "off" | "solo" | "race" | "controller" | undefined;
+    modeId?: "solo" | "oneDevice" | "snag" | "multiplayer" | undefined;
+    buzzerMode?: "solo" | "off" | "race" | "controller" | undefined;
     noHost?: boolean | undefined;
 }>, z.ZodObject<{
     t: z.ZodLiteral<"pickLevel">;
@@ -549,4 +572,4 @@ type ServerMsg = {
     message: string;
 };
 
-export { type AvatarView, type BuzzerGameMode, type CategoryView, ClientMsg, type Effect, GAME_IDS, type GameId, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, PROTOCOL_VERSION, type QuestionView, ROOM_ALPHABET, type ServerMsg, type SoundName, type TeamSlotView, type TeamView, type YouContext };
+export { type AvatarView, type BuzzerGameMode, type CategoryView, ClientMsg, type Effect, GAME_IDS, type GameId, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MODES, MODE_IDS, type ModeId, type ModeInfo, PROTOCOL_VERSION, type QuestionView, ROOM_ALPHABET, type ServerMsg, type SoundName, type TeamSlotView, type TeamView, type YouContext, modesForGame };

package/dist/index.d.ts

@@ -37,6 +37,26 @@ declare const PROTOCOL_VERSION = 1;
  */
 declare const GAME_IDS: readonly ["trivia"];
 type GameId = (typeof GAME_IDS)[number];
+/**
+ * The MODE REGISTRY — the list of ways to play each game. A client renders its mode picker from this
+ * and sends the chosen `modeId` on `startGame`; the SERVER owns the modeId → engine-rules mapping (the
+ * flags are an internal relay detail, not the client's job). Adding a mode = one entry here. Game #2
+ * gets its own `gameId` rows. `label` is a short English label — clients may localize by `id` (Arabic
+ * UI is Kuwaiti). `onlineEligible` = a finished game in this mode counts toward the global leaderboard
+ * (only server-arbitrated, multi-device modes; single-device/solo are local-only — the host controls
+ * input, so the server can't trust the score).
+ */
+declare const MODE_IDS: readonly ["solo", "oneDevice", "snag", "multiplayer"];
+type ModeId = (typeof MODE_IDS)[number];
+interface ModeInfo {
+    id: ModeId;
+    gameId: GameId;
+    label: string;
+    onlineEligible: boolean;
+}
+declare const MODES: readonly ModeInfo[];
+/** The modes available for a given game (for a client's mode picker). */
+declare const modesForGame: (gameId: GameId) => ModeInfo[];
 /** Unambiguous room-code alphabet — no 0/O, 1/I/L. */
 declare const ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 declare const HelpType: z.ZodEnum<["removeTwoAnswers", "changeQuestion", "extraTime", "doublePoints", "stealPoints", "restPlayer", "tripLevel"]>;
@@ -228,6 +248,7 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     game: z.ZodOptional<z.ZodEnum<["trivia"]>>;
     totalRounds: z.ZodNumber;
     categoryIds: z.ZodArray<z.ZodString, "many">;
+    modeId: z.ZodOptional<z.ZodEnum<["solo", "oneDevice", "snag", "multiplayer"]>>;
     buzzerMode: z.ZodOptional<z.ZodEnum<["off", "solo", "race", "controller"]>>;
     noHost: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
@@ -235,14 +256,16 @@ declare const ClientMsg: z.ZodDiscriminatedUnion<"t", [z.ZodObject<{
     categoryIds: string[];
     totalRounds: number;
     game?: "trivia" | undefined;
-    buzzerMode?: "off" | "solo" | "race" | "controller" | undefined;
+    modeId?: "solo" | "oneDevice" | "snag" | "multiplayer" | undefined;
+    buzzerMode?: "solo" | "off" | "race" | "controller" | undefined;
     noHost?: boolean | undefined;
 }, {
     t: "startGame";
     categoryIds: string[];
     totalRounds: number;
     game?: "trivia" | undefined;
-    buzzerMode?: "off" | "solo" | "race" | "controller" | undefined;
+    modeId?: "solo" | "oneDevice" | "snag" | "multiplayer" | undefined;
+    buzzerMode?: "solo" | "off" | "race" | "controller" | undefined;
     noHost?: boolean | undefined;
 }>, z.ZodObject<{
     t: z.ZodLiteral<"pickLevel">;
@@ -549,4 +572,4 @@ type ServerMsg = {
     message: string;
 };
 
-export { type AvatarView, type BuzzerGameMode, type CategoryView, ClientMsg, type Effect, GAME_IDS, type GameId, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, PROTOCOL_VERSION, type QuestionView, ROOM_ALPHABET, type ServerMsg, type SoundName, type TeamSlotView, type TeamView, type YouContext };
+export { type AvatarView, type BuzzerGameMode, type CategoryView, ClientMsg, type Effect, GAME_IDS, type GameId, type GameStateView, type GameStatus, type GameplayFlow, type HelpName, LIMITS, type LobbyPlayer, MODES, MODE_IDS, type ModeId, type ModeInfo, PROTOCOL_VERSION, type QuestionView, ROOM_ALPHABET, type ServerMsg, type SoundName, type TeamSlotView, type TeamView, type YouContext, modesForGame };

package/dist/index.js

@@ -8,6 +8,14 @@ var LIMITS = {
 };
 var PROTOCOL_VERSION = 1;
 var GAME_IDS = ["trivia"];
+var MODE_IDS = ["solo", "oneDevice", "snag", "multiplayer"];
+var MODES = [
+  { id: "solo", gameId: "trivia", label: "Solo", onlineEligible: false },
+  { id: "oneDevice", gameId: "trivia", label: "One Device", onlineEligible: false },
+  { id: "snag", gameId: "trivia", label: "Snag", onlineEligible: true },
+  { id: "multiplayer", gameId: "trivia", label: "Multiplayer", onlineEligible: true }
+];
+var modesForGame = (gameId) => MODES.filter((m) => m.gameId === gameId);
 var ROOM_ALPHABET = "ACDEFGHJKMNPQRTUVWXY2346789";
 var UNSAFE_CHARS = /[\p{Cc}<>]/gu;
 var DisplayName = z.string().trim().min(1).max(LIMITS.MAX_NAME_LEN).transform((s) => s.replace(UNSAFE_CHARS, "").trim()).refine((s) => s.length >= 1, "name is empty after sanitizing");
@@ -57,6 +65,10 @@ var ClientMsg = z.discriminatedUnion("t", [
     // which game to play; defaults to 'trivia'
     totalRounds: z.number().int().min(1).max(50),
     categoryIds: z.array(z.string().max(60)).min(1).max(12),
+    // PREFERRED: pick a mode from the registry (see MODES). The server maps it to the engine
+    // rules. Send this and omit buzzerMode/noHost. Falls back to the legacy flags below if omitted.
+    modeId: z.enum(MODE_IDS).optional(),
+    // LEGACY (pre-modeId clients) — the raw engine flags. Ignored when modeId is present.
     // How to play (maps to the engine). Omit → controller (each player answers from
     // their own device). 'off' = one device drives (Me-Controller); pair with noHost.
     //   solo=Solo · race=Snag/buzz · controller=each-player-from-device · off=Me-Controller
@@ -91,6 +103,9 @@ export {
   ClientMsg,
   GAME_IDS,
   LIMITS,
+  MODES,
+  MODE_IDS,
   PROTOCOL_VERSION,
-  ROOM_ALPHABET
+  ROOM_ALPHABET,
+  modesForGame
 };

package/package.json

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