@jgengine/core 0.19.0 → 0.22.0

package/dist/game/contentValidation.d.ts

@@ -0,0 +1,69 @@
+/** A definition in a game-owned namespace, located in its authored document. */
+export interface ContentEntry {
+    kind: string;
+    id: string;
+    path: string;
+}
+/** A located reference; namespaces can express game-owned roles such as questgiver. */
+export interface ContentReference extends ContentEntry {
+    contentId: string;
+    /** Optional game-declared relationship, such as the quests offered by this particular giver. */
+    allowedIds?: readonly string[];
+}
+/** A repairable authoring issue. Paths are caller document locations, usually JSON Pointers. */
+export interface ContentIssue {
+    code: string;
+    severity: "error" | "warning";
+    path: string;
+    contentId?: string;
+    referenceId?: string;
+    message: string;
+    repair: string;
+}
+/**
+ * Index definitions once and check references in input order, without mutating the catalog.
+ * Namespace strings and roles are game-owned; identical ids in different namespaces are valid.
+ * Typed input must be decoded before calling. Work is O(definitions + references + allowed ids).
+ *
+ * @capability content-reference-validation locate duplicate content ids and broken references across game-owned catalog namespaces with repair guidance
+ */
+export declare function validateContentReferences(entries: readonly ContentEntry[], references: readonly ContentReference[]): ContentIssue[];
+/** A possible source or action; all required facts must be reachable to provide its facts. */
+export interface ContentProgressionRule {
+    id: string;
+    path: string;
+    requires: readonly string[];
+    provides: readonly string[];
+}
+/** A game-declared availability requirement, located at the content that needs it. */
+export interface ContentProgressionRequirement {
+    id: string;
+    path: string;
+    contentId: string;
+}
+/** Explicit possible sources; opaque fact strings may represent items, unlocks or skill milestones. */
+export interface ContentProgressionInput {
+    initial: readonly string[];
+    rules: readonly ContentProgressionRule[];
+    required?: readonly ContentProgressionRequirement[];
+    /** True only when the game declares all possible sources; otherwise blocked routes are warnings. */
+    closedWorld?: boolean;
+}
+/** Potential availability and diagnostics in deterministic input/traversal order. */
+export interface ContentProgressionResult {
+    reachable: string[];
+    reachableRules: string[];
+    issues: ContentIssue[];
+}
+/**
+ * Check declared potential progression using a dependency queue in O(facts + rules + edges).
+ * Alternatives are separate rules; every requirement within one rule is necessary.
+ * Seeded cycles are valid. An unseeded cycle is blocked only under the declared sources.
+ * Facts describe possible availability, not quantities, consumption, mutually exclusive choices,
+ * chronology, station proximity or economic balance. Encode those constraints in game-owned rules
+ * or playtests. Skill training caps must be explicitly translated into attainable milestones.
+ * This is offline authoring analysis, not a quest engine or a per-frame catalog scan.
+ *
+ * @capability content-progression-validation diagnose unavailable sources and blocked cross-content progression under explicit game-owned rules without rejecting intentional seeded cycles
+ */
+export declare function validateContentProgression(input: ContentProgressionInput): ContentProgressionResult;

package/dist/game/contentValidation.js

@@ -0,0 +1,118 @@
+/**
+ * Index definitions once and check references in input order, without mutating the catalog.
+ * Namespace strings and roles are game-owned; identical ids in different namespaces are valid.
+ * Typed input must be decoded before calling. Work is O(definitions + references + allowed ids).
+ *
+ * @capability content-reference-validation locate duplicate content ids and broken references across game-owned catalog namespaces with repair guidance
+ */
+export function validateContentReferences(entries, references) {
+    const namespaces = new Map();
+    const issues = [];
+    for (const entry of entries) {
+        let ids = namespaces.get(entry.kind);
+        if (ids === undefined)
+            namespaces.set(entry.kind, ids = new Map());
+        const earlier = ids.get(entry.id);
+        if (earlier !== undefined) {
+            issues.push({ code: "duplicate-content", severity: "error", path: entry.path,
+                contentId: entry.id, referenceId: entry.id,
+                message: `Duplicate ${entry.kind} "${entry.id}"; first defined at ${earlier}.`,
+                repair: "Give the definitions distinct ids and update their references, or remove the duplicate." });
+        }
+        else
+            ids.set(entry.id, entry.path);
+    }
+    for (const reference of references) {
+        if (!namespaces.get(reference.kind)?.has(reference.id)) {
+            issues.push({ code: "unknown-reference", severity: "error", path: reference.path,
+                contentId: reference.contentId, referenceId: reference.id,
+                message: `Content "${reference.contentId}" references unknown ${reference.kind} "${reference.id}".`,
+                repair: `Correct this reference or declare "${reference.id}" in the ${reference.kind} catalog.` });
+        }
+        else if (reference.allowedIds !== undefined && !reference.allowedIds.includes(reference.id)) {
+            issues.push({ code: "inconsistent-reference", severity: "error", path: reference.path,
+                contentId: reference.contentId, referenceId: reference.id,
+                message: `Content "${reference.contentId}" references ${reference.kind} "${reference.id}" outside its declared relationship.`,
+                repair: `Use an allowed id (${reference.allowedIds.map((id) => `"${id}"`).join(", ") || "none declared"}) or correct the game-owned relationship declaration.` });
+        }
+    }
+    return issues;
+}
+/**
+ * Check declared potential progression using a dependency queue in O(facts + rules + edges).
+ * Alternatives are separate rules; every requirement within one rule is necessary.
+ * Seeded cycles are valid. An unseeded cycle is blocked only under the declared sources.
+ * Facts describe possible availability, not quantities, consumption, mutually exclusive choices,
+ * chronology, station proximity or economic balance. Encode those constraints in game-owned rules
+ * or playtests. Skill training caps must be explicitly translated into attainable milestones.
+ * This is offline authoring analysis, not a quest engine or a per-frame catalog scan.
+ *
+ * @capability content-progression-validation diagnose unavailable sources and blocked cross-content progression under explicit game-owned rules without rejecting intentional seeded cycles
+ */
+export function validateContentProgression(input) {
+    const issues = [];
+    const ids = new Set();
+    const available = new Set(input.initial);
+    const dependents = new Map();
+    const remaining = [];
+    const ready = [];
+    const reached = new Set();
+    for (let index = 0; index < input.rules.length; index++) {
+        const rule = input.rules[index];
+        if (ids.has(rule.id)) {
+            issues.push({ code: "duplicate-rule", severity: "error", path: rule.path,
+                contentId: rule.id, referenceId: rule.id, message: `Progression rule "${rule.id}" repeats.`,
+                repair: "Give each source/action a distinct rule id, or remove the duplicate." });
+        }
+        ids.add(rule.id);
+        let count = 0;
+        for (const fact of new Set(rule.requires)) {
+            if (available.has(fact))
+                continue;
+            count++;
+            let waiting = dependents.get(fact);
+            if (waiting === undefined)
+                dependents.set(fact, waiting = []);
+            waiting.push(index);
+        }
+        remaining.push(count);
+        if (count === 0)
+            ready.push(index);
+    }
+    const reachableRules = [];
+    for (let head = 0; head < ready.length; head++) {
+        const index = ready[head];
+        reached.add(index);
+        const rule = input.rules[index];
+        reachableRules.push(rule.id);
+        for (const fact of rule.provides) {
+            if (available.has(fact))
+                continue;
+            available.add(fact);
+            for (const dependent of dependents.get(fact) ?? []) {
+                remaining[dependent]--;
+                if (remaining[dependent] === 0)
+                    ready.push(dependent);
+            }
+        }
+    }
+    const severity = input.closedWorld === true ? "error" : "warning";
+    for (let index = 0; index < input.rules.length; index++) {
+        if (reached.has(index))
+            continue;
+        const rule = input.rules[index];
+        const missing = [...new Set(rule.requires)].filter((fact) => !available.has(fact));
+        issues.push({ code: "blocked-rule", severity, path: rule.path, contentId: rule.id,
+            message: `Content rule "${rule.id}" is blocked by ${missing.map((fact) => `"${fact}"`).join(", ")}.`,
+            repair: "Correct the prerequisites or add a reachable source. Declare legitimate external sources as initial facts; review intentional unavailable content." });
+    }
+    for (const requirement of input.required ?? []) {
+        if (available.has(requirement.id))
+            continue;
+        issues.push({ code: "unreachable-content", severity, path: requirement.path,
+            contentId: requirement.contentId, referenceId: requirement.id,
+            message: `Content "${requirement.contentId}" needs unavailable fact "${requirement.id}".`,
+            repair: "Correct this requirement or connect a source to the declared entry facts. If sources are incomplete, use open-world warnings until the game declares them." });
+    }
+    return { reachable: [...available], reachableRules, issues };
+}

package/dist/game/controlGate.d.ts

@@ -7,4 +7,12 @@ export declare function actionContextStack(ctx: GameContext): ActionContextStack
 /** Applies active contexts to a base action map for shell input tracking. */
 export declare function activeActionCodes(ctx: GameContext, base: ActionCodesMap): ActionCodesMap;
 export declare function setPlayControlsActive(ctx: GameContext, active: boolean): void;
+/**
+ * Suspends this context's player controls until the returned release function is called.
+ * Independent owners compose; repeated release is safe and preserves the existing play gate.
+ * Dispose the lease when its menu closes or its owning context unmounts.
+ * Leases survive this context's binding restore and are excluded from saved binding state.
+ * @capability control-suspension Suspend player input across overlapping menus without stopping shared simulation.
+ */
+export declare function suspendPlayControls(ctx: GameContext): () => void;
 export declare function playControlsActive(ctx: GameContext): boolean;

package/dist/game/controlGate.js

@@ -1,13 +1,25 @@
 import { createActionContextStack } from "../input/actionContexts.js";
 export const PLAY_CONTROLS_STORE_KEY = "jg.playControls";
+const SUSPENSION_PREFIX = "__jg_control_suspension:";
 const ACTION_CONTEXTS = new WeakMap();
 function contextsFor(ctx) {
-    let stack = ACTION_CONTEXTS.get(ctx);
-    if (stack === undefined) {
-        stack = createActionContextStack();
-        ACTION_CONTEXTS.set(ctx, stack);
+    let state = ACTION_CONTEXTS.get(ctx);
+    if (state === undefined) {
+        const stack = createActionContextStack();
+        state = {
+            nextLease: 0,
+            stack: {
+                ...stack,
+                snapshot: () => ({ contexts: stack.snapshot().contexts.filter((context) => !context.id.startsWith(SUSPENSION_PREFIX)) }),
+                restore(snapshot) {
+                    const leases = stack.snapshot().contexts.filter((context) => context.id.startsWith(SUSPENSION_PREFIX));
+                    stack.restore({ contexts: [...snapshot.contexts.filter((context) => !context.id.startsWith(SUSPENSION_PREFIX)), ...leases] });
+                },
+            },
+        };
+        ACTION_CONTEXTS.set(ctx, state);
     }
-    return stack;
+    return state.stack;
 }
 /** Returns the context stack associated with a game context. */
 export function actionContextStack(ctx) {
@@ -16,6 +28,8 @@ export function actionContextStack(ctx) {
 /** Applies active contexts to a base action map for shell input tracking. */
 export function activeActionCodes(ctx, base) {
     const stack = contextsFor(ctx);
+    if (stack.ids().some((id) => id.startsWith(SUSPENSION_PREFIX)))
+        return {};
     const layered = createActionContextStack();
     layered.push({ id: "__jg_base_actions", codes: base, passthrough: true });
     for (const context of stack.snapshot().contexts)
@@ -30,7 +44,30 @@ export function setPlayControlsActive(ctx, active) {
         stack.push({ id: "menu", codes: {}, passthrough: false });
     ctx.game.store.set(PLAY_CONTROLS_STORE_KEY, active);
 }
+/**
+ * Suspends this context's player controls until the returned release function is called.
+ * Independent owners compose; repeated release is safe and preserves the existing play gate.
+ * Dispose the lease when its menu closes or its owning context unmounts.
+ * Leases survive this context's binding restore and are excluded from saved binding state.
+ * @capability control-suspension Suspend player input across overlapping menus without stopping shared simulation.
+ */
+export function suspendPlayControls(ctx) {
+    const stack = contextsFor(ctx);
+    const state = ACTION_CONTEXTS.get(ctx);
+    let id;
+    do {
+        id = `${SUSPENSION_PREFIX}${state.nextLease++}`;
+    } while (stack.ids().includes(id));
+    stack.push({ id, codes: {}, passthrough: false });
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        stack.pop(id);
+    };
+}
 export function playControlsActive(ctx) {
     return ctx.game.store.get(PLAY_CONTROLS_STORE_KEY) !== false &&
-        !actionContextStack(ctx).snapshot().contexts.some((context) => context.id === "menu");
+        !actionContextStack(ctx).ids().some((id) => id === "menu" || id.startsWith(SUSPENSION_PREFIX));
 }

package/dist/game/defineGame.d.ts

@@ -1,3 +1,5 @@
+import type { EditorDocument } from "../editor/types.js";
+import type { ProjectileTravelDeps } from "../combat/projectiles.js";
 import type { ActionCodesMap } from "../input/actionBindings.js";
 import type { GameFeedOptions } from "./feed.js";
 import type { GamePhase } from "./gamePhase.js";
@@ -6,7 +8,7 @@ import type { ItemTraits } from "../inventory/inventoryModel.js";
 import type { StorageTier } from "../inventory/storageTier.js";
 import type { GameContext } from "../runtime/gameContext.js";
 import type { ReplicationPolicy } from "../runtime/worldProjection.js";
-import type { RuntimeSaveMode } from "../runtime/runtimeSave.js";
+import type { RuntimeSaveMode, RuntimeSaveOptions } from "../runtime/runtimeSave.js";
 import type { SaveConfig } from "../runtime/save.js";
 import { type AssetCatalog, type ModelAssetRef } from "../scene/assetCatalog.js";
 import { type EntityStore } from "../scene/entityStore.js";
@@ -22,8 +24,10 @@ export interface PersistConfig {
     mode?: RuntimeSaveMode;
     /** `"local"` (default) persists to `localStorage`; `"memory"` keeps saves in-session only (tests, "no persistence" mode). */
     storage?: "local" | "memory";
-    /** Save-format version; bump when the world shape changes in a save-breaking way. */
+    /** Save-format version. Supply `migrate` for incompatible older shapes; without it, mismatched versions retain compatible load behavior. */
     version?: number;
+    /** Convert a mismatched version (or raw payload, version 0) before world restoration. Throw to reject without hydrating or changing the stored save. Current-version payloads bypass this hook. */
+    migrate?: RuntimeSaveOptions["migrate"];
     /** Autosave debounce in ms (autosave mode). Default 3000. */
     autosaveMs?: number;
 }
@@ -150,7 +154,7 @@ export interface LifecycleConfig<TState = unknown> {
 /**
  * How a game declares its run-phase story to {@link defineGameDefinition}. Every game states this
  * explicitly so the shell never has to guess — a silent game used to default to `"playing"`, which
- * painted the touch dock over title/menu/results screens (#1337, Vice Isle #1329).
+ * painted the touch dock over title/menu/results screens (#1337, Harbor Heat #1329).
  *
  * - A {@link LifecycleConfig} — the game moves through menu/playing/paused/ended run states; the
  *   runtime owns the command glue and phase sync.
@@ -161,6 +165,17 @@ export interface LifecycleConfig<TState = unknown> {
  *   this unset.
  */
 export type GameLifecycle<TState = unknown> = LifecycleConfig<TState> | "always-live";
+/** Context-aware projectile policy; callbacks are not included in saved shot state. */
+export interface GameProjectileTravelOptions extends Pick<ProjectileTravelDeps, "maxActive" | "maxRetained"> {
+    /** Collision-source limit, default 2048; an oversized source throws rather than dropping targets. */
+    maxTargets?: number;
+    /** Override the default centerline cover query with a radius-aware collision provider. */
+    sweep?: (ctx: GameContext, ...args: Parameters<NonNullable<ProjectileTravelDeps["sweep"]>>) => ReturnType<NonNullable<ProjectileTravelDeps["sweep"]>>;
+    /** Full acceleration override; call ctx.environment.accelerationAt explicitly to compose authored forces. */
+    acceleration?: (ctx: GameContext, ...args: Parameters<NonNullable<ProjectileTravelDeps["acceleration"]>>) => ReturnType<NonNullable<ProjectileTravelDeps["acceleration"]>>;
+    /** Bounded entity IDs for the default moving-target query; omission uses this world's entities. */
+    targets?(ctx: GameContext): readonly string[];
+}
 /** Fully-resolved game description produced by {@link defineGameDefinition} — assets, scene, and opted-in subsystems. */
 export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     name: string;
@@ -183,6 +198,20 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
      * pure UI/rules games that are not a spatial place.
      */
     world?: WorldFeature;
+    /** Validated authored scene inputs consumed by the environmental authority. */
+    authoredDocument?: EditorDocument;
+    /** Bounded projectile travel providers receive their live world; the authoritative clock stays engine-owned. */
+    projectileTravel?: GameProjectileTravelOptions;
+    /** Optional pursuit target policy; callbacks are world-local injections, never saved behavior data. */
+    pursuit?: {
+        /** Additional eligibility for nearest, held, explicit and forced targets at scheduled pursuit ticks.
+         * Receives the live world and entity IDs; cannot bypass self/existence/effect acceptance checks.
+         * Omission retains player-role acquisition; explicit targets may still name nonplayers.
+         * A supplied callback must return exactly true to accept; missing, null or asynchronous results deny.
+         * Keep this pair query bounded (for example, a caller-owned faction roster lookup).
+         */
+        eligible(ctx: GameContext, selfId: string, candidateId: string): boolean;
+    };
     /** Game-level default physics laws; a place world's own `physics` resolves over this. */
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */

package/dist/game/dialogueGraph.d.ts

@@ -36,6 +36,26 @@ export interface DialogueGraph {
     /** Every node in the conversation. */
     nodes: readonly DialogueGraphNode[];
 }
+/** A structural authoring issue, located in the original graph's node/choice arrays. */
+export interface DialogueGraphIssue {
+    code: "duplicate-node" | "missing-start" | "missing-target" | "unreachable-node" | "no-exit";
+    severity: "error" | "warning";
+    message: string;
+    nodeId?: string;
+    nodeIndex?: number;
+    choiceIndex?: number;
+    targetId?: string;
+}
+/**
+ * Check authored dialogue references, reachability, and routes to an ending in O(nodes + choices).
+ * A node without choices, or a choice with no target, is an ending. Loops with an exit are valid.
+ * Duplicate ids and missing references are errors; unreachable nodes and closed loops are warnings
+ * because games may jump to nodes or intentionally keep conversations open. Topology uses the first
+ * node for each id, matching {@link selectDialogueView}. This does not evaluate story semantics.
+ *
+ * @capability dialogue-graph-validation diagnose duplicate ids, broken branches, unreachable dialogue, and nodes without a route to an ending before play
+ */
+export declare function validateDialogueGraph(graph: DialogueGraph): DialogueGraphIssue[];
 /**
  * The render-ready snapshot of a conversation at one node — everything a view needs to
  * draw speaker, line, and choice buttons, with no traversal logic in the component.

package/dist/game/dialogueGraph.js

@@ -1,3 +1,110 @@
+/**
+ * Check authored dialogue references, reachability, and routes to an ending in O(nodes + choices).
+ * A node without choices, or a choice with no target, is an ending. Loops with an exit are valid.
+ * Duplicate ids and missing references are errors; unreachable nodes and closed loops are warnings
+ * because games may jump to nodes or intentionally keep conversations open. Topology uses the first
+ * node for each id, matching {@link selectDialogueView}. This does not evaluate story semantics.
+ *
+ * @capability dialogue-graph-validation diagnose duplicate ids, broken branches, unreachable dialogue, and nodes without a route to an ending before play
+ */
+export function validateDialogueGraph(graph) {
+    const issues = [];
+    const nodes = new Map();
+    for (let index = 0; index < graph.nodes.length; index++) {
+        const node = graph.nodes[index];
+        if (nodes.has(node.id)) {
+            issues.push({
+                code: "duplicate-node", severity: "error", nodeId: node.id, nodeIndex: index,
+                message: `Duplicate dialogue node "${node.id}".`,
+            });
+        }
+        else {
+            nodes.set(node.id, { node, index });
+        }
+    }
+    if (!nodes.has(graph.start)) {
+        issues.push({
+            code: "missing-start", severity: "error", targetId: graph.start,
+            message: `Dialogue start "${graph.start}" does not exist.`,
+        });
+    }
+    for (let index = 0; index < graph.nodes.length; index++) {
+        const node = graph.nodes[index];
+        const choices = node.choices ?? [];
+        for (let choiceIndex = 0; choiceIndex < choices.length; choiceIndex++) {
+            const target = choices[choiceIndex].to;
+            if (target == null || nodes.has(target))
+                continue;
+            issues.push({
+                code: "missing-target", severity: "error", nodeId: node.id, nodeIndex: index,
+                choiceIndex, targetId: target,
+                message: `Dialogue choice targets unknown node "${target}".`,
+            });
+        }
+    }
+    const predecessors = new Map();
+    const canEnd = new Set();
+    const endings = [];
+    for (const { node } of nodes.values()) {
+        const choices = node.choices ?? [];
+        let ending = choices.length === 0;
+        for (const choice of choices) {
+            if (choice.to == null) {
+                ending = true;
+            }
+            else if (nodes.has(choice.to)) {
+                let incoming = predecessors.get(choice.to);
+                if (incoming === undefined) {
+                    incoming = [];
+                    predecessors.set(choice.to, incoming);
+                }
+                incoming.push(node.id);
+            }
+        }
+        if (ending) {
+            canEnd.add(node.id);
+            endings.push(node.id);
+        }
+    }
+    for (let head = 0; head < endings.length; head++) {
+        for (const id of predecessors.get(endings[head]) ?? []) {
+            if (canEnd.has(id))
+                continue;
+            canEnd.add(id);
+            endings.push(id);
+        }
+    }
+    const reachable = new Set();
+    const pending = [];
+    if (nodes.has(graph.start)) {
+        reachable.add(graph.start);
+        pending.push(graph.start);
+    }
+    for (let head = 0; head < pending.length; head++) {
+        for (const choice of nodes.get(pending[head]).node.choices ?? []) {
+            const target = choice.to;
+            if (target == null || !nodes.has(target) || reachable.has(target))
+                continue;
+            reachable.add(target);
+            pending.push(target);
+        }
+    }
+    for (const { node, index } of nodes.values()) {
+        if (nodes.has(graph.start) && !reachable.has(node.id)) {
+            issues.push({
+                code: "unreachable-node", severity: "warning", nodeId: node.id, nodeIndex: index,
+                message: `Dialogue node "${node.id}" is unreachable from the start.`,
+            });
+        }
+        if (!canEnd.has(node.id)) {
+            issues.push({
+                code: "no-exit", severity: "warning", nodeId: node.id, nodeIndex: index,
+                message: `Dialogue node "${node.id}" has no route to an ending.`,
+            });
+        }
+    }
+    return issues;
+}
 /**
  * Project a {@link DialogueGraph} node id to its render-ready {@link DialogueGraphView} —
  * the pure "current view" selector a stateless renderer reads (speaker, line, choices,

package/dist/game/events.d.ts

@@ -1,3 +1,4 @@
+import type { EffectResult } from "../combat/effects.js";
 import type { DeathReason } from "../combat/deathReason.js";
 import type { TelegraphShape } from "../combat/telegraph.js";
 import type { CameraShake } from "../combat/hitReaction.js";
@@ -159,7 +160,11 @@ export interface CombatHitReactionEvent {
     /** Trauma (0..1) for a trauma² shake channel — set when the reaction resolved from `trauma` instead of `shake`. */
     trauma?: number;
 }
+/** Exactly-once projectile result for shot-specific game policy and presentation. */
 export interface ProjectileSettledEvent {
+    shotId: string;
+    /** Actual applied effects; empty for misses and cover impacts. */
+    hits: readonly EffectResult[];
     from: string;
     origin: [number, number, number];
     at: [number, number, number];

package/dist/game/keyValueStore.d.ts

@@ -4,8 +4,21 @@ export interface KeyValueStorage {
     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;
+/** The ambient `localStorage` when available, otherwise `null`. An optional observer receives denied getter errors; it may rethrow to reject fallback. Never references the DOM `Storage` type, so it is safe in core. */
+export declare function defaultKeyValueStorage(onError?: (error: unknown) => void): KeyValueStorage | null;
+/** A failed storage operation, retaining the backend's original error and affected key. */
+export interface KeyValueStorageFailure {
+    operation: "read" | "write" | "remove";
+    key: string;
+    error: unknown;
+}
+/** Fallback keeps session state after a failed operation; throw exposes failure and preserves the previous cell value. Observers must not throw. */
+export interface KeyValueStorageErrorPolicy {
+    errorMode?: "fallback" | "throw";
+    onError?: (failure: KeyValueStorageFailure) => void;
+}
+/** @internal */
+export declare function reportStorageFailure(policy: KeyValueStorageErrorPolicy, failure: KeyValueStorageFailure): void;
 /** 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;
@@ -14,12 +27,12 @@ export interface KeyValueStore<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> {
+export interface KeyValueStoreConfig<T> extends KeyValueStorageErrorPolicy {
     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. */
+/** A mutable local save cell through {@link KeyValueStorage}. Default fallback keeps session state on failure; `errorMode: "throw"` exposes failed reads/writes/removals through the original error. `storage: null` deliberately uses memory only. */
 export declare function createKeyValueStore<T>(config: KeyValueStoreConfig<T>): KeyValueStore<T>;

package/dist/game/keyValueStore.js

@@ -1,42 +1,54 @@
-/** 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() {
+/** The ambient `localStorage` when available, otherwise `null`. An optional observer receives denied getter errors; it may rethrow to reject fallback. Never references the DOM `Storage` type, so it is safe in core. */
+export function defaultKeyValueStorage(onError) {
     try {
         if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
             return globalThis.localStorage ?? null;
         }
     }
-    catch {
+    catch (error) {
+        onError?.(error);
         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. */
+/** @internal */
+export function reportStorageFailure(policy, failure) {
+    policy.onError?.(failure);
+    if (policy.errorMode === "throw")
+        throw failure.error;
+}
+/** A mutable local save cell through {@link KeyValueStorage}. Default fallback keeps session state on failure; `errorMode: "throw"` exposes failed reads/writes/removals through the original error. `storage: null` deliberately uses memory only. */
 export function createKeyValueStore(config) {
-    const storage = config.storage === undefined ? defaultKeyValueStorage() : config.storage;
+    const fail = (operation, error) => reportStorageFailure(config, { operation, key: config.key, error });
+    const storage = config.storage === undefined ? defaultKeyValueStorage((error) => fail("read", error)) : config.storage;
     const serialize = config.serialize ?? ((value) => JSON.stringify(value));
     const deserialize = config.deserialize ?? ((raw) => JSON.parse(raw));
     const read = () => {
-        if (storage === null)
+        if (storage === null) {
+            if (config.storage !== null && config.errorMode === "throw")
+                fail("read", new Error("Local storage is unavailable"));
             return config.initial;
+        }
         try {
             const raw = storage.getItem(config.key);
             return raw === null ? config.initial : deserialize(raw);
         }
-        catch {
+        catch (error) {
+            fail("read", error);
             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
+        if (storage !== null) {
+            try {
+                storage.setItem(config.key, serialize(value));
+            }
+            catch (error) {
+                fail("write", error);
+            }
         }
+        current = value;
     };
     return {
         get: () => current,
@@ -47,15 +59,15 @@ export function createKeyValueStore(config) {
             return next;
         },
         clear: () => {
-            current = config.initial;
-            if (storage === null)
-                return;
-            try {
-                storage.removeItem(config.key);
-            }
-            catch {
-                // ignore removal failure; in-memory value already reset
+            if (storage !== null) {
+                try {
+                    storage.removeItem(config.key);
+                }
+                catch (error) {
+                    fail("remove", error);
+                }
             }
+            current = config.initial;
         },
     };
 }

package/dist/game/lootModifiers.d.ts

@@ -0,0 +1,17 @@
+import type { LootEntry } from "./lootTable.js";
+import type { LootModifier } from "./lootPipeline.js";
+/** Caller-authored weighting curve; item ids, quality tiers and balance never live in the modifier. */
+export interface TimeScaledRarityOptions {
+    id?: string;
+    ramp: (entry: LootEntry, hours: number) => number;
+}
+/**
+ * Multiply weighted odds (or independent chances, clamped to one) by a caller-authored elapsed-time
+ * curve. Keeps source tables unchanged and uses the existing pipeline's modifier provenance.
+ * Elapsed time and multipliers must be finite and nonnegative; invalid curves reject the roll.
+ *
+ * @capability time-scaled-loot shape loot odds by elapsed hours with caller-authored curves and pipeline provenance
+ */
+export declare function timeScaledRarity<TCtx extends {
+    elapsedMs: number;
+}>(options: TimeScaledRarityOptions): LootModifier<TCtx>;