@orakl/protocol 0.1.0

package/dist/question.schema.js

@@ -0,0 +1,132 @@
+import { Schema } from "effect";
+import { GAME } from "./game.settings.js";
+export const DifficultySchema = Schema.Literal(...GAME.roundConfig.difficulties);
+export const MediaTypeSchema = Schema.Literal("image", "audio", "video");
+export const QuestionTypeSchema = Schema.Literal("text_choice", "image_choice", "true_false", "finish_line", "audio_identify", "sequence_order", "estimate_range", "fill_blank", "matching_pairs", "progressive_reveal", "image_matching");
+export const SourceSchema = Schema.Literal(...GAME.question.sources);
+export const MediaSchema = Schema.Struct({
+    type: MediaTypeSchema,
+    url: Schema.String,
+    thumbnail: Schema.optional(Schema.String),
+});
+/** True for an https URL WHATWG-parses; false for anything else (including unparsable strings). */
+export function isHttpsUrl(url) {
+    try {
+        return new URL(url).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+// Security: source.url is stored in the DB and read back on results/history
+// pages; cap to match imageUrl's bound (curator.schema.ts) since both are
+// URLs of the same practical size.
+const HttpsUrlSchema = Schema.String.pipe(Schema.maxLength(2048, {
+    message: () => "Source URL must be 2048 characters or fewer",
+}), Schema.filter(isHttpsUrl, { message: () => "Source URL must be https" }));
+export const QuestionSourceSchema = Schema.Struct({
+    url: HttpsUrlSchema,
+    label: Schema.optional(Schema.String.pipe(Schema.maxLength(200, {
+        message: () => "Source label must be 200 characters or fewer",
+    }))),
+});
+export const PostAnswerNoteSchema = Schema.String.pipe(Schema.maxLength(160, {
+    message: () => "Post-answer note must be 160 characters or fewer",
+}));
+const MetadataSchema = Schema.Struct({
+    source: SourceSchema,
+    tags: Schema.optional(Schema.Array(Schema.String)),
+    region: Schema.optional(Schema.Array(Schema.String)),
+    isNiche: Schema.optional(Schema.Boolean),
+    timeLimit: Schema.optional(Schema.Number),
+    points: Schema.optional(Schema.Number),
+});
+const QuestionBaseSchema = Schema.Struct({
+    id: Schema.String,
+    category: Schema.String,
+    difficulty: DifficultySchema,
+    question: Schema.Struct({
+        text: Schema.String,
+        media: Schema.optional(MediaSchema),
+    }),
+    correctAnswer: Schema.String,
+    incorrectAnswers: Schema.Array(Schema.String),
+    question_fingerprint: Schema.optional(Schema.String),
+    metadata: MetadataSchema,
+    createdAt: Schema.String,
+    // Evidence for the fact asked about. Hidden through play (map #912,
+    // decision 2) — enters the client only via results/history page loads.
+    source: Schema.optional(QuestionSourceSchema),
+    // The curator's explanation of the answer, delivered to players only at
+    // reveal (map #912, decision 2) — see game-store.ts's round-result payload.
+    postAnswerNote: Schema.optional(PostAnswerNoteSchema),
+});
+const TextChoiceSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("text_choice"),
+});
+const ImageChoiceSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("image_choice"),
+    question: Schema.Struct({ text: Schema.String, media: MediaSchema }),
+});
+const TrueFalseSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("true_false"),
+    correctAnswer: Schema.Literal("true", "false"),
+    incorrectAnswers: Schema.Tuple(Schema.Literal("true", "false")),
+});
+const FinishLineSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("finish_line"),
+    question: Schema.Struct({ text: Schema.String, media: MediaSchema }),
+});
+const AudioIdentifySchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("audio_identify"),
+    question: Schema.Struct({ text: Schema.String, media: MediaSchema }),
+});
+const SequenceOrderSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("sequence_order"),
+});
+const EstimateRangeSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("estimate_range"),
+    metadata: Schema.Struct({
+        ...MetadataSchema.fields,
+        acceptableRange: Schema.Number,
+    }),
+});
+const FillBlankSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("fill_blank"),
+});
+const MatchingPairsSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("matching_pairs"),
+});
+const ProgressiveRevealSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("progressive_reveal"),
+    question: Schema.Struct({ text: Schema.String, media: MediaSchema }),
+    metadata: Schema.Struct({
+        ...MetadataSchema.fields,
+        revealSteps: Schema.Number,
+    }),
+});
+const ImageMatchingSchema = Schema.Struct({
+    ...QuestionBaseSchema.fields,
+    type: Schema.Literal("image_matching"),
+    question: Schema.Struct({ text: Schema.String, media: MediaSchema }),
+    correctAnswer: Schema.String,
+    incorrectAnswers: Schema.Array(Schema.String),
+    matchItems: Schema.Struct({
+        left: Schema.Tuple(Schema.String, Schema.String, Schema.String, Schema.String),
+        right: Schema.Tuple(Schema.String, Schema.String, Schema.String, Schema.String),
+    }),
+});
+// Discriminant: Effect Schema detects the shared `type: Schema.Literal(...)` field and
+// short-circuits matching without sequential probing — but this is implicit, not an API
+// contract. All members must keep a unique `type` literal or the optimisation silently degrades.
+export const QuestionSchema = Schema.Union(TextChoiceSchema, ImageChoiceSchema, TrueFalseSchema, FinishLineSchema, AudioIdentifySchema, SequenceOrderSchema, EstimateRangeSchema, FillBlankSchema, MatchingPairsSchema, ProgressiveRevealSchema, ImageMatchingSchema);

package/dist/scoring.schema.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** Shared scoring-mode literal — single source for every schema that accepts it
+ *  (game start, lobby create, preset save). Mirrors GAME.roundConfig.scoringOptions. */
+export declare const ScoringModeSchema: Schema.Literal<["classic", "time-based"]>;
+/** Optional variant for request bodies where scoringMode may be omitted
+ *  (defaults to GAME.roundConfig.defaultScoring at the call site). */
+export declare const OptionalScoringModeSchema: Schema.optional<Schema.Literal<["classic", "time-based"]>>;

package/dist/scoring.schema.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+import { GAME } from "./game.settings.js";
+/** Shared scoring-mode literal — single source for every schema that accepts it
+ *  (game start, lobby create, preset save). Mirrors GAME.roundConfig.scoringOptions. */
+export const ScoringModeSchema = Schema.Literal(...GAME.roundConfig.scoringOptions);
+/** Optional variant for request bodies where scoringMode may be omitted
+ *  (defaults to GAME.roundConfig.defaultScoring at the call site). */
+export const OptionalScoringModeSchema = Schema.optional(ScoringModeSchema);

package/dist/solo-ws.d.ts

@@ -0,0 +1,202 @@
+import type { BadgeAward } from "./badges.ts";
+import type { PlayerSafeQuestion } from "./player-safe-question.ts";
+import type { MediaType, QuestionSource } from "./question.ts";
+export type SoloAuthMessage = {
+    type: "auth";
+    token: string;
+};
+export type SoloStartMessage = {
+    type: "solo:start";
+    categoryIds: string[];
+    timerDuration: number;
+    questionCount: number;
+    mode: "normal" | "endless";
+    difficulty: "all" | "easy" | "medium" | "hard";
+    /** Client device class (mobile/tablet/desktop) for cross-device stats. */
+    device?: "mobile" | "tablet" | "desktop";
+};
+export type SoloAnswerMessage = {
+    type: "solo:answer";
+    answerId: string;
+    /**
+     * The nonce from the current solo:question. The server rejects answers whose
+     * nonce doesn't match the in-flight question, defeating replayed answer frames
+     * (anti-cheat). Optional for backward compatibility with older clients.
+     */
+    nonce?: string;
+};
+/** The player switched their selection before committing (hesitation signal). */
+export type SoloAnswerChangeMessage = {
+    type: "solo:answer-change";
+};
+export type SoloNextMessage = {
+    type: "solo:next";
+};
+export type SoloTabBlurMessage = {
+    type: "solo:tab-blur";
+};
+export type SoloTabFocusMessage = {
+    type: "solo:tab-focus";
+};
+export type SoloPongMessage = {
+    type: "solo:pong";
+};
+export type SoloResumeMessage = {
+    type: "solo:resume";
+    sessionId: string;
+    /** Secret issued in solo:ready; required to resume a guest session (anti-hijack). */
+    resumeToken?: string;
+};
+export type SoloClientMessage = SoloAuthMessage | SoloStartMessage | SoloAnswerMessage | SoloAnswerChangeMessage | SoloNextMessage | SoloTabBlurMessage | SoloTabFocusMessage | SoloPongMessage | SoloResumeMessage;
+export type SoloReadyMessage = {
+    type: "solo:ready";
+    isGuest: boolean;
+    sessionId: string;
+    /**
+     * Secret the client must echo on solo:resume to reclaim this session. Binds
+     * resume to the original connection so a leaked sessionId alone can't hijack a
+     * run (anti-cheat, CHEAT-1).
+     */
+    resumeToken?: string;
+};
+export type SoloQuestionMessage = {
+    type: "solo:question";
+    question: PlayerSafeQuestion;
+    questionIndex: number;
+    totalQuestions: number | null;
+    timeRemaining: number;
+    serverTs: number;
+    /** Per-question nonce the client must echo on solo:answer (anti-replay). */
+    nonce?: string;
+};
+export type SoloTickMessage = {
+    type: "solo:tick";
+    timeRemaining: number;
+    serverTs: number;
+};
+export type SoloRoundResultMessage = {
+    type: "solo:round-result";
+    correctAnswerId: string;
+    /** The answer the player gave (null on timeout) — lets reconnect restore the reveal. */
+    selectedAnswerId: string | null;
+    isCorrect: boolean;
+    score: number;
+    totalScore: number;
+    timeToAnswerMs: number;
+    streak: number;
+    /** Strikes used in endless mode (0 in normal mode). */
+    strikes: number;
+    /**
+     * For a correct answer with enough prior data: the % of players this answer
+     * beat on time for this question. Null otherwise (wrong/timeout, or too few
+     * samples). Drives the "faster than most" cue (US #11).
+     */
+    fasterThanPercent: number | null;
+    /** The curator's explanation of the answer, withheld until now (map #912,
+     *  decision 2). Omitted when the question has none. */
+    postAnswerNote?: string;
+};
+export type SoloStreakMessage = {
+    type: "solo:streak";
+    milestone: number;
+    streak: number;
+};
+export type SoloStreakLostMessage = {
+    type: "solo:streak-lost";
+    /** Size of the streak that just broke (see GAME.streak.losses). */
+    lostStreak: number;
+    streak: number;
+};
+export type SoloStreakNearMissMessage = {
+    type: "solo:streak-near-miss";
+    /** Size of the streak that broke one short of its next milestone. */
+    lostStreak: number;
+    streak: number;
+};
+export type SoloStreakBestMessage = {
+    type: "solo:streak-best";
+    /** New run-best streak — crossed the prior peak after a comeback. */
+    streak: number;
+};
+export type SoloLifeSpentMessage = {
+    type: "solo:life-spent";
+    /** Endless-mode lives left after this strike; the run continues. */
+    livesRemaining: number;
+    streak: number;
+};
+export type SoloFinalMessage = {
+    type: "solo:final";
+    totalScore: number;
+    totalAnswered: number;
+    correctCount: number;
+    timeToAnswerAvgMs: number;
+    /** Peak consecutive-correct streak this session. */
+    maxStreak: number;
+    /** Eligible for score leaderboards (non-guest, fixed-count mode). */
+    isLeaderboardEligible: boolean;
+    /** Eligible for the streak leaderboard (any non-guest session). */
+    isStreakEligible: boolean;
+    /**
+     * Total tab-away events across the whole session (US #23). 0 means the player
+     * never left the trial — drives the "you stayed focused" cue.
+     */
+    tabAwayCount: number;
+    /**
+     * The per-question timer (ms) this session ran with. Lets the results screen
+     * read each answer's `timeToAnswerMs` as a fraction of the clock for the
+     * implicit-confidence / decisiveness cue (US #24).
+     */
+    timerDurationMs: number;
+    /**
+     * For guest sessions, the persisted session id the player can claim by
+     * signing up/in (links the run to the new account). Null when already signed
+     * in (nothing to claim).
+     */
+    claimId: string | null;
+    mode: "normal" | "endless";
+    /** Difficulty the run was played at — feeds per-badge rarity on results. */
+    difficulty: "all" | "easy" | "medium" | "hard";
+    /**
+     * Achievement badges earned this run (US #14, #23, #24) — server-computed so
+     * they're authoritative and match what's tallied on the stats page. Optional
+     * for backward compatibility with pre-badge persisted/final payloads.
+     */
+    badges?: BadgeAward[];
+    results: Array<{
+        questionId: string;
+        questionText: string;
+        categoryId: string;
+        /** Difficulty band of the question (for per-difficulty results breakdowns). */
+        difficulty?: "easy" | "medium" | "hard";
+        isCorrect: boolean;
+        selectedAnswerId: string | null;
+        correctAnswerId: string;
+        timeToAnswerMs: number;
+        /** Results-only extras (never sent earlier in the run, map #912): the
+         *  question's image, source and note. Absent when the question has none. */
+        mediaUrl?: string;
+        mediaType?: MediaType;
+        source?: QuestionSource;
+        postAnswerNote?: string;
+        /** From the same batched precheck as `solo:question`'s `alreadyFlagged`
+         *  (issue #922) — hides the results screen's flag control for a question
+         *  already flagged. Always false for guests. */
+        alreadyFlagged: boolean;
+    }>;
+};
+export type SoloPingMessage = {
+    type: "solo:ping";
+};
+export type SoloErrorMessage = {
+    type: "solo:error";
+    code: "auth_failed" | "entitlement_exceeded" | "invalid_message" | "session_expired" | "internal";
+    message: string;
+};
+/** Build a `solo:error` frame — the one shape every failure site sends. */
+export declare function soloError(code: SoloErrorMessage["code"], message: string): SoloErrorMessage;
+export type SoloGuestLimitMessage = {
+    type: "solo:guest-limit";
+    reason: string;
+    upgradeHint: string;
+};
+export type SoloServerMessage = SoloReadyMessage | SoloQuestionMessage | SoloTickMessage | SoloRoundResultMessage | SoloStreakMessage | SoloStreakLostMessage | SoloStreakNearMissMessage | SoloStreakBestMessage | SoloLifeSpentMessage | SoloFinalMessage | SoloPingMessage | SoloErrorMessage | SoloGuestLimitMessage;

package/dist/solo-ws.js

@@ -0,0 +1,4 @@
+/** Build a `solo:error` frame — the one shape every failure site sends. */
+export function soloError(code, message) {
+    return { type: "solo:error", code, message };
+}

package/dist/streak-flourish.d.ts

@@ -0,0 +1,6 @@
+/** A streak milestone/loss flourish carried on a wire frame — the app derives
+ *  it from the answer log (see `src/lib/streak-flourish.ts`'s `streakFromLog`). */
+export type StreakFlourish = {
+    kind: "gain" | "loss" | "near-miss" | "best";
+    value: number;
+};

package/dist/streak-flourish.js

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

package/dist/wire/leaderboard.d.ts

@@ -0,0 +1,6 @@
+/** Which ranking a leaderboard sorts by. */
+export type LeaderboardBoard = "score" | "streak" | "accuracy" | "speed" | "survival";
+/** Rolling window a leaderboard is scoped to. */
+export type LeaderboardScope = "all-time" | "daily" | "weekly" | "monthly";
+/** Difficulty filter a leaderboard is narrowed to. */
+export type LeaderboardDifficulty = "easy" | "medium" | "hard";

package/dist/wire/leaderboard.js

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

package/dist/wire/question-bank.d.ts

@@ -0,0 +1,23 @@
+import type { Question } from "../question.schema.ts";
+/** One prior version of an edited question, decoded. */
+export type QuestionRevision = {
+    id: string;
+    createdAt: string;
+    actorId: string | null;
+    question: Question;
+};
+/** A revision plus the actor's identity, for the operator dashboard. */
+export type OperatorQuestionRevision = QuestionRevision & {
+    actor: {
+        nickname: string | null;
+        email: string | null;
+    } | null;
+};
+/** One outcome of a bulk publish — an id that promoted, was already shared,
+ *  is flagged, or wasn't found. */
+export type PublishManyResult = {
+    id: string;
+    outcome: "promoted" | "already" | "flagged" | "not_found";
+    published_at?: string;
+    published_by?: string;
+};

package/dist/wire/question-bank.js

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

package/dist/wire/question-flags.d.ts

@@ -0,0 +1,40 @@
+import type { QuestionSource } from "../question.schema.ts";
+/** Whether a flagged question still has an unreviewed report. */
+export type FlagStatus = "open" | "resolved";
+/** One answer as it stood when a flag was filed. */
+export type QuestionFlagAnswerSnapshot = {
+    id: string;
+    text: string;
+    isCorrect: boolean;
+};
+/** Frozen-at-write-time question shape a flag was filed against — later
+ *  edits/deletes to the source question never change what this reads. */
+export type QuestionSnapshot = {
+    text: string;
+    type: string;
+    categoryId: string;
+    difficulty: string;
+    mediaUrl?: string;
+    mediaType?: string;
+    source?: QuestionSource;
+    postAnswerNote?: string;
+    answers: QuestionFlagAnswerSnapshot[];
+};
+/** One flag reporter's identity and submission. */
+export type FlagReporter = {
+    userId: string;
+    nickname: string | null;
+    email: string;
+    selectedAnswerId: string | null;
+    reason: string | null;
+    url: string | null;
+    createdAt: string;
+};
+/** Full detail for one flagged question: its frozen snapshot plus every
+ *  reporter. */
+export type FlagDetail = {
+    questionId: string;
+    status: FlagStatus;
+    snapshot: QuestionSnapshot;
+    reporters: FlagReporter[];
+};

package/dist/wire/question-flags.js

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

package/dist/ws-game.schema.d.ts

@@ -0,0 +1,75 @@
+import { Schema } from "effect";
+export declare const ClientMessageSchema: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["auth"]>;
+    token: Schema.filter<typeof Schema.NonEmptyString>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["player:answer"]>;
+    answerId: Schema.filter<typeof Schema.NonEmptyString>;
+    playerId: Schema.optional<Schema.filter<typeof Schema.NonEmptyString>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["player:emote"]>;
+    emoteId: Schema.Literal<["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"]>;
+    offsetX: Schema.filter<Schema.filter<typeof Schema.Number>>;
+    offsetY: Schema.filter<Schema.filter<typeof Schema.Number>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["player:role"]>;
+    role: Schema.Literal<["player", "observer"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["player:leave"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["curator:start"]>;
+    categoryIds: Schema.optional<Schema.filter<Schema.Array$<typeof Schema.NonEmptyString>>>;
+    timerDuration: Schema.optional<Schema.Literal<[15, 30, 45, 60]>>;
+    questionsPerRound: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
+    difficulty: Schema.optional<Schema.Literal<["all", "easy", "medium", "hard"]>>;
+    advanceMode: Schema.optional<Schema.Literal<["auto_5", "auto_10", "manual"]>>;
+    scoringMode: Schema.optional<Schema.Literal<["classic", "time-based"]>>;
+    preloadedQuestions: Schema.optional<Schema.filter<Schema.Array$<Schema.Union<[Schema.Struct<{
+        type: Schema.Literal<["text_choice", "image_choice", "true_false", "finish_line", "audio_identify", "sequence_order", "estimate_range", "fill_blank", "matching_pairs", "progressive_reveal"]>;
+        id: Schema.filter<typeof Schema.NonEmptyString>;
+        text: Schema.filter<typeof Schema.String>;
+        categoryId: Schema.filter<typeof Schema.NonEmptyString>;
+        difficulty: Schema.Literal<["easy", "medium", "hard"]>;
+        answers: Schema.filter<Schema.filter<Schema.Array$<Schema.Struct<{
+            id: Schema.filter<typeof Schema.NonEmptyString>;
+            text: Schema.filter<typeof Schema.String>;
+            isCorrect: typeof Schema.Boolean;
+        }>>>>;
+        mediaUrl: Schema.optional<Schema.filter<typeof Schema.String>>;
+        mediaType: Schema.optional<Schema.Literal<["image", "audio", "video"]>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["image_matching"]>;
+        matchItems: Schema.Struct<{
+            left: Schema.filter<Schema.filter<Schema.Array$<Schema.filter<typeof Schema.String>>>>;
+            right: Schema.filter<Schema.filter<Schema.Array$<Schema.filter<typeof Schema.String>>>>;
+        }>;
+        id: Schema.filter<typeof Schema.NonEmptyString>;
+        text: Schema.filter<typeof Schema.String>;
+        categoryId: Schema.filter<typeof Schema.NonEmptyString>;
+        difficulty: Schema.Literal<["easy", "medium", "hard"]>;
+        answers: Schema.filter<Schema.filter<Schema.Array$<Schema.Struct<{
+            id: Schema.filter<typeof Schema.NonEmptyString>;
+            text: Schema.filter<typeof Schema.String>;
+            isCorrect: typeof Schema.Boolean;
+        }>>>>;
+        mediaUrl: Schema.optional<Schema.filter<typeof Schema.String>>;
+        mediaType: Schema.optional<Schema.Literal<["image", "audio", "video"]>>;
+    }>]>>>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["curator:advance"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["curator:start-role-selection"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["curator:intermission"]>;
+    action: Schema.Literal<["start", "end"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["curator:player"]>;
+    playerId: Schema.filter<typeof Schema.NonEmptyString>;
+    action: Schema.Literal<["approve", "reject", "remove", "block"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["curator:stop"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["curator:reset"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["pong"]>;
+}>]>;

package/dist/ws-game.schema.js

@@ -0,0 +1,131 @@
+import { Schema } from "effect";
+import { SELECTABLE_EMOTE_IDS } from "./emotes.js";
+import { GAME } from "./game.settings.js";
+import { DifficultySchema, MediaTypeSchema } from "./question.schema.js";
+import { OptionalScoringModeSchema } from "./scoring.schema.js";
+/**
+ * Frame-level validation for the multiplayer game WebSocket (issue #734 hardening).
+ * One schema per `ClientMessage` union member in `./ws.ts` — mirrors the
+ * hand-written types (no `Schema.Type` derivation feeds back into `ClientMessage`,
+ * see `game-connection-handler.ts`). Keep this file in sync with `ws.ts` whenever
+ * a frame is added/changed.
+ */
+// Tokens ride the WS handshake/first-frame; generous cap is a DoS guard only.
+const TokenSchema = Schema.NonEmptyString.pipe(Schema.maxLength(4096));
+// Security: mirrors the retired REST AnswerSchema — answerId is broadcast in
+// game:round-result to every player; cap to prevent stored DoS.
+const AnswerIdSchema = Schema.NonEmptyString.pipe(Schema.maxLength(500));
+// DoS guard: ids that round-trip through store state / broadcasts.
+const BoundedIdSchema = Schema.NonEmptyString.pipe(Schema.maxLength(200));
+// ─── auth ───────────────────────────────────────────────────────────────────
+const WsAuthMessageSchema = Schema.Struct({
+    type: Schema.Literal("auth"),
+    token: TokenSchema,
+});
+// ─── player:* ───────────────────────────────────────────────────────────────
+const PlayerAnswerMessageSchema = Schema.Struct({
+    type: Schema.Literal("player:answer"),
+    answerId: AnswerIdSchema,
+    // @deprecated identity is bound at the socket upgrade; ignored if sent.
+    playerId: Schema.optional(BoundedIdSchema),
+});
+const PlayerEmoteMessageSchema = Schema.Struct({
+    type: Schema.Literal("player:emote"),
+    emoteId: Schema.Literal(...SELECTABLE_EMOTE_IDS),
+    // Broadcast to every player and used directly as CSS left%/top% (0-1) —
+    // bounded, not just finite, or an attacker-controlled value corrupts the
+    // shared emote overlay for the whole lobby.
+    offsetX: Schema.Number.pipe(Schema.finite(), Schema.between(0, 1)),
+    offsetY: Schema.Number.pipe(Schema.finite(), Schema.between(0, 1)),
+});
+const PlayerRoleMessageSchema = Schema.Struct({
+    type: Schema.Literal("player:role"),
+    role: Schema.Literal("player", "observer"),
+});
+const PlayerLeaveMessageSchema = Schema.Struct({
+    type: Schema.Literal("player:leave"),
+});
+// ─── curator:* ──────────────────────────────────────────────────────────────
+// QuestionType minus "image_matching" (mirrors StandardQuizQuestion).
+const StandardQuizQuestionTypeSchema = Schema.Literal("text_choice", "image_choice", "true_false", "finish_line", "audio_identify", "sequence_order", "estimate_range", "fill_blank", "matching_pairs", "progressive_reveal");
+// Security: text/answer content is broadcast in game:question to every player
+// on every start using this import; cap to prevent stored-DoS amplification.
+// Bounds mirror curator.schema.ts's CustomQuestionSchema (same broadcast path).
+const QuizAnswerSchema = Schema.Struct({
+    id: BoundedIdSchema,
+    text: Schema.String.pipe(Schema.maxLength(300)),
+    isCorrect: Schema.Boolean,
+});
+const BoundedMatchString = Schema.String.pipe(Schema.maxLength(200));
+const MatchItemsSchema = Schema.Struct({
+    left: Schema.Array(BoundedMatchString).pipe(Schema.minItems(1), Schema.maxItems(10)),
+    right: Schema.Array(BoundedMatchString).pipe(Schema.minItems(1), Schema.maxItems(10)),
+});
+const BaseQuizQuestionFields = {
+    id: BoundedIdSchema,
+    text: Schema.String.pipe(Schema.maxLength(500)),
+    categoryId: BoundedIdSchema,
+    difficulty: DifficultySchema,
+    // image_matching stores a single correct-answer entry (see question-mapper.ts);
+    // everything else needs at least 2 options — 1 is the real floor across both.
+    answers: Schema.Array(QuizAnswerSchema).pipe(Schema.minItems(1), Schema.maxItems(8)),
+    mediaUrl: Schema.optional(Schema.String.pipe(Schema.maxLength(2048))),
+    mediaType: Schema.optional(MediaTypeSchema),
+};
+const StandardPreloadedQuestionSchema = Schema.Struct({
+    ...BaseQuizQuestionFields,
+    type: StandardQuizQuestionTypeSchema,
+});
+const ImageMatchingPreloadedQuestionSchema = Schema.Struct({
+    ...BaseQuizQuestionFields,
+    type: Schema.Literal("image_matching"),
+    matchItems: MatchItemsSchema,
+});
+const PreloadedQuestionSchema = Schema.Union(StandardPreloadedQuestionSchema, ImageMatchingPreloadedQuestionSchema);
+const DifficultyFilterSchema = Schema.Literal(...GAME.roundConfig.difficultyOptions);
+const CuratorStartMessageSchema = Schema.Struct({
+    type: Schema.Literal("curator:start"),
+    // No minItems: an empty/omitted categoryIds is a valid business state when
+    // preloadedQuestions carries the round — game-ws-server.ts's makeStartGame
+    // surfaces the friendly "select a category" error itself.
+    categoryIds: Schema.optional(Schema.Array(Schema.NonEmptyString).pipe(Schema.maxItems(50))),
+    timerDuration: Schema.optional(Schema.Literal(...GAME.roundConfig.timerOptions)),
+    // Not the QuestionsPerRound literal on purpose (ws.ts types this as a plain
+    // number) — bounded generously instead, mirroring DrawQuestionsSchema's cap.
+    questionsPerRound: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.greaterThan(0), Schema.lessThanOrEqualTo(500))),
+    difficulty: Schema.optional(DifficultyFilterSchema),
+    advanceMode: Schema.optional(Schema.Literal(...GAME.roundConfig.advanceModeOptions)),
+    scoringMode: OptionalScoringModeSchema,
+    // Generous headroom above any real round size (max 100) so a legitimate
+    // curator import is never rejected; still bounded against a DoS payload.
+    preloadedQuestions: Schema.optional(Schema.Array(PreloadedQuestionSchema).pipe(Schema.maxItems(500))),
+});
+const CuratorAdvanceMessageSchema = Schema.Struct({
+    type: Schema.Literal("curator:advance"),
+});
+const CuratorStopMessageSchema = Schema.Struct({
+    type: Schema.Literal("curator:stop"),
+});
+const CuratorResetMessageSchema = Schema.Struct({
+    type: Schema.Literal("curator:reset"),
+});
+const CuratorStartRoleSelectionMessageSchema = Schema.Struct({
+    type: Schema.Literal("curator:start-role-selection"),
+});
+const CuratorIntermissionMessageSchema = Schema.Struct({
+    type: Schema.Literal("curator:intermission"),
+    action: Schema.Literal("start", "end"),
+});
+const CuratorPlayerActionMessageSchema = Schema.Struct({
+    type: Schema.Literal("curator:player"),
+    playerId: BoundedIdSchema,
+    action: Schema.Literal("approve", "reject", "remove", "block"),
+});
+// ─── pong ───────────────────────────────────────────────────────────────────
+const WsPongMessageSchema = Schema.Struct({
+    type: Schema.Literal("pong"),
+});
+// Discriminant: Effect Schema detects the shared `type: Schema.Literal(...)`
+// field and short-circuits matching — every member needs a unique `type`.
+export const ClientMessageSchema = Schema.Union(WsAuthMessageSchema, PlayerAnswerMessageSchema, PlayerEmoteMessageSchema, PlayerRoleMessageSchema, PlayerLeaveMessageSchema, CuratorStartMessageSchema, CuratorAdvanceMessageSchema, CuratorStartRoleSelectionMessageSchema, CuratorIntermissionMessageSchema, CuratorPlayerActionMessageSchema, CuratorStopMessageSchema, CuratorResetMessageSchema, WsPongMessageSchema);
+const _assertNoClientMessageDrift = null;