@jgengine/core 0.9.0 → 0.11.0

package/dist/game/playableGame.d.ts

@@ -1,6 +1,10 @@
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
+import type { MusicTheme } from "../audio/music.js";
+import type { PostProcessingConfig } from "../render/postProcessing.js";
+import type { LookPreset } from "../render/lookPreset.js";
 import type { TouchControlsConfig } from "../input/touchScheme.js";
 import type { GameSettingsConfig } from "../settings/settingsModel.js";
+import type { GameOrientation } from "../ui/orientation.js";
 import type { HudPlatform, HudViewportConfig } from "../ui/hudScale.js";
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
 import type { CatalogEntityRole, GameContext, GameContextContent } from "../runtime/gameContext.js";
@@ -47,6 +51,10 @@ export interface CameraFollowState {
     };
     distance: number;
 }
+/** Props handed to a `WorldOverlay` component (#542): explicit `ctx` access so canvas-layer VFX read live engine state directly, without an extra hook or a module-global workaround. */
+export interface WorldOverlayProps {
+    ctx: GameContext;
+}
 export interface FirstPersonCameraConfig {
     /** Camera height above the followed entity's origin. Default 1.6. */
     eyeHeight?: number;
@@ -56,7 +64,7 @@ export interface FirstPersonCameraConfig {
     maxPitch?: number;
     /** Show the centered crosshair overlay. Default true. */
     reticle?: boolean;
-    /** Render a simple first-person weapon in view. Default true. */
+    /** Render a viewmodel in view: the built-in three-mesh gun, or `PlayableGame.viewmodel` when set (#542). `false` renders no viewmodel regardless of `PlayableGame.viewmodel`. Default true. */
     viewmodel?: boolean;
 }
 /**
@@ -74,7 +82,7 @@ export interface FirstPersonCameraConfig {
  * - `observer` — detached spectator/photo cam bound to any entity or fixed point; never reads player input.
  * - `turntable` — slow auto-orbit of a fixed point: a rotating display stand for a scene. The friendly, flat spelling of `observer`'s point-orbit mode; providing `camera.turntable` selects it without an explicit `rig`.
  * - `sideScroll` — fixed lateral follow (2.5D platformer/beat-'em-up side view); reads no player input.
- * - `inspection` — model-viewer rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor; orbits a fixed point, reads no player/entity input.
+ * - `inspection` — model-viewer / editor rig (#207.7, #866): middle-drag pan, right-drag orbit, scroll zoom toward a configurable anchor; orbits a fixed point, reads no player/entity input.
  * - `none` — no camera rig is mounted; use for HUD-only presentations or a game that manages its own camera.
  */
 export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none";
@@ -323,7 +331,7 @@ export interface InspectionCameraConfig {
     /** Vertical orbit clamp (radians). Unset allows a full pole-to-pole orbit, unlike the tighter default on the classic orbit rig. */
     minPolarAngle?: number;
     maxPolarAngle?: number;
-    /** Middle-mouse/right-drag pan. Default true for this rig. */
+    /** Middle-mouse pan. Default true for this rig. */
     pan?: boolean;
     rotateSpeed?: number;
     zoomSpeed?: number;
@@ -438,6 +446,10 @@ export interface GameCameraConfig {
     };
     initialDistance?: number;
     initialHeight?: number;
+    /** Initial horizontal boom facing (radians): 0 = camera behind on -Z, PI = camera on +Z. Seeds the orbit rig; unset keeps the legacy -Z placement. */
+    initialYaw?: number;
+    /** Initial boom elevation (radians): 0 = level, positive = camera above the target looking down. Seeds the orbit rig; unset derives elevation from `initialHeight`/`initialDistance`. */
+    initialPitch?: number;
     /** Lock orbit radius while the follow target moves (default true in shell). */
     followLock?: boolean;
     /** When false, orbit target stays fixed (cinematic / debug). Default true. */
@@ -455,6 +467,14 @@ export interface GameCameraConfig {
     /** Vertical look clamp (three.js polar angle, radians): 0 = top-down over the head, PI/2 = level, >PI/2 = look up from below. Widen for top-down or vertical aim; unset keeps the standard chase feel. */
     minPolarAngle?: number;
     maxPolarAngle?: number;
+    /** Signed boom-elevation clamp `[min, max]` (radians): min < 0 dips the camera below the target, max > 0 rises overhead. Maps onto `minPolarAngle`/`maxPolarAngle` (polar = PI/2 − pitch); explicit polar fields win. */
+    pitchClamp?: readonly [number, number];
+    /** Spring-arm occlusion for the orbit rig: pull the camera in past walls/terrain so it never clips inside geometry. Off unless `enabled`. */
+    collision?: {
+        enabled?: boolean;
+        padding?: number;
+        minTargetDistance?: number;
+    };
 }
 export interface EntitySpriteConfig {
     url: string;
@@ -492,6 +512,21 @@ export interface VoxelCollisionConfig {
     /** Tallest ledge walked up without jumping. Default 0.6. */
     stepHeight?: number;
 }
+/** Movement-state clip set for `ModelAnimationConfig.states`: the shell reads the entity's live speed each frame and crossfades between these clips, so a walking mob animates without any game-side driver. */
+export interface ModelAnimationStates {
+    /** Clip name while the entity is stationary. */
+    idle: string;
+    /** Clip name while the entity is moving. */
+    walk: string;
+    /** Clip name above `runSpeed`; omit to keep `walk` at any speed. */
+    run?: string;
+    /** Speed (world units/sec) above which the entity counts as moving. Default 0.5. */
+    walkSpeed?: number;
+    /** Speed above which `run` plays when provided. Default 6. */
+    runSpeed?: number;
+    /** Crossfade duration in seconds when the state changes. Default 0.2. */
+    fadeSec?: number;
+}
 /** Rig playback for a `ModelConfig`'s GLTF animation clips — looping idles, one-shots, and held poses. */
 export interface ModelAnimationConfig {
     /** Clip name to play; defaults to the GLB's first clip. */
@@ -504,6 +539,26 @@ export interface ModelAnimationConfig {
     paused?: boolean;
     /** Seek the clip to this time in seconds; combine with `paused: true` to hold a specific pose ("pose library" usage). */
     time?: number;
+    /** Speed-driven idle/walk/run clip switching, crossfaded by the shell from the entity's live movement; overrides `clip` while set. */
+    states?: ModelAnimationStates;
+    /**
+     * One-shot clips keyed by event name, each played once over the locomotion state then released back to it.
+     * Reserved keys `hit` and `death` auto-fire on this entity's `combat.hitReaction` / `entity.died`; any other
+     * key fires when the game emits `entity.animation` (`ctx.game.playEntityAnimation(instanceId, event)`). A
+     * `string[]` picks a random variant per trigger. `death` clamps on its final frame instead of returning.
+     */
+    oneShots?: Record<string, string | readonly string[]>;
+}
+/**
+ * Real PBR map URLs (e.g. `buildMaterialCatalog(...).resolve(id)!.maps` from `@jgengine/assets`)
+ * layered onto a model's material — the seam for texturing an otherwise-flat/untextured GLB. Any
+ * role may be omitted to keep the model's own map.
+ */
+export interface ModelMaterialMaps {
+    color?: string;
+    normal?: string;
+    roughness?: string;
+    ao?: string;
 }
 /** Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph. */
 export interface ModelMaterialOverride {
@@ -512,10 +567,38 @@ export interface ModelMaterialOverride {
     roughness?: number;
     emissive?: string;
     emissiveIntensity?: number;
+    /** Real PBR texture maps applied over the model's material — see {@link ModelMaterialMaps}. */
+    maps?: ModelMaterialMaps;
+}
+/** Parents a prop/weapon model to a named bone or node on the host model's rig — a sword on `handslot.r`, a spellbook offhand — following the bone's animated transform each frame. */
+export interface ModelAttachment {
+    /** Bone or node name in the rig to parent to (e.g. `"handslot.r"`). */
+    slot: string;
+    /** The attached model — a catalog asset id or an inline `ModelConfig`. */
+    model: string | ModelConfig;
+    /** Local position offset at the bone, in the attached model's own space. */
+    position?: [number, number, number];
+    /** Local Euler rotation (radians) applied at the bone. */
+    rotation?: [number, number, number];
+    /** Uniform scale of the attached model at the bone. Default 1. */
+    scale?: number;
+}
+/** Static child model stacked at a fixed local offset under its parent's transform — no bone/rig resolution, unlike `ModelAttachment`. Assembles a compound entity (e.g. a modular castle wall + tower + roof) from several single-mesh kit pieces. */
+export interface ModelPart {
+    /** The child model — a catalog asset id or an inline `ModelConfig`; resolves through the catalog exactly like the top-level model and gets its own `dims`/anchor centering. */
+    model: string | ModelConfig;
+    /** Local position offset under the parent's transform. */
+    position?: [number, number, number];
+    /** Local Euler rotation (radians) under the parent's transform. */
+    rotation?: [number, number, number];
+    /** Uniform scale of the part under the parent's transform. Default 1. */
+    scale?: number;
 }
 export interface ModelConfig {
     url: string;
     scale?: number;
+    /** Normalize the rendered model to this world-unit height: the shell measures the loaded scene's bounding box, scales it so its height matches, and grounds its lowest point at the placement Y. Composes with `scale` as a multiplier. */
+    targetHeight?: number;
     y?: number;
     /** How the model registers on its placement point. `"center"` (default) horizontally centers the measured footprint on the point and ground-snaps its lowest vertex to the point's Y — the correct behavior for corner-pivot modular kits. `"origin"` renders at the raw GLB origin (legacy). */
     anchor?: "center" | "origin";
@@ -525,6 +608,10 @@ export interface ModelConfig {
     material?: ModelMaterialOverride;
     /** Plays a GLTF animation clip on the model when the source has any (skinned or not); omit to render the rig's bind pose. */
     animation?: ModelAnimationConfig;
+    /** Props/weapons parented to named bones on this model's rig; each follows its bone through animation. */
+    attachments?: readonly ModelAttachment[];
+    /** Static kit-of-parts pieces stacked at fixed local offsets — no bone/rig involved. Use this for a compound entity assembled from several modular meshes (a castle keep from base + mid + roof pieces); use `attachments` for props parented to an animated rig's bones. */
+    parts?: readonly ModelPart[];
 }
 export interface ObjectStyle {
     color?: string;
@@ -540,6 +627,14 @@ export interface DirectionalLightingConfig {
     intensity?: number;
     position: readonly [number, number, number];
     castShadow?: boolean;
+    /** Shadow map resolution in px (square) when `castShadow`. Higher = crisper, costlier. Default 1024. */
+    shadowMapSize?: number;
+    /** Half-extent of the orthographic shadow camera in world units — sized to the shadowed area. Default 40. */
+    shadowCameraSize?: number;
+    /** Shadow depth bias to fight acne. Default -0.0004. */
+    shadowBias?: number;
+    /** Shadow normal bias to fight peter-panning. Default 0.02. */
+    shadowNormalBias?: number;
 }
 export interface HemisphereLightingConfig {
     skyColor?: string;
@@ -579,6 +674,18 @@ export interface PlayerMovementConfig {
     beforeCommit?: (frame: MovementCommitFrame) => readonly [number, number, number] | undefined | void;
     /** Gates the built-in sprint (`runSpeedMultiplier`) behind live game state — a stamina stat, an encumbrance check (#282.3). Called each frame while sprint is held; `false` walks. */
     canSprint?: (ctx: GameContext) => boolean;
+    /** Fraction of walk speed while backpedalling (holding `moveBack`). Overrides the engine default (0.65). */
+    backpedalMult?: number;
+    /** Radians/second the rendered body rotates toward its movement heading (shortest arc), so strafing/backpedalling read as a turn rather than an instant flip; also the rate the internally-integrated `turnLeft`/`turnRight` heading turns when the shell doesn't own yaw. Unset = body facing snaps instantly (no change to existing feel). */
+    turnSpeed?: number;
+    /** On-foot swimming when the terrain declares a `waterLevel` and the player is submerged: caps speed and floats them at the surface. `true` uses defaults; default off. */
+    swim?: {
+        speedMultiplier?: number;
+    } | boolean;
+    /** Slide the player downhill on terrain steeper than they can stand on (heightfield worlds only). `true` uses defaults; default off. */
+    slopeSlide?: {
+        maxClimbSlope?: number;
+    } | boolean;
 }
 /** One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`. */
 export interface MovementCommitFrame {
@@ -589,17 +696,36 @@ export interface MovementCommitFrame {
     /** The live game context (#282.2) — movement rules read stores/stats directly instead of module-level bridge objects. */
     ctx: GameContext;
 }
-export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never> {
+/** How a screenshot host reaches live gameplay in this game — the data behind `shoot --mode play`. */
+export interface GameCaptureConfig {
+    /** Commands run (in order, via `ctx.game.commands.run`) right after boot when a capture host requests the play screen — the same commands the start-menu buttons dispatch. A bare string runs with a default input; the object form carries the input a command needs (e.g. `[{ name: "class.select", input: { classId: "siren" } }, "startRun"]`). A name the game never registers fails the capture loudly instead of shipping a menu screenshot. */
+    play?: readonly (string | {
+        name: string;
+        input?: unknown;
+    })[];
+    /** Named capture states beyond live gameplay — any screen worth screenshotting on demand (`lobby`, `store`, `game_over`), each mapping to the command sequence that reaches it from boot. `shoot <game> --state <name>` runs that sequence and captures whatever is on screen — menus included, no live-play guard. An unknown state name fails the capture with the declared list. */
+    states?: Record<string, readonly (string | {
+        name: string;
+        input?: unknown;
+    })[]>;
+    /** Extra milliseconds the capture host waits after `play` commands before taking the play-mode screenshot — cover an intro cinematic or spawn-in fade. Default 2500. */
+    settleMs?: number;
+    /** Bot-playtest read hook: maps live game state to a flat vector of numeric progress metrics the `drive --playtest` harness samples over time (e.g. `{ x, z, score, phase }`). Genre-agnostic — "progress" is whatever the game reports; the engine stays neutral. The harness watches these numbers move under scripted input: any metric changing beyond an epsilon counts as forward progress, all metrics flat past the softlock threshold under active input flags a softlock. Return every value that should count as advancing; omit to opt the game out of the playtest rung. */
+    probe?: (ctx: GameContext) => Record<string, number>;
+}
+export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never, TViewmodel = unknown, TOverlay = TWorldOverlay> {
     game: GameDefinition;
     content: GameContextContent;
-    loop: Required<GameLoop<GameContext>>;
+    loop: Required<Omit<GameLoop<GameContext>, "onPlayerLeave">> & Pick<GameLoop<GameContext>, "onPlayerLeave">;
     GameUI: TUi;
     /** Which shell mount to use. Default `"3d"` (canvas, camera rig, pointer, world rendering). `"hud"` mounts no 3D canvas, camera rig, or pointer — the game is `GameUI` plus the command/input loop, for board/card/menu games. */
     presentation?: "3d" | "hud";
-    /** Optional canvas-layer VFX component (e.g. traveling projectiles). */
-    WorldOverlay?: TWorldOverlay;
+    /** Optional canvas-layer VFX component (e.g. traveling projectiles); receives `{ ctx }` (#542) so overlay VFX read live engine state without a separate hook or a module-global workaround. */
+    WorldOverlay?: TOverlay;
     /** Replaces the default demo backdrop (ground + grid + rocks) with the game's own scene — ground, sky, structures. Camera, input, HUD, entity rendering, and the loop stay shell-provided; supply your world without forking the shell. When unset and `game.world` is an `environment()` descriptor, the shell auto-renders that world here — no manual wiring needed. */
     environment?: TWorldOverlay;
+    /** Custom first-person viewmodel (#542), read when the active rig is first-person. Rendered inside the shell's camera-locked, muzzle-tracked anchor in place of the built-in three-mesh gun; receives a live `cuesRef` (velocity/bob/firing/reloading/recoil) driven from the followed entity — see `@jgengine/shell/camera`'s `ViewmodelProps`. Set `camera.firstPerson.viewmodel: false` to render no viewmodel at all regardless of this field. */
+    viewmodel?: TViewmodel;
     /** Per-entity visual override: return your own mesh for an entity and the shell still positions it and drives selection/targeting. Return null/undefined to fall back to model → sprite → primitive. */
     renderEntity?: TRenderEntity;
     /** Per-object visual override: return your own mesh for a placed scene object and the shell still positions it and drives picking. Return null/undefined to fall back to objectModels → styled box. */
@@ -618,27 +744,45 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     prompts?: (ctx: GameContext) => readonly PositionedPrompt[];
     /** Camera tuning (perspective, orbit, first-person) for the dev game player shell. */
     camera?: GameCameraConfig;
+    /** Screenshot-host recipe for reaching live gameplay past a start menu (`shoot --mode play` runs `capture.play` automatically). Any game with a start/title screen declares this. */
+    capture?: GameCaptureConfig;
     /** Cast/receive shadows across the scene (R3F Canvas shadow pass). Default true. */
     shadows?: boolean;
     /** Pointer-driven input: click-to-move, box-select, right-click verbs, cursor aim (#22/#30/#31). */
     pointer?: PointerConfig;
     /** Touch controls on coarse-pointer devices. Unset derives a scheme from `input` (virtual joystick for movement actions, on-screen buttons for the rest); a config refines it with gestures and curated buttons; `false` opts out. */
     touch?: TouchControlsConfig | false;
-    /** Preferred phone orientation. When a coarse-pointer device is held the other way the shell shows a dismissible rotate hint; purely advisory, never blocks play. */
-    orientation?: "landscape" | "portrait";
+    /** Phone orientation contract. Legacy `"landscape"`/`"portrait"` stays advisory (a dismissible rotate hint). The object form `{ mobile: "landscape-required" }` is strict — the shell shows an engine-owned rotate screen and blocks gameplay until the device is turned. See `GameOrientation`. */
+    orientation?: GameOrientation;
     /** Where the game is meant to be played. Default `["web", "mobile"]` — design-resolution HUD fit is on for every game: `HudCanvas` auto-scales from `hudFit.designSize` down to the live viewport, so the desktop layout shrinks to fit a phone instead of overflowing it. Declare `["web"]` to opt a desktop-only game out (compact displays fall back to the legacy fixed 0.85 zoom). */
     platforms?: readonly HudPlatform[];
     /** HUD design resolution + scale clamps (default 1600×900, scale 0.4–1). `mobile` overrides tune the phone fit separately — the same resolution system drives desktop UI-scale and phone shrink. */
     hudFit?: HudViewportConfig;
-    /** Opt in to world-space health bars floating over non-local entities that carry the stat. `roles` restricts bars to entities whose catalog entry declares one of the given roles. */
+    /** Opt in to world-space health bars floating over non-local entities that carry the stat. `roles` restricts bars to entities whose catalog entry declares one of the given roles; `maxDistance` hides bars beyond this many world units from the player (default 60). */
     worldHealthBars?: boolean | {
         statId?: string;
         roles?: readonly CatalogEntityRole[];
+        maxDistance?: number;
+    };
+    /**
+     * Opt in to billboarded nameplates (name + optional HP bar) floating over non-local entities — the
+     * MMO "who's this and how hurt are they" readout. `roles` restricts to entities whose catalog entry
+     * declares one of the given roles (default: all); `maxDistance` hides nameplates beyond this many
+     * world units from the player (default 40). Headless: skin every part via `className`/`data-*` hooks
+     * on `WorldNameplates` (`@jgengine/shell/world/WorldHud`) — this flag only turns the readout on and
+     * scopes which entities it covers.
+     */
+    nameplates?: boolean | {
+        statId?: string;
+        roles?: readonly CatalogEntityRole[];
+        maxDistance?: number;
     };
-    /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. */
+    /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. `sounds` may be sample (`url`) or procedural (`synth`); `music` holds procedural themes crossfaded via `ctx.game.audio.music(id)`. */
     audio?: {
         sounds: Record<string, SoundDef>;
         buses?: Record<string, AudioBusDef>;
+        music?: Record<string, MusicTheme>;
+        musicBus?: string;
     };
     /** Continuous positional emitter keyed by entity kind name: while a matching entity exists, the shell plays and repositions the mapped `audio.sounds` id (looping engine hum, campfire crackle, footstep loop) with listener-distance falloff. */
     entitySounds?: Record<string, string>;
@@ -650,11 +794,15 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     collision?: VoxelCollisionConfig;
     /** Movement-control levers (axis/grid constraints, object collision, pre-commit hook) for the shell-driven walk controller. */
     movement?: PlayerMovementConfig;
+    /** Default-look preset (#773). Unset/`"cinematic"` composes a real sky, a shadow-casting sun+hemisphere rig, a network-free image-based-lighting environment (soft PBR reflections), and a tuned tone-map/bloom/AO/vignette post stack, so a scene reads lit-like-a-game out of the box; `"flat"` opts out to the bare ambient+directional default. Upgraded default primitive materials (tuned PBR + subtle procedural surface detail) apply under both presets. Any explicit `lighting`/`backdrop`/`postProcessing` always wins. */
+    look?: LookPreset;
     /** Declarative ambient/directional/hemisphere lighting (#207.5); replaces the shell's hardcoded default lights when present, regardless of world kind. */
     lighting?: LightingConfig;
     /** Generic background/sky/fog (#207.6), applied for any world kind including a custom `environment` component. */
     backdrop?: BackdropConfig;
-    /** F2 debug overlay (frame/sim timing, logs, backend latency, keybinds, live tunables). On for every game by default; `false` disables the toggle. */
+    /** Declarative post-processing chain (AO/bloom/tone-map/grade). When set, the shell mounts an EffectComposer and owns the render; absent leaves the renderer drawing directly (unchanged). */
+    postProcessing?: PostProcessingConfig;
+    /** F2+D debug overlay (frame/sim timing, logs, backend latency, keybinds, live tunables). On for every game by default; `false` disables the toggle. */
     devtools?: boolean;
     /** Player settings menu. Auto-mounted for every game (Sound / Graphics / Gameplay / Controls); unset uses the defaults, `false` opts out. Add game-specific rows via `extra`, switch overlay/full-page via `mode`, or swap the gear for compact on-screen buttons via `surface: "quick"`. */
     settings?: GameSettingsConfig | false;

package/dist/game/quest.d.ts

@@ -89,7 +89,15 @@ export interface QuestJournal {
     bind(action: "entity.died" | "inventory.added"): () => void;
     snapshot(userId: string): QuestSnapshotEntry[];
     hydrate(userId: string, data: QuestSnapshotEntry[]): void;
+    /** Whole-store capture across every user — the world-save/replication seam (per-user `snapshot` can't enumerate users). */
+    snapshotAll(): Record<string, QuestSnapshotEntry[]>;
+    hydrateAll(data: Record<string, QuestSnapshotEntry[]>): void;
 }
+/**
+ * Track accepted quests and their per-objective progress, granting rewards on completion.
+ *
+ * @capability quest-log track accepted quests and their per-objective progress
+ */
 export declare function createQuestJournal(deps: QuestJournalDeps): QuestJournal;
 export interface QuestAcceptOptions {
     hasUnlock?(id: string): boolean;

package/dist/game/quest.js

@@ -1,6 +1,11 @@
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
+/**
+ * Track accepted quests and their per-objective progress, granting rewards on completion.
+ *
+ * @capability quest-log track accepted quests and their per-objective progress
+ */
 export function createQuestJournal(deps) {
     const catalog = new Map();
     const users = new Map();
@@ -230,6 +235,30 @@ export function createQuestJournal(deps) {
             }
             users.set(userId, quests);
         },
+        snapshotAll() {
+            const out = {};
+            for (const [userId, quests] of users) {
+                out[userId] = Array.from(quests, ([questId, state]) => ({
+                    questId,
+                    status: state.status,
+                    progress: Object.fromEntries(state.progress),
+                }));
+            }
+            return out;
+        },
+        hydrateAll(data) {
+            users.clear();
+            for (const [userId, entries] of Object.entries(data)) {
+                const quests = new Map();
+                for (const entry of entries) {
+                    quests.set(entry.questId, {
+                        status: entry.status,
+                        progress: new Map(Object.entries(entry.progress)),
+                    });
+                }
+                users.set(userId, quests);
+            }
+        },
     };
 }
 export function applyQuestRewards(rewards, appliers) {

package/dist/game/race.d.ts

@@ -135,4 +135,145 @@ export declare class RaceState {
     private compare;
     update(now: number, positions: Record<string, readonly [number, number, number]> | Map<string, readonly [number, number, number]>): readonly RaceEvent[];
 }
+/**
+ * A checkpoint race state machine — laps, forks, live standings, splits, and pluggable win conditions.
+ *
+ * @capability race-track a checkpoint race with laps, standings, splits, and win conditions
+ */
 export declare function createRaceState(config: RaceStateConfig): RaceState;
+/** Wall-clock lap timing: the current/last/best/total split-book every racing HUD reads. */
+export interface LapTimerSnapshot {
+    /** Seconds elapsed in the lap now underway. */
+    currentLap: number;
+    /** Duration of the lap just completed, or `null` before the first lap closes. */
+    lastLap: number | null;
+    /** Fastest completed lap so far, or `null` before the first lap closes. */
+    bestLap: number | null;
+    /** Total time across every lap, including the current one. */
+    total: number;
+    /** Number of laps completed. */
+    lapCount: number;
+    /** Completed lap durations in order — the split book for a results screen. */
+    splits: readonly number[];
+}
+/**
+ * Wall-clock lap timer complementing {@link RaceState}: feed it `tick(dt)` each frame and call
+ * `completeLap()` when the race emits a player `lap.completed` event. It accumulates the current lap,
+ * carries best/last, banks splits, and `penalize()` folds a time penalty into the running lap — the
+ * timing bookkeeping every racer reimplemented on top of the position-only race state.
+ */
+export interface LapTimer {
+    /** Advance the current lap and total by `dt` seconds. */
+    tick(dt: number): void;
+    /** Close the current lap: bank its split, update last/best, reset the current lap to 0, and return its time. */
+    completeLap(): number;
+    /** Add a time penalty (seconds) to the lap currently underway. */
+    penalize(seconds: number): void;
+    /** Clear all timing back to the start line. */
+    reset(): void;
+    /** Immutable view of the current timing state. */
+    snapshot(): LapTimerSnapshot;
+}
+/**
+ * Create a {@link LapTimer} starting at lap 0 with no splits, best, or last time recorded.
+ *
+ * @capability lap-timer wall-clock current/last/best lap timing with splits
+ */
+export declare function createLapTimer(): LapTimer;
+/**
+ * The lifecycle every race runs through before, during, and after the clock: `idle` on the grid,
+ * `countdown` on the lights, `racing` once they go green, `finished` at the flag. A pure value driven
+ * by the transition functions below — it carries no track, racer, or lap data, so it composes with
+ * {@link RaceState} (position/laps) and {@link LapTimer} (wall-clock) rather than duplicating them.
+ */
+export type RacePhase = "idle" | "countdown" | "racing" | "finished";
+/** Immutable lifecycle snapshot: the current {@link RacePhase} plus the two clocks it owns. */
+export interface RaceSessionState {
+    /** Where the session sits in the start→countdown→race→finish lifecycle. */
+    readonly phase: RacePhase;
+    /** Seconds left on the countdown, or 0 outside the `countdown` phase. */
+    readonly countdown: number;
+    /** Seconds of green-flag racing accumulated so far. */
+    readonly elapsed: number;
+}
+/** Options for {@link startRaceCountdown}. */
+export interface RaceCountdownOptions {
+    /** Countdown length in seconds before the race goes green (default 3). A value ≤ 0 starts racing immediately. */
+    readonly seconds?: number;
+}
+/**
+ * The pre-race session on the grid: `idle`, both clocks at zero. Call {@link startRaceCountdown} to
+ * light the lights, or hold here until the field is ready.
+ *
+ * @capability race-session pure idle→countdown→racing→finished clock every racer wraps around its state
+ */
+export declare function idleRaceSession(): RaceSessionState;
+/**
+ * Drop the lights: return a fresh `countdown` session of `seconds` (default 3). A non-positive length
+ * skips straight to `racing` for a standing start with no countdown.
+ */
+export declare function startRaceCountdown(options?: RaceCountdownOptions): RaceSessionState;
+/**
+ * Advance the session by `dt` seconds: bleed the countdown down and flip to `racing` when it reaches
+ * zero, or accumulate `elapsed` while `racing`. `idle` and `finished` are inert. Overshoot past the
+ * countdown is dropped rather than banked into `elapsed`, so the race clock always starts from zero.
+ */
+export declare function tickRaceSession(session: RaceSessionState, dt: number): RaceSessionState;
+/** Cross the flag: move a `racing` session to `finished`, freezing its `elapsed`. A no-op in any other phase. */
+export declare function finishRaceSession(session: RaceSessionState): RaceSessionState;
+/** Whether a racer won or lost, derived from where they placed against the winning-places cutoff. */
+export type RaceOutcome = "win" | "lose";
+/** A racer's finishing position (`place`, 1-based) in a finish order, and the {@link RaceOutcome} it earns. */
+export interface RacePlacement {
+    readonly racerId: string;
+    /** 1-based finishing position: `1` is the winner. */
+    readonly place: number;
+    readonly outcome: RaceOutcome;
+}
+/** Options for {@link racePlacements} / {@link placementOf} / {@link raceOutcomeOf}. */
+export interface PlacementOptions {
+    /** How many top places count as a win (default 1). A podium finish would pass `3`. */
+    readonly winningPlaces?: number;
+}
+/**
+ * Turn a finish-order ranking (index 0 = winner, e.g. the `ranking` of a `race.finished` event) into
+ * per-racer {@link RacePlacement}s — the `1st/2nd/3rd` + win/lose every results screen shows.
+ *
+ * @capability race-placements finish order into per-racer place + win/lose for a results screen
+ */
+export declare function racePlacements(finishOrder: readonly string[], options?: PlacementOptions): readonly RacePlacement[];
+/**
+ * One racer's {@link RacePlacement} within a finish order, or `null` if they never crossed the line.
+ *
+ * @capability race-placements look up one racer's place + win/lose within a finish order
+ */
+export declare function placementOf(finishOrder: readonly string[], racerId: string, options?: PlacementOptions): RacePlacement | null;
+/**
+ * The win/lose verdict for one racer in a finish order — `ranking[0] === player ? "win" : "lose"`, the
+ * check every racing game hand-rolls, generalized to a `winningPlaces` cutoff. A racer absent from the
+ * order counts as a `lose`.
+ */
+export declare function raceOutcomeOf(finishOrder: readonly string[], racerId: string, options?: PlacementOptions): RaceOutcome;
+/**
+ * Per-segment durations from a cumulative split book (`splits[i]` = elapsed time at checkpoint `i`):
+ * `segments[i] = splits[i] − splits[i−1]`, the first measured from `start` (default 0). Turns the
+ * cumulative splits {@link RacerProgress} records into the individual leg times a results screen shows.
+ *
+ * @capability lap-splits turn cumulative split times into per-segment leg times
+ */
+export declare function splitSegments(splits: readonly number[], start?: number): number[];
+/**
+ * Per-lap durations from a cumulative split book with `gatesPerLap` checkpoints per lap — each lap's time
+ * is its finish-gate split minus the previous lap's finish. Only complete laps are returned.
+ *
+ * @capability lap-splits per-lap durations from a cumulative split book
+ */
+export declare function lapDurations(splits: readonly number[], gatesPerLap: number): number[];
+/**
+ * Elementwise delta of a cumulative split book against a `reference` book (a personal best or par lap):
+ * positive means behind the reference at that checkpoint. Compared up to the shorter length — the
+ * `+0.3s` / `−1.2s` gap every racing HUD shows against its ghost.
+ *
+ * @capability lap-splits delta of splits against a personal-best or par reference
+ */
+export declare function parDelta(splits: readonly number[], reference: readonly number[]): number[];