@orakl/protocol 0.14.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

@@ -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/pages/app.schema.d.ts

@@ -431,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;
@@ -498,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;
@@ -513,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

@@ -282,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/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.14.0",
+  "version": "0.15.0",
   "description": "Orakl wire contract: WebSocket frames and API response schemas.",
   "license": "AGPL-3.0-only",
   "repository": {