@jgengine/core 0.18.1 → 0.21.0

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>;

package/dist/game/lootModifiers.js

@@ -0,0 +1,26 @@
+/**
+ * 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 function timeScaledRarity(options) {
+    return {
+        id: options.id ?? "time-scaled-rarity",
+        plan(plan, ctx) {
+            if (!Number.isFinite(ctx.elapsedMs) || ctx.elapsedMs < 0)
+                throw new RangeError("Loot elapsedMs must be finite and nonnegative");
+            const hours = ctx.elapsedMs / 3_600_000;
+            return { ...plan, entries: plan.entries.map(candidate => {
+                    const factor = options.ramp(candidate.entry, hours);
+                    if (!Number.isFinite(factor) || factor < 0)
+                        throw new RangeError("Loot time multiplier must be finite and nonnegative");
+                    const value = (plan.mode === "weighted" ? candidate.weight : candidate.chance ?? 0) * factor;
+                    if (!Number.isFinite(value))
+                        throw new RangeError("Loot time weighting overflowed");
+                    return plan.mode === "weighted" ? { ...candidate, weight: value } : { ...candidate, chance: Math.min(1, value) };
+                }) };
+        },
+    };
+}

package/dist/game/lootTable.d.ts

@@ -38,6 +38,10 @@ export interface LootRegistry {
     register(def: LootTableDef): void;
     has(id: string): boolean;
     roll(id: string, rng?: () => number): Drop[];
+    /** Registered tables in registration order; plain JSON unless an entry uses `generate`. */
+    snapshot(): LootTableDef[];
+    /** Replaces every registered table with `next`, validating each. */
+    restore(next: readonly LootTableDef[]): void;
 }
 /** Options for {@link createLootRegistry} — inject a default RNG so bare `roll(id)` uses the world stream. */
 export interface LootRegistryOptions {

package/dist/game/lootTable.js

@@ -1,4 +1,10 @@
 import { resolveRng } from "../random/resolveRng.js";
+function copyDef(def) {
+    return {
+        ...def,
+        entries: def.entries.map((entry) => ({ ...entry, count: typeof entry.count === "number" ? entry.count : [entry.count[0], entry.count[1]] })),
+    };
+}
 function assertValidEntry(entry, mode) {
     const kinds = [entry.item !== undefined, entry.currency !== undefined, entry.generate !== undefined].filter(Boolean).length;
     if (kinds !== 1) {
@@ -88,6 +94,16 @@ export function createLootRegistry(options = {}) {
             }
             return drops;
         },
+        snapshot() {
+            return [...tables.values()].map(copyDef);
+        },
+        restore(next) {
+            for (const def of next)
+                assertValidDef(def);
+            tables.clear();
+            for (const def of next)
+                tables.set(def.id, copyDef(def));
+        },
     };
 }
 /**

package/dist/game/narrativeAuthoring.d.ts

@@ -0,0 +1,67 @@
+import { type DialogueGraph } from "./dialogueGraph.js";
+/** Caller-reviewed facts for one authoring revision; event ids are in strict chronological order. */
+export interface NarrativeCanon {
+    readonly revision: string;
+    readonly characterIds: readonly string[];
+    readonly facts: Readonly<Record<string, string>>;
+    readonly eventIds: readonly string[];
+}
+/** An explicit assertion attached to a dialogue node; dialogue prose is never parsed. */
+export type NarrativeClaim = {
+    readonly nodeId: string;
+} & ({
+    readonly kind: "character";
+    readonly characterId: string;
+} | {
+    readonly kind: "fact";
+    readonly factId: string;
+    readonly value: string;
+} | {
+    readonly kind: "before";
+    readonly earlier: string;
+    readonly later: string;
+});
+/** Authored dialogue with optional structured assertions against canon. */
+export interface NarrativeDialogue {
+    readonly id: string;
+    readonly graph: DialogueGraph;
+    readonly claims: readonly NarrativeClaim[];
+}
+/** A candidate batch never changes canon; accepted new facts need a separately reviewed revision. */
+export interface NarrativeBatch {
+    readonly canonRevision: string;
+    readonly dialogues: readonly NarrativeDialogue[];
+}
+/** Caller budgets across the entire batch, including graph branches and explicit assertions. */
+export interface NarrativeBatchLimits {
+    readonly maxDialogues: number;
+    readonly maxNodes: number;
+    readonly maxChoices: number;
+    readonly maxClaims: number;
+    /** Sum of spoken lines and player choice text lengths (UTF-16 code units). */
+    readonly maxTextCharacters: number;
+}
+/** A repair diagnostic with a JSON-pointer location in the candidate batch. */
+export interface NarrativeIssue {
+    readonly code: string;
+    readonly severity: "error" | "warning";
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Detach and freeze reviewed canon before passing it to an asynchronous authoring callback.
+ * Duplicate character/event ids and an empty revision throw; facts retain exact caller values.
+ *
+ * @capability narrative-canon freeze caller-reviewed character ids, facts and chronology for a narrative authoring revision
+ */
+export declare function freezeNarrativeCanon(canon: NarrativeCanon): NarrativeCanon;
+/**
+ * Check a typed candidate against caller budgets, canon revision, explicit claims and graph topology.
+ * Stops at the first exceeded budget before topology work; stale revisions also stop immediately.
+ * Claims check exact fact values and the declared strict event order, never prose, speaker labels,
+ * motivations, branch consequences or story quality. O(canon + bounded nodes + choices + claims).
+ * Validate/parse external JSON before calling; this is not an untrusted JSON decoder.
+ *
+ * @capability narrative-batch-validation locate stale canon, oversized batches, explicit character/fact/chronology contradictions and dialogue graph issues for bounded repair
+ */
+export declare function validateNarrativeBatch(canon: NarrativeCanon, batch: NarrativeBatch, limits: NarrativeBatchLimits): NarrativeIssue[];

package/dist/game/narrativeAuthoring.js

@@ -0,0 +1,122 @@
+import { validateDialogueGraph } from "./dialogueGraph.js";
+/**
+ * Detach and freeze reviewed canon before passing it to an asynchronous authoring callback.
+ * Duplicate character/event ids and an empty revision throw; facts retain exact caller values.
+ *
+ * @capability narrative-canon freeze caller-reviewed character ids, facts and chronology for a narrative authoring revision
+ */
+export function freezeNarrativeCanon(canon) {
+    if (canon.revision.length === 0)
+        throw new RangeError("Canon revision must not be empty.");
+    for (const ids of [canon.characterIds, canon.eventIds]) {
+        if (new Set(ids).size !== ids.length)
+            throw new RangeError("Canon ids must be unique within each list.");
+    }
+    return Object.freeze({
+        revision: canon.revision,
+        characterIds: Object.freeze([...canon.characterIds]),
+        facts: Object.freeze({ ...canon.facts }),
+        eventIds: Object.freeze([...canon.eventIds]),
+    });
+}
+/**
+ * Check a typed candidate against caller budgets, canon revision, explicit claims and graph topology.
+ * Stops at the first exceeded budget before topology work; stale revisions also stop immediately.
+ * Claims check exact fact values and the declared strict event order, never prose, speaker labels,
+ * motivations, branch consequences or story quality. O(canon + bounded nodes + choices + claims).
+ * Validate/parse external JSON before calling; this is not an untrusted JSON decoder.
+ *
+ * @capability narrative-batch-validation locate stale canon, oversized batches, explicit character/fact/chronology contradictions and dialogue graph issues for bounded repair
+ */
+export function validateNarrativeBatch(canon, batch, limits) {
+    for (const value of Object.values(limits)) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new RangeError("Narrative limits must be non-negative safe integers.");
+    }
+    if (batch.canonRevision !== canon.revision) {
+        return [{ code: "stale-canon", severity: "error", path: "/canonRevision", message: "Candidate uses a different canon revision." }];
+    }
+    const budget = (path) => [{
+            code: "batch-budget", severity: "error", path, message: "Candidate exceeds the caller's narrative batch budget.",
+        }];
+    if (batch.dialogues.length > limits.maxDialogues)
+        return budget("/dialogues");
+    let nodes = 0;
+    let choices = 0;
+    let claims = 0;
+    let text = 0;
+    for (let index = 0; index < batch.dialogues.length; index++) {
+        const dialogue = batch.dialogues[index];
+        const path = `/dialogues/${index}`;
+        nodes += dialogue.graph.nodes.length;
+        claims += dialogue.claims.length;
+        if (nodes > limits.maxNodes)
+            return budget(`${path}/graph/nodes`);
+        if (claims > limits.maxClaims)
+            return budget(`${path}/claims`);
+        for (let nodeIndex = 0; nodeIndex < dialogue.graph.nodes.length; nodeIndex++) {
+            const node = dialogue.graph.nodes[nodeIndex];
+            choices += node.choices?.length ?? 0;
+            if (choices > limits.maxChoices)
+                return budget(`${path}/graph/nodes/${nodeIndex}/choices`);
+            text += node.text.length;
+            for (const choice of node.choices ?? [])
+                text += choice.text.length;
+            if (text > limits.maxTextCharacters)
+                return budget(`${path}/graph/nodes/${nodeIndex}`);
+        }
+    }
+    const issues = [];
+    const add = (code, path, message) => {
+        issues.push({ code, severity: "error", path, message });
+    };
+    const characters = new Set(canon.characterIds);
+    const facts = new Map(Object.entries(canon.facts));
+    const events = new Map(canon.eventIds.map((id, index) => [id, index]));
+    const dialogueIds = new Set();
+    for (let index = 0; index < batch.dialogues.length; index++) {
+        const dialogue = batch.dialogues[index];
+        const path = `/dialogues/${index}`;
+        if (dialogueIds.has(dialogue.id))
+            add("duplicate-dialogue", `${path}/id`, "Dialogue id repeats within the batch.");
+        dialogueIds.add(dialogue.id);
+        for (const issue of validateDialogueGraph(dialogue.graph)) {
+            let location = `${path}/graph`;
+            if (issue.nodeIndex !== undefined)
+                location += `/nodes/${issue.nodeIndex}`;
+            if (issue.choiceIndex !== undefined)
+                location += `/choices/${issue.choiceIndex}/to`;
+            if (issue.code === "missing-start")
+                location += "/start";
+            issues.push({ code: `dialogue:${issue.code}`, severity: issue.severity, path: location, message: issue.message });
+        }
+        const nodeIds = new Set(dialogue.graph.nodes.map((node) => node.id));
+        for (let claimIndex = 0; claimIndex < dialogue.claims.length; claimIndex++) {
+            const claim = dialogue.claims[claimIndex];
+            const location = `${path}/claims/${claimIndex}`;
+            if (!nodeIds.has(claim.nodeId))
+                add("missing-claim-node", `${location}/nodeId`, "Claim references an unknown dialogue node.");
+            if (claim.kind === "character" && !characters.has(claim.characterId)) {
+                add("unknown-character", `${location}/characterId`, "Claim references an unknown canon character.");
+            }
+            else if (claim.kind === "fact") {
+                if (!facts.has(claim.factId))
+                    add("unknown-fact", `${location}/factId`, "Claim references an unknown canon fact.");
+                else if (facts.get(claim.factId) !== claim.value)
+                    add("fact-conflict", `${location}/value`, "Claim differs from the reviewed fact value.");
+            }
+            else if (claim.kind === "before") {
+                const earlier = events.get(claim.earlier);
+                const later = events.get(claim.later);
+                if (earlier === undefined)
+                    add("unknown-event", `${location}/earlier`, "Claim references an unknown canon event.");
+                if (later === undefined)
+                    add("unknown-event", `${location}/later`, "Claim references an unknown canon event.");
+                if (earlier !== undefined && later !== undefined && earlier >= later) {
+                    add("chronology-conflict", location, "Claim contradicts the reviewed strict event order.");
+                }
+            }
+        }
+    }
+    return issues;
+}