@jgengine/core 0.18.1 → 0.21.0

package/dist/input/haptics.js

@@ -0,0 +1,74 @@
+const clamp01 = (value) => (Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0);
+/**
+ * Per-player haptic channels mixed by priority.
+ * @capability haptics Continuous gamepad rumble from named channels (engine, road, impact) mixed by priority, plus fading pulses.
+ */
+export function createHapticChannels(options = {}) {
+    let duck = clamp01(options.duck ?? 0.4);
+    const channels = new Map();
+    const last = { strong: 0, weak: 0 };
+    const write = (name, channel) => {
+        if (channel.strong === 0 && channel.weak === 0)
+            channels.delete(name);
+        else
+            channels.set(name, channel);
+    };
+    return {
+        set(name, level, priority = 0) {
+            write(name, { strong: clamp01(level.strong), weak: clamp01(level.weak), priority, remainingMs: null, totalMs: null });
+        },
+        pulse(name, pulse, priority = 0) {
+            const ms = Math.max(0, pulse.ms);
+            if (ms === 0) {
+                channels.delete(name);
+                return;
+            }
+            write(name, { strong: clamp01(pulse.strong), weak: clamp01(pulse.weak), priority, remainingMs: ms, totalMs: ms });
+        },
+        clear(name) {
+            if (name === undefined)
+                channels.clear();
+            else
+                channels.delete(name);
+        },
+        mix(dt) {
+            const stepMs = Math.max(0, dt) * 1000;
+            let top = -Infinity;
+            for (const [name, channel] of channels) {
+                if (channel.remainingMs !== null) {
+                    channel.remainingMs -= stepMs;
+                    if (channel.remainingMs <= 0) {
+                        channels.delete(name);
+                        continue;
+                    }
+                }
+                if (channel.priority > top)
+                    top = channel.priority;
+            }
+            let strong = 0;
+            let weak = 0;
+            for (const channel of channels.values()) {
+                const fade = channel.remainingMs === null || channel.totalMs === null ? 1 : channel.remainingMs / channel.totalMs;
+                const scale = (channel.priority >= top ? 1 : duck) * fade;
+                strong = Math.max(strong, channel.strong * scale);
+                weak = Math.max(weak, channel.weak * scale);
+            }
+            last.strong = strong;
+            last.weak = weak;
+            return last;
+        },
+        level: () => last,
+        retune(next) {
+            duck = clamp01(next.duck ?? duck);
+        },
+        snapshot() {
+            return { duck, channels: [...channels].map(([name, channel]) => ({ name, ...channel })) };
+        },
+        restore(snapshot) {
+            duck = clamp01(snapshot.duck);
+            channels.clear();
+            for (const { name, ...channel } of snapshot.channels)
+                channels.set(name, { ...channel });
+        },
+    };
+}

package/dist/input/inputBuffer.d.ts

@@ -0,0 +1,40 @@
+/** One action's press history inside an {@link InputBuffer}. */
+export interface BufferedAction {
+    pressedAt: number;
+    previousPressAt: number | null;
+    releasedAt: number | null;
+    consumed: boolean;
+}
+/** Serializable state for an {@link InputBuffer}. */
+export interface InputBufferSnapshot {
+    windowMs: number;
+    actions: Record<string, BufferedAction>;
+}
+/** Remembers recent action presses so a press slightly early (a jump before landing) still counts. Times are caller-supplied ms, so it runs the same on a client, a host or in a replay. */
+export interface InputBuffer {
+    /** Record a press edge. */
+    press(action: string, nowMs: number): void;
+    /** Record a release edge; {@link InputBuffer.hold} stops growing. */
+    release(action: string, nowMs: number): void;
+    /** `true` once for a press no older than `windowMs` (default: the buffer's window), then the press is spent. */
+    consume(action: string, nowMs: number, windowMs?: number): boolean;
+    /** `true` while `nowMs` is within `windowMs` of `groundedAtMs` — late-jump grace after leaving a ledge. `null` never qualifies. */
+    coyote(groundedAtMs: number | null, nowMs: number, windowMs: number): boolean;
+    /** How long the action has been held, ms; `0` when released or never pressed. */
+    hold(action: string, nowMs: number): number;
+    /** `true` when the last two presses were at most `gapMs` apart and the latest is no older than `gapMs`. */
+    doubleTap(action: string, nowMs: number, gapMs: number): boolean;
+    /** Change the default buffer window. */
+    retune(next: {
+        windowMs: number;
+    }): void;
+    snapshot(): InputBufferSnapshot;
+    restore(snapshot: InputBufferSnapshot): void;
+}
+/**
+ * Creates an input buffer for jump buffering, coyote time, hold duration and double taps.
+ * @capability input-buffer buffer early presses, coyote time, hold duration and double tap for responsive controls
+ */
+export declare function createInputBuffer(options: {
+    windowMs: number;
+}): InputBuffer;

package/dist/input/inputBuffer.js

@@ -0,0 +1,59 @@
+/**
+ * Creates an input buffer for jump buffering, coyote time, hold duration and double taps.
+ * @capability input-buffer buffer early presses, coyote time, hold duration and double tap for responsive controls
+ */
+export function createInputBuffer(options) {
+    let windowMs = options.windowMs;
+    let actions = new Map();
+    return {
+        press(action, nowMs) {
+            const previous = actions.get(action);
+            actions.set(action, {
+                pressedAt: nowMs,
+                previousPressAt: previous === undefined ? null : previous.pressedAt,
+                releasedAt: null,
+                consumed: false,
+            });
+        },
+        release(action, nowMs) {
+            const entry = actions.get(action);
+            if (entry !== undefined && entry.releasedAt === null)
+                entry.releasedAt = nowMs;
+        },
+        consume(action, nowMs, window = windowMs) {
+            const entry = actions.get(action);
+            if (entry === undefined || entry.consumed || nowMs - entry.pressedAt > window)
+                return false;
+            entry.consumed = true;
+            return true;
+        },
+        coyote(groundedAtMs, nowMs, window) {
+            return groundedAtMs !== null && nowMs - groundedAtMs <= window;
+        },
+        hold(action, nowMs) {
+            const entry = actions.get(action);
+            if (entry === undefined || entry.releasedAt !== null)
+                return 0;
+            return Math.max(0, nowMs - entry.pressedAt);
+        },
+        doubleTap(action, nowMs, gapMs) {
+            const entry = actions.get(action);
+            if (entry === undefined || entry.previousPressAt === null)
+                return false;
+            return entry.pressedAt - entry.previousPressAt <= gapMs && nowMs - entry.pressedAt <= gapMs;
+        },
+        retune(next) {
+            windowMs = next.windowMs;
+        },
+        snapshot() {
+            const copy = {};
+            for (const [action, entry] of actions)
+                copy[action] = { ...entry };
+            return { windowMs, actions: copy };
+        },
+        restore(snapshot) {
+            windowMs = snapshot.windowMs;
+            actions = new Map(Object.entries(snapshot.actions).map(([action, entry]) => [action, { ...entry }]));
+        },
+    };
+}

package/dist/input/lookChannel.d.ts

@@ -9,6 +9,14 @@ export interface LookDeltas {
     yaw: number;
     pitch: number;
 }
+/** Plain JSON state of a {@link LookChannel}: the pending pixel deltas and the committed pose. */
+export interface LookChannelState {
+    deltaX: number;
+    deltaY: number;
+    yaw: number;
+    pitch: number;
+    verticalOffset: number;
+}
 export interface LookChannel {
     accumulate(dx: number, dy: number): void;
     /** Yaw/pitch deltas (radians) for this frame; clears the accumulator. */
@@ -19,6 +27,8 @@ export interface LookChannel {
     readPitch(): number;
     setVerticalOffset(offset: number): void;
     readVerticalOffset(): number;
+    snapshot(): LookChannelState;
+    restore(next: LookChannelState): void;
 }
 export interface LookChannelOptions {
     /** Radians of rotation per pixel of pointer travel. */

package/dist/input/lookChannel.js

@@ -40,5 +40,11 @@ export function createLookChannel({ sensitivity, maxVerticalOffset = Infinity })
         readVerticalOffset() {
             return verticalOffset;
         },
+        snapshot() {
+            return { deltaX, deltaY, yaw, pitch, verticalOffset };
+        },
+        restore(next) {
+            ({ deltaX, deltaY, yaw, pitch, verticalOffset } = next);
+        },
     };
 }

package/dist/input/pointer.d.ts

@@ -65,5 +65,7 @@ export interface DragCapture {
     cancel(): void;
     /** The current drag state, or `null` when idle. */
     state(): DragState | null;
+    /** Resumes the drag a {@link DragCapture.state} described (its `origin` and `current`), or goes idle on `null`. */
+    restore(next: DragState | null): void;
 }
 export declare function createDragCapture(config?: DragCaptureConfig): DragCapture;

package/dist/input/pointer.js

@@ -61,5 +61,9 @@ export function createDragCapture(config = {}) {
             current = null;
         },
         state: snapshot,
+        restore(next) {
+            origin = next === null ? null : [next.origin[0], next.origin[1], next.origin[2]];
+            current = next === null ? null : [next.current[0], next.current[1], next.current[2]];
+        },
     };
 }

package/dist/interaction/promptRegistry.d.ts

@@ -29,13 +29,14 @@ export interface PromptRegistrySnapshot {
 export interface PromptRegistry {
     /**
      * Add (or replace, by id) a positioned prompt. Replacing an existing id keeps
-     * its registration slot so tie-break order is stable. Does not re-resolve on
-     * its own — the next {@link resolve} picks up the change.
+     * its registration slot so tie-break order is stable. Changed active content
+     * notifies immediately; selection is recalculated by the next {@link resolve}.
      */
     register(prompt: PositionedPrompt): void;
     /**
      * Patch a registered prompt in place. No-op if `id` is unknown. Only the fields
-     * present in `patch` change; the rest are preserved.
+     * present in `patch` change; the rest are preserved. Changed active content
+     * notifies immediately without recalculating selection.
      */
     update(id: string, patch: PositionedPromptPatch): void;
     /** Remove the prompt with this id, if present. Returns whether one was removed. */
@@ -54,7 +55,7 @@ export interface PromptRegistry {
     resolve(playerPosition: PromptPoint): PositionedPrompt | null;
     /** The prompt selected by the most recent {@link resolve}, or `null`. */
     active(): PositionedPrompt | null;
-    /** Observe active-prompt changes (resolve transitions, clear, restore). Returns an unsubscribe fn. */
+    /** Observe active-prompt content changes, selection transitions, clear and restore. Returns an unsubscribe fn. */
     subscribe(listener: () => void): () => void;
     /** Serializable state for a save. */
     snapshot(): PromptRegistrySnapshot;

package/dist/interaction/promptRegistry.js

@@ -1,4 +1,4 @@
-import { resolveActivePrompt, } from "./proximityPrompt.js";
+import { positionedPromptsEqual, resolveActivePrompt, } from "./proximityPrompt.js";
 /** Structural copy of a positioned prompt so external mutation can't corrupt registry state. */
 function clonePrompt(prompt) {
     const copy = {
@@ -50,8 +50,12 @@ export function createPromptRegistry() {
     }
     return {
         register(prompt) {
-            prompts.set(prompt.id, clonePrompt(prompt));
+            const existing = prompts.get(prompt.id);
+            const next = clonePrompt(prompt);
+            prompts.set(prompt.id, next);
             invalidate();
+            if (activeId === prompt.id && existing !== undefined && !positionedPromptsEqual(existing, next))
+                notify();
         },
         update(id, patch) {
             const existing = prompts.get(id);
@@ -71,6 +75,8 @@ export function createPromptRegistry() {
             }
             prompts.set(id, merged);
             invalidate();
+            if (activeId === id && !positionedPromptsEqual(existing, merged))
+                notify();
         },
         unregister(id) {
             const removed = prompts.delete(id);

package/dist/inventory/inventoryModel.js

@@ -14,6 +14,9 @@ function violatesKind(layout, traits, itemId) {
         return kind === null || !layout.accepts.includes(kind);
     return kind !== layout.accepts;
 }
+function validSlot(state, slot) {
+    return Number.isInteger(slot) && slot >= 0 && slot < state.slots.length;
+}
 function computeCapacity(state, traits, itemId) {
     const limit = traits.stackLimit(itemId);
     let existingRoom = 0;
@@ -58,7 +61,7 @@ function autoPut(state, layout, traits, itemId, count) {
     return { status: "ok", state: { slots } };
 }
 function explicitPut(state, layout, traits, itemId, count, slot) {
-    if (slot < 0 || slot >= state.slots.length)
+    if (!validSlot(state, slot))
         return { status: "rejected", reason: "invalid-slot" };
     if (violatesKind(layout, traits, itemId))
         return { status: "rejected", reason: "wrong-kind" };
@@ -120,7 +123,7 @@ export function hasItem(state, itemId, count) {
 }
 /** Move the stack at `fromSlot` to `toSlot` (or auto-stack when omitted) — swapping, merging with remainder, or relocating across two inventories. Rejects on empty source, wrong kind, or no space. */
 export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
-    if (fromSlot < 0 || fromSlot >= from.slots.length)
+    if (!validSlot(from, fromSlot))
         return { status: "rejected", reason: "invalid-slot" };
     const source = from.slots[fromSlot];
     if (source === null)
@@ -138,7 +141,7 @@ export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
     const toSlots = sameInventory ? fromSlots : to.slots.slice();
     const limit = traits.stackLimit(source.itemId);
     if (toSlot !== undefined) {
-        if (toSlot < 0 || toSlot >= toSlots.length)
+        if (!validSlot(to, toSlot))
             return { status: "rejected", reason: "invalid-slot" };
         const dest = toSlots[toSlot];
         if (dest === null) {
@@ -179,12 +182,12 @@ export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
  * @capability inventory-split split a stack into a target or first-empty slot
  */
 export function splitStack(state, slot, amount, toSlot) {
-    if (slot < 0 || slot >= state.slots.length)
+    if (!validSlot(state, slot))
         return { status: "rejected", reason: "invalid-slot" };
     const source = state.slots[slot];
     if (source === null)
         return { status: "rejected", reason: "empty-slot" };
-    if (amount <= 0 || amount >= source.count)
+    if (!Number.isFinite(amount) || amount <= 0 || amount >= source.count)
         return { status: "rejected", reason: "invalid-amount" };
     let target = toSlot;
     if (target === undefined) {
@@ -193,7 +196,7 @@ export function splitStack(state, slot, amount, toSlot) {
             return { status: "rejected", reason: "no-space" };
     }
     else {
-        if (target < 0 || target >= state.slots.length)
+        if (!validSlot(state, target))
             return { status: "rejected", reason: "invalid-slot" };
         if (target === slot)
             return { status: "rejected", reason: "slot-occupied" };

package/dist/inventory/shapedGrid.d.ts

@@ -18,7 +18,7 @@ export interface ShapedGrid<T> {
     readonly height: number;
     readonly placements: readonly Placement<T>[];
 }
-export type ShapedRejection = "out-of-bounds" | "overlap" | "duplicate-id" | "unknown-id";
+export type ShapedRejection = "out-of-bounds" | "overlap" | "duplicate-id" | "unknown-id" | "invalid-footprint" | "invalid-origin";
 export interface ShapedPlaceResult<T> {
     status: "ok";
     grid: ShapedGrid<T>;
@@ -36,19 +36,58 @@ export declare function rotateFootprint(footprint: Footprint, rotation: Rotation
 /** @internal */
 export declare function occupiedCells(footprint: Footprint, origin: Cell, rotation: Rotation): Cell[];
 /**
- * A spatial grid inventory that holds shaped multi-cell items, Resident-Evil/Tarkov style.
+ * An immutable spatial inventory board holding caller-defined multi-cell items.
  *
- * @capability tetris-inventory a spatial grid inventory holding shaped multi-cell items
-  * @internal
-  */
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export declare function createShapedGrid<T>(width: number, height: number): ShapedGrid<T>;
-/** @internal */
+/**
+ * Check bounds and overlap for a discrete footprint, optionally ignoring the item being moved.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export declare function canPlace<T>(grid: ShapedGrid<T>, footprint: Footprint, origin: Cell, rotation: Rotation, ignoreId?: string): ShapedRejection | null;
-/** @internal */
+/** Search policy: rotation order first, then rows and columns; the work budget counts candidate origins. */
+export interface ShapedPlacementSearchOptions {
+    /** Defaults to `[0, 1, 2, 3]`; a game can prefer or forbid rotations. */
+    rotations?: readonly Rotation[];
+    /** Ignore an existing placement while searching for its next position. */
+    ignoreId?: string;
+    /** Nonnegative integer candidate limit; defaults to 4096. */
+    maxChecks?: number;
+}
+/** A detached placement, a completed no-fit search, or an incomplete search that reached its budget. */
+export type ShapedPlacementSearchResult = {
+    status: "found";
+    origin: Cell;
+    rotation: Rotation;
+    checks: number;
+} | {
+    status: "no-space";
+    checks: number;
+} | {
+    status: "budget-exceeded";
+    checks: number;
+};
+/**
+ * Find the first legal placement without mutating the board; occupancy is indexed once per search.
+ *
+ * @capability shaped-placement find a shaped inventory item's first fit with ordered rotations, row-major placement, and an explicit search budget
+ */
+export declare function findShapedPlacement<T>(grid: ShapedGrid<T>, footprint: Footprint, options?: ShapedPlacementSearchOptions): ShapedPlacementSearchResult;
+/**
+ * Place a caller-defined item without mutating the source board; duplicate ids reject.
+ * @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>;
-/** @internal */
+/**
+ * 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
+ */
 export declare function removeShaped<T>(grid: ShapedGrid<T>, id: string): ShapedResult<T>;
-/** @internal */
+/**
+ * Move or rotate one placement, ignoring its current cells during overlap checks.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export declare function moveShaped<T>(grid: ShapedGrid<T>, id: string, origin: Cell, rotation?: Rotation): ShapedResult<T>;
 /** @internal */
 export declare function cellOccupant<T>(grid: ShapedGrid<T>, cell: Cell): string | null;

package/dist/inventory/shapedGrid.js

@@ -41,16 +41,28 @@ export function occupiedCells(footprint, origin, rotation) {
     return rotated.map(([c, r]) => [c + origin[0], r + origin[1]]);
 }
 /**
- * A spatial grid inventory that holds shaped multi-cell items, Resident-Evil/Tarkov style.
+ * An immutable spatial inventory board holding caller-defined multi-cell items.
  *
- * @capability tetris-inventory a spatial grid inventory holding shaped multi-cell items
-  * @internal
-  */
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function createShapedGrid(width, height) {
-    if (width <= 0 || height <= 0)
-        throw new Error("shaped grid needs positive dimensions");
+    requireDimensions(width, height);
     return { width, height, placements: [] };
 }
+function requireDimensions(width, height) {
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) {
+        throw new RangeError("shaped grid needs positive integer dimensions");
+    }
+}
+function validCell(cell) {
+    return Number.isSafeInteger(cell[0]) && Number.isSafeInteger(cell[1]);
+}
+function validFootprint(footprint) {
+    return footprint.length > 0 && footprint.every(validCell);
+}
+function validRotation(rotation) {
+    return Number.isInteger(rotation) && rotation >= 0 && rotation <= 3;
+}
 function inBounds(grid, cells) {
     return cells.every(([c, r]) => c >= 0 && r >= 0 && c < grid.width && r < grid.height);
 }
@@ -65,8 +77,16 @@ function occupancyMap(grid, ignoreId) {
     }
     return map;
 }
-/** @internal */
+/**
+ * Check bounds and overlap for a discrete footprint, optionally ignoring the item being moved.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function canPlace(grid, footprint, origin, rotation, ignoreId) {
+    requireDimensions(grid.width, grid.height);
+    if (!validFootprint(footprint) || !validRotation(rotation))
+        return "invalid-footprint";
+    if (!validCell(origin))
+        return "invalid-origin";
     const cells = occupiedCells(footprint, origin, rotation);
     if (!inBounds(grid, cells))
         return "out-of-bounds";
@@ -77,7 +97,40 @@ export function canPlace(grid, footprint, origin, rotation, ignoreId) {
     }
     return null;
 }
-/** @internal */
+/**
+ * Find the first legal placement without mutating the board; occupancy is indexed once per search.
+ *
+ * @capability shaped-placement find a shaped inventory item's first fit with ordered rotations, row-major placement, and an explicit search budget
+ */
+export function findShapedPlacement(grid, footprint, options = {}) {
+    requireDimensions(grid.width, grid.height);
+    const rotations = options.rotations ?? [0, 1, 2, 3];
+    const maxChecks = options.maxChecks ?? 4096;
+    if (!validFootprint(footprint) || !rotations.every(validRotation))
+        throw new RangeError("invalid footprint or rotation");
+    if (!Number.isSafeInteger(maxChecks) || maxChecks < 0)
+        throw new RangeError("invalid placement search budget");
+    const occupied = occupancyMap(grid, options.ignoreId);
+    let checks = 0;
+    for (const rotation of rotations) {
+        const cells = rotateFootprint(footprint, rotation);
+        for (let row = 0; row < grid.height; row += 1) {
+            for (let column = 0; column < grid.width; column += 1) {
+                if (checks >= maxChecks)
+                    return { status: "budget-exceeded", checks };
+                checks += 1;
+                if (cells.every(([c, r]) => column + c < grid.width && row + r < grid.height && !occupied.has(cellKey([column + c, row + r])))) {
+                    return { status: "found", origin: [column, row], rotation, checks };
+                }
+            }
+        }
+    }
+    return { status: "no-space", checks };
+}
+/**
+ * Place a caller-defined item without mutating the source board; duplicate ids reject.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function placeShaped(grid, item, origin, rotation = 0) {
     if (grid.placements.some((p) => p.id === item.id)) {
         return { status: "rejected", reason: "duplicate-id", detail: item.id };
@@ -94,14 +147,20 @@ export function placeShaped(grid, item, origin, rotation = 0) {
     };
     return { status: "ok", grid: { ...grid, placements: [...grid.placements, placement] } };
 }
-/** @internal */
+/**
+ * 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
+ */
 export function removeShaped(grid, id) {
     if (!grid.placements.some((p) => p.id === id)) {
         return { status: "rejected", reason: "unknown-id", detail: id };
     }
     return { status: "ok", grid: { ...grid, placements: grid.placements.filter((p) => p.id !== id) } };
 }
-/** @internal */
+/**
+ * Move or rotate one placement, ignoring its current cells during overlap checks.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function moveShaped(grid, id, origin, rotation) {
     const existing = grid.placements.find((p) => p.id === id);
     if (existing === undefined)

package/dist/item/affix.d.ts

@@ -51,4 +51,10 @@ export interface AffixRoller {
     roll(base: ItemBaseDef, rarityId: string, rng: () => number): RolledItem;
     rollRandom(base: ItemBaseDef, rng: () => number): RolledItem;
 }
+/**
+ * Rolls randomized gear from a base item: a weighted rarity tier scales base stats and picks
+ * prefix/suffix affixes that name and modify the item. Deterministic for a given `rng`.
+ *
+ * @capability affix-roller roll randomized gear (guns, armor, loot) with rarity tiers, stat scaling and prefix/suffix affixes from a seed
+ */
 export declare function createAffixRoller(config: RollerConfig): AffixRoller;

package/dist/item/affix.js

@@ -20,6 +20,12 @@ function assertConfig(config) {
             throw new Error(`rarity "${tier.id}" weight must be positive`);
     }
 }
+/**
+ * Rolls randomized gear from a base item: a weighted rarity tier scales base stats and picks
+ * prefix/suffix affixes that name and modify the item. Deterministic for a given `rng`.
+ *
+ * @capability affix-roller roll randomized gear (guns, armor, loot) with rarity tiers, stat scaling and prefix/suffix affixes from a seed
+ */
 export function createAffixRoller(config) {
     assertConfig(config);
     const poolById = new Map(config.pools.map((p) => [p.id, p]));

package/dist/item/durability.js

@@ -21,6 +21,8 @@ export function wearAmount(spec, kind) {
  * @capability durability track item wear, breakage, and repair
  */
 export function applyWear(state, amount) {
+    if (Number.isNaN(amount))
+        throw new RangeError("Wear amount must not be NaN.");
     if (amount <= 0)
         return state;
     return { current: clamp(state.current - amount, 0, state.max), max: state.max };
@@ -40,6 +42,8 @@ export function repairQuote(spec, state, options) {
         return null;
     if (repair.station !== undefined && repair.station !== options?.station)
         return null;
+    if (options?.to !== undefined && !Number.isFinite(options.to))
+        return null;
     const loss = repair.qualityLossPerRepair ?? 0;
     const newMax = Math.max(1, state.max - loss);
     const capped = Math.min(state.current, newMax);

package/dist/item/itemInstanceRegistry.d.ts

@@ -1,3 +1,26 @@
+/** Save data for a registry; definitions must be structured-cloneable and use the caller's serialization format. */
+export interface ItemInstanceRegistryState<TDef> {
+    prefix: string;
+    sequence: number;
+    entries: [string, TDef][];
+}
+/** Caller-owned synchronous storage; `entries()` must stream without materializing the collection. */
+export interface ItemInstanceStorage<TDef> {
+    get(id: string): TDef | undefined;
+    has(id: string): boolean;
+    set(id: string, def: TDef): void;
+    delete(id: string): void;
+    count(): number;
+    entries(): Iterable<[string, TDef]>;
+    /** Consume entries completely and atomically replace storage; any failure must preserve previous data. */
+    replace(entries: Iterable<[string, TDef]>): void;
+}
+/** Inject storage and its saved allocator sequence when attaching an existing collection. */
+export interface ItemInstanceRegistryOptions<TDef> {
+    storage?: ItemInstanceStorage<TDef>;
+    /** Nonnegative safe integer; defaults to zero. Retain it across releases and storage reattachment. */
+    sequence?: number;
+}
 /**
  * A runtime store for procedurally generated item instances — a rolled unique gun, a rolled
  * affixed relic — keyed by a generated id distinct from any static catalog id. The counterpart a
@@ -5,6 +28,14 @@
  * rolls never need a hand-rolled parallel registry (#536.1).
  */
 export interface ItemInstanceRegistry<TDef> {
+    /** Detached definitions and allocator state, including ids of released instances in the sequence. */
+    state(): ItemInstanceRegistryState<TDef>;
+    /** Detached batches of at most `pageSize` entries; throws if the registry changes during iteration. Keep external storage and definitions unchanged until finished. */
+    statePages(pageSize: number): IterableIterator<ItemInstanceRegistryState<TDef>>;
+    /** Replace the registry; returns false without mutation when the prefix or allocator is invalid. */
+    restore(next: ItemInstanceRegistryState<TDef>): boolean;
+    /** Stream detached pages through atomic storage replacement. All pages must share prefix and sequence; malformed pages or storage failures throw without changing state. Empty saves require one empty page. */
+    restorePages(pages: Iterable<ItemInstanceRegistryState<TDef>>): boolean;
     /** Stores `def` under a fresh generated id derived from `baseId`; returns that id. */
     register(baseId: string, def: TDef): string;
     get(id: string): TDef | undefined;
@@ -19,7 +50,7 @@ export interface ItemInstanceRegistry<TDef> {
  *
  * @capability item-instance-registry a runtime store for procedurally generated item instances
  */
-export declare function createItemInstanceRegistry<TDef>(prefix?: string): ItemInstanceRegistry<TDef>;
+export declare function createItemInstanceRegistry<TDef>(prefix?: string, options?: ItemInstanceRegistryOptions<TDef>): ItemInstanceRegistry<TDef>;
 /**
  * Bridges any procedural roller into a `LootEntry.generate` callback: rolls a `{ baseId, def }` pair
  * and registers it, returning the runtime id the loot roll hands back as the drop's `item`.