@joystyk/launcher 0.0.0 → 0.2.0

package/dist/model.d.ts

@@ -0,0 +1,431 @@
+import { type GameOption, type GameManifest, type Json, type Mode, type Outcome, type OutcomeResult, type SeatInfo } from '@joystyk/contracts';
+import { type DailyWordStats } from '@joystyk/daily';
+import type { LocalMode } from '@joystyk/session';
+import type { StoredPreferences } from '@joystyk/storage';
+export type GameStatus = 'available' | 'coming-soon';
+/** What the launcher needs from the page: manifest facts, plus whether the game exists yet. */
+export type LauncherGame = {
+    readonly id: string;
+    readonly name: string;
+    readonly modes: readonly Mode[];
+    /** `default`: the table size the player-count picker starts at against the computer. */
+    readonly players: {
+        readonly min: number;
+        readonly max: number;
+        readonly default?: number | undefined;
+    };
+    readonly aiLevels: readonly string[];
+    readonly status: GameStatus;
+    /** The game plays AI-generated content: it stays locked until the player accepts the notice (D-44). */
+    readonly aiContent?: boolean;
+    readonly options?: readonly GameOption[];
+};
+export declare const MODES: readonly Mode[];
+export declare const isLauncherGame: (value: unknown) => value is LauncherGame;
+/** The launcher's view of a manifest, for pages that have the manifest itself. */
+export declare const launcherGame: (manifest: GameManifest, status?: GameStatus) => LauncherGame;
+/** The AI-content notice (D-44; wording approved as D-52). */
+export declare const AI_NOTICE: {
+    readonly title: "This game uses AI-made content";
+    readonly body: "Some puzzles and clues here are written by an AI model. Each one passes automatic safety checks before it appears, but no person reads every one first, so now and then something may be odd or wrong. If you spot a problem, use Report a problem.";
+    readonly scope: "Accepting unlocks all AI-content games on this device. You can change this anytime in Preferences.";
+};
+/** True when an AI-content game must show the notice before it can start. */
+export declare const needsAiNotice: (game: LauncherGame, preferences: StoredPreferences) => boolean;
+/**
+ * The access gate (monetization.md): where premium games and modes will ask for an
+ * entitlement in v2. Every game is free in v1, so it is always open.
+ */
+export declare const accessGate: (access: GameManifest["access"]) => "open";
+export declare const MODE_LABELS: Readonly<Record<Mode, string>>;
+/** The modes the launcher runs on a local session. The daily puzzle is a local session on today's published config. */
+export declare const toLocalMode: (mode: Mode) => LocalMode | null;
+/** What the stage runs: a local session, or a server room (D-48). P2P rooms arrive later. */
+export type StageMode = LocalMode | 'server';
+export declare const toStageMode: (mode: Mode) => StageMode | null;
+export type ModeOption = {
+    readonly mode: Mode;
+    readonly label: string;
+    readonly playable: boolean;
+    /** Why it can't be picked, or null. */
+    readonly note: string | null;
+};
+/**
+ * What the launcher knows about the room server (`GET /api/rooms/games`): still asking, the
+ * games it hosts, or no usable answer. A manifest may list `server` before the room server
+ * hosts the game; only a hosted game offers Online with friends.
+ */
+export type OnlineRooms = {
+    readonly _tag: 'Checking';
+} | {
+    readonly _tag: 'Hosted';
+    readonly games: readonly string[];
+    readonly protocol: number;
+} | {
+    readonly _tag: 'Unreachable';
+};
+export declare const ONLINE_CHECKING: OnlineRooms;
+export declare const ONLINE_UNREACHABLE: OnlineRooms;
+/** The room server's answer, checked at the boundary; anything else (an error page, a proxy's 502 body) is undefined. */
+export declare const parseHostedGames: (value: unknown) => OnlineRooms | undefined;
+/** True when the room server opens rooms for this game. */
+export declare const hostedOnline: (game: LauncherGame, online: OnlineRooms) => boolean;
+/**
+ * One option per mode in the manifest, in manifest order. Online with friends is playable only
+ * once the room server says it hosts the game; until it answers, and when it can't be reached,
+ * the local modes are unaffected.
+ */
+export declare const modeOptions: (game: LauncherGame, online?: OnlineRooms) => readonly ModeOption[];
+/**
+ * The player counts a mode allows: solo is one; local multiplayer takes two or more; a room
+ * sizes itself. In pass-and-play the count is people: a game with AI and more seats than
+ * people (Hearts, Spades) lets two or more share the device while the computer fills the rest.
+ */
+export declare const playerCounts: (game: LauncherGame, mode: Mode | null) => readonly number[];
+/**
+ * The count the picker starts at for a mode: against the computer, the game's declared
+ * default when the mode offers it (Shift 23 seats five, D-58); otherwise the fewest. Other
+ * modes count people, and a room sizes itself, so the default never applies to them.
+ */
+export declare const startingCount: (game: LauncherGame, mode: Mode | null) => number;
+/** Pass-and-play with fewer people than the game's seats: the computer plays the rest. */
+export declare const computerSeatsFor: (game: LauncherGame, setup: Setup) => number;
+export type Setup = {
+    readonly mode: Mode | null;
+    readonly aiLevel: string | null;
+    readonly players: number;
+    /** Pass-and-play names as typed, by seat. */
+    readonly names: readonly string[];
+    /** A problem per name, by seat, or null. */
+    readonly errors: readonly (string | null)[];
+    /** Online with friends: the invite code (or link) as typed into the join form. */
+    readonly code: string;
+    /** Join to watch, even if a seat is free (D-33). */
+    readonly watch: boolean;
+    /** Why the code can't be used, or null. */
+    readonly codeError: string | null;
+    readonly options?: Readonly<Record<string, string | number | boolean>>;
+};
+export declare const initialSetup: (game: LauncherGame, online?: OnlineRooms) => Setup;
+export declare const isRoomCode: (value: unknown) => value is string;
+/**
+ * The room code in what a player typed or pasted: a code in any case, with spaces or dashes
+ * ("k7m-2qx"), or a whole invite link (`…?room=K7M2QX`). Null when there is none.
+ */
+export declare const parseRoomCode: (input: string) => string | null;
+/** "K7M 2QX": a code grouped for reading aloud and copying by eye. */
+export declare const spacedCode: (code: string) => string;
+/** How the stage opens its room. */
+export type RoomPlan = {
+    readonly action: 'create';
+} | {
+    readonly action: 'join';
+    readonly code: string;
+    readonly watch: boolean;
+};
+/** A clock choice in the lobby (D-34, D-42): a per-move clock, a time bank, or Off. */
+export type ClockSetting = {
+    readonly kind: 'move';
+    readonly ms: number;
+} | {
+    readonly kind: 'bank';
+    readonly initialMs: number;
+    readonly incrementMs: number;
+} | {
+    readonly kind: 'off';
+};
+/** A select option for a clock setting; `value` round-trips through `parseClockValue`. */
+export type ClockOption = {
+    readonly value: string;
+    readonly label: string;
+};
+export declare const clockValue: (setting: ClockSetting) => string;
+export declare const parseClockValue: (value: string | undefined) => ClockSetting | undefined;
+/** "30 seconds a move", "5 minutes, plus 2 seconds a move", "Off". */
+export declare const clockLabel: (setting: ClockSetting) => string;
+/**
+ * The lobby's clock choices for a manifest clock: its presets with the default marked, then
+ * Off, which private rooms always offer and never default to (D-42). None for a game without
+ * a clock.
+ */
+export declare const clockOptions: (clock: GameManifest["clock"]) => readonly ClockOption[];
+/** A seat in the lobby, as the stage reports it. */
+export type RoomSeat = {
+    readonly id: number;
+    readonly name: string;
+    readonly controller: 'human' | 'ai';
+    readonly aiLevel: string | null;
+    /** A player holds the seat (also while the computer covers for them). */
+    readonly claimed: boolean;
+    readonly ready: boolean;
+    readonly connected: boolean;
+};
+/** The current decision clock, for the bar; `paused` while nobody is at the table (D-58). */
+export type RoomTimer = {
+    readonly seat: number;
+    readonly name: string;
+    readonly seconds: number;
+    readonly paused: boolean;
+};
+/** A rematch or end-match offer as the results and the bar show it (D-61). */
+export type RoomOfferFrame = {
+    /** Names the offer in answers. */
+    readonly id: number;
+    readonly kind: 'rematch' | 'end';
+    readonly by: number;
+    readonly byName: string;
+    readonly status: 'open' | 'declined' | 'withdrawn';
+    /** Seats that have accepted (the proposer, and computer seats for a rematch). */
+    readonly accepted: readonly number[];
+    /** The seat that declined, if one did, and its player's name. */
+    readonly declinedBy: number | null;
+    readonly declinedName: string | null;
+    /** Players whose answer an open offer still waits for. */
+    readonly waiting: readonly string[];
+    /** An end offer: whole seconds until the match ends unless someone declines. */
+    readonly seconds: number | null;
+};
+/** What the stage reports about its room after every change: plain data for the lobby and the bar. */
+export type RoomFrame = {
+    readonly code: string;
+    /** The invite link: this game page with `?room=CODE`. */
+    readonly link: string;
+    /** `connecting` until the first snapshot arrives. */
+    readonly phase: 'connecting' | 'lobby' | 'playing' | 'finished' | 'closed';
+    readonly connection: 'connecting' | 'online' | 'reconnecting' | 'closed';
+    /** The viewer's seat; null for a spectator. */
+    readonly seat: number | null;
+    readonly host: number | null;
+    readonly seats: readonly RoomSeat[];
+    readonly minSeats: number;
+    readonly clock: ClockSetting;
+    readonly clockOptions: readonly ClockOption[];
+    readonly aiLevel: string | null;
+    readonly aiLevels: readonly string[];
+    readonly spectators: number;
+    readonly timer: RoomTimer | null;
+    /** The latest rejection or connection problem, worded for players, and its code. */
+    readonly notice: string | null;
+    readonly noticeCode: string | null;
+    /** Counts matches in this room; a rematch raises it. */
+    readonly match: number;
+    /** The latest rematch or end-match offer. */
+    readonly offer: RoomOfferFrame | null;
+};
+/** What the lobby asks of the room. The stage turns each into a room control. */
+export type RoomRequest = {
+    readonly kind: 'ready';
+    readonly ready: boolean;
+} | {
+    readonly kind: 'clock';
+    readonly setting: ClockSetting;
+} | {
+    readonly kind: 'ai-level';
+    readonly level: string;
+} | {
+    readonly kind: 'fill-with-ai';
+    readonly seat: number;
+} | {
+    readonly kind: 'remove-seat';
+    readonly seat: number;
+} | {
+    readonly kind: 'start';
+}
+/** Offer a rematch, or to end the match early (D-61); offering what is already offered accepts it. */
+ | {
+    readonly kind: 'offer';
+    readonly offer: 'rematch' | 'end';
+}
+/** Answer the offer with this id. */
+ | {
+    readonly kind: 'answer';
+    readonly offer: number;
+    readonly answer: 'accept' | 'decline' | 'withdraw';
+} | {
+    readonly kind: 'leave';
+}
+/** Take the seat back after another tab replaced this one. */
+ | {
+    readonly kind: 'reconnect';
+};
+/**
+ * What an offer's state means to the viewer (`me`, null for a spectator), in words. An open
+ * end offer says how long is left unless `countdown` is false (live-region announcements).
+ */
+export declare const offerText: (offer: RoomOfferFrame, me: number | null, countdown?: boolean) => string;
+/**
+ * What to announce (politely) when the room's offer changed: a new offer, an answer, or
+ * nothing. `seats` names the players who accepted.
+ */
+export declare const offerAnnouncement: (before: RoomOfferFrame | null, after: RoomOfferFrame | null, me: number | null, seats: readonly RoomSeat[]) => string | null;
+/** Seats a player or the computer fills. */
+export declare const filledSeats: (room: RoomFrame) => readonly RoomSeat[];
+/** Why the host can't start yet, or null when the match can start (the room checks again). */
+export declare const startProblem: (room: RoomFrame) => string | null;
+/**
+ * A new mode keeps the AI level, and fits the player count to the mode: a count the player
+ * chose carries over when the new mode allows it. In a game that declares a default, a count
+ * still at the old mode's starting count was never chosen, so the new mode starts at its own.
+ */
+export declare const pickMode: (game: LauncherGame, setup: Setup, mode: Mode) => Setup;
+/** The name a seat gets when its field is left empty. */
+export declare const defaultName: (seat: number) => string;
+/** An empty name on a human seat means "the guest's own display name"; the stage fills it in. */
+export declare const GUEST_NAME = "";
+/**
+ * The seats for a setup, numbered from 0, or a problem per pass-and-play name. Solo and
+ * vs-AI play seat the guest first; AI seats are named for the computer.
+ */
+export declare const seatsFor: (game: LauncherGame, setup: Setup) => {
+    readonly ok: true;
+    readonly seats: readonly SeatInfo[];
+} | {
+    readonly ok: false;
+    readonly errors: readonly (string | null)[];
+};
+/** How to start: a new game, the saved one, or not yet (only load and look for a save). */
+export type Begin = 'new' | 'resume' | null;
+/**
+ * What the launcher's view hands the stage element that runs the game. Plain data: the
+ * stage acts on changes (begin, pause, a new reveal, new preferences).
+ */
+export type StageControl = {
+    readonly gameId: string;
+    readonly mode: StageMode;
+    readonly seats: readonly SeatInfo[];
+    readonly begin: Begin;
+    /** True while the platform overlay is open. */
+    readonly paused: boolean;
+    /** How many hand-offs the players have revealed. Each increase reveals one. */
+    readonly reveals: number;
+    /** The player's choices, or null until the stage has read them. */
+    readonly preferences: StoredPreferences | null;
+    /** A rematch's config (the engine's `rematch`), or null for the game's own setup. */
+    readonly config: Json | null;
+    /** Online with friends: how to open the room. Null for local play. */
+    readonly room: RoomPlan | null;
+    /** A validated choice from the resume offer, when this game keeps several saves. */
+    readonly resumeSlot?: string;
+    readonly setup?: Json;
+};
+/** A saved game, as the resume offer describes it. */
+export type SaveSummary = {
+    readonly savedAt: number;
+    readonly elapsedMs: number;
+    readonly players: readonly string[];
+    readonly slot?: string;
+    readonly choices?: readonly {
+        readonly slot: string;
+        readonly label: string;
+        readonly savedAt: number;
+        readonly elapsedMs: number;
+        readonly players: readonly string[];
+    }[];
+};
+/** What the frame needs from each snapshot; the stage reports it only when it changes. */
+export type FrameState = {
+    readonly seats: readonly SeatInfo[];
+    /** Pass-and-play, D-31: the seat the device goes to next, behind the hand-off screen. */
+    readonly handoff: {
+        readonly seat: number;
+        readonly name: string;
+    } | null;
+    readonly outcome: Outcome | null;
+    readonly safePoint: boolean;
+    /** The latest rejection or problem, worded for players. */
+    readonly notice: string | null;
+};
+/**
+ * The daily puzzle's results, as the stage reports them after recording the result
+ * (content-pipeline.md, "Results and streaks" and "Share text"). Plain data.
+ */
+export type DailyFrame = {
+    readonly statistics?: DailyWordStats;
+    /** The puzzle's UTC date, `yyyy-mm-dd`. */
+    readonly date: string;
+    /** The share text in both forms: emoji rows, and the rows in words for *Copy as text*. */
+    readonly share: string;
+    readonly shareWords: string;
+    /** Days finished in a row, and the best run. */
+    readonly streak: number;
+    readonly bestStreak: number;
+    /** Days won in a row, for a daily that can be lost; null otherwise. */
+    readonly winStreak: number | null;
+    readonly bestWinStreak: number | null;
+    /** "New puzzle at 8:00 PM (in 6 hours)", in the player's own time. */
+    readonly next: string;
+    /** Set when today's puzzle was already finished before this visit: its result and summary. */
+    readonly earlier: {
+        readonly result: OutcomeResult;
+        readonly summary: string;
+    } | null;
+};
+export type StageOutput = {
+    readonly _tag: 'Prepared';
+    readonly save: SaveSummary | null;
+    readonly preferences: StoredPreferences;
+}
+/** The player changed a preference in another tab of the site (gp-d4v). */
+ | {
+    readonly _tag: 'Preferences';
+    readonly preferences: StoredPreferences;
+} | {
+    readonly _tag: 'Frame';
+    readonly frame: FrameState;
+} | {
+    readonly _tag: 'ExitRequested';
+} | {
+    readonly _tag: 'Announce';
+    readonly message: string;
+    readonly politeness: 'polite' | 'assertive';
+} | {
+    readonly _tag: 'Notice';
+    readonly message: string;
+}
+/** At the outcome, when the engine names a rematch config: what "Play again" starts with. */
+ | {
+    readonly _tag: 'Rematch';
+    readonly config: Json;
+}
+/** Online with friends: the room after every change (and each second while a clock runs). */
+ | {
+    readonly _tag: 'Room';
+    readonly room: RoomFrame;
+}
+/** The daily puzzle: its recorded result, streaks and share text, or today's earlier result. */
+ | {
+    readonly _tag: 'Daily';
+    readonly daily: DailyFrame;
+}
+/** The puzzle the game plays, when the stage knows its ID (a daily puzzle): for "Report a problem". */
+ | {
+    readonly _tag: 'Puzzle';
+    readonly puzzleId: string;
+} | {
+    readonly _tag: 'Failed';
+    readonly message: string;
+};
+export declare const isStoredPreferences: (value: unknown) => value is StoredPreferences;
+/** Checks a stage report at the boundary; anything unexpected is dropped. */
+export declare const parseStageOutput: (value: unknown) => StageOutput | undefined;
+export type ResultView = {
+    readonly result: OutcomeResult;
+    readonly headline: string;
+    readonly summary: string;
+    readonly elapsedMs: number | null;
+    /** "Assisted: 2 undos, hints", or null for an unassisted game. */
+    readonly assisted: string | null;
+};
+/** "0:42", "12:05", "1:02:03". */
+export declare const formatElapsed: (ms: number) => string;
+/** An ISO 8601 duration for `<time datetime>`: "PT1M5S". */
+export declare const isoDuration: (ms: number) => string;
+/** The assistance line for an outcome, from what the runner recorded, or null when there was none. */
+export declare const assistLine: (outcome: Outcome) => string | null;
+/**
+ * The results screen's words for an outcome. In a room the headline depends on who is
+ * looking: `viewer` is the player's seat, or null for a spectator, who hears who won.
+ */
+export declare const resultView: (outcome: Outcome, seats: readonly SeatInfo[], mode: StageMode, viewer?: number | null) => ResultView;
+/** One preference control's change, parsed from its name and value, or undefined if invalid. */
+export declare const parsePreferenceChange: (name: string, value: string | undefined, checked: boolean | undefined) => Partial<StoredPreferences> | undefined;