@jgengine/core 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -26,6 +26,50 @@ 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.27.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.27.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.24.0`; `@jgengine/github` is `0.14.0`.
+
+### Added
+
+- `rollLoot` (`@jgengine/core/loot/lootGen`) rolls a named item from a caller `LootCatalog`: bases with mount slots, parts, affix pools, weighted rarity tiers, manufacturer personalities and a `levelScale` curve. Stats are `base × rarity.statScale × levelScale`, then part stats/multipliers, maker `bias`/`scale`, then additive and multiplicative affixes; additive affix rolls scale with level, multiplicative ones do not.
+- `createLootRoller` wraps a validated catalog with roll counts per rarity, `snapshot()`/`restore()`/`reset()` and an optional devtools probe; `assertLootCatalog` rejects duplicate ids, unresolvable pools, empty item slots and a non-ascending level curve at construction.
+- `validateLootItem` returns coded issues (`unknown-base`, `manufacturer-base`, `missing-slot-part`, `part-category`, `unknown-affix`, `empty-name`, …) and `compareLootItems` returns sorted per-stat deltas plus a weighted score with caller-named `lowerIsBetter` stats.
+- `lootWeaponDefinition` (`@jgengine/core/loot/lootWeapon`) projects a rolled item onto a `WeaponDefinition` through a caller stat map, so a generated gun runs in `createWeaponSystem` after `assertWeaponDefinition`.
+- `defineXpCurve` (`@jgengine/core/gameplay`) resolves one authored growth rule (`flat`, `linear`, `power`, `geometric`, `table`) plus a `maxLevel` cap into per-level thresholds, lifetime totals, a plain-words rule string and a `leveling` track.
+- `createSkillTree` spends and refunds points over authored nodes with `cost`, `requires`, `excludes`, passives, actives and multi-node `synergies`; `resolved()` returns the stat modifiers and actions, and state snapshots/restores as `{ points, ranks }`.
+- `gearScore` / `compareGearSets` score a whole loadout from stat weights, level, rarity and slot coverage.
+- `lootStatContributions` and `scoreLootStats` expose the weight policy `compareLootItems` already used.
+- `createEquipment` (`@jgengine/core/inventory/equipment`) wears gear by slot: slot defs declare accepted kinds and the slots they block, item defs declare the slots an item may occupy, a filled slot swaps and hands back the replaced item, and a two-handed item and the slot it blocks cannot both be filled. `state()` / `restore()` round-trip the worn set; a devtools probe reports filled slots.
+- `characterLoad` and `canCarry` (`@jgengine/core/inventory/carryLoad`) weigh carried inventories plus worn gear against a capacity and hand back the shared encumbrance bands (tier, `moveMultiplier`, sprint/jump gates, `remaining`), so a stash left out of `carried` adds no weight.
+- `fitShapedItem` (`@jgengine/core/inventory/shapedGrid`) places a shaped item at its first fit or names why not: `too-large` (with both sizes), `no-space`, `budget-exceeded`.
+- `InventorySet.snapshot()` / `restore()` / `reset()` (`@jgengine/core/inventory/inventoryModel`) save and reload every declared inventory as detached plain data, so a bag and a stash never share live slots.
+- `splitStack` takes an optional stack `limit`, rejecting `over-stack` instead of merging past the max stack.
+- `createLaneGraph` and `laneGraphFromDocument` (`@jgengine/core/world`) read an authored lane graph out of the scene document: `traffic_lane` paths are one directed span each, `road` paths (the street bake) become a lane per direction split where streets cross, `traffic_intersection` markers carry signal phases and right-of-way in `meta`, and `traffic_parking` markers place kerbside spots.
+- `createTraffic` (`@jgengine/core/world`) runs cars on that graph: IDM car following and braking, one car at a time through each intersection box behind a signal phase or first-come right-of-way, lane changes across authored neighbours, parking that reserves a spot, deterministic injected variety, `snapshot`/`restore`, and a devtools probe.
+- `Traffic.setDemand(count)` is the fleet target; the time-of-day curve stays the caller's policy.
+- `applyVehicleParts` (`@jgengine/core/world`) composes data-driven tuning parts onto a `KinematicVehicleTuning` — stat multipliers/addends applied in install order plus an optional tire grip curve — and returns the composed tuning, the installed ids, and a `VehicleFeel` (top speed, drive, brakes, turn rate, handbrake grip, and the grip curve's peak/slide). `withPart` swaps a part within its slot and `feelOf` reads the numbers out of any tuning.
+- `createVehicleDamage` (`@jgengine/core/world`) is fixed-zone crash damage wired to handling and visuals: impacts accumulate into discrete stages, each stage costs grip/drive/brakes/top speed/drag and pulls the steering (`effect`), and each zone shows one bounded dent (`deformation`) that never exceeds its authored `deform`. Parts can detach at a set stage, a total impulse can disable the vehicle, and `snapshot`/`restore` resume mid-crash. `damagedTuning` and `damagedAxis` fold the effect into a tuning or an input, and `modifiers()` carries it as per-tick overrides.
+- `KinematicVehicleTuning.weightTransfer` (`@jgengine/core/world`) adds load-transfer grip: longitudinal transfer under braking/traction and lateral transfer under cornering cut the tire grip curve (tire load sensitivity), so braking into a corner holds less slide than coasting through it. Each tick reports `weightTransfer` and `loadGrip`; omitting the block keeps the previous flat-grip model exactly.
+- `KinematicVehicleModifiers.gripScale` scales the grip curve for one tick, mirroring `VehicleDynamicsModifiers.gripScale` so a damage layer drives either sim.
+- `decal` scene kind (`@jgengine/core/world/decalKind`) and its renderer (`@jgengine/shell/scene/DecalRenderer`): dirt, cracks, paint and blood decals authored as placed markers, draped on the live terrain or standing on an authored tilt, with a deterministic procedural texture per style+seed.
+- `TerrainMaterialLayer.material` (`@jgengine/core/world/terraform`): a material library name whose scanned color map paints that terrain layer. The runtime samples up to four layer maps at each layer's `tiling` and blends them through the authored mask weights (`createTerrainDetailMaterial`'s `layerMaps`), so painted terrain blends between authored layers instead of tiling one flat map.
+- `grass_field` volumes now paint a ground-cover mat under their blades (`groundCover` rule, `@jgengine/shell/terrain/GrassCover`), so an authored patch reads as turf rather than bare ground with stubble. `GrassEnvironmentConfig.groundCover` does the same for `grass()` patches.
+- `ModelConfig.wind` (`@jgengine/core/game/playableGame`) and `applyModelWind` (`@jgengine/shell/render/modelWind`): per-model foliage sway with height-ramped travel, shared gust clock and per-model strength/speed/direction.
+
+### Fixed
+
+- The player shell re-renders only for the ctx slices it reads — the possessed entity and the touch control mode — instead of on every `ctx` write. Subscribing the shell root to the raw ctx version reconciled the canvas, the whole actor tree and the HUD on each per-frame entity pose write, which is what `subscribeMembership` and the markers' imperative `useFrame` pose reads exist to avoid (#625). Scrap Signal: 86.6 ms → 16.7 ms per frame at the same 621 draws; Harbor Heat: 102.8 ms → 46.2 ms at the same ~7.2k draws.
+- The `ocean()` environment feature passes the live ground to its shader, so the sea shades shallow→deep and its shoreline foam band lands where the bed meets the surface.
+
+### Numbers
+
+- Test catalog (60/25/10/4/1 rarity weights) over 10,000 drops at level 20, fixed seed: common 59.41% (target 60%), uncommon 25.66% (25%), rare 9.58% (10%), epic 4.20% (4%), legendary 1.15% (1%); every tier inside its 4σ binomial bound. All 10,000 items validated with zero issues and composed names (e.g. `Voss Rare Long Keen Lightframe of Reach`, `Tallow Long Lightframe`, `Voss Snub Lightframe of Steadying`).
+- Level curve `[[1,1],[15,1.6],[30,2.4],[60,4]]`: a level-60 roll's base and additive affix values are 4× the same seed at level 1; maker personalities move the same roll (`Voss` +power/−cadence, `Tallow` the reverse).
+- A rolled epic projects to a hitscan `WeaponDefinition` (rate, damage, integer magazine capacity, spread, range), passes `assertWeaponDefinition`, and its first `tick` fires one shot and one impact through `createDamageRuntime` with the rolled capacity spent.
+
 ## 0.26.0
 
 ### Migrate

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

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

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

package/dist/inventory/inventoryModel.js

@@ -175,13 +175,14 @@ export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
 }
 /**
  * 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 function splitStack(state, slot, amount, toSlot) {
+export function splitStack(state, slot, amount, toSlot, limit) {
     if (!validSlot(state, slot))
         return { status: "rejected", reason: "invalid-slot" };
     const source = state.slots[slot];
@@ -206,6 +207,9 @@ export function splitStack(state, slot, amount, toSlot) {
     }
     const slots = state.slots.slice();
     const dest = slots[target];
+    if (limit !== undefined && dest !== null && dest !== undefined && dest.count + amount > limit) {
+        return { status: "rejected", reason: "over-stack" };
+    }
     slots[slot] = { itemId: source.itemId, count: source.count - amount };
     slots[target] =
         dest === null || dest === undefined
@@ -213,6 +217,26 @@ export function splitStack(state, slot, amount, toSlot) {
             : { itemId: source.itemId, count: dest.count + amount };
     return { status: "ok", state: { slots } };
 }
+function cloneSlots(slots) {
+    return slots.map((slot) => (slot === null ? null : { itemId: slot.itemId, count: slot.count }));
+}
+function validInventoryState(state, slots) {
+    if (state === null || typeof state !== "object" || !Array.isArray(state.slots))
+        return false;
+    if (state.slots.length !== slots)
+        return false;
+    for (const slot of state.slots) {
+        if (slot === null)
+            continue;
+        if (typeof slot !== "object")
+            return false;
+        if (typeof slot.itemId !== "string")
+            return false;
+        if (!Number.isFinite(slot.count) || slot.count <= 0)
+            return false;
+    }
+    return true;
+}
 /** Build a keyed set of named inventories from their `layouts`, sharing one `traits` table — the stateful façade over put/take/move/count. */
 export function createInventorySet(layouts, traits) {
     const states = new Map();
@@ -258,5 +282,30 @@ export function createInventorySet(layouts, traits) {
         replaceState(id, state) {
             states.set(id, state);
         },
+        snapshot() {
+            const out = {};
+            for (const id of Object.keys(layouts)) {
+                out[id] = { slots: cloneSlots(requireState(id).slots) };
+            }
+            return out;
+        },
+        restore(next) {
+            if (next === null || typeof next !== "object")
+                return false;
+            const staged = new Map();
+            for (const id of Object.keys(layouts)) {
+                const state = next[id];
+                if (state === undefined || !validInventoryState(state, layouts[id].slots))
+                    return false;
+                staged.set(id, { slots: cloneSlots(state.slots) });
+            }
+            for (const [id, state] of staged)
+                states.set(id, state);
+            return true;
+        },
+        reset() {
+            for (const id of Object.keys(layouts))
+                states.set(id, createEmptyInventory(layouts[id]));
+        },
     };
 }

package/dist/inventory/shapedGrid.d.ts

@@ -79,6 +79,32 @@ export declare function findShapedPlacement<T>(grid: ShapedGrid<T>, footprint: F
  * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
  */
 export declare function placeShaped<T>(grid: ShapedGrid<T>, item: ShapedItem<T>, origin: Cell, rotation?: Rotation): ShapedResult<T>;
+/**
+ * Why a first-fit placement failed: the footprint cannot fit an empty board at any offered rotation
+ * (`too-large`), the board is genuinely full (`no-space`), or the search hit its budget.
+ */
+export type ShapedFitRejection = "duplicate-id" | "invalid-footprint" | "too-large" | "no-space" | "budget-exceeded";
+/** A placed board, or a refusal that names why the item does not fit. */
+export type ShapedFitResult<T> = {
+    status: "ok";
+    grid: ShapedGrid<T>;
+    origin: Cell;
+    rotation: Rotation;
+    checks: number;
+} | {
+    status: "rejected";
+    reason: ShapedFitRejection;
+    detail: string;
+    checks: number;
+};
+/**
+ * Place a shaped item at the first legal spot, or say why it does not fit. Distinguishes an item that
+ * can never fit the board (`too-large`, with its footprint and the board size in `detail`) from a full
+ * board (`no-space`) and an exhausted search (`budget-exceeded`, not a full bag).
+ *
+ * @capability shaped-placement place a shaped item at its first fit and name why it does not fit
+ */
+export declare function fitShapedItem<T>(grid: ShapedGrid<T>, item: ShapedItem<T>, options?: ShapedPlacementSearchOptions): ShapedFitResult<T>;
 /**
  * Remove one placement without mutating the source board.
  * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement