@jgengine/core 0.26.0 → 0.28.0

package/dist/gameplay.d.ts

@@ -7,10 +7,13 @@ export { advanceTransport, createProductionState, drainOutput, feedProduction, p
 export { canCraft, craft, craftSeconds, createRecipeGraph, stationSatisfied, type RecipeDef, type RecipeItem, } from "./crafting/recipe.js";
 export { createAuctionBook, type Auction, type AuctionSettlement } from "./economy/auctionBook.js";
 export { createListingBook, type Listing } from "./economy/listingBook.js";
+export { buildLoanSchedule, createLoanBook, type LoanAdvanceResult, type LoanBook, type LoanBookOptions, type LoanBookState, type LoanBookStats, type LoanPayment, type LoanRecord, type LoanRepayment, type LoanSchedule, type LoanState, type LoanTerms, } from "./economy/loanBook.js";
+export { createMarket, type Market, type MarketConfig, type MarketGoodDef, type MarketGoodState, type MarketPriceInput, type MarketQuote, type MarketSale, type MarketSaleRejection, type MarketSaleResult, type MarketSnapshot, type MarketStats, } from "./economy/market.js";
 export { createPriceHistory, type PriceStats, type SaleRecord } from "./economy/priceHistory.js";
 export { addScheduledRule, advanceLedger, annotate, balanceOf, cancelRule, capAmount, createResourceLedger, curveScale, pauseRule, redirect, rejectWhen, resumeRule, taxFraction, thresholdScale, type AdvanceOptions, type AdvanceResult, type AppliedTransaction, type CatchUpPolicy, type LedgerEvent, type LedgerEventKind, type PolicyContext, type PolicyRead, type Precision, type ResourceLedger, type ResourcePolicy, type ResourceTransaction, type RuleCursor, type ScheduledRule, type ThresholdBand, } from "./economy/resourceLedger.js";
 export { createShopStock, type ShopBuyRejection, type ShopBuyResult, type ShopPrice, type ShopSellRejection, type ShopSellResult, type ShopStock, type ShopStockConfig, type ShopStockEntry, type ShopStockSnapshot, } from "./economy/shopStock.js";
 export { type TechNodeDef } from "./economy/techTree.js";
+export { createTransactionLedger, type ChargeCursor, type LedgerAdvanceResult, type LedgerEntry, type LedgerEntryFilter, type LedgerPostInput, type LedgerPostResult, type LedgerState, type LedgerStats, type LedgerTotals, type RecurringCharge, type TransactionLedger, type TransactionLedgerOptions, } from "./economy/transactionLedger.js";
 export { balance, canAfford, charge, chargeAll, createEmptyWallet, grant, isOverdrawn, type ChargeOptions, type ChargeResult, type Overdraft, } from "./economy/wallet.js";
 export { createAchievementTracker, type AchievementDef, type AchievementSnapshot, type AchievementTracker, type AchievementTrackerOptions, type AchievementUnlock, type AchievementView, } from "./game/achievements.js";
 export { DEFAULT_CHAT_BODY_LENGTH, DEFAULT_CHAT_HISTORY_LIMIT, DEFAULT_CHAT_RATE_LIMIT, createChatRateLimiter, type Chat, type ChatMessage, type ChatRateLimit, type ChatSendResult, } from "./game/chat.js";
@@ -25,6 +28,7 @@ export { createEventTicker, type EventTicker, type EventTickerEntry, type EventT
 export { createGameEvents, type CombatTelegraphEvent, type CombatVfxEvent, type EntityDiedEvent, type EntityFloatTextEvent, type GameEventMap, type GameEvents, type RetainedVfxKind, type StatLevelUpEvent, type VfxKind, type VfxRef, } from "./game/events.js";
 export { appendFeed, createGameFeed, pruneFeed, type FeedEntry, type FeedWindow, type TimedFeedEntry, } from "./game/feed.js";
 export { gamePhase, setGamePhase, type GamePhase } from "./game/gamePhase.js";
+export { GAME_SAVE_VERSION, createGameSave, gameSaveDigest, type GameSave, type GameSaveConfig, type GameSaveDocument, type GameSaveRng, type GameSaveRngState, type GameSaveSystem, } from "./game/gameSave.js";
 export { createKeyValueStore, type KeyValueStorage } from "./game/keyValueStore.js";
 export { createLeaderboard, type LeaderboardRow, type LeaderboardScope } from "./game/leaderboard.js";
 export { medalFor, rankLeaderboard, type RankLeaderboardOptions, type RankableRow, type RankedEntry, type TieMode, } from "./game/leaderboardRank.js";
@@ -39,7 +43,7 @@ export { createNotificationCenter, type NotificationCenterOptions, type Notifica
 export { evaluateObjective } from "./game/objectives.js";
 export { createLayerRegistry, diffParams, orderLayers, resolveParams, resolveSelection, validateLayers, type LayerConflict, type LayerOps, type LayerRegistry, type LayerSelection, type ParamContribution, type ParamDelta, type ParamLayer, type ParamOp, type ParamSnapshot, } from "./game/paramLayers.js";
 export { DEFAULT_PING_CATEGORIES, PING_FEED_ACTION, createPingSystem, type PingCategory, type PingSystem, } from "./game/ping.js";
-export { CAMERA_FRUSTUM_DEFAULTS, worldHealthBarAllowsRole, type BackdropConfig, type CameraKeyframe, type CameraRigKind, type ChaseCameraConfig, type CinematicCameraConfig, type DirectionalLightingConfig, type EntitySpriteConfig, type FirstPersonCameraConfig, type GameCameraConfig, type InspectionCameraConfig, type InspectionZoomAnchor, type LightingConfig, type LockOnCameraConfig, type ModelConfig, type ModelMaterialMaps, type ModelMaterialOverride, type ObjectStyle, type ObserverCameraConfig, type PlayableGame, type PointerConfig, type RtsCameraConfig, type ShoulderCameraConfig, type SideScrollCameraConfig, type TopDownCameraConfig, type WorldItemRenderConfig, type WorldOverlayProps, } from "./game/playableGame.js";
+export { CAMERA_FRUSTUM_DEFAULTS, worldHealthBarAllowsRole, type BackdropConfig, type CameraKeyframe, type CameraRigKind, type ChaseCameraConfig, type CinematicCameraConfig, type DirectionalLightingConfig, type EntitySpriteConfig, type FirstPersonCameraConfig, type FirstPersonCollisionConfig, type GameCameraConfig, type InspectionCameraConfig, type InspectionZoomAnchor, type LightingConfig, type LockOnCameraConfig, type ModelConfig, type ModelMaterialMaps, type ModelMaterialOverride, type ObjectStyle, type ObserverCameraConfig, type PlayableGame, type PointerConfig, type RtsCameraConfig, type ShoulderCameraConfig, type SideScrollCameraConfig, type TopDownCameraConfig, type WorldItemRenderConfig, type WorldOverlayProps, } from "./game/playableGame.js";
 export { curve, evalCurve, leveling, type Curve, type LevelProgress, type LevelingConfig, type LevelingTrack, } from "./game/progression.js";
 export { createQuestJournal, defaultObjectiveLabel, describeTrackedQuest, type QuestDef, type QuestInstance, type QuestRewards, type TrackedObjectiveView, type TrackedQuestView, } from "./game/quest.js";
 export { RaceState, createLapTimer, createRaceState, finishRaceSession, firstPastPost, idleRaceSession, lapDurations, parDelta, placementOf, raceOutcomeOf, racePlacements, raceTrack, splitSegments, startRaceCountdown, tickRaceSession, } from "./game/race.js";
@@ -47,7 +51,7 @@ export { createRecordBook } from "./game/recordBook.js";
 export { createRuleRegistry, rerollRules, selectRules, type RuleDef, type RuleRegistry, type RuleSelection, type RuleSelectionConfig, } from "./game/ruleSelection.js";
 export { createRunDraft, type RunDraft, type RunModifierOffer } from "./game/runDraft.js";
 export { createSaveSlots, type SaveSlotMeta, type SaveSlotWrite, type SaveSlots, type SaveSlotsConfig, type SaveSlotsSnapshot, } from "./game/saveSlots.js";
-export { createSaveStore, localSaveBackend, memorySaveBackend, remoteSaveBackend, type SaveBackend, type SaveStatus, type SaveStore, } from "./game/saveStore.js";
+export { createSaveStore, localSaveBackend, memorySaveBackend, remoteSaveBackend, type SaveAutoConfig, type SaveBackend, type SaveStatus, type SaveStore, type SaveTimers, } from "./game/saveStore.js";
 export { createSocial, type FriendEntry, type FriendRequestEntry, type Friends, type Party, type PartyInviteEntry, type PartyMemberEntry, type PresenceInfo, type Social, type SocialDeps, type WorldInvite, type WorldInviteTarget, } from "./game/social.js";
 export { createSpawnPoints } from "./game/spawnPoints.js";
 export { composeGameLoop } from "./game/systemRuntime.js";
@@ -81,7 +85,15 @@ 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 { 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 { 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";
 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";
@@ -98,6 +110,9 @@ 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 { createVisitorPopulation, type Visitor, type VisitorFlow, type VisitorPolicy, type VisitorPolicyPatch, type VisitorPopulation, type VisitorPopulationOptions, type VisitorPopulationSnapshot, type VisitorPopulationStats, type VisitorWorld, } from "./sim/population.js";
+export { DEFAULT_QUEUE_SEED_SERVICE_SECONDS, DEFAULT_QUEUE_WINDOW, createWaitQueue, type QueueEntry, type QueueWait, type WaitQueue, type WaitQueueOptions, type WaitQueueSnapshot, } from "./sim/queue.js";
+export { DEFAULT_RIDE_BREAKDOWN, DEFAULT_RIDE_FUN_CURVE, DEFAULT_RIDE_RATING_RANGE, createRideChooser, createRideSystem, rideAppeal, rideChoiceCandidates, rideChoiceOptions, rideQueueCostWeight, type RideBreakdown, type RideChoicePolicy, type RideChooser, type RideChooserConfig, type RideChooserSnapshot, type RideDefinition, type RidePhase, type RideQueueView, type RideRatingRange, type RideRatings, type RideRetune, type RideServiceResult, type RideStats, type RideSystem, type RideSystemConfig, type RideSystemSnapshot, type RideTaste, type RideTickSink, type RideView, type RideWaitSource, } from "./sim/rides.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";

package/dist/gameplay.js

@@ -7,10 +7,13 @@ export { advanceTransport, createProductionState, drainOutput, feedProduction, p
 export { canCraft, craft, craftSeconds, createRecipeGraph, stationSatisfied, } from "./crafting/recipe.js";
 export { createAuctionBook } from "./economy/auctionBook.js";
 export { createListingBook } from "./economy/listingBook.js";
+export { buildLoanSchedule, createLoanBook, } from "./economy/loanBook.js";
+export { createMarket, } from "./economy/market.js";
 export { createPriceHistory } from "./economy/priceHistory.js";
 export { addScheduledRule, advanceLedger, annotate, balanceOf, cancelRule, capAmount, createResourceLedger, curveScale, pauseRule, redirect, rejectWhen, resumeRule, taxFraction, thresholdScale, } from "./economy/resourceLedger.js";
 export { createShopStock, } from "./economy/shopStock.js";
 export {} from "./economy/techTree.js";
+export { createTransactionLedger, } from "./economy/transactionLedger.js";
 export { balance, canAfford, charge, chargeAll, createEmptyWallet, grant, isOverdrawn, } from "./economy/wallet.js";
 export { createAchievementTracker, } from "./game/achievements.js";
 export { DEFAULT_CHAT_BODY_LENGTH, DEFAULT_CHAT_HISTORY_LIMIT, DEFAULT_CHAT_RATE_LIMIT, createChatRateLimiter, } from "./game/chat.js";
@@ -25,6 +28,7 @@ export { createEventTicker, } from "./game/eventTicker.js";
 export { createGameEvents, } from "./game/events.js";
 export { appendFeed, createGameFeed, pruneFeed, } from "./game/feed.js";
 export { gamePhase, setGamePhase } from "./game/gamePhase.js";
+export { GAME_SAVE_VERSION, createGameSave, gameSaveDigest, } from "./game/gameSave.js";
 export { createKeyValueStore } from "./game/keyValueStore.js";
 export { createLeaderboard } from "./game/leaderboard.js";
 export { medalFor, rankLeaderboard, } from "./game/leaderboardRank.js";
@@ -81,7 +85,15 @@ 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 { 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 { MISSION_TRIGGER_ACTIONS, createMissionTriggerBridge, missionMarkers, registerMissionTriggerActions, } from "./mission/triggers.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";
@@ -98,6 +110,9 @@ export {} from "./session/roundState.js";
 export { createNearAgents, } from "./sim/nearAgents.js";
 export { createNeedSet } from "./sim/needs.js";
 export { createOffScreenWorld, } from "./sim/offScreen.js";
+export { createVisitorPopulation, } from "./sim/population.js";
+export { DEFAULT_QUEUE_SEED_SERVICE_SECONDS, DEFAULT_QUEUE_WINDOW, createWaitQueue, } from "./sim/queue.js";
+export { DEFAULT_RIDE_BREAKDOWN, DEFAULT_RIDE_FUN_CURVE, DEFAULT_RIDE_RATING_RANGE, createRideChooser, createRideSystem, rideAppeal, rideChoiceCandidates, rideChoiceOptions, rideQueueCostWeight, } from "./sim/rides.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";

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]));
+        },
     };
 }