@jgengine/core 0.25.0 → 0.27.0

package/dist/editor/types.d.ts

@@ -7,6 +7,7 @@ import type { MinimapBakeBounds } from "../world/minimapBake.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
 import type { EditorGridLayer } from "./grid.js";
 import type { EnvironmentSource } from "../render/environment.js";
+import type { IrradianceBakeSettings, IrradianceVolume } from "../render/lightProbes.js";
 import type { PointLightingConfig } from "../game/playableGame.js";
 /** Runtime point-light shape reused by authored editor light markers. */
 export type { PointLightingConfig } from "../game/playableGame.js";
@@ -196,6 +197,17 @@ export interface EditorBake {
 }
 /** Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`. */
 export type EditorSkyPreset = "day" | "dusk" | "night";
+/**
+ * An irradiance volume authored on the scene document: a grid of baked SH probes over a box, plus
+ * the bake settings that produced them so a scene can re-bake without the editor session.
+ * @capability light-probes author a baked irradiance volume on the scene document
+ */
+export interface EditorLightProbe extends IrradianceVolume {
+    /** Label shown in the lighting workspace. */
+    label?: string;
+    /** The authored bake inputs; absent means the volume was authored elsewhere and only the probe data matters. */
+    bake?: IrradianceBakeSettings;
+}
 /**
  * Linear distance fog authored on the scene document — serializable subset of sky/backdrop fog.
  * Absent fields keep engine defaults when the document is applied at runtime.
@@ -205,6 +217,40 @@ export interface EditorFogConfig {
     near?: number;
     far?: number;
 }
+/**
+ * Authored colour grading for the scene document's final image. The editor bakes a small
+ * display-space LUT from these controls and the shell applies it after tone mapping, so a game's
+ * grade is authored data like its sky, not a hardcoded pass in the game's config.
+ *
+ * The three band colours are display swatches (`#rrggbb`) that the pixels of that band are pulled
+ * toward, by `tint`. `saturation` and `contrast` are applied before the bands. Baking at a small cube
+ * size keeps the whole grade — including the LUT — a few hundred bytes of JSON.
+ */
+export interface EditorColorGrading {
+    /** Cube edge length the runtime bakes, 2..16. Default 8 — small enough to read, smooth enough for a grade. */
+    size?: number;
+    /** Swatch shadows are tinted toward, e.g. `#2a3a52` for a cool night. Absent leaves shadows alone. */
+    shadows?: string;
+    /** Swatch midtones are tinted toward. Absent leaves midtones alone. */
+    midtones?: string;
+    /** Swatch highlights are tinted toward, e.g. `#ffe9c4` for a warm sun. Absent leaves highlights alone. */
+    highlights?: string;
+    /** How far each band is pulled toward its swatch, 0..1. Default 0.45. */
+    tint?: number;
+    /** Display saturation around luma. Default 1. */
+    saturation?: number;
+    /** Display contrast around mid-grey. Default 1. */
+    contrast?: number;
+    /** Clamped auto-exposure authored with the grade; absent uses the pipeline's default range. */
+    autoExposure?: EditorAutoExposure;
+}
+/** Authored clamped auto-exposure range: how far the meter may pull a dark room or a bright street. */
+export interface EditorAutoExposure {
+    /** Lowest exposure multiplier the meter may reach. Default 0.5. */
+    min?: number;
+    /** Highest exposure multiplier the meter may reach. Default 2.5. */
+    max?: number;
+}
 /**
  * Scene-document environment/lighting authoring (#1110): sky preset, optional time-of-day drive,
  * horizon/zenith tints, sun/ambient intensity, and fog. Serializable and genre-agnostic — games
@@ -216,8 +262,16 @@ export interface EditorFogConfig {
 export interface EditorEnvironment {
     /** Optional runtime environment map source; absent keeps the procedural gradient. */
     source?: EnvironmentSource;
+    /** Authored clamped auto-exposure and colour grade; the shell applies it to the post chain. */
+    grading?: EditorColorGrading;
     /** Authored local point lights; the runtime clamps these to its bounded light budget. */
     pointLights?: readonly PointLightingConfig[];
+    /**
+     * Authored irradiance volumes: baked light probes for interiors and shaded streets. The runtime
+     * samples them at the camera and feeds three.js's scene light probe, so a room's ambient comes
+     * from its own lights instead of the sky.
+     */
+    probes?: readonly EditorLightProbe[];
     /** Fixed sky look when `timeOfDay` is off (or no clock is available). */
     preset?: EditorSkyPreset;
     /** Drive sun/sky from the world clock's day fraction instead of the fixed `preset`. */

package/dist/game/playableGame.d.ts

@@ -250,9 +250,15 @@ export interface ModelConfig {
     material?: ModelMaterialOverride;
     /** `false` keeps this model's exported material params and skips the engine's default painted surface detail. Default true. */
     surfaceDetail?: boolean;
+    /**
+     * Per-model wind sway for foliage: trunk and standing geometry stay planted while the upper
+     * canopy drifts in the shared gust field. `strength` is metres of tip travel, `speed` the gust
+     * rate, `height` the world height over which sway ramps in (defaults to the model's own height).
+     * `false` or omitted keeps the model rigid. Compiles into each cloned material.
+     */
+    wind?: ModelWindConfig | false;
     /** Reusable authored surfaces available to this model's named slot assignments. */
-    materialAssets?: readonly MaterialAsset[];
-    /** Sparse per-slot assignments; unselected imported materials keep their original appearance. */
+    materialAssets?: readonly MaterialAsset[]; /** Sparse per-slot assignments; unselected imported materials keep their original appearance. */
     materialAssignments?: readonly MaterialAssignment[];
     /** Hide named visual subtrees on this instance before placement measurement. Exact runtime names or unique original imported names resolve without removing bones or changing the cached model; missing or ambiguous names warn and leave existing visibility unchanged. Malformed lists reject before model or texture allocation. Omit or pass [] to retain imported visibility. */
     hiddenNodes?: readonly string[];
@@ -282,6 +288,17 @@ export interface ModelConfig {
     /** Tuning for the procedural part-motion driver when any part carries a `role`; omit for defaults. */
     partMotion?: PartMotionParams;
 }
+/** Wind sway for a foliage model; see {@link ModelConfig.wind}. */
+export interface ModelWindConfig {
+    /** Tip travel in metres. Default 0.35. */
+    strength?: number;
+    /** Gust rate multiplier. Default 1. */
+    speed?: number;
+    /** World height over which sway ramps from the base to full tip travel, in metres. Defaults to the model's measured height. */
+    height?: number;
+    /** Wind heading as a two-axis direction; defaults to the engine's shared gust direction. */
+    direction?: readonly [number, number];
+}
 /** Bone names and limits for {@link ModelConfig.ik}. */
 export interface ModelIkConfig {
     /** Thigh → shin → foot chains; omit to find them by bone name. `[]` turns foot IK off. */

package/dist/gameplay.d.ts

@@ -81,7 +81,12 @@ export { computeEffectiveStats, createModularItem, install, isComplete, missingR
 export { createItemUse, type ItemUseHandler, type ItemUseInput } from "./item/use.js";
 export { createUseBehaviorRegistry, type BehaviorConfig, type BehaviorState, type ComposedUse, type CompositionResult, type SerializedBehaviorState, type UseBehaviorContext, type UseBehaviorDef, type UseBehaviorOutcome, type UseBehaviorRef, type UseBehaviorRegistry, type UseBehaviorRejection, } from "./item/useBehavior.js";
 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 { 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";
 export { createStatGraph, statModifierContributions, type StatContribution, type StatContributionStep, type StatDeriveContext, type StatDerivedDef, type StatExplanation, type StatGraph, type StatGraphDef, type StatInputDef, type StatModEntry, type StatOp, type StatSheet, type StatSheetState, } from "./progression/statGraph.js";
+export { assertXpCurve, defineXpCurve, type XpCurve, type XpCurveDef, type XpGrowthRule, type XpLevelStep, } from "./progression/xpCurve.js";
 export { type CellGrid } from "./puzzle/cellGrid.js";
 export { type ShapeTable } from "./puzzle/fallingPiece.js";
 export { createNameGenerator } from "./random/nameGen.js";
@@ -95,6 +100,10 @@ export { createTriggeredRuleEngine, type ActiveEffect, type EffectRef, type Firi
 export { createRing, ringSampleAt, type Ring, type RingConfig, type RingPhase } from "./session/ring.js";
 export { type RoleSpec } from "./session/roles.js";
 export { type RoundConfig, type RoundSnapshot } from "./session/roundState.js";
+export { createNearAgents, type NearAgentSnapshot, type NearAgentView, type NearAgentsOptions, type NearCrowdAgents, } from "./sim/nearAgents.js";
+export { createNeedSet, type NeedDefinition, type NeedReading, type NeedSet, type NeedSnapshot } from "./sim/needs.js";
+export { createOffScreenWorld, type NearAgents, type NearHandoff, type NearSpawn, type OffScreenAgentView, type OffScreenMode, type OffScreenOptions, type OffScreenPolicy, type OffScreenPolicyPatch, type OffScreenResidentSpec, type OffScreenSnapshot, type OffScreenStats, type OffScreenWorld, } from "./sim/offScreen.js";
+export { resolveRoutine, type RoutineConfig, type RoutinePhase, type RoutineStop, type RoutineStopSpec, type RoutineTimeline, } from "./sim/routine.js";
 export { createDecayMeterSet, decayMeterMoodles, decayMeterSnapshot, decayMeterState, decayMeters, initDecayMeters, refillMeter, type DecayMeterSet, type DecayMeterValues, type DecayModifier, } from "./survival/decayMeter.js";
 export { createMoodleStack, stackMoodles, type Moodle, type MoodleStack } from "./survival/moodle.js";
 export { createMultiRegionHealth, type MultiRegionHealth } from "./survival/regionHealth.js";

package/dist/gameplay.js

@@ -81,7 +81,12 @@ export { computeEffectiveStats, createModularItem, install, isComplete, missingR
 export { createItemUse } from "./item/use.js";
 export { createUseBehaviorRegistry, } from "./item/useBehavior.js";
 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 { compareGearSets, gearScore, } from "./progression/gearScore.js";
+export { assertSkillTreeConfig, createSkillTree, } from "./progression/skillTree.js";
 export { createStatGraph, statModifierContributions, } from "./progression/statGraph.js";
+export { assertXpCurve, defineXpCurve, } from "./progression/xpCurve.js";
 export {} from "./puzzle/cellGrid.js";
 export {} from "./puzzle/fallingPiece.js";
 export { createNameGenerator } from "./random/nameGen.js";
@@ -95,6 +100,10 @@ export { createTriggeredRuleEngine, } from "./rules/triggeredRules.js";
 export { createRing, ringSampleAt } from "./session/ring.js";
 export {} from "./session/roles.js";
 export {} from "./session/roundState.js";
+export { createNearAgents, } from "./sim/nearAgents.js";
+export { createNeedSet } from "./sim/needs.js";
+export { createOffScreenWorld, } from "./sim/offScreen.js";
+export { resolveRoutine, } from "./sim/routine.js";
 export { createDecayMeterSet, decayMeterMoodles, decayMeterSnapshot, decayMeterState, decayMeters, initDecayMeters, refillMeter, } from "./survival/decayMeter.js";
 export { createMoodleStack, stackMoodles } from "./survival/moodle.js";
 export { createMultiRegionHealth } from "./survival/regionHealth.js";

package/dist/inventory/carryLoad.d.ts

@@ -0,0 +1,48 @@
+import { type EncumbranceConfig, type EncumbranceState, type LoadEntry } from "./encumbrance.js";
+import type { InventoryState } from "./inventoryModel.js";
+/** Per-item mass in the caller's weight unit; an unknown item weighs 0. */
+export type WeightLookup = (itemId: string) => number;
+/**
+ * Every filled stack in the given inventories as load entries, in slot order. Only the inventories
+ * the caller passes count, so a stash left out of the list adds no weight.
+ *
+ * @capability carry-load read carried stacks out of one or more inventories for a weight query
+ */
+export declare function carriedEntries(states: readonly InventoryState[]): LoadEntry[];
+/** Everything a {@link characterLoad} reading takes: carried inventories, worn gear and the capacity they are measured against. */
+export interface CharacterLoadInput {
+    /** Carried inventories (bag, rig, pockets); a stash left out does not weigh anything. */
+    carried?: readonly InventoryState[];
+    /** Worn item ids, one unit each — `Equipment.worn()` mapped to `itemId`. */
+    worn?: readonly string[];
+    weightOf: WeightLookup;
+    /** Carrying capacity in the same unit as `weightOf`; the caller adds level and gear bonuses. */
+    capacity: number;
+    /** Fraction of worn gear weight that counts against capacity (default `1`). */
+    wornFactor?: number;
+    encumbrance?: EncumbranceConfig;
+}
+/** A carrier's load: the encumbrance state, how it splits into carried and worn, and capacity left. */
+export interface CharacterLoad extends EncumbranceState {
+    /** Mass of the carried inventories alone. */
+    carriedMass: number;
+    /** Mass worn gear adds after `wornFactor`. */
+    wornMass: number;
+    /** Capacity left before the carrier is immobile; negative when overloaded. */
+    remaining: number;
+}
+/**
+ * Weigh a character: carried stacks plus worn gear against a capacity, resolved into the shared
+ * encumbrance bands. Movement reads `moveMultiplier`, `canSprint`, `canJump` and `immobile`; pickup
+ * gates read `remaining` or {@link canCarry}. The stash is not part of `carried`, so it adds nothing.
+ *
+ * @capability carry-encumbrance weigh carried inventories plus worn gear against a capacity and hand back movement penalties
+ */
+export declare function characterLoad(input: CharacterLoadInput): CharacterLoad;
+/**
+ * Whether `addedMass` more weight still fits under `capacity`. Pure: the caller decides what to do
+ * with a refusal, so an overload policy stays with the game.
+ *
+ * @capability carry-encumbrance gate a pickup against the carrier's remaining capacity
+ */
+export declare function canCarry(load: Pick<CharacterLoad, "mass" | "capacity">, addedMass: number): boolean;

package/dist/inventory/carryLoad.js

@@ -0,0 +1,44 @@
+import { resolveEncumbrance, totalLoad, } from "./encumbrance.js";
+/**
+ * Every filled stack in the given inventories as load entries, in slot order. Only the inventories
+ * the caller passes count, so a stash left out of the list adds no weight.
+ *
+ * @capability carry-load read carried stacks out of one or more inventories for a weight query
+ */
+export function carriedEntries(states) {
+    const entries = [];
+    for (const state of states) {
+        for (const slot of state.slots) {
+            if (slot !== null)
+                entries.push({ itemId: slot.itemId, quantity: slot.count });
+        }
+    }
+    return entries;
+}
+/**
+ * Weigh a character: carried stacks plus worn gear against a capacity, resolved into the shared
+ * encumbrance bands. Movement reads `moveMultiplier`, `canSprint`, `canJump` and `immobile`; pickup
+ * gates read `remaining` or {@link canCarry}. The stash is not part of `carried`, so it adds nothing.
+ *
+ * @capability carry-encumbrance weigh carried inventories plus worn gear against a capacity and hand back movement penalties
+ */
+export function characterLoad(input) {
+    const carriedMass = totalLoad(carriedEntries(input.carried ?? []), input.weightOf);
+    const factor = input.wornFactor !== undefined && Number.isFinite(input.wornFactor) && input.wornFactor >= 0
+        ? input.wornFactor
+        : 1;
+    const wornEntries = (input.worn ?? []).map((itemId) => ({ itemId, quantity: 1 }));
+    const wornMass = totalLoad(wornEntries, input.weightOf) * factor;
+    const base = resolveEncumbrance(carriedMass + wornMass, input.capacity, input.encumbrance);
+    return { ...base, carriedMass, wornMass, remaining: input.capacity - base.mass };
+}
+/**
+ * Whether `addedMass` more weight still fits under `capacity`. Pure: the caller decides what to do
+ * with a refusal, so an overload policy stays with the game.
+ *
+ * @capability carry-encumbrance gate a pickup against the carrier's remaining capacity
+ */
+export function canCarry(load, addedMass) {
+    const added = Number.isFinite(addedMass) && addedMass > 0 ? addedMass : 0;
+    return load.mass + added <= load.capacity;
+}

package/dist/inventory/equipment.d.ts

@@ -0,0 +1,95 @@
+/** One body slot: the item kinds it accepts and the slots it occupies while filled. */
+export interface EquipSlotDef {
+    /** Stable slot id, in the caller's nouns ("weapon", "rig", "boots"). */
+    id: string;
+    /** Item kinds this slot accepts; omitted accepts any kind. */
+    accepts?: readonly string[];
+    /** Slot ids this slot occupies while filled, e.g. a two-handed weapon blocking "offhand". */
+    blocks?: readonly string[];
+}
+/**
+ * The gear facts the equip rules read from an item. A rolled item resolves its runtime id through
+ * the instance registry to its base and answers from that base's data — this is not a second item type.
+ */
+export interface EquipItemDef {
+    /** Slot ids this item may occupy, most preferred first. */
+    slots: readonly string[];
+    /** Kind tag checked against {@link EquipSlotDef.accepts}. */
+    kind?: string;
+}
+/** Item lookup the rules read; returns nothing for an unknown id. */
+export type EquipItemLookup = (itemId: string) => EquipItemDef | null | undefined;
+/** Serializable equip state: the filled slots as `[slotId, itemId]` pairs. */
+export interface EquipmentState {
+    slots: readonly (readonly [string, string])[];
+}
+/** Why an equip attempt was refused; `detail` names the item and slots involved. */
+export type EquipRejection = "unknown-slot" | "not-equippable" | "wrong-slot" | "already-equipped" | "blocked";
+/** An equip attempt: the new worn set plus the replaced item, or the refusal with its reason and detail. */
+export type EquipResult = {
+    status: "ok";
+    state: EquipmentState;
+    slotId: string;
+    replaced: string | null;
+} | {
+    status: "rejected";
+    reason: EquipRejection;
+    detail: string;
+};
+/** An unequip attempt: the new worn set plus the item taken off, or the refusal with its detail. */
+export type UnequipResult = {
+    status: "ok";
+    state: EquipmentState;
+    itemId: string;
+} | {
+    status: "rejected";
+    reason: "unknown-slot" | "empty-slot";
+    detail: string;
+};
+/** One worn item and the slot holding it. */
+export interface WornEntry {
+    slotId: string;
+    itemId: string;
+}
+/** What the debug overlay reads about a worn set. */
+export interface EquipmentProbeReading {
+    filled: number;
+    slots: Readonly<Record<string, string>>;
+}
+/** A worn-gear set: one item per slot, rules from slot and item data, state out and back in. */
+export interface Equipment {
+    /** Wear `itemId` in `slotId`; a filled slot is replaced and its item returned as `replaced`. */
+    equip(slotId: string, itemId: string): EquipResult;
+    /** Wear `itemId` in the first of its preferred slots that is empty, else the first slot that accepts it. */
+    equipBest(itemId: string): EquipResult;
+    /** Clear `slotId` and hand back the item it held. */
+    unequip(slotId: string): UnequipResult;
+    /** Worn items in declared slot order. */
+    worn(): readonly WornEntry[];
+    /** The slot holding `itemId`, or null when that item is not worn. */
+    slotOf(itemId: string): string | null;
+    /** Declared slot ids, in order. */
+    slotIds(): readonly string[];
+    state(): EquipmentState;
+    /** Replace the worn set; returns false without mutation when an entry breaks the rules. */
+    restore(next: EquipmentState): boolean;
+    reset(): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/** Options for {@link createEquipment}. */
+export interface EquipmentOptions {
+    /** Register a devtools probe under this name reporting which slots are filled. */
+    devtoolsName?: string;
+}
+/**
+ * A worn-gear set over caller slot and item data.
+ *
+ * Slot defs own what a slot accepts and which slots it blocks; item defs own which slots an item may
+ * occupy and its kind. Equipping into a filled slot swaps and returns the replaced item, so gear is
+ * never silently lost: the caller puts `replaced` back. A two-handed item and the slot it blocks
+ * cannot both be filled, and the rejection names the occupied slot.
+ *
+ * @capability equipment-slot-inventory wear gear by slot with item-kind rules, two-handed blocking and replace-on-equip
+ */
+export declare function createEquipment(slotDefs: readonly EquipSlotDef[], lookup: EquipItemLookup, options?: EquipmentOptions): Equipment;

package/dist/inventory/equipment.js

@@ -0,0 +1,169 @@
+import { devtools } from "../devtools/devtools.js";
+function slotAcceptsKind(slot, kind) {
+    if (slot.accepts === undefined)
+        return true;
+    return kind !== undefined && slot.accepts.includes(kind);
+}
+/**
+ * A worn-gear set over caller slot and item data.
+ *
+ * Slot defs own what a slot accepts and which slots it blocks; item defs own which slots an item may
+ * occupy and its kind. Equipping into a filled slot swaps and returns the replaced item, so gear is
+ * never silently lost: the caller puts `replaced` back. A two-handed item and the slot it blocks
+ * cannot both be filled, and the rejection names the occupied slot.
+ *
+ * @capability equipment-slot-inventory wear gear by slot with item-kind rules, two-handed blocking and replace-on-equip
+ */
+export function createEquipment(slotDefs, lookup, options = {}) {
+    const byId = new Map();
+    for (const def of slotDefs) {
+        if (def.id.trim() === "")
+            throw new RangeError('Equipment slot field "id" must not be empty');
+        if (byId.has(def.id))
+            throw new RangeError(`Equipment slot "${def.id}" is declared twice`);
+        byId.set(def.id, def);
+    }
+    const order = slotDefs.map((def) => def.id);
+    const filled = new Map();
+    function readState() {
+        const slots = [];
+        for (const slotId of order) {
+            const itemId = filled.get(slotId);
+            if (itemId !== undefined)
+                slots.push([slotId, itemId]);
+        }
+        return { slots };
+    }
+    function conflicts(slotId, occupied = filled) {
+        const blockedByOwn = byId.get(slotId)?.blocks ?? [];
+        const blocking = order.filter((other) => other !== slotId && (byId.get(other)?.blocks ?? []).includes(slotId));
+        return [...new Set([...blockedByOwn, ...blocking])].filter((other) => occupied.has(other));
+    }
+    function check(slotId, itemId, occupied) {
+        const slot = byId.get(slotId);
+        if (slot === undefined) {
+            return { status: "rejected", reason: "unknown-slot", detail: `"${slotId}" is not a declared slot (${order.join(", ")})` };
+        }
+        const item = lookup(itemId);
+        if (item === null || item === undefined || item.slots.length === 0) {
+            return { status: "rejected", reason: "not-equippable", detail: `item "${itemId}" declares no equip slot` };
+        }
+        if (!item.slots.includes(slotId)) {
+            return {
+                status: "rejected",
+                reason: "wrong-slot",
+                detail: `item "${itemId}" belongs in ${item.slots.join(", ")}; "${slotId}" is not one of them`,
+            };
+        }
+        if (!slotAcceptsKind(slot, item.kind)) {
+            return {
+                status: "rejected",
+                reason: "wrong-slot",
+                detail: `slot "${slotId}" accepts ${(slot.accepts ?? []).join(", ")}; item "${itemId}" is ${item.kind ?? "untyped"}`,
+            };
+        }
+        const wornAt = [...occupied].find(([, worn]) => worn === itemId)?.[0];
+        if (wornAt !== undefined && wornAt !== slotId) {
+            return { status: "rejected", reason: "already-equipped", detail: `item "${itemId}" is already worn in "${wornAt}"` };
+        }
+        const conflict = conflicts(slotId, occupied).filter((other) => other !== slotId)[0];
+        if (conflict !== undefined) {
+            return {
+                status: "rejected",
+                reason: "blocked",
+                detail: `slot "${conflict}" is occupied and cannot be worn with "${slotId}"`,
+            };
+        }
+        return null;
+    }
+    function equipInto(slotId, itemId) {
+        const refusal = check(slotId, itemId, filled);
+        if (refusal !== null)
+            return refusal;
+        const replaced = filled.get(slotId) ?? null;
+        filled.set(slotId, itemId);
+        return { status: "ok", state: readState(), slotId, replaced };
+    }
+    const probe = options.devtoolsName === undefined
+        ? null
+        : devtools.probes.register(options.devtoolsName, () => ({
+            filled: filled.size,
+            slots: Object.fromEntries(filled),
+        }));
+    return {
+        equip: equipInto,
+        equipBest(itemId) {
+            const item = lookup(itemId);
+            if (item === null || item === undefined || item.slots.length === 0) {
+                return { status: "rejected", reason: "not-equippable", detail: `item "${itemId}" declares no equip slot` };
+            }
+            const allowed = item.slots.filter((slotId) => byId.has(slotId));
+            if (allowed.length === 0) {
+                return {
+                    status: "rejected",
+                    reason: "unknown-slot",
+                    detail: `item "${itemId}" names no declared slot (${item.slots.join(", ")})`,
+                };
+            }
+            const preferred = allowed.filter((slotId) => check(slotId, itemId, filled) === null);
+            if (preferred.length === 0)
+                return check(allowed[0], itemId, filled);
+            return equipInto(preferred.find((slotId) => !filled.has(slotId)) ?? preferred[0], itemId);
+        },
+        unequip(slotId) {
+            if (!byId.has(slotId)) {
+                return { status: "rejected", reason: "unknown-slot", detail: `"${slotId}" is not a declared slot (${order.join(", ")})` };
+            }
+            const itemId = filled.get(slotId);
+            if (itemId === undefined) {
+                return { status: "rejected", reason: "empty-slot", detail: `slot "${slotId}" holds nothing` };
+            }
+            filled.delete(slotId);
+            return { status: "ok", state: readState(), itemId };
+        },
+        worn() {
+            const out = [];
+            for (const slotId of order) {
+                const itemId = filled.get(slotId);
+                if (itemId !== undefined)
+                    out.push({ slotId, itemId });
+            }
+            return out;
+        },
+        slotOf(itemId) {
+            for (const [slotId, worn] of filled)
+                if (worn === itemId)
+                    return slotId;
+            return null;
+        },
+        slotIds: () => [...order],
+        state: readState,
+        restore(next) {
+            if (next === null || typeof next !== "object" || !Array.isArray(next.slots))
+                return false;
+            const staged = new Map();
+            for (const entry of next.slots) {
+                if (!Array.isArray(entry) || entry.length !== 2)
+                    return false;
+                const [slotId, itemId] = entry;
+                if (typeof slotId !== "string" || typeof itemId !== "string" || itemId.trim() === "")
+                    return false;
+                if (staged.has(slotId))
+                    return false;
+                if (check(slotId, itemId, staged) !== null)
+                    return false;
+                staged.set(slotId, itemId);
+            }
+            filled.clear();
+            for (const [slotId, itemId] of staged)
+                filled.set(slotId, itemId);
+            return true;
+        },
+        reset() {
+            filled.clear();
+        },
+        dispose() {
+            probe?.();
+        },
+    };
+}

package/dist/inventory/inventoryModel.d.ts

@@ -41,7 +41,7 @@ export type SplitResult = {
     state: InventoryState;
 } | {
     status: "rejected";
-    reason: "invalid-slot" | "empty-slot" | "invalid-amount" | "no-space" | "slot-occupied";
+    reason: "invalid-slot" | "empty-slot" | "invalid-amount" | "no-space" | "slot-occupied" | "over-stack";
 };
 /**
  * A bag of stackable items supporting add, remove, count, and move — the base inventory model.
@@ -63,13 +63,14 @@ export declare function hasItem(state: InventoryState, itemId: string, count: nu
 export declare function moveItem(from: InventoryState, fromSlot: number, to: InventoryState, toLayout: InventoryLayout, traits: ItemTraits, toSlot?: number): MoveResult;
 /**
  * Splits `amount` off the stack in `slot` into `toSlot` (or the first empty slot when `toSlot` is
- * omitted). Limit-agnostic: it does not consult {@link ItemTraits}, so a same-item target merges by
- * simple addition. Rejects an empty source, `amount <= 0`, `amount >= stack count` (a split must
- * leave both sides non-empty), no free slot, or a target holding a different item.
+ * omitted). Without `limit` it is limit-agnostic: a same-item target merges by simple addition.
+ * Pass the item's stack limit to keep the merge legal, which rejects `over-stack`. Rejects an empty
+ * source, `amount <= 0`, `amount >= stack count` (a split must leave both sides non-empty), no free
+ * slot, or a target holding a different item.
  *
- * @capability inventory-split split a stack into a target or first-empty slot
+ * @capability inventory-split split a stack into a target or first-empty slot, honoring a stack limit
  */
-export declare function splitStack(state: InventoryState, slot: number, amount: number, toSlot?: number): SplitResult;
+export declare function splitStack(state: InventoryState, slot: number, amount: number, toSlot?: number, limit?: number): SplitResult;
 export interface InventorySet<TId extends string> {
     put(id: TId, itemId: string, count: number, options?: {
         slot?: number;
@@ -80,6 +81,14 @@ export interface InventorySet<TId extends string> {
     has(id: TId, itemId: string, count: number): boolean;
     state(id: TId): InventoryState;
     replaceState(id: TId, state: InventoryState): void;
+    /** Detached copy of every declared inventory — a save, never a live alias. */
+    snapshot(): InventorySetState<TId>;
+    /** Replace every declared inventory from a snapshot; returns false without mutation when an entry is malformed or incomplete. */
+    restore(next: InventorySetState<TId>): boolean;
+    /** Empty every declared inventory. */
+    reset(): void;
 }
+/** Every inventory in a set, keyed by id, as plain slot data. */
+export type InventorySetState<TId extends string> = Record<TId, InventoryState>;
 /** Build a keyed set of named inventories from their `layouts`, sharing one `traits` table — the stateful façade over put/take/move/count. */
 export declare function createInventorySet<TId extends string>(layouts: Record<TId, InventoryLayout>, traits: ItemTraits): InventorySet<TId>;