@orakl/protocol 0.1.0

package/dist/badges.js

@@ -0,0 +1 @@
+export {};

package/dist/emotes.d.ts

@@ -0,0 +1,5 @@
+export declare const EMOTE_SPRITES: Record<string, {
+    x: number;
+    y: number;
+}>;
+export declare const SELECTABLE_EMOTE_IDS: readonly ["alert", "anger", "bars", "cash", "circle", "cloud", "cross", "dots1", "dots2", "dots3", "drop", "drops", "exclamation", "exclamations", "faceAngry", "faceHappy", "faceSad", "heart", "heartBroken", "hearts", "idea", "laugh", "music", "question", "sleep", "sleeps", "star", "stars", "swirl"];

package/dist/emotes.js

@@ -0,0 +1,62 @@
+export const EMOTE_SPRITES = {
+    alert: { x: 64, y: 64 },
+    anger: { x: 64, y: 48 },
+    bars: { x: 64, y: 32 },
+    cash: { x: 64, y: 16 },
+    circle: { x: 64, y: 0 },
+    cloud: { x: 48, y: 80 },
+    cross: { x: 48, y: 64 },
+    dots1: { x: 48, y: 48 },
+    dots2: { x: 48, y: 32 },
+    dots3: { x: 48, y: 16 },
+    drop: { x: 48, y: 0 },
+    drops: { x: 32, y: 80 },
+    exclamation: { x: 32, y: 64 },
+    exclamations: { x: 32, y: 48 },
+    faceAngry: { x: 64, y: 80 },
+    faceHappy: { x: 32, y: 16 },
+    faceSad: { x: 32, y: 0 },
+    heart: { x: 16, y: 80 },
+    heartBroken: { x: 16, y: 64 },
+    hearts: { x: 16, y: 48 },
+    idea: { x: 16, y: 32 },
+    laugh: { x: 16, y: 16 },
+    music: { x: 16, y: 0 },
+    question: { x: 0, y: 80 },
+    sleep: { x: 0, y: 64 },
+    sleeps: { x: 0, y: 48 },
+    star: { x: 0, y: 32 },
+    stars: { x: 0, y: 16 },
+    swirl: { x: 0, y: 0 },
+};
+export const SELECTABLE_EMOTE_IDS = [
+    "alert",
+    "anger",
+    "bars",
+    "cash",
+    "circle",
+    "cloud",
+    "cross",
+    "dots1",
+    "dots2",
+    "dots3",
+    "drop",
+    "drops",
+    "exclamation",
+    "exclamations",
+    "faceAngry",
+    "faceHappy",
+    "faceSad",
+    "heart",
+    "heartBroken",
+    "hearts",
+    "idea",
+    "laugh",
+    "music",
+    "question",
+    "sleep",
+    "sleeps",
+    "star",
+    "stars",
+    "swirl",
+];

package/dist/error-codes.d.ts

@@ -0,0 +1 @@
+export type ErrorCode = "no_active_lobby" | "no_active_game" | "device_blocked" | "nickname_taken" | "device_in_lobby" | "player_not_found" | "player_not_pending" | "intermission_invalid_phase" | "not_in_intermission" | "category_name_exists" | "category_not_found" | "category_has_questions" | "user_not_found" | "curation_request_pending" | "curator_self_join" | "already_flagged" | "question_not_found" | "invalid_answer" | "game_in_progress" | "already_answered" | "observer_forbidden" | "no_questions" | "no_categories" | "too_few_players" | "hosting_closed" | "not_answered" | "flag_not_toggleable" | "solo_invalid_phase" | "solo_invalid_answer" | "solo_nonce_mismatch" | "solo_answer_expired" | "solo_guest_limit" | "solo_no_questions" | "solo_resume_denied" | "solo_auth_failed";

package/dist/error-codes.js

@@ -0,0 +1 @@
+export {};

package/dist/game-answer-record.d.ts

@@ -0,0 +1,31 @@
+import type { MediaType, QuestionSource } from "./question.schema.ts";
+/**
+ * One round in a player's multiplayer answer log. Misses recorded during the
+ * player's hero tenure (timeout, disconnect, quit) appear with isCorrect=false
+ * and the full clock as timeToAnswerMs. Persisted as game_results.question_breakdown.
+ */
+export interface GameAnswerRecord {
+    questionIndex: number;
+    categoryId: string;
+    difficulty?: "easy" | "medium" | "hard";
+    isCorrect: boolean;
+    timeToAnswerMs: number;
+    /** Full-fidelity fields (ADR 0020) — optional, absent on rows written before this. */
+    questionId?: string;
+    questionText?: string;
+    selectedAnswerId?: string;
+    selectedAnswerText?: string;
+    correctAnswerId?: string;
+    correctAnswerText?: string;
+    /** Snapshotted at play time — a later edit to the question does not
+     *  change what a finished game shows (map #912). Absent on rows written
+     *  before this. `mediaUrl` holds whatever form the question carried when
+     *  the round was played: a signed `/media/<key>` path for a bucket object,
+     *  since questions reach the wire already signed, or a curator's pasted
+     *  external URL. Either way its signature has long expired by the time a
+     *  game is reviewed, so a reader re-signs it (see `resignBreakdown`). */
+    mediaUrl?: string;
+    mediaType?: MediaType;
+    source?: QuestionSource;
+    postAnswerNote?: string;
+}

package/dist/game-answer-record.js

@@ -0,0 +1 @@
+export {};

package/dist/game.d.ts

@@ -0,0 +1,83 @@
+import type { AdvanceMode, Difficulty, TimerDuration } from "./game.settings.ts";
+import type { MediaType, QuestionSource, QuestionType } from "./question.schema.ts";
+export type { AdvanceMode, Difficulty, TimerDuration, } from "./game.settings.ts";
+export type PlayerRole = "player" | "observer";
+export type PlayerStatus = "pending" | "active" | "disconnected";
+export type AccessMode = "open" | "invite-only";
+export type GamePhase = "lobby" | "playing" | "round_results" | "final_scores" | "role_selection" | "intermission";
+export type ActiveGamePhase = Exclude<GamePhase, "lobby">;
+export interface QuizConfig {
+    name: string;
+    description?: string;
+    categoryIds: string[];
+    timerDuration: TimerDuration;
+    questionsPerRound: number;
+    difficulty?: Difficulty;
+    advanceMode?: AdvanceMode;
+}
+export interface Player {
+    id: string;
+    nickname: string;
+    avatar: string;
+    score: number;
+    ready: boolean;
+    status: PlayerStatus;
+    role: PlayerRole;
+    deviceId?: string;
+    /** True only for the curator's own player row (playing curator, ADR 0019).
+     *  Fresh-UUID row id, never the curator's token/user id — see game-store.ts
+     *  joinAsCurator. Omitted (not false) for every other player. */
+    isCurator?: true;
+    /**
+     * Real `users.id` this row is linked to, when known — the ONE mechanism a
+     * row ends up with a genuine account link (question-flagging precheck,
+     * ADR 0020 follow-up). Set at join time only when the browser held a
+     * genuine account session (captured in POST /api/lobby/join, before the
+     * response overwrites the cookie with a rowless per-lobby player token —
+     * see that route's doc comment), or for the curator's own row via
+     * joinAsCurator (mirrors `lobby.curatorUserId`). Never trust `role` alone
+     * for "has an account" — a joined player's token role is always "member"
+     * regardless of whether they have one. Omitted (not null) when absent —
+     * never sent over the wire (see serializers.ts's toPublicPlayer allowlist). */
+    accountUserId?: string;
+}
+export interface QuizAnswer {
+    id: string;
+    text: string;
+    isCorrect: boolean;
+}
+interface BaseQuizQuestion {
+    id: string;
+    text: string;
+    categoryId: string;
+    difficulty: Difficulty;
+    answers: QuizAnswer[];
+    mediaUrl?: string;
+    mediaType?: MediaType;
+    /** Carried only so `toPlayerSafeQuestion` can strip it — never sent on the
+     *  wire during a game (map #912, decision 2). */
+    source?: QuestionSource;
+    /** Carried only so `toPlayerSafeQuestion` can strip it from `game:question`;
+     *  reaches the client separately in `game:round-result` at reveal. */
+    postAnswerNote?: string;
+}
+export interface StandardQuizQuestion extends BaseQuizQuestion {
+    type: Exclude<QuestionType, "image_matching">;
+}
+export interface ImageMatchingQuizQuestion extends BaseQuizQuestion {
+    type: "image_matching";
+    matchItems: {
+        left: string[];
+        right: string[];
+    };
+}
+export type QuizQuestion = StandardQuizQuestion | ImageMatchingQuizQuestion;
+export interface GameState {
+    phase: GamePhase;
+    config: QuizConfig;
+    players: Player[];
+    questions: QuizQuestion[];
+    currentQuestion: number;
+    totalQuestions: number;
+    timeRemaining: number;
+}

package/dist/game.js

@@ -0,0 +1 @@
+export {};

package/dist/game.settings.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Single source of truth for all game constants.
+ * Derive types from this file — do not duplicate values elsewhere.
+ */
+export declare const GAME: {
+    readonly roundConfig: {
+        readonly timerOptions: readonly [15, 30, 45, 60];
+        readonly questionCounts: readonly [10, 20, 50, 100];
+        readonly difficultyOptions: readonly ["all", "easy", "medium", "hard"];
+        readonly difficulties: readonly ["easy", "medium", "hard"];
+        readonly autoAdvanceMs: 5000;
+        readonly advanceModeOptions: readonly ["auto_5", "auto_10", "manual"];
+        readonly defaultAdvanceMode: "auto_5";
+        readonly autoAdvanceMsMap: {
+            readonly auto_5: 5000;
+            readonly auto_10: 10000;
+        };
+        readonly scoringOptions: readonly ["classic", "time-based"];
+        readonly defaultScoring: "classic";
+        readonly defaultQuestions: 10;
+        readonly defaultTimer: 30;
+    };
+    readonly endless: {
+        readonly lives: 3;
+    };
+    readonly streak: {
+        readonly steps: readonly [{
+            readonly threshold: 3;
+            readonly label: "Kindled!";
+            readonly tone: "ember";
+        }, {
+            readonly threshold: 5;
+            readonly label: "Ablaze!";
+            readonly tone: "spark";
+        }, {
+            readonly threshold: 10;
+            readonly label: "Inferno!";
+            readonly tone: "blaze";
+        }, {
+            readonly threshold: 15;
+            readonly label: "Rampage!";
+            readonly tone: "conflagration";
+        }, {
+            readonly threshold: 20;
+            readonly label: "Legendary!";
+            readonly tone: "inferno";
+        }, {
+            readonly threshold: 25;
+            readonly label: "We ran out of medals...";
+            readonly tone: "inferno";
+        }];
+        readonly losses: readonly [{
+            readonly threshold: 3;
+            readonly label: "Flame quenched.";
+        }, {
+            readonly threshold: 5;
+            readonly label: "Embers scattered.";
+        }, {
+            readonly threshold: 10;
+            readonly label: "The inferno falls silent.";
+        }, {
+            readonly threshold: 15;
+            readonly label: "Rampage broken.";
+        }, {
+            readonly threshold: 20;
+            readonly label: "Legend undone.";
+        }, {
+            readonly threshold: 25;
+            readonly label: "The oracle mourns.";
+        }];
+        readonly visibleAt: 2;
+    };
+    readonly question: {
+        readonly sources: readonly ["opentdb", "custom", "the-trivia-api"];
+    };
+    readonly roleSelection: {
+        readonly durationSeconds: 60;
+    };
+    readonly player: {
+        readonly maxNicknameLength: 20;
+    };
+    readonly sse: {
+        readonly keepaliveIntervalMs: 15000;
+    };
+};
+export type TimerDuration = (typeof GAME.roundConfig.timerOptions)[number];
+export type QuestionsPerRound = (typeof GAME.roundConfig.questionCounts)[number];
+export type DifficultyFilter = (typeof GAME.roundConfig.difficultyOptions)[number];
+export type Difficulty = Exclude<DifficultyFilter, "all">;
+export type AdvanceMode = (typeof GAME.roundConfig.advanceModeOptions)[number];
+export type ScoringMode = (typeof GAME.roundConfig.scoringOptions)[number];

package/dist/game.settings.js

@@ -0,0 +1,61 @@
+/**
+ * Single source of truth for all game constants.
+ * Derive types from this file — do not duplicate values elsewhere.
+ */
+export const GAME = {
+    roundConfig: {
+        timerOptions: [15, 30, 45, 60],
+        questionCounts: [10, 20, 50, 100],
+        difficultyOptions: ["all", "easy", "medium", "hard"],
+        difficulties: ["easy", "medium", "hard"],
+        autoAdvanceMs: 5000,
+        advanceModeOptions: ["auto_5", "auto_10", "manual"],
+        defaultAdvanceMode: "auto_5",
+        autoAdvanceMsMap: { auto_5: 5000, auto_10: 10000 },
+        // Scoring: "classic" = 1 point per correct answer; "time-based" = base +
+        // speed bonus (mirrors solo, see src/lib/scoring.ts).
+        scoringOptions: ["classic", "time-based"],
+        defaultScoring: "classic",
+        defaultQuestions: 10,
+        defaultTimer: 30,
+    },
+    endless: {
+        lives: 3,
+    },
+    streak: {
+        // Milestone flourish shown mid-round — extend/reorder here, nowhere else.
+        // tone keys map to the app's flame/flame-dark/flame-light/flame-lighter palette.
+        steps: [
+            { threshold: 3, label: "Kindled!", tone: "ember" },
+            { threshold: 5, label: "Ablaze!", tone: "spark" },
+            { threshold: 10, label: "Inferno!", tone: "blaze" },
+            { threshold: 15, label: "Rampage!", tone: "conflagration" },
+            { threshold: 20, label: "Legendary!", tone: "inferno" },
+            { threshold: 25, label: "We ran out of medals...", tone: "inferno" },
+        ],
+        // Loss flourish shown when a streak at/above threshold breaks. Mirrors the
+        // gain thresholds so a run always mourns the tier it fell from.
+        losses: [
+            { threshold: 3, label: "Flame quenched." },
+            { threshold: 5, label: "Embers scattered." },
+            { threshold: 10, label: "The inferno falls silent." },
+            { threshold: 15, label: "Rampage broken." },
+            { threshold: 20, label: "Legend undone." },
+            { threshold: 25, label: "The oracle mourns." },
+        ],
+        // Streak counter only earns screen space once it's genuinely building.
+        visibleAt: 2,
+    },
+    question: {
+        sources: ["opentdb", "custom", "the-trivia-api"],
+    },
+    roleSelection: {
+        durationSeconds: 60,
+    },
+    player: {
+        maxNicknameLength: 20,
+    },
+    sse: {
+        keepaliveIntervalMs: 15000,
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type { BadgeAward, BadgeId, BadgeMode, BadgeRunParams, } from "./badges.ts";
+export { EMOTE_SPRITES, SELECTABLE_EMOTE_IDS } from "./emotes.ts";
+export type { ErrorCode } from "./error-codes.ts";
+export { type AdvanceMode, type Difficulty, type DifficultyFilter, GAME, type QuestionsPerRound, type ScoringMode, type TimerDuration, } from "./game.settings.ts";
+export type { AccessMode, ActiveGamePhase, GamePhase, GameState, ImageMatchingQuizQuestion, Player, PlayerRole, PlayerStatus, QuizAnswer, QuizConfig, QuizQuestion, StandardQuizQuestion, } from "./game.ts";
+export type { GameAnswerRecord } from "./game-answer-record.ts";
+export * from "./pages/app.schema.ts";
+export * from "./pages/auth.schema.ts";
+export * from "./pages/common.schema.ts";
+export * from "./pages/history.schema.ts";
+export * from "./pages/quiz.schema.ts";
+export type { PlayerSafeQuestion } from "./player-safe-question.ts";
+export { DifficultySchema, type ImageChoiceQuestion, type ImageMatchingQuestion, isHttpsUrl, type Media, MediaSchema, type MediaType, MediaTypeSchema, PostAnswerNoteSchema, type Question, QuestionSchema, type QuestionSource, QuestionSourceSchema, type QuestionType, QuestionTypeSchema, type Source, SourceSchema, type TextChoiceQuestion, type TrueFalseQuestion, } from "./question.schema.ts";
+export { hasMedia, isImageMatching, isTextChoice, isTrueFalse, } from "./question.ts";
+export { OptionalScoringModeSchema, ScoringModeSchema, } from "./scoring.schema.ts";
+export { type SoloAnswerChangeMessage, type SoloAnswerMessage, type SoloAuthMessage, type SoloClientMessage, type SoloErrorMessage, type SoloFinalMessage, type SoloGuestLimitMessage, type SoloLifeSpentMessage, type SoloNextMessage, type SoloPingMessage, type SoloPongMessage, type SoloQuestionMessage, type SoloReadyMessage, type SoloResumeMessage, type SoloRoundResultMessage, type SoloServerMessage, type SoloStartMessage, type SoloStreakBestMessage, type SoloStreakLostMessage, type SoloStreakMessage, type SoloStreakNearMissMessage, type SoloTabBlurMessage, type SoloTabFocusMessage, type SoloTickMessage, soloError, } from "./solo-ws.ts";
+export type { StreakFlourish } from "./streak-flourish.ts";
+export type { LeaderboardBoard, LeaderboardDifficulty, LeaderboardScope, } from "./wire/leaderboard.ts";
+export type { OperatorQuestionRevision, PublishManyResult, QuestionRevision, } from "./wire/question-bank.ts";
+export type { FlagDetail, FlagReporter, FlagStatus, QuestionFlagAnswerSnapshot, QuestionSnapshot, } from "./wire/question-flags.ts";
+export type { ClientMessage, CuratorAdvanceMessage, CuratorIntermissionMessage, CuratorPlayerActionMessage, CuratorResetMessage, CuratorStartMessage, CuratorStartRoleSelectionMessage, CuratorStopMessage, GameErrorMessage, GameFinalScoresMessage, GameIntermissionMessage, GamePingMessage, GameQuestionMessage, GameResultsReadyMessage, GameResumeMessage, GameRoundResultMessage, GameStartMessage, GameTickMessage, JoinAcceptedMessage, JoinRejectedMessage, LobbyEndedMessage, LobbyResetMessage, LobbyUpdateMessage, PlayerAnsweredMessage, PlayerAnswerMessage, PlayerEmoteBroadcastMessage, PlayerEmoteMessage, PlayerLeaveMessage, PlayerNicknameChangedMessage, PlayerQuestionAnswer, PlayerRemovedMessage, PlayerRoleMessage, RoleSelectionLockedMessage, RoleSelectionStartMessage, RoleSelectionUpdateMessage, ServerMessage, WsAuthMessage, WsPongMessage, } from "./ws.ts";
+export { ClientMessageSchema } from "./ws-game.schema.ts";
+export { SoloClientMessageSchema } from "./ws-solo.schema.ts";

package/dist/index.js

@@ -0,0 +1,13 @@
+export { EMOTE_SPRITES, SELECTABLE_EMOTE_IDS } from "./emotes.js";
+export { GAME, } from "./game.settings.js";
+export * from "./pages/app.schema.js";
+export * from "./pages/auth.schema.js";
+export * from "./pages/common.schema.js";
+export * from "./pages/history.schema.js";
+export * from "./pages/quiz.schema.js";
+export { DifficultySchema, isHttpsUrl, MediaSchema, MediaTypeSchema, PostAnswerNoteSchema, QuestionSchema, QuestionSourceSchema, QuestionTypeSchema, SourceSchema, } from "./question.schema.js";
+export { hasMedia, isImageMatching, isTextChoice, isTrueFalse, } from "./question.js";
+export { OptionalScoringModeSchema, ScoringModeSchema, } from "./scoring.schema.js";
+export { soloError, } from "./solo-ws.js";
+export { ClientMessageSchema } from "./ws-game.schema.js";
+export { SoloClientMessageSchema } from "./ws-solo.schema.js";