@jgengine/core 0.29.0 → 0.31.0

package/dist/ai/director/sound.js

@@ -0,0 +1,113 @@
+const DEFAULTS = {
+    maxInvestigators: 3,
+    giveUpConfidence: 0.15,
+    maxSeconds: 20,
+    maxNoises: 16,
+};
+function flatDistance(a, b) {
+    return Math.hypot(a[0] - b[0], a[2] - b[2]);
+}
+/**
+ * Make enemies investigate a noise, reusing the hearing owner.
+ *
+ * The noise goes into `PerceptionService.pushStimulus` as a `sound` stimulus, so the same range,
+ * loudness and linear memory decay that every other hearing consumer gets apply here; this layer
+ * adds only the two things a squad needs: a *bound* on how many enemies chase one noise, and a
+ * *give-up* rule, both read back from that memory instead of a second copy of it. A sighting of the
+ * source during the hunt raises the same memory's confidence, so an investigation escalates into a
+ * pursuit without any bookkeeping here.
+ *
+ * @capability sound-hunting send a bounded set of nearby enemies to investigate a noise with decaying memory
+ */
+export function createSoundHunt(config) {
+    const maxInvestigators = Math.max(0, Math.floor(config.maxInvestigators ?? DEFAULTS.maxInvestigators));
+    const giveUp = Math.max(0, config.giveUpConfidence ?? DEFAULTS.giveUpConfidence);
+    const maxSeconds = Math.max(0, config.maxSeconds ?? DEFAULTS.maxSeconds);
+    const maxNoises = Math.max(1, Math.floor(config.maxNoises ?? DEFAULTS.maxNoises));
+    let entries = [];
+    return {
+        noise(event) {
+            if (!Number.isFinite(event.at))
+                throw new Error("noise.at must be finite.");
+            const loudness = Math.max(0, event.loudness ?? 1);
+            const audible = config.hearingRange * loudness;
+            const ranked = [];
+            if (audible > 0) {
+                for (const hunter of config.hunters(event.position, audible)) {
+                    if (hunter.id === event.sourceId)
+                        continue;
+                    if (flatDistance(hunter.position, event.position) >= audible)
+                        continue;
+                    ranked.push(hunter);
+                }
+            }
+            ranked.sort((a, b) => {
+                const distance = flatDistance(a.position, event.position) - flatDistance(b.position, event.position);
+                if (Math.abs(distance) > 0.0001)
+                    return distance;
+                return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+            });
+            const admitted = ranked.slice(0, maxInvestigators).map((hunter) => hunter.id);
+            config.perception.pushStimulus({
+                kind: "sound",
+                sourceId: event.sourceId,
+                position: [...event.position],
+                loudness,
+                at: event.at,
+            });
+            const admittedSet = new Set(admitted);
+            entries = entries
+                .filter((entry) => entry.noise.sourceId !== event.sourceId)
+                .map((entry) => ({ noise: entry.noise, hunters: entry.hunters.filter((id) => !admittedSet.has(id)) }))
+                .filter((entry) => entry.hunters.length > 0);
+            entries.push({
+                noise: { ...event, position: [...event.position], loudness },
+                hunters: admitted,
+            });
+            while (entries.length > maxNoises)
+                entries.shift();
+            return admitted;
+        },
+        investigations(nowMs) {
+            const results = [];
+            const kept = [];
+            for (const entry of entries) {
+                const ageSeconds = Math.max(0, nowMs - entry.noise.at) / 1000;
+                if (ageSeconds > maxSeconds)
+                    continue;
+                const alive = [];
+                for (const hunterId of entry.hunters) {
+                    const memory = config.perception.memoryOf(hunterId, entry.noise.sourceId);
+                    if (memory === null || memory.confidence <= giveUp)
+                        continue;
+                    alive.push(hunterId);
+                    results.push({
+                        hunterId,
+                        sourceId: entry.noise.sourceId,
+                        position: [...memory.lastKnownPos],
+                        confidence: memory.confidence,
+                        ageSeconds,
+                    });
+                }
+                if (alive.length > 0)
+                    kept.push({ noise: entry.noise, hunters: alive });
+            }
+            entries = kept;
+            return results;
+        },
+        snapshot() {
+            return {
+                entries: entries.map((entry) => ({
+                    noise: { ...entry.noise, position: [...entry.noise.position] },
+                    hunters: [...entry.hunters],
+                })),
+            };
+        },
+        restore(snapshot) {
+            entries = snapshot.entries.map((entry) => ({
+                noise: { ...entry.noise, position: [...entry.noise.position] },
+                hunters: [...entry.hunters],
+            }));
+        },
+    };
+}

package/dist/game/gameSave.d.ts

@@ -111,6 +111,12 @@ export interface GameSave {
     peek(slot: string): Promise<GameSaveDocument | null>;
     /** Slots this save has written. */
     slots(): Promise<string[]>;
+    /**
+     * Delete one slot's document and drop it from the slot index, so `slots()` and `peek()` stop
+     * seeing it. Resolves `true` when a document was removed and `false` when the slot held nothing.
+     * Deleting the active slot resets the registered systems to a fresh document.
+     */
+    deleteSlot(slot: string): Promise<boolean>;
     slot(): string;
     status(): SaveStatus;
     /** Monotonic change counter — bumps on any value or status change. */

package/dist/game/gameSave.js

@@ -150,6 +150,12 @@ export function createGameSave(config) {
             return stored.value;
         },
         slots: () => store.slots(),
+        async deleteSlot(slot) {
+            const deleted = await store.deleteSlot(slot);
+            if (deleted && slot === store.slot())
+                apply(store.value());
+            return deleted;
+        },
         slot: () => store.slot(),
         status: () => store.status(),
         revision: () => store.revision(),

package/dist/game/playableGame.d.ts

@@ -729,7 +729,7 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     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; `maxDistance` hides bars beyond this many world units from the render camera (default 60). */
+    /** 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 render camera, and unset derives the range from the camera and the target height (an overhead camera reaches the units it looks at). */
     worldHealthBars?: boolean | {
         statId?: string;
         roles?: readonly CatalogEntityRole[];
@@ -745,7 +745,7 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
      * 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 render camera (default 40). Headless: skin every part via `className`/`data-*` hooks
+     * world units from the render camera, and unset derives the range the same way the bars do. 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. Set `showHealth: false` for a name-only plate when a game already
      * draws the HP bar itself (its own HUD, or `worldHealthBars`) — otherwise the nameplate's built-in bar

package/dist/game/saveStore.d.ts

@@ -92,6 +92,13 @@ export interface SaveStore<T> {
     save(): Promise<void>;
     /** Delete the active slot and reset `value()` to `initial`. */
     clear(): Promise<void>;
+    /**
+     * Delete any slot: remove its stored payload and drop it from the slot index, so `slots()` and
+     * `peek()` stop seeing it. Resolves `true` when a payload was removed and `false` when the slot
+     * held nothing (an unknown slot is a no-op). Deleting the active slot resets `value()` to
+     * `initial`; other slots leave the live value alone.
+     */
+    deleteSlot(slot: string): Promise<boolean>;
     /**
      * Read a stored slot without touching the live value, active slot or status — what a save-select
      * menu shows. Returns `null` when the slot holds nothing.

package/dist/game/saveStore.js

@@ -231,6 +231,10 @@ export function createSaveStore(config) {
             firstDirtyAt = null;
             setStatus("idle");
             emit();
+            // Only a slot that holds a payload belongs in the index — loading an empty
+            // slot must not resurrect an id a deleteSlot removed.
+            if (raw === null)
+                return current;
             void rememberSlot(currentSlot).catch((error) => {
                 setStatus("error");
                 reportError(error);
@@ -279,6 +283,37 @@ export function createSaveStore(config) {
                 reportError(error);
             }
         },
+        async deleteSlot(slot) {
+            const wasActive = slot === currentSlot;
+            if (wasActive) {
+                clearTimer();
+                dirty = false;
+                firstDirtyAt = null;
+            }
+            const run = saveChain.then(async () => {
+                if (wasActive)
+                    setStatus("saving");
+                try {
+                    const existing = await backend.read(dataKey(slot));
+                    if (existing !== null)
+                        await backend.remove(dataKey(slot));
+                    await forgetSlot(slot);
+                    if (existing !== null && wasActive)
+                        current = initial;
+                    if (wasActive)
+                        setStatus("idle");
+                    emit();
+                    return existing !== null;
+                }
+                catch (error) {
+                    setStatus("error");
+                    reportError(error);
+                    return false;
+                }
+            });
+            saveChain = run.then(() => undefined, () => undefined);
+            return run;
+        },
         async switchSlot(slot) {
             if (dirty)
                 await save();

package/dist/gameplay.d.ts

@@ -88,7 +88,7 @@ export { createWeaponStats } from "./item/weapon.js";
 export { MAX_LOOT_AFFIXES, assertLootCatalog, compareLootItems, createLootRoller, lootLevelScale, lootStatContributions, rollLoot, scoreLootStats, validateLootItem, type LootBaseDef, type LootCatalog, type LootComparison, type LootComparisonOptions, type LootInstalledPart, type LootIssueCode, type LootItem, type LootManufacturerDef, type LootPartDef, type LootRollOptions, type LootRoller, type LootRollerOptions, type LootRollerState, type LootStatDelta, type LootValidationIssue, } from "./loot/lootGen.js";
 export { lootWeaponDefinition, type LootWeaponProjection, type LootWeaponStatMap } from "./loot/lootWeapon.js";
 export { chaseMission, defendMission, escortMission, type ChaseMissionOptions, type ComposedMissionOptions, type DefendMissionOptions, type EscortMissionOptions, } from "./mission/compositions.js";
-export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, type MissionActorFact, type MissionBranch, type MissionDef, type MissionEvent, type MissionEventFilter, type MissionFactCondition, type MissionFailCondition, type MissionFailDef, type MissionIssue, type MissionObjectiveDef, type MissionObjectiveKind, type MissionRewardAppliers, type MissionRewards, type MissionRuntime, type MissionRuntimeConfig, type MissionRuntimeSnapshot, type MissionState, type MissionStats, type MissionStatus, type MissionTickInput, type MissionValidationOptions, type MissionView, type MissionWorldEvent, type MissionWorldEventKind, } from "./mission/mission.js";
+export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_MARKER_TOLERANCE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, type MissionActorFact, type MissionBranch, type MissionDef, type MissionEvent, type MissionEventFilter, type MissionFactCondition, type MissionFailCondition, type MissionFailDef, type MissionIssue, type MissionMarkerPlane, type MissionMarkerProximity, type MissionObjectiveDef, type MissionObjectiveKind, type MissionRewardAppliers, type MissionRewards, type MissionRuntime, type MissionRuntimeConfig, type MissionRuntimeSnapshot, type MissionState, type MissionStats, type MissionStatus, type MissionTickInput, type MissionValidationOptions, type MissionView, type MissionWorldEvent, type MissionWorldEventKind, } from "./mission/mission.js";
 export { MISSION_TRIGGER_ACTIONS, createMissionTriggerBridge, missionMarkers, registerMissionTriggerActions, type MissionTriggerBridge, } from "./mission/triggers.js";
 export { compareGearSets, gearScore, type GearScore, type GearScoreOptions, type GearSlotItem, } from "./progression/gearScore.js";
 export { assertSkillTreeConfig, createSkillTree, type SkillActiveDef, type SkillNodeDef, type SkillRequirement, type SkillResolution, type SkillSpendReason, type SkillSpendResult, type SkillSynergyDef, type SkillTree, type SkillTreeConfig, type SkillTreeState, } from "./progression/skillTree.js";

package/dist/gameplay.js

@@ -88,7 +88,7 @@ export { createWeaponStats } from "./item/weapon.js";
 export { MAX_LOOT_AFFIXES, assertLootCatalog, compareLootItems, createLootRoller, lootLevelScale, lootStatContributions, rollLoot, scoreLootStats, validateLootItem, } from "./loot/lootGen.js";
 export { lootWeaponDefinition } from "./loot/lootWeapon.js";
 export { chaseMission, defendMission, escortMission, } from "./mission/compositions.js";
-export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, } from "./mission/mission.js";
+export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_MARKER_TOLERANCE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, } from "./mission/mission.js";
 export { MISSION_TRIGGER_ACTIONS, createMissionTriggerBridge, missionMarkers, registerMissionTriggerActions, } from "./mission/triggers.js";
 export { compareGearSets, gearScore, } from "./progression/gearScore.js";
 export { assertSkillTreeConfig, createSkillTree, } from "./progression/skillTree.js";

package/dist/item/affix.d.ts

@@ -5,6 +5,8 @@ export interface AffixDef {
     op?: AffixOp;
     roll: number | [number, number];
     weight: number;
+    /** Lowest item level whose roll pool includes this affix; omitted means every level. */
+    minLevel?: number;
     namePart?: {
         position: "prefix" | "suffix";
         text: string;

package/dist/loot/drop.d.ts

@@ -0,0 +1,47 @@
+import { type LootCatalog, type LootComparisonOptions, type LootItem, type LootRollOptions, type LootStatDelta } from "./lootGen.js";
+/** A rolled item with a stable instance id, so a stash, ledger and vendor stock can name it. */
+export interface ItemDrop extends LootItem {
+    id: string;
+}
+/** {@link rollDrop} options: the loot roll plus the instance id (defaults to `drop:<seed>`). */
+export interface RollDropOptions extends LootRollOptions {
+    id?: string;
+}
+/**
+ * Roll one item from a seed. Same seed, catalog and options produce the same id, name, affixes,
+ * stats and mass on every run; level gates which bases and affixes are in the pool.
+ *
+ * @capability item-roll roll one deterministic, level-gated item from a seed
+ */
+export declare function rollDrop(catalog: LootCatalog, seed: string | number, options?: RollDropOptions): ItemDrop;
+/** A per-stat delta from the equipped item to the candidate; positive `delta` means the candidate is larger. */
+export interface EquippedStatDelta extends LootStatDelta {
+    /** Whether this stat reads better on the candidate, following `lowerIsBetter`. */
+    better: "candidate" | "equipped" | "equal";
+}
+/** What a HUD renders when a drop lands: per-stat deltas against the worn item and one verdict. */
+export interface EquippedComparison {
+    candidateId: string;
+    equippedId: string | null;
+    deltas: readonly EquippedStatDelta[];
+    scoreCandidate: number;
+    scoreEquipped: number;
+    /** `scoreCandidate - scoreEquipped`. */
+    scoreDelta: number;
+    better: "candidate" | "equipped" | "equal";
+}
+/**
+ * Compare a dropped item against what is equipped, with one delta per stat and a weighted verdict.
+ * The delta is `candidate - equipped`; `better` flips for stats the caller lists in
+ * `lowerIsBetter`, so reload time improving does not read as worse. A missing equipped item
+ * compares against zeros.
+ *
+ * @capability item-comparison show per-stat deltas and a weighted verdict for a drop against equipped gear
+ */
+export declare function compareToEquipped(candidate: ItemDrop, equipped: ItemDrop | null, options?: LootComparisonOptions): EquippedComparison;
+/**
+ * Carried mass of a rolled item. Older saves may predate `mass`; those default to `1`.
+ *
+ * @capability item-weight read a rolled item's mass for a carry check
+ */
+export declare function itemMass(item: Pick<LootItem, "mass">): number;

package/dist/loot/drop.js

@@ -0,0 +1,57 @@
+import { compareLootItems, rollLoot, } from "./lootGen.js";
+import { seededRng } from "../random/rng.js";
+/**
+ * Roll one item from a seed. Same seed, catalog and options produce the same id, name, affixes,
+ * stats and mass on every run; level gates which bases and affixes are in the pool.
+ *
+ * @capability item-roll roll one deterministic, level-gated item from a seed
+ */
+export function rollDrop(catalog, seed, options = {}) {
+    const item = rollLoot(catalog, seededRng(seed), options);
+    return { ...item, id: options.id ?? `drop:${String(seed)}` };
+}
+const NO_ITEM = {
+    baseId: "none",
+    manufacturer: "none",
+    rarity: "none",
+    level: 0,
+    name: "",
+    parts: [],
+    affixes: [],
+    stats: {},
+    mass: 0,
+};
+/**
+ * Compare a dropped item against what is equipped, with one delta per stat and a weighted verdict.
+ * The delta is `candidate - equipped`; `better` flips for stats the caller lists in
+ * `lowerIsBetter`, so reload time improving does not read as worse. A missing equipped item
+ * compares against zeros.
+ *
+ * @capability item-comparison show per-stat deltas and a weighted verdict for a drop against equipped gear
+ */
+export function compareToEquipped(candidate, equipped, options = {}) {
+    const base = equipped ?? NO_ITEM;
+    const comparison = compareLootItems(base, candidate, options);
+    const lower = new Set(options.lowerIsBetter ?? []);
+    const deltas = comparison.deltas.map((entry) => ({
+        ...entry,
+        better: entry.delta === 0 ? "equal" : (entry.delta > 0) !== lower.has(entry.stat) ? "candidate" : "equipped",
+    }));
+    return {
+        candidateId: candidate.id,
+        equippedId: equipped?.id ?? null,
+        deltas,
+        scoreCandidate: comparison.scoreB,
+        scoreEquipped: comparison.scoreA,
+        scoreDelta: comparison.scoreDelta,
+        better: comparison.better === "b" ? "candidate" : comparison.better === "a" ? "equipped" : "equal",
+    };
+}
+/**
+ * Carried mass of a rolled item. Older saves may predate `mass`; those default to `1`.
+ *
+ * @capability item-weight read a rolled item's mass for a carry check
+ */
+export function itemMass(item) {
+    return item.mass !== undefined && Number.isFinite(item.mass) && item.mass > 0 ? item.mass : 1;
+}

package/dist/loot/haul.d.ts

@@ -0,0 +1,78 @@
+import { type WeightLookup } from "../inventory/carryLoad.js";
+import type { InventorySet, InventoryState } from "../inventory/inventoryModel.js";
+import type { ItemStack } from "../inventory/storageTier.js";
+import type { KeyValueStorage } from "../game/keyValueStore.js";
+/** What a carry attempt returns: the new load, or the rule that refused it. */
+export type CarryOutcome = {
+    ok: true;
+    mass: number;
+    remaining: number;
+} | {
+    ok: false;
+    reason: "over-capacity" | "no-space" | "invalid-count";
+    mass: number;
+    remaining: number;
+};
+/** Stacks moved between a run and its stash, or lost when the run fails. */
+export interface HaulTransfer {
+    /** Stacks that reached the stash, or were lost, in slot order. */
+    stacks: readonly ItemStack[];
+    /** Stacks the stash had no room for; they stay in the run inventory. */
+    refused: readonly ItemStack[];
+}
+/** Detached run and stash contents, for a save or a debug readout. */
+export interface RunHaulState {
+    run: InventoryState;
+    stash: InventoryState;
+}
+/** What a run haul needs: two inventories, a weight rule and an optional save cell. */
+export interface RunHaulConfig<TId extends string> {
+    /** The keyed inventory set that owns both the run and stash inventories. */
+    inventories: InventorySet<TId>;
+    /** Inventory carried during the run; its contents are lost on `fail`. */
+    runId: TId;
+    /** Inventories that survive a failed run; left out of the carry weight. */
+    stashId: TId;
+    /** Per-instance mass in the caller's weight unit; unknown ids weigh 0 only if the caller says so. */
+    weightOf: WeightLookup;
+    /** Carrying capacity in the same unit as `weightOf`. */
+    capacity: number;
+    /** Worn item ids, one unit each; they weigh against capacity. */
+    worn?: readonly string[];
+    /** Fraction of worn weight that counts (default `1`). */
+    wornFactor?: number;
+    /** Save backend for the stash; `null` keeps it in memory for the session only. */
+    storage?: KeyValueStorage | null;
+    /** Storage key; defaults to `"jgengine.items.stash"`. */
+    key?: string;
+}
+/** A run's carried loot and the stash that outlives it. */
+export interface RunHaul {
+    /** Add `count` of `itemId` to the run if the carrier can take its weight and there is slot room. */
+    carry(itemId: string, count?: number): CarryOutcome;
+    /** Move everything the stash fits out of the run and save; returns what moved and what did not. */
+    bank(): HaulTransfer;
+    /** Discard the run's haul and save the untouched stash; returns the lost stacks. */
+    fail(): HaulTransfer;
+    /** Load the stash from storage; false when absent or malformed. */
+    load(): boolean;
+    /** Write the stash to storage. */
+    save(): void;
+    state(): RunHaulState;
+    /** Replace run and stash contents; false without mutation when either is malformed. */
+    restore(next: RunHaulState): boolean;
+    /** Carried and stashed mass plus capacity left, for the HUD. */
+    mass(): {
+        run: number;
+        stash: number;
+        remaining: number;
+    };
+}
+/**
+ * A run's haul beside a persistent stash. Carrying is gated by the shared encumbrance rules;
+ * `bank` moves what the stash fits and saves; `fail` throws the run's haul away and leaves the
+ * stash as it was. The game decides when a run succeeds or fails and calls one of them.
+ *
+ * @capability item-run-haul carry loot with a weight gate, bank it into a persistent stash, or lose it when the run fails
+ */
+export declare function createRunHaul<TId extends string>(config: RunHaulConfig<TId>): RunHaul;

package/dist/loot/haul.js

@@ -0,0 +1,126 @@
+import { canCarry, characterLoad } from "../inventory/carryLoad.js";
+const DEFAULT_KEY = "jgengine.items.stash";
+function emptyLike(state) {
+    return { slots: new Array(state.slots.length).fill(null) };
+}
+function stacksOf(state) {
+    const out = [];
+    for (const slot of state.slots)
+        if (slot !== null)
+            out.push({ itemId: slot.itemId, count: slot.count });
+    return out;
+}
+/**
+ * A run's haul beside a persistent stash. Carrying is gated by the shared encumbrance rules;
+ * `bank` moves what the stash fits and saves; `fail` throws the run's haul away and leaves the
+ * stash as it was. The game decides when a run succeeds or fails and calls one of them.
+ *
+ * @capability item-run-haul carry loot with a weight gate, bank it into a persistent stash, or lose it when the run fails
+ */
+export function createRunHaul(config) {
+    const { inventories, runId, stashId } = config;
+    const key = config.key ?? DEFAULT_KEY;
+    const storage = config.storage ?? null;
+    const runMass = () => characterLoad({
+        carried: [inventories.state(runId)],
+        worn: config.worn,
+        wornFactor: config.wornFactor,
+        weightOf: config.weightOf,
+        capacity: config.capacity,
+    });
+    const persist = () => {
+        if (storage === null)
+            return;
+        try {
+            storage.setItem(key, JSON.stringify({ stash: inventories.snapshot()[stashId] }));
+        }
+        catch {
+            // A full or blocked save cell must not lose the live stash; the next save retries.
+        }
+    };
+    return {
+        carry(itemId, count = 1) {
+            const load = runMass();
+            if (!Number.isFinite(count) || count <= 0) {
+                return { ok: false, reason: "invalid-count", mass: load.mass, remaining: load.remaining };
+            }
+            const added = config.weightOf(itemId) * count;
+            if (!canCarry(load, added)) {
+                return { ok: false, reason: "over-capacity", mass: load.mass, remaining: load.remaining };
+            }
+            const put = inventories.put(runId, itemId, count);
+            if (put.status !== "ok") {
+                return { ok: false, reason: "no-space", mass: load.mass, remaining: load.remaining };
+            }
+            const after = runMass();
+            return { ok: true, mass: after.mass, remaining: after.remaining };
+        },
+        bank() {
+            const moved = [];
+            const refused = [];
+            const run = inventories.state(runId);
+            for (let slot = 0; slot < run.slots.length; slot += 1) {
+                const stack = inventories.state(runId).slots[slot];
+                if (stack === null)
+                    continue;
+                const put = inventories.put(stashId, stack.itemId, stack.count);
+                if (put.status !== "ok") {
+                    refused.push({ itemId: stack.itemId, count: stack.count });
+                    continue;
+                }
+                inventories.take(runId, stack.itemId, stack.count);
+                moved.push({ itemId: stack.itemId, count: stack.count });
+            }
+            persist();
+            return { stacks: moved, refused };
+        },
+        fail() {
+            const lost = stacksOf(inventories.state(runId));
+            inventories.replaceState(runId, emptyLike(inventories.state(runId)));
+            persist();
+            return { stacks: lost, refused: [] };
+        },
+        load() {
+            if (storage === null)
+                return false;
+            try {
+                const raw = storage.getItem(key);
+                if (raw === null)
+                    return false;
+                const saved = JSON.parse(raw);
+                if (saved === null || typeof saved !== "object" || saved.stash === undefined)
+                    return false;
+                const next = inventories.snapshot();
+                next[stashId] = saved.stash;
+                return inventories.restore(next);
+            }
+            catch {
+                return false;
+            }
+        },
+        save: persist,
+        state() {
+            const saved = inventories.snapshot();
+            return { run: saved[runId], stash: saved[stashId] };
+        },
+        restore(next) {
+            const attempt = inventories.snapshot();
+            attempt[runId] = next.run;
+            attempt[stashId] = next.stash;
+            return inventories.restore(attempt);
+        },
+        mass() {
+            const load = runMass();
+            let stash = 0;
+            for (const slot of inventories.state(stashId).slots) {
+                if (slot !== null)
+                    stash += config.weightOf(slot.itemId) * slot.count;
+            }
+            return {
+                run: load.carriedMass,
+                stash,
+                remaining: load.remaining,
+            };
+        },
+    };
+}

package/dist/loot/lootGen.d.ts

@@ -13,6 +13,10 @@ export interface LootPartDef extends PartDef {
 export interface LootBaseDef extends ItemBaseDef {
     /** Relative pick weight among bases a manufacturer can produce (default `1`). */
     weight?: number;
+    /** Lowest item level a roll may pick this base at; omitted means every level. */
+    minLevel?: number;
+    /** Mass at item level 1 in the caller's weight unit (default `1`); grows 10% per level. */
+    mass?: number;
     /** Free-form tags for caller filters and UI. */
     tags?: readonly string[];
     /** Mount slots a roll fills; every declared slot receives one part. */
@@ -69,6 +73,8 @@ export interface LootItem {
     parts: readonly LootInstalledPart[];
     affixes: readonly RolledAffix[];
     stats: Readonly<Record<string, number>>;
+    /** Carried mass from the base def at this level; absent on saves made before mass existed. */
+    mass?: number;
 }
 /** Pin any part of a roll; omitted fields are drawn from the catalog. */
 export interface LootRollOptions {
@@ -79,7 +85,7 @@ export interface LootRollOptions {
     rarity?: string;
 }
 /** A defect found by {@link validateLootItem}. */
-export type LootIssueCode = "invalid-level" | "unknown-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-finite-stat" | "empty-name";
+export type LootIssueCode = "invalid-level" | "unknown-base" | "level-gated-base" | "unknown-manufacturer" | "manufacturer-base" | "unknown-rarity" | "duplicate-slot" | "unknown-slot" | "missing-slot-part" | "unknown-part" | "part-category" | "unknown-affix" | "duplicate-affix" | "invalid-affix" | "non-finite-stat" | "invalid-mass" | "empty-name";
 /** One reason a rolled item is not legal against its catalog, with the offending value named. */
 export interface LootValidationIssue {
     code: LootIssueCode;