@jgengine/core 0.8.0 → 0.10.0

package/dist/faction/reputation.js

@@ -0,0 +1,82 @@
+export const DEFAULT_REPUTATION_TIERS = [
+    { id: "hated", min: -42000, relation: "hostile" },
+    { id: "hostile", min: -6000, relation: "hostile" },
+    { id: "unfriendly", min: -3000, relation: "neutral" },
+    { id: "neutral", min: 0, relation: "neutral" },
+    { id: "friendly", min: 3000, relation: "friendly" },
+    { id: "honored", min: 9000, relation: "friendly" },
+    { id: "revered", min: 21000, relation: "friendly" },
+    { id: "exalted", min: 42000, relation: "friendly" },
+];
+export function tierForStanding(tiers, standing) {
+    let match = tiers[0];
+    for (const tier of tiers) {
+        if (standing >= tier.min && tier.min >= match.min)
+            match = tier;
+    }
+    return match;
+}
+export function createReputationLedger(config = {}) {
+    const tiers = [...(config.tiers ?? DEFAULT_REPUTATION_TIERS)].sort((a, b) => a.min - b.min);
+    const initial = config.initial ?? {};
+    const min = config.min ?? Number.NEGATIVE_INFINITY;
+    const max = config.max ?? Number.POSITIVE_INFINITY;
+    const records = new Map();
+    function clamp(value) {
+        return Math.min(max, Math.max(min, value));
+    }
+    function standing(actorId, factionId) {
+        const stored = records.get(actorId)?.get(factionId);
+        if (stored !== undefined)
+            return stored;
+        return initial[factionId] ?? 0;
+    }
+    function store(actorId, factionId, value) {
+        const clamped = clamp(value);
+        let row = records.get(actorId);
+        if (row === undefined) {
+            row = new Map();
+            records.set(actorId, row);
+        }
+        row.set(factionId, clamped);
+        return clamped;
+    }
+    return {
+        standing,
+        hasStanding(actorId, factionId) {
+            return records.get(actorId)?.has(factionId) === true || initial[factionId] !== undefined;
+        },
+        gain(actorId, factionId, amount) {
+            return store(actorId, factionId, standing(actorId, factionId) + amount);
+        },
+        set(actorId, factionId, value) {
+            return store(actorId, factionId, value);
+        },
+        tier(actorId, factionId) {
+            return tierForStanding(tiers, standing(actorId, factionId));
+        },
+        relation(actorId, factionId) {
+            return tierForStanding(tiers, standing(actorId, factionId)).relation;
+        },
+        standings(actorId) {
+            const out = { ...initial };
+            const row = records.get(actorId);
+            if (row !== undefined)
+                for (const [factionId, value] of row)
+                    out[factionId] = value;
+            return out;
+        },
+        reset(actorId, factionId) {
+            if (factionId === undefined)
+                records.delete(actorId);
+            else
+                records.get(actorId)?.delete(factionId);
+        },
+    };
+}
+export function effectiveRelation(input) {
+    if (input.ledger.hasStanding(input.actorId, input.factionId)) {
+        return input.ledger.relation(input.actorId, input.factionId);
+    }
+    return input.base;
+}

package/dist/game/chat.d.ts

@@ -1,4 +1,5 @@
 import type { GameEvents } from "./events.js";
+import type { ChatFilter } from "./chatFilter.js";
 import type { EmotesDeps } from "./social.js";
 export type ChatChannelKind = "global" | "party" | "proximity";
 export interface ChatRateLimit {
@@ -52,6 +53,7 @@ export interface ChatDeps {
     blockedBy?: (userId: string) => readonly string[];
     maxBodyLength?: number;
     defaultRateLimit?: ChatRateLimit;
+    filter?: ChatFilter;
 }
 export declare const DEFAULT_CHAT_RATE_LIMIT: ChatRateLimit;
 export declare const DEFAULT_CHAT_HISTORY_LIMIT = 100;

package/dist/game/chat.js

@@ -34,6 +34,7 @@ export function createChat(deps) {
     const maxBodyLength = deps.maxBodyLength ?? DEFAULT_CHAT_BODY_LENGTH;
     const defaultRateLimit = deps.defaultRateLimit ?? DEFAULT_CHAT_RATE_LIMIT;
     const blockedBy = deps.blockedBy ?? (() => []);
+    const filter = deps.filter;
     const channelDefs = new Map();
     for (const def of BUILTIN_CHANNELS)
         channelDefs.set(def.id, { ...def });
@@ -97,6 +98,13 @@ export function createChat(deps) {
             return { reason: "empty message" };
         if (trimmed.length > maxBodyLength)
             return { reason: "message too long" };
+        let filteredBody = trimmed;
+        if (filter !== undefined) {
+            const filtered = filter.apply(trimmed);
+            if (!filtered.ok)
+                return { reason: "filtered" };
+            filteredBody = filtered.body;
+        }
         const resolved = resolveRecipients(fromUserId, channelId, def);
         if ("reason" in resolved)
             return resolved;
@@ -110,7 +118,7 @@ export function createChat(deps) {
             id: `msg_${counter}`,
             channelId,
             fromUserId,
-            body: trimmed,
+            body: filteredBody,
             at,
         };
         append(channelId, message, def?.historyLimit ?? DEFAULT_CHAT_HISTORY_LIMIT);

package/dist/game/chatFilter.d.ts

@@ -0,0 +1,15 @@
+export interface ChatFilterConfig {
+    blockedWords: readonly string[];
+    mode?: "mask" | "reject";
+    mask?: string;
+}
+export interface ChatFilterResult {
+    ok: boolean;
+    body: string;
+    matched: readonly string[];
+}
+export interface ChatFilter {
+    apply(body: string): ChatFilterResult;
+}
+export declare function normalizeChatText(text: string): string;
+export declare function createChatFilter(config: ChatFilterConfig): ChatFilter;

package/dist/game/chatFilter.js

@@ -0,0 +1,55 @@
+const LEET_SUBSTITUTIONS = {
+    "0": "o",
+    "1": "i",
+    "3": "e",
+    "4": "a",
+    "5": "s",
+    "7": "t",
+    "@": "a",
+    $: "s",
+    "!": "i",
+};
+const TOKEN_PATTERN = /[\p{L}\p{N}@$!]+/gu;
+export function normalizeChatText(text) {
+    let normalized = "";
+    for (const char of text.toLowerCase()) {
+        normalized += LEET_SUBSTITUTIONS[char] ?? char;
+    }
+    return normalized;
+}
+export function createChatFilter(config) {
+    const mode = config.mode ?? "mask";
+    const mask = config.mask ?? "*";
+    const blockedByNormalized = new Map();
+    for (const word of config.blockedWords) {
+        blockedByNormalized.set(normalizeChatText(word), word);
+    }
+    return {
+        apply(body) {
+            if (blockedByNormalized.size === 0)
+                return { ok: true, body, matched: [] };
+            const hit = new Set();
+            let masked = "";
+            let cursor = 0;
+            for (const token of body.matchAll(TOKEN_PATTERN)) {
+                const word = token[0];
+                const start = token.index;
+                const blockedWord = blockedByNormalized.get(normalizeChatText(word));
+                if (blockedWord === undefined)
+                    continue;
+                hit.add(blockedWord);
+                if (mode === "reject")
+                    continue;
+                masked += body.slice(cursor, start) + mask.repeat(word.length);
+                cursor = start + word.length;
+            }
+            if (hit.size === 0)
+                return { ok: true, body, matched: [] };
+            const matched = [...new Set(config.blockedWords)].filter((word) => hit.has(word));
+            if (mode === "reject")
+                return { ok: false, body, matched };
+            masked += body.slice(cursor);
+            return { ok: true, body: masked, matched };
+        },
+    };
+}

package/dist/game/connectedPlayers.d.ts

@@ -0,0 +1,28 @@
+import type { InputFrame } from "../runtime/inputSnapshot.js";
+/** A player currently joined to a hosted world — the unit a shared-world loop iterates instead of `ctx.player`. */
+export interface ConnectedPlayer {
+    userId: string;
+    isNew: boolean;
+    /** This player's latest {@link InputFrame}, written by the host each time the client sends input; `null` until the first frame arrives. The per-player movement seam reads it in `onTick`. */
+    input: InputFrame | null;
+}
+/**
+ * The set of players connected to one hosted world. A single-player game uses `ctx.player`; a shared-world loop
+ * reads `ctx.game.players` so `onTick` can advance every connected hero, not just the one local player. The host
+ * (`HostedGameRunner`) drives `join`/`leave`/`setInput`; game code reads `list`/`ids`/`has`/`count`/`input`.
+ */
+export interface ConnectedPlayers {
+    join(userId: string, isNew: boolean): void;
+    leave(userId: string): boolean;
+    has(userId: string): boolean;
+    get(userId: string): ConnectedPlayer | null;
+    list(): readonly ConnectedPlayer[];
+    ids(): readonly string[];
+    count(): number;
+    /** Record a player's latest input frame (host-driven); a no-op for a player that hasn't joined. */
+    setInput(userId: string, frame: InputFrame): void;
+    /** This player's latest input frame, or `null` if they haven't joined or no frame has arrived yet. */
+    input(userId: string): InputFrame | null;
+}
+/** Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them. */
+export declare function createConnectedPlayers(): ConnectedPlayers;

package/dist/game/connectedPlayers.js

@@ -0,0 +1,21 @@
+/** Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them. */
+export function createConnectedPlayers() {
+    const players = new Map();
+    return {
+        join(userId, isNew) {
+            players.set(userId, { userId, isNew, input: null });
+        },
+        leave: (userId) => players.delete(userId),
+        has: (userId) => players.has(userId),
+        get: (userId) => players.get(userId) ?? null,
+        list: () => Array.from(players.values()),
+        ids: () => Array.from(players.keys()),
+        count: () => players.size,
+        setInput(userId, frame) {
+            const player = players.get(userId);
+            if (player !== undefined)
+                player.input = frame;
+        },
+        input: (userId) => players.get(userId)?.input ?? null,
+    };
+}

package/dist/game/controlGate.d.ts

@@ -0,0 +1,4 @@
+import type { GameContext } from "../runtime/gameContext.js";
+export declare const PLAY_CONTROLS_STORE_KEY = "jg.playControls";
+export declare function setPlayControlsActive(ctx: GameContext, active: boolean): void;
+export declare function playControlsActive(ctx: GameContext): boolean;

package/dist/game/controlGate.js

@@ -0,0 +1,7 @@
+export const PLAY_CONTROLS_STORE_KEY = "jg.playControls";
+export function setPlayControlsActive(ctx, active) {
+    ctx.game.store.set(PLAY_CONTROLS_STORE_KEY, active);
+}
+export function playControlsActive(ctx) {
+    return ctx.game.store.get(PLAY_CONTROLS_STORE_KEY) !== false;
+}

package/dist/game/defineGame.d.ts

@@ -7,10 +7,14 @@ import { type AssetCatalog, type ModelAssetRef } from "../scene/assetCatalog.js"
 import { type EntityStore } from "../scene/entityStore.js";
 import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
+/** World gravity and jump tuning, plus scene-object collision opt-ins, for the game's physics step. */
 export interface PhysicsConfig {
     gravity?: number;
     jumpVelocity?: number;
+    /** Opt placed scene objects into projectile raycasts as blocking cover AABBs. Default false — enabling changes where shots land. */
+    projectileObstacles?: boolean;
 }
+/** Shape of one named inventory a game declares — slot count, accepted item types, HUD binding. */
 export interface InventoryDeclaration {
     slots: number;
     hud?: string;
@@ -19,20 +23,57 @@ export interface InventoryDeclaration {
     applyModifiers?: boolean;
     tier?: StorageTier;
 }
+/** Hosting mode for a game's multiplayer server: `"persistent"`, or a custom mode with its own options. */
 export type GameServerConfig = "persistent" | {
     mode: string;
     [key: string]: unknown;
 };
+/** Identity of a player joining or leaving a hosted world — passed to the multiplayer loop hooks. */
+export interface LoopPlayer {
+    userId: string;
+    isNew: boolean;
+}
+/** Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave. */
 export interface GameLoop<TContext = unknown> {
     onInit?(ctx: TContext): void;
-    onNewPlayer?(ctx: TContext): void;
+    /** Once per join. `player` identifies the joiner in a hosted world; single-player callers may omit it. */
+    onNewPlayer?(ctx: TContext, player?: LoopPlayer): void;
     onTick?(ctx: TContext, dt: number): void;
+    /** Once per leave in a hosted world (never fired single-player). Despawn the player's entities / release their slots here. */
+    onPlayerLeave?(ctx: TContext, player: LoopPlayer): void;
+}
+/**
+ * Opt-in `ctx.game.*` subsystems. Absent = off: the game doesn't carry (or expose) it, and `ctx.game.<name>`
+ * is `undefined`. Present (`true`) builds it. The universal base — `commands`, `events`, `store`, `feed` — is
+ * always on and not listed here. This is what keeps core genre-agnostic: a puzzle game isn't handed an MMO's
+ * leaderboard/roster/turn plumbing it never asked for.
+ */
+export interface GameFeatures {
+    /** Owned/captured entity roster (`ctx.game.roster`) — pet/monster collection games. */
+    roster?: boolean;
+    /** Card pile zones (`ctx.game.cards`) — deckbuilders, card games. */
+    cards?: boolean;
+    /** Turn/phase loop (`ctx.game.turn`) — turn-based games. */
+    turn?: boolean;
+    /** Lap/checkpoint race state (`ctx.game.race`) — racers. */
+    race?: boolean;
+    /** Competitive score tracking (`ctx.game.leaderboard`) — ranked/arcade games. */
+    leaderboard?: boolean;
+    /** Friends/party/presence/emotes/world-invites (`ctx.game.social`) — social/MMO games. */
+    social?: boolean;
+    /** Channels + messages (`ctx.game.chat`) — implies `social`; multiplayer/social games. */
+    chat?: boolean;
+    /** Connected-player set (`ctx.game.players`) — shared-world hosts whose loop ticks every player, not just `ctx.player`. */
+    players?: boolean;
 }
+/** Fully-resolved game description produced by {@link defineGame} — assets, scene, and opted-in subsystems. */
 export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     name: string;
     assets: AssetCatalog<TAssetRef>;
     multiplayer: TMultiplayer;
     scene: EntityStore;
+    /** Opt-in `ctx.game.*` subsystems beyond the always-on base; omitted systems are `undefined` on `ctx.game`. */
+    features?: GameFeatures;
     world?: WorldFeature;
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
@@ -46,7 +87,9 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     ui?: unknown;
     loop?: GameLoop<any>;
 }
+/** Input to {@link defineGame} — a `GameDefinition` with `scene` derived and `assets` optional. */
 export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
     assets?: AssetCatalog<TAssetRef>;
 };
+/** Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`. */
 export declare function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;

package/dist/game/defineGame.js

@@ -1,5 +1,6 @@
 import { createAssetCatalog } from "../scene/assetCatalog.js";
 import { createEntityStore } from "../scene/entityStore.js";
+/** Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`. */
 export function defineGame(config) {
     if (config.name.trim().length === 0) {
         throw new Error("defineGame: name must be non-empty");

package/dist/game/events.d.ts

@@ -22,6 +22,11 @@ export interface EntityDiedEvent {
     position: [number, number, number];
     serverId?: string;
 }
+/** Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state. */
+export interface EntityAnimationEvent {
+    instanceId: string;
+    event: string;
+}
 export interface LootGrantedEvent {
     userId: string;
     drops: {
@@ -109,6 +114,10 @@ export interface CombatTelegraphEvent {
     windupMs: number;
     kind: string;
 }
+export interface CombatTelegraphCancelledEvent {
+    /** The `combat.telegraph` event id whose decal should disappear early. */
+    id: number;
+}
 export interface CombatHitReactionEvent {
     instanceId?: string;
     position: [number, number, number];
@@ -156,10 +165,22 @@ export interface FormChangedEvent {
     instanceId: string;
     formId: string | null;
 }
+export interface AudioPlayEvent {
+    sound: string;
+    at?: readonly [number, number, number];
+}
+/** Request that the shell's audio engine resume its (browser-gesture-suspended) context; carries no payload. */
+export type AudioResumeEvent = Record<string, never>;
+/** Crossfade the procedural soundtrack to `theme` (null fades out), optionally transposing the incoming theme by `transpose` semitones. */
+export interface AudioMusicEvent {
+    theme: string | null;
+    transpose?: number;
+}
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
     "entity.floatText": EntityFloatTextEvent;
     "combat.telegraph": CombatTelegraphEvent;
+    "combat.telegraphCancelled": CombatTelegraphCancelledEvent;
     "combat.hitReaction": CombatHitReactionEvent;
     "loot.granted": LootGrantedEvent;
     "inventory.added": InventoryAddedEvent;
@@ -180,6 +201,10 @@ export interface GameEventMap {
     "emote.played": EmotePlayedEvent;
     "possession.swapped": PossessionSwappedEvent;
     "form.changed": FormChangedEvent;
+    "audio.play": AudioPlayEvent;
+    "audio.music": AudioMusicEvent;
+    "audio.resume": AudioResumeEvent;
+    "entity.animation": EntityAnimationEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {

package/dist/game/gamePhase.d.ts

@@ -0,0 +1,20 @@
+import type { GameContext } from "../runtime/gameContext.js";
+/**
+ * Canonical run phase every game moves through. `menu` (title/main menu),
+ * `playing` (live), `paused` (mid-run pause), `ended` (win/lose/results).
+ * Touch controls are shown only while `playing`; menus and results never paint
+ * the touch dock over themselves.
+ */
+export type GamePhase = "menu" | "playing" | "paused" | "ended";
+export declare const GAME_PHASE_STORE_KEY = "jg.phase";
+/**
+ * Set the current phase. Publishes it to `ctx.game.store` (React reads it via
+ * `useGamePhase`) and gates the shell's on-screen touch controls in one call —
+ * `playing` shows them, every other phase hides them. This is the whole
+ * "main menu shouldn't show touch controls" wiring: call it once per phase
+ * transition and the dock follows.
+ */
+export declare function setGamePhase(ctx: GameContext, phase: GamePhase): void;
+/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+export declare function gamePhase(ctx: GameContext): GamePhase;
+export declare function isPlaying(ctx: GameContext): boolean;

package/dist/game/gamePhase.js

@@ -0,0 +1,21 @@
+import { setPlayControlsActive } from "./controlGate.js";
+export const GAME_PHASE_STORE_KEY = "jg.phase";
+/**
+ * Set the current phase. Publishes it to `ctx.game.store` (React reads it via
+ * `useGamePhase`) and gates the shell's on-screen touch controls in one call —
+ * `playing` shows them, every other phase hides them. This is the whole
+ * "main menu shouldn't show touch controls" wiring: call it once per phase
+ * transition and the dock follows.
+ */
+export function setGamePhase(ctx, phase) {
+    ctx.game.store.set(GAME_PHASE_STORE_KEY, phase);
+    setPlayControlsActive(ctx, phase === "playing");
+}
+/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+export function gamePhase(ctx) {
+    const value = ctx.game.store.get(GAME_PHASE_STORE_KEY);
+    return value === "menu" || value === "paused" || value === "ended" ? value : "playing";
+}
+export function isPlaying(ctx) {
+    return gamePhase(ctx) === "playing";
+}

package/dist/game/keyValueStore.d.ts

@@ -0,0 +1,25 @@
+/** Structural, DOM-free storage backend: the browser `localStorage` satisfies it, as does a test stub or `null`. The one storage seam core primitives target so persistence code never needs the DOM `Storage` lib. */
+export interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The ambient `localStorage` as a {@link KeyValueStorage} when one exists (browser), otherwise `null` (server/tests) — never references the DOM `Storage` type, so it is safe in core. */
+export declare function defaultKeyValueStorage(): KeyValueStorage | null;
+/** A single persisted, mutable cell: read the current value, overwrite it, or read-modify-write with {@link KeyValueStore.update}. Unlike a record book it has no monotonic guard — the value goes wherever you set it. */
+export interface KeyValueStore<T> {
+    get(): T;
+    set(value: T): void;
+    update(mutate: (previous: T) => T): T;
+    clear(): void;
+}
+/** Config for {@link createKeyValueStore}: the storage `key`, the `initial` value used before anything is saved, an optional `storage` backend (defaults to `localStorage`, pass `null` for memory-only), and optional custom `serialize`/`deserialize` (default JSON). */
+export interface KeyValueStoreConfig<T> {
+    readonly key: string;
+    readonly initial: T;
+    readonly storage?: KeyValueStorage | null;
+    readonly serialize?: (value: T) => string;
+    readonly deserialize?: (raw: string) => T;
+}
+/** A lightweight mutable local save cell for single-player state (a credit bank, a settings blob, level progress) — the read-modify-write counterpart to the monotonic `recordBook`. Persists through a {@link KeyValueStorage} (browser `localStorage` by default); corrupt or unavailable storage degrades to in-memory and never throws into a game tick. */
+export declare function createKeyValueStore<T>(config: KeyValueStoreConfig<T>): KeyValueStore<T>;

package/dist/game/keyValueStore.js

@@ -0,0 +1,61 @@
+/** The ambient `localStorage` as a {@link KeyValueStorage} when one exists (browser), otherwise `null` (server/tests) — never references the DOM `Storage` type, so it is safe in core. */
+export function defaultKeyValueStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** A lightweight mutable local save cell for single-player state (a credit bank, a settings blob, level progress) — the read-modify-write counterpart to the monotonic `recordBook`. Persists through a {@link KeyValueStorage} (browser `localStorage` by default); corrupt or unavailable storage degrades to in-memory and never throws into a game tick. */
+export function createKeyValueStore(config) {
+    const storage = config.storage === undefined ? defaultKeyValueStorage() : config.storage;
+    const serialize = config.serialize ?? ((value) => JSON.stringify(value));
+    const deserialize = config.deserialize ?? ((raw) => JSON.parse(raw));
+    const read = () => {
+        if (storage === null)
+            return config.initial;
+        try {
+            const raw = storage.getItem(config.key);
+            return raw === null ? config.initial : deserialize(raw);
+        }
+        catch {
+            return config.initial;
+        }
+    };
+    let current = read();
+    const write = (value) => {
+        current = value;
+        if (storage === null)
+            return;
+        try {
+            storage.setItem(config.key, serialize(value));
+        }
+        catch {
+            // storage rejected the write; keep the value in memory for this session
+        }
+    };
+    return {
+        get: () => current,
+        set: (value) => write(value),
+        update: (mutate) => {
+            const next = mutate(current);
+            write(next);
+            return next;
+        },
+        clear: () => {
+            current = config.initial;
+            if (storage === null)
+                return;
+            try {
+                storage.removeItem(config.key);
+            }
+            catch {
+                // ignore removal failure; in-memory value already reset
+            }
+        },
+    };
+}

package/dist/game/levelSequence.d.ts

@@ -1,11 +1,23 @@
+import { type KeyValueStorage } from "./keyValueStore.js";
 export interface LevelDescriptor<TLevelConfig> {
     id: string;
     config: TLevelConfig;
 }
+/** A level's star rating, 0 (cleared, no stars) to 3. */
+export type LevelStars = 0 | 1 | 2 | 3;
+/** Persisted per-level outcome: whether it has ever been cleared and the best star rating achieved. */
+export interface LevelRecord {
+    cleared: boolean;
+    stars: LevelStars;
+}
 export interface LevelSequenceConfig<TLevelConfig> {
     levels: readonly LevelDescriptor<TLevelConfig>[];
     /** Extra attempts granted after the first per level. Defaults to 0 (a single attempt, no retries). */
     retriesPerLevel?: number;
+    /** Persistence key for per-level completion/stars. Omit to keep records in-memory only. */
+    key?: string;
+    /** Storage backend for the records (browser `localStorage` by default when `key` is set); pass `null` for memory-only. */
+    storage?: KeyValueStorage | null;
 }
 export type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete";
 export interface CurrentLevel<TLevelConfig> {
@@ -24,15 +36,25 @@ export interface LevelSequence<TLevelConfig> {
     status(): LevelSequenceStatus;
     /** Enters level 0. A no-op on an empty level list, which leaves `status()` at "idle" forever. */
     start(): void;
-    /** Marks the current level cleared; call `advance()` to move to the next one. */
-    clear(): void;
+    /** Marks the current level cleared, recording its best star rating; call `advance()` to move to the next one. */
+    clear(stars?: LevelStars): void;
     /** Consumes an attempt on the current level. Returns "retry" while attempts remain, else "failed". */
     fail(): "retry" | "failed";
     /** Restarts the current level after a "retry"-eligible failure. Returns false if there was nothing to retry. */
     retry(): boolean;
     /** Moves past a cleared level, or to "complete" if it was the last one. Returns false unless status is "cleared". */
     advance(): boolean;
+    /** Jumps directly to an unlocked level and starts it. Returns false for an unknown or still-locked level. */
+    select(level: string): boolean;
+    /** Whether a level can be entered: the first level always, later ones once the preceding level has a cleared record. */
+    isUnlocked(level: string): boolean;
+    /** The persisted record for a level, or `null` if it has never been cleared. */
+    record(level: string): LevelRecord | null;
+    /** A snapshot of every persisted level record, keyed by level id. */
+    records(): Readonly<Record<string, LevelRecord>>;
     reset(): void;
+    /** Wipes all persisted completion/star records (and the frontier), returning to a fresh campaign. */
+    clearRecords(): void;
     progress(): LevelSequenceProgress;
 }
 /**