@orakl/protocol 0.13.0 → 0.15.0

package/dist/error-codes.d.ts

@@ -1 +1 @@
-export type ErrorCode = "no_active_lobby" | "no_active_game" | "device_blocked" | "nickname_taken" | "nickname_locked" | "device_in_lobby" | "player_not_found" | "player_not_pending" | "intermission_invalid_phase" | "not_in_intermission" | "category_name_exists" | "category_not_found" | "category_has_questions" | "tag_name_exists" | "tag_not_found" | "tag_has_questions" | "tag_in_season" | "category_in_season" | "season_name_exists" | "season_not_found" | "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" | "season_out_of_season" | "no_categories" | "too_few_players" | "hosting_closed" | "not_answered" | "emote_not_in_set" | "flag_not_toggleable" | "solo_invalid_phase" | "solo_invalid_answer" | "solo_nonce_mismatch" | "solo_answer_expired" | "solo_guest_limit" | "solo_no_questions" | "solo_season_out_of_season" | "solo_resume_denied" | "solo_auth_failed";
+export type ErrorCode = "no_active_lobby" | "no_active_game" | "device_blocked" | "nickname_taken" | "nickname_locked" | "device_in_lobby" | "player_not_found" | "player_not_pending" | "intermission_invalid_phase" | "not_in_intermission" | "category_name_exists" | "category_not_found" | "category_has_questions" | "tag_name_exists" | "tag_not_found" | "tag_has_questions" | "tag_in_season" | "category_in_season" | "season_name_exists" | "season_not_found" | "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" | "season_out_of_season" | "no_categories" | "too_few_players" | "hosting_closed" | "not_answered" | "emote_not_in_set" | "flag_not_toggleable" | "undo_disabled" | "undo_exhausted" | "solo_invalid_phase" | "solo_invalid_answer" | "solo_nonce_mismatch" | "solo_answer_expired" | "solo_guest_limit" | "solo_no_questions" | "solo_season_out_of_season" | "solo_resume_denied" | "solo_auth_failed";

package/dist/game.settings.d.ts

@@ -79,6 +79,11 @@ export declare const GAME: {
     readonly player: {
         readonly maxNicknameLength: 20;
     };
+    readonly undo: {
+        readonly budgetFraction: 0.1;
+        readonly minBudget: 1;
+        readonly lastCallSeconds: 5;
+    };
     readonly sse: {
         readonly keepaliveIntervalMs: 15000;
     };

package/dist/game.settings.js

@@ -55,6 +55,14 @@ export const GAME = {
     player: {
         maxNicknameLength: 20,
     },
+    undo: {
+        // Per-player budget = max(minBudget, ceil(totalQuestions * budgetFraction)).
+        budgetFraction: 0.1,
+        minBudget: 1,
+        // Grace window once every hero has answered, during which an undo may
+        // still cancel the round close.
+        lastCallSeconds: 5,
+    },
     sse: {
         keepaliveIntervalMs: 15000,
     },

package/dist/index.d.ts

@@ -10,7 +10,7 @@ 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 { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, type CreditLicence, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, type ImageChoiceQuestion, type ImageMatchingQuestion, isHttpsUrl, type Media, type MediaCredit, MediaCreditSchema, 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 { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, type CreditLicence, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, type ImageChoiceQuestion, type ImageMatchingQuestion, isHttpsUrl, type Media, type MediaCredit, MediaCreditSchema, MediaSchema, type MediaType, MediaTypeSchema, POST_ANSWER_NOTE_MAX_LEN, PostAnswerNoteSchema, type Question, QuestionSchema, type QuestionSource, QuestionSourceSchema, type QuestionType, QuestionTypeSchema, SOURCE_LABEL_MAX_LEN, SOURCE_URL_MAX_LEN, type Source, SourceSchema, type TextChoiceQuestion, type TrueFalseQuestion, } from "./question.schema.ts";
 export { hasMedia, isImageMatching, isTextChoice, isTrueFalse, } from "./question.ts";
 export type { QuestionRating } from "./question-rating.ts";
 export { OptionalScoringModeSchema, ScoringModeSchema, } from "./scoring.schema.ts";
@@ -19,6 +19,6 @@ 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, PlayerRateAckMessage, PlayerRateMessage, PlayerRemovedMessage, PlayerRoleMessage, RateAckReason, RoleSelectionLockedMessage, RoleSelectionStartMessage, RoleSelectionUpdateMessage, ServerMessage, WsAuthMessage, WsPongMessage, } from "./ws.ts";
+export type { ClientMessage, CuratorAdvanceMessage, CuratorIntermissionMessage, CuratorPlayerActionMessage, CuratorResetMessage, CuratorStartMessage, CuratorStartRoleSelectionMessage, CuratorStopMessage, GameErrorMessage, GameFinalScoresMessage, GameIntermissionMessage, GameLastCallCancelledMessage, GameLastCallMessage, GamePingMessage, GameQuestionMessage, GameResultsReadyMessage, GameResumeMessage, GameRoundResultMessage, GameStartMessage, GameTickMessage, JoinAcceptedMessage, JoinRejectedMessage, LobbyEndedMessage, LobbyResetMessage, LobbyUpdateMessage, PlayerAnsweredMessage, PlayerAnswerMessage, PlayerEmoteBroadcastMessage, PlayerEmoteMessage, PlayerLeaveMessage, PlayerNicknameChangedMessage, PlayerQuestionAnswer, PlayerRateAckMessage, PlayerRateMessage, PlayerRemovedMessage, PlayerRoleMessage, PlayerUnansweredMessage, PlayerUndoAckMessage, PlayerUndoMessage, RateAckReason, 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

@@ -5,7 +5,7 @@ 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 { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, isHttpsUrl, MediaCreditSchema, MediaSchema, MediaTypeSchema, PostAnswerNoteSchema, QuestionSchema, QuestionSourceSchema, QuestionTypeSchema, SourceSchema, } from "./question.schema.js";
+export { ATTRIBUTION_LICENCES, CREDIT_LICENCE_LABEL, CREDIT_LICENCES, CreditLicenceSchema, DISTRIBUTABLE_LICENCES, DifficultySchema, isHttpsUrl, MediaCreditSchema, MediaSchema, MediaTypeSchema, POST_ANSWER_NOTE_MAX_LEN, PostAnswerNoteSchema, QuestionSchema, QuestionSourceSchema, QuestionTypeSchema, SOURCE_LABEL_MAX_LEN, SOURCE_URL_MAX_LEN, 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";

package/dist/pages/app.schema.d.ts

@@ -288,6 +288,47 @@ export declare const ManageQuestionRatingsPageSchema: Schema.Struct<{
     initialHasMore: typeof Schema.Boolean;
     page: typeof Schema.Number;
 }>;
+declare const BankQuestionRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    excerpt: typeof Schema.String;
+    source: Schema.Literal<["built-in", "promoted"]>;
+    category: typeof Schema.String;
+    /** The stored question type, e.g. `text_choice`. */
+    type: typeof Schema.String;
+    difficulty: Schema.NullOr<Schema.Literal<["easy", "medium", "hard"]>>;
+    /** At least one revision exists. */
+    edited: typeof Schema.Boolean;
+}>;
+/** One question an operator may edit on the question bank page: built-in or promoted. */
+export type BankQuestionRow = typeof BankQuestionRowSchema.Type;
+/** Body of `GET /api/pages/manage/bank`. */
+export declare const ManageBankPageSchema: Schema.Struct<{
+    initial: Schema.mutable<Schema.Array$<Schema.Schema<{
+        readonly type: string;
+        readonly source: "built-in" | "promoted";
+        readonly id: string;
+        readonly category: string;
+        readonly difficulty: "medium" | "easy" | "hard" | null;
+        readonly excerpt: string;
+        readonly edited: boolean;
+    }, {
+        readonly type: string;
+        readonly source: "built-in" | "promoted";
+        readonly id: string;
+        readonly category: string;
+        readonly difficulty: "medium" | "easy" | "hard" | null;
+        readonly excerpt: string;
+        readonly edited: boolean;
+    }, never>>>;
+    initialHasMore: typeof Schema.Boolean;
+    page: typeof Schema.Number;
+    /** The search term the page was loaded with; empty for none. */
+    q: typeof Schema.String;
+    /** The category name the page was filtered to; empty for all. */
+    category: typeof Schema.String;
+    /** Category names offered by the filter, A to Z. */
+    categories: Schema.mutable<Schema.Array$<Schema.Schema<string, string, never>>>;
+}>;
 declare const AuthoredQuestionRowSchema: Schema.Struct<{
     id: typeof Schema.String;
     category: typeof Schema.String;
@@ -390,6 +431,7 @@ declare const QuizPresetSchema: Schema.Struct<{
     scoring_mode: Schema.NullOr<typeof Schema.String>;
     access_mode: typeof Schema.String;
     max_players: Schema.NullOr<typeof Schema.Number>;
+    undo_enabled: typeof Schema.Number;
     created_at: typeof Schema.String;
 }>;
 export type QuizPreset = typeof QuizPresetSchema.Type;
@@ -457,6 +499,7 @@ export declare const CuratorCreatePageSchema: Schema.Struct<{
         readonly scoring_mode: string | null;
         readonly access_mode: string;
         readonly max_players: number | null;
+        readonly undo_enabled: number;
     }, {
         readonly name: string;
         readonly id: string;
@@ -472,6 +515,7 @@ export declare const CuratorCreatePageSchema: Schema.Struct<{
         readonly scoring_mode: string | null;
         readonly access_mode: string;
         readonly max_players: number | null;
+        readonly undo_enabled: number;
     }, never>>>;
     presetMarks: Schema.Record$<typeof Schema.String, Schema.Struct<{
         closedSeasons: Schema.mutable<Schema.Array$<Schema.Schema<{

package/dist/pages/app.schema.js

@@ -196,6 +196,29 @@ export const ManageQuestionRatingsPageSchema = Schema.Struct({
     initialHasMore: Schema.Boolean,
     page: Schema.Number,
 });
+const BankQuestionRowSchema = Schema.Struct({
+    id: Schema.String,
+    excerpt: Schema.String,
+    source: Schema.Literal("built-in", "promoted"),
+    category: Schema.String,
+    /** The stored question type, e.g. `text_choice`. */
+    type: Schema.String,
+    difficulty: Schema.NullOr(Schema.Literal("easy", "medium", "hard")),
+    /** At least one revision exists. */
+    edited: Schema.Boolean,
+});
+/** Body of `GET /api/pages/manage/bank`. */
+export const ManageBankPageSchema = Schema.Struct({
+    initial: Arr(BankQuestionRowSchema),
+    initialHasMore: Schema.Boolean,
+    page: Schema.Number,
+    /** The search term the page was loaded with; empty for none. */
+    q: Schema.String,
+    /** The category name the page was filtered to; empty for all. */
+    category: Schema.String,
+    /** Category names offered by the filter, A to Z. */
+    categories: Arr(Schema.String),
+});
 const AuthoredQuestionRowSchema = Schema.Struct({
     id: Schema.String,
     category: Schema.String,
@@ -259,6 +282,7 @@ const QuizPresetSchema = Schema.Struct({
     scoring_mode: Schema.NullOr(Schema.String),
     access_mode: Schema.String,
     max_players: Schema.NullOr(Schema.Number),
+    undo_enabled: Schema.Number,
     created_at: Schema.String,
 });
 /** What stopped a saved Quiz's members from drawing: closed or gone Seasons, gone or hidden categories. */

package/dist/pages/quiz.schema.d.ts

@@ -69,6 +69,9 @@ export type PlayerJourney = typeof PlayerJourneySchema.Type;
 /** Body of `GET /api/quiz/journey`: a `PlayerJourney` plus the registry-miss diagnosis. */
 export declare const QuizJourneyPageSchema: Schema.Struct<{
     miss: Schema.NullOr<Schema.Literal<["lobby_lost"]>>;
+    /** The caller's token names a lobby that is gone for good (closed or
+     *  expired): the client can say so instead of showing a bare code entry. */
+    lobbyGone: Schema.optional<typeof Schema.Boolean>;
     membership: Schema.Literal<["none", "pending", "active"]>;
     phase: Schema.NullOr<Schema.Literal<["lobby", "playing", "round_results", "final_scores", "role_selection", "intermission"]>>;
     state: Schema.Literal<["code-entry", "setup", "pending", "lobby", "playing", "role_selection", "final_scores"]>;

package/dist/pages/quiz.schema.js

@@ -70,6 +70,9 @@ const PlayerJourneySchema = Schema.Struct({
 export const QuizJourneyPageSchema = Schema.Struct({
     ...PlayerJourneySchema.fields,
     miss: Schema.NullOr(Schema.Literal("lobby_lost")),
+    /** The caller's token names a lobby that is gone for good (closed or
+     *  expired): the client can say so instead of showing a bare code entry. */
+    lobbyGone: Schema.optional(Schema.Boolean),
 });
 // ---- quiz context (the `/quiz/*` layout's session seed) ----
 const DifficultyFilterSchema = Schema.Literal(...GAME.roundConfig.difficultyOptions);

package/dist/question.schema.d.ts

@@ -53,6 +53,12 @@ export declare const MediaSchema: Schema.Struct<{
         licenceUrl: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
     }>>>;
 }>;
+/** Max characters in a question source URL. */
+export declare const SOURCE_URL_MAX_LEN = 2048;
+/** Max characters in a question source label. */
+export declare const SOURCE_LABEL_MAX_LEN = 200;
+/** Max characters in a post-answer note. */
+export declare const POST_ANSWER_NOTE_MAX_LEN = 160;
 export declare const QuestionSourceSchema: Schema.Struct<{
     url: Schema.filter<Schema.filter<typeof Schema.String>>;
     label: Schema.optional<Schema.filter<typeof Schema.String>>;

package/dist/question.schema.js

@@ -77,13 +77,19 @@ export const MediaSchema = Schema.Struct({
 // 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",
+/** Max characters in a question source URL. */
+export const SOURCE_URL_MAX_LEN = 2048;
+/** Max characters in a question source label. */
+export const SOURCE_LABEL_MAX_LEN = 200;
+/** Max characters in a post-answer note. */
+export const POST_ANSWER_NOTE_MAX_LEN = 160;
+const HttpsUrlSchema = Schema.String.pipe(Schema.maxLength(SOURCE_URL_MAX_LEN, {
+    message: () => `Source URL must be ${SOURCE_URL_MAX_LEN} 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",
+    label: Schema.optional(Schema.String.pipe(Schema.maxLength(SOURCE_LABEL_MAX_LEN, {
+        message: () => `Source label must be ${SOURCE_LABEL_MAX_LEN} characters or fewer`,
     }))),
 });
 const isQuestionSource = Schema.is(QuestionSourceSchema);
@@ -97,8 +103,8 @@ export const StoredQuestionSourceSchema = Schema.transform(Schema.Unknown, Schem
     decode: (source) => (isQuestionSource(source) ? source : undefined),
     encode: (source) => source,
 });
-export const PostAnswerNoteSchema = Schema.String.pipe(Schema.maxLength(160, {
-    message: () => "Post-answer note must be 160 characters or fewer",
+export const PostAnswerNoteSchema = Schema.String.pipe(Schema.maxLength(POST_ANSWER_NOTE_MAX_LEN, {
+    message: () => `Post-answer note must be ${POST_ANSWER_NOTE_MAX_LEN} characters or fewer`,
 }));
 const MetadataSchema = Schema.Struct({
     source: SourceSchema,

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

@@ -16,6 +16,8 @@ export declare const ClientMessageSchema: Schema.Union<[Schema.Struct<{
     role: Schema.Literal<["player", "observer"]>;
 }>, Schema.Struct<{
     type: Schema.Literal<["player:leave"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["player:undo"]>;
 }>, Schema.Struct<{
     type: Schema.Literal<["player:rate"]>;
     questionId: Schema.filter<typeof Schema.NonEmptyString>;
@@ -29,6 +31,7 @@ export declare const ClientMessageSchema: Schema.Union<[Schema.Struct<{
     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"]>>;
+    undoEnabled: Schema.optional<typeof Schema.Boolean>;
     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>;

package/dist/ws-game.schema.js

@@ -46,6 +46,9 @@ const PlayerRoleMessageSchema = Schema.Struct({
 const PlayerLeaveMessageSchema = Schema.Struct({
     type: Schema.Literal("player:leave"),
 });
+const PlayerUndoMessageSchema = Schema.Struct({
+    type: Schema.Literal("player:undo"),
+});
 const PlayerRateMessageSchema = Schema.Struct({
     type: Schema.Literal("player:rate"),
     questionId: BoundedIdSchema,
@@ -104,6 +107,7 @@ const CuratorStartMessageSchema = Schema.Struct({
     difficulty: Schema.optional(DifficultyFilterSchema),
     advanceMode: Schema.optional(Schema.Literal(...GAME.roundConfig.advanceModeOptions)),
     scoringMode: OptionalScoringModeSchema,
+    undoEnabled: Schema.optional(Schema.Boolean),
     // 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))),
@@ -135,5 +139,5 @@ const WsPongMessageSchema = Schema.Struct({
 });
 // 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, PlayerRateMessageSchema, CuratorStartMessageSchema, CuratorAdvanceMessageSchema, CuratorStartRoleSelectionMessageSchema, CuratorIntermissionMessageSchema, CuratorPlayerActionMessageSchema, CuratorStopMessageSchema, CuratorResetMessageSchema, WsPongMessageSchema);
+export const ClientMessageSchema = Schema.Union(WsAuthMessageSchema, PlayerAnswerMessageSchema, PlayerEmoteMessageSchema, PlayerRoleMessageSchema, PlayerLeaveMessageSchema, PlayerUndoMessageSchema, PlayerRateMessageSchema, CuratorStartMessageSchema, CuratorAdvanceMessageSchema, CuratorStartRoleSelectionMessageSchema, CuratorIntermissionMessageSchema, CuratorPlayerActionMessageSchema, CuratorStopMessageSchema, CuratorResetMessageSchema, WsPongMessageSchema);
 const _assertNoClientMessageDrift = null;

package/dist/ws.d.ts

@@ -6,7 +6,7 @@ import type { GameAnswerRecord } from "./game-answer-record.ts";
 import type { MediaCredit, MediaType, QuestionType } from "./question.schema.ts";
 import type { QuestionRating } from "./question-rating.ts";
 import type { StreakFlourish } from "./streak-flourish.ts";
-export type ClientMessage = WsAuthMessage | PlayerAnswerMessage | PlayerEmoteMessage | PlayerRoleMessage | PlayerLeaveMessage | PlayerRateMessage | CuratorStartMessage | CuratorAdvanceMessage | CuratorStartRoleSelectionMessage | CuratorIntermissionMessage | CuratorPlayerActionMessage | CuratorStopMessage | CuratorResetMessage | WsPongMessage;
+export type ClientMessage = WsAuthMessage | PlayerAnswerMessage | PlayerEmoteMessage | PlayerRoleMessage | PlayerLeaveMessage | PlayerUndoMessage | PlayerRateMessage | CuratorStartMessage | CuratorAdvanceMessage | CuratorStartRoleSelectionMessage | CuratorIntermissionMessage | CuratorPlayerActionMessage | CuratorStopMessage | CuratorResetMessage | WsPongMessage;
 /** First frame for native/display (cross-origin, no cookie): authenticates the
  *  socket with the bearer game token (ADR 0014). Web rides the cookie instead. */
 export interface WsAuthMessage {
@@ -35,6 +35,12 @@ export interface PlayerRoleMessage {
 export interface PlayerLeaveMessage {
     type: "player:leave";
 }
+/** Player withdraws their answer to the open question and may answer again.
+ *  Needs the curator's undo flag and remaining budget; the server replies with
+ *  `player:undo-ack`. */
+export interface PlayerUndoMessage {
+    type: "player:undo";
+}
 /** Rate a question revealed in this game — from a signed-in player who played
  *  its round, or the curator. The server answers with `player:rate-ack`
  *  echoing `questionId`; `reason: "disabled"` when the rating flag is off. */
@@ -57,6 +63,8 @@ export interface CuratorStartMessage {
     difficulty?: DifficultyFilter;
     advanceMode?: AdvanceMode;
     scoringMode?: ScoringMode;
+    /** Players may withdraw and redo answers, within a per-player budget. */
+    undoEnabled?: boolean;
     preloadedQuestions?: QuizQuestion[];
 }
 export interface CuratorAdvanceMessage {
@@ -89,7 +97,7 @@ export interface CuratorPlayerActionMessage {
 export interface WsPongMessage {
     type: "pong";
 }
-export type ServerMessage = JoinAcceptedMessage | JoinRejectedMessage | LobbyUpdateMessage | LobbyEndedMessage | LobbyResetMessage | PlayerNicknameChangedMessage | GameStartMessage | GameQuestionMessage | GameTickMessage | PlayerAnsweredMessage | GameRoundResultMessage | GameFinalScoresMessage | GameResultsReadyMessage | RoleSelectionStartMessage | RoleSelectionUpdateMessage | RoleSelectionLockedMessage | PlayerRemovedMessage | GameIntermissionMessage | GameResumeMessage | PlayerEmoteBroadcastMessage | GameErrorMessage | GamePingMessage | PlayerRateAckMessage;
+export type ServerMessage = JoinAcceptedMessage | JoinRejectedMessage | LobbyUpdateMessage | LobbyEndedMessage | LobbyResetMessage | PlayerNicknameChangedMessage | GameStartMessage | GameQuestionMessage | GameTickMessage | PlayerAnsweredMessage | GameRoundResultMessage | GameFinalScoresMessage | GameResultsReadyMessage | RoleSelectionStartMessage | RoleSelectionUpdateMessage | RoleSelectionLockedMessage | PlayerRemovedMessage | GameIntermissionMessage | GameResumeMessage | PlayerEmoteBroadcastMessage | GameErrorMessage | GamePingMessage | PlayerRateAckMessage | PlayerUndoAckMessage | PlayerUnansweredMessage | GameLastCallMessage | GameLastCallCancelledMessage;
 export interface JoinAcceptedMessage {
     type: "join:accepted";
     playerId: string;
@@ -139,6 +147,8 @@ export interface GameStartMessage {
     totalQuestions: number;
     timerDuration: TimerDuration;
     advanceMode: AdvanceMode;
+    /** Undos each player may use this game; absent or 0 = undo is off. */
+    undoBudget?: number;
 }
 /** Question sent to players — isCorrect is omitted to prevent cheating */
 export interface PlayerQuestionAnswer {
@@ -177,6 +187,10 @@ export interface GameQuestionMessage {
      *  resets to 0 until the next player:answered frame). Omitted on broadcast. */
     answeredCount?: number;
     answeredTotal?: number;
+    /** This recipient's undos left, set only on a snapshot replay. */
+    undoRemaining?: number;
+    /** Seconds left of an active last call, set only on a snapshot replay. */
+    lastCallSeconds?: number;
 }
 export interface GameTickMessage {
     type: "game:tick";
@@ -194,6 +208,32 @@ export interface PlayerAnsweredMessage {
     answeredCount: number;
     totalCount: number;
 }
+/** A player withdrew their answer. Curator/display only. */
+export interface PlayerUnansweredMessage {
+    type: "player:unanswered";
+    playerId: string;
+    answeredCount: number;
+    totalCount: number;
+}
+/** Reply to `player:undo`, sent to the acting socket only. */
+export interface PlayerUndoAckMessage {
+    type: "player:undo-ack";
+    ok: boolean;
+    /** Undos the player has left after this request. */
+    remaining: number;
+    /** Why the undo was refused; set when `ok` is false. */
+    reason?: ErrorCode;
+}
+/** Every active hero has answered with undo on: the round closes after
+ *  `seconds` unless an undo cancels the last call. */
+export interface GameLastCallMessage {
+    type: "game:last-call";
+    seconds: number;
+}
+/** An undo during the last call cancelled it; the round resumes its timer. */
+export interface GameLastCallCancelledMessage {
+    type: "game:last-call-cancelled";
+}
 export interface GameRoundResultMessage {
     type: "game:round-result";
     correctAnswerId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orakl/protocol",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Orakl wire contract: WebSocket frames and API response schemas.",
   "license": "AGPL-3.0-only",
   "repository": {