@jgengine/core 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -26,6 +26,38 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.31.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.31.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.28.0`; `@jgengine/github` is `0.18.0`.
+
+### Added
+
+- `createAgent` (`@jgengine/core/agents/agent`) runs one resident's whole loop on the world clock: needs decay through `sim/needs`, a utility brain picks among the targets the game offers, an authored day plan says where the agent belongs, and the agent falls back to a declared target when its pick disappears. Mood, action and the far flag snapshot and restore with the needs.
+- `createMoodReader` / `readMood` (`@jgengine/core/agents/mood`) derive a 0-100 mood and a caller-labelled tier from weighted need satisfaction, plus named sources a queue, a litter patch or a cold snap raises and clears.
+- `createAgentSchedule` (`@jgengine/core/agents/schedule`) resolves an authored day plan through `sim/routine` and adds a work beat: a stop names the places it patrols, so a janitor is an agent with a route rather than a special case. Off-hours behaviour is a stop without a beat.
+- `createRelationshipBook` (`@jgengine/core/agents/relationships`) keeps undirected familiarity and opinion per pair. A social action moves both and reports the milestones crossed, friends prefer each other's company, and a bonded pair refuses to split. Pair keys come from `relation/keyedValues` and crossings from `relation/thresholds`.
+- `GameSave.deleteSlot(slot)` and `SaveStore.deleteSlot(slot)` remove one slot's payload and drop it from the slot index; they resolve `true` when a document was removed and `false` for an unknown slot. Deleting the active slot resets the live state to the initial document. `load()` no longer lists a slot that holds nothing, so a deleted slot cannot return.
+- `HudPanel` takes `lane` (`@jgengine/react`): blocks naming the same anchor and lane stack without overlap, lanes in one anchor sit side by side, and `resolveHudLanes` resolves the rectangles. A moved panel leaves its lane and keeps its authored placement.
+- `hudBlockOverlaps` and `formatHudOverlapReport` (`@jgengine/react`) name every pair of rendered HUD blocks whose rectangles intersect, with both ids and the viewport; `HudCanvas` warns with that report in a dev build.
+- `rollDrop` (`@jgengine/core/loot/drop`) rolls one deterministic item from a seed and `compareToEquipped` turns it into per-stat deltas against worn gear with a weighted verdict a HUD can render.
+- `createRunHaul` (`@jgengine/core/loot/haul`) gates carried loot by weight through the shared encumbrance rules, banks what the persistent stash fits, and discards the run's haul when the game calls `fail`.
+- `salvageItem` and `createItemLedger` (`@jgengine/core/loot/salvage`) break an item down for the currency its level and rarity say and claim the instance, so a salvaged item cannot be salvaged, equipped or sold again.
+- `stockVendor` and `createVendorRotation` (`@jgengine/core/loot/vendor`) fill a `ShopStock` with rolled items priced through the economy wallet, with a run-count restock rule the game authors.
+- `markerProximity` on `createMissionRuntime` picks the plane a marker proximity test compares in: `"horizontal"` (default) measures ground distance and allows the actor a `tolerance` (default 8 m) above or below the marker, `"spatial"` is the straight 3D check for worlds with stacked platforms. `MissionMarkerPlane`, `MissionMarkerProximity` and `DEFAULT_MARKER_TOLERANCE` are exported with it.
+
+### Changed
+
+- `evaluatePressure` (`@jgengine/core/ai/director/pressure`) reads pressure as player control: a healthy player further into a run is leaned on harder, a hurt player is eased off, and every effect stays inside the rule's `maxTier`.
+- Loot bases and affixes take `minLevel`, so `rollLoot` only draws from entries at or below the item level. Loot bases take `mass`; rolled items carry it for carry checks.
+
+### Fixed
+
+- `HudCanvas` resolved its host with `canvas.parentElement`, which is `HudThemeRoot`'s `display: contents` element and measures 0x0 — the boundary overlay, the HUD-fit measurement and the new overlap report never ran under the standard HUD root. It now uses the nearest ancestor with a real box.
+- The HUD boundary check returned early whenever nothing overflowed, so a later report in the same pass could never run.
+- `reach`, `interact` and the `left-area` fail condition compared a marker in 3D, so a marker authored at `y=0` under rising ground was unreachable. They now read the same plane.
+
 ## 0.30.0
 
 ### Migrate

package/dist/ai/director/pressure.d.ts

@@ -5,18 +5,18 @@
  */
 /** What the director reads about the player before it chooses a tier. */
 export interface PressureReading {
-    /** Player health fraction `0..1`. Lower leans harder. */
+    /** Player health fraction `0..1`. A healthier player is leaned on harder. */
     health: number;
-    /** Encounter progress `0..1` — waves cleared over waves authored. Lower leans harder. */
+    /** Encounter progress `0..1` — waves cleared over waves authored. Further in leans harder. */
     progress: number;
     /** Seconds the encounter has run. Longer leans harder, up to the window. */
     elapsed: number;
 }
 /** The weights and window that turn a reading into an index, plus the hard cap. */
 export interface PressureRule {
-    /** Weight of low player health. Default `1`. */
+    /** Weight of the player staying in control (health). Default `0.5`. */
     healthWeight?: number;
-    /** Weight of the encounter not being finished. Default `1`. */
+    /** Weight of how far through the encounter the player is. Default `1`. */
     progressWeight?: number;
     /** Weight of time spent past `timeFloorSeconds`. Default `0.5`. */
     timeWeight?: number;
@@ -47,11 +47,12 @@ export interface PressurePlan {
 /**
  * Turn one reading into a bounded pressure plan.
  *
- * The index is the weighted mean of three terms — how hurt the player is (`1 - health`), how far
- * from finished the encounter is (`1 - progress`), and how long it has run — each clamped to
- * `0..1`, then split into `maxTier + 1` bands. Because every term and every derived effect is a
- * clamp of an authored cap, the rule cannot climb: a dead player on a stalled timer for an hour
- * lands on `tier === maxTier` with `countBonus === maxTier`, never above it.
+ * The index is the weighted mean of three terms — the player's health (staying in control), how far
+ * through the encounter they are, and how long it has run — each clamped to `0..1`, then split into
+ * `maxTier + 1` bands. A hurt player is leaned on *less*, so a director that reads this plan never
+ * piles on someone already losing. Because every term and every derived effect is a clamp of an
+ * authored cap, the rule cannot climb: a full-health player on a long run lands on
+ * `tier === maxTier` with `countBonus === maxTier`, never above it.
  *
  * @capability encounter-pressure bounded difficulty tier read from player health, encounter progress and time
  */

package/dist/ai/director/pressure.js

@@ -4,7 +4,7 @@
  * a callback, so a test can sweep it and a probe can print it.
  */
 const RULE_DEFAULTS = {
-    healthWeight: 1,
+    healthWeight: 0.5,
     progressWeight: 1,
     timeWeight: 0.5,
     timeFloorSeconds: 90,
@@ -35,11 +35,12 @@ function timeTerm(elapsed, rule) {
 /**
  * Turn one reading into a bounded pressure plan.
  *
- * The index is the weighted mean of three terms — how hurt the player is (`1 - health`), how far
- * from finished the encounter is (`1 - progress`), and how long it has run — each clamped to
- * `0..1`, then split into `maxTier + 1` bands. Because every term and every derived effect is a
- * clamp of an authored cap, the rule cannot climb: a dead player on a stalled timer for an hour
- * lands on `tier === maxTier` with `countBonus === maxTier`, never above it.
+ * The index is the weighted mean of three terms — the player's health (staying in control), how far
+ * through the encounter they are, and how long it has run — each clamped to `0..1`, then split into
+ * `maxTier + 1` bands. A hurt player is leaned on *less*, so a director that reads this plan never
+ * piles on someone already losing. Because every term and every derived effect is a clamp of an
+ * authored cap, the rule cannot climb: a full-health player on a long run lands on
+ * `tier === maxTier` with `countBonus === maxTier`, never above it.
  *
  * @capability encounter-pressure bounded difficulty tier read from player health, encounter progress and time
  */
@@ -52,8 +53,8 @@ export function evaluatePressure(reading, rule = {}) {
     const totalWeight = resolved.healthWeight + resolved.progressWeight + resolved.timeWeight;
     const index = totalWeight <= 0
         ? 0
-        : clamp01((resolved.healthWeight * (1 - health) +
-            resolved.progressWeight * (1 - progress) +
+        : clamp01((resolved.healthWeight * health +
+            resolved.progressWeight * progress +
             resolved.timeWeight * time) /
             totalWeight);
     const tier = Math.min(resolved.maxTier, Math.max(0, Math.floor(index * (resolved.maxTier + 1))));

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