@jgengine/core 0.10.0 → 0.12.0

package/dist/interaction/lockpick.js

@@ -0,0 +1,168 @@
+import { seededRng } from "../random/rng.js";
+/** Vertical row delta applied to the pick for each action. Row 0 is the shallow/top row. */
+export const LOCK_ACTION_DELTA = {
+    hardSet: -2,
+    set: -1,
+    steady: 0,
+    ease: 1,
+    drop: 2,
+};
+/** The five pick actions, in display order (shallow → deep). */
+export const LOCK_ACTIONS = ["hardSet", "set", "steady", "ease", "drop"];
+function randInt(rng, min, max) {
+    return min + Math.floor(rng() * (max - min + 1));
+}
+function legalDeltas(tier) {
+    return tier.allowedActions.map((action) => LOCK_ACTION_DELTA[action]);
+}
+function sampleGateColumns(rng, cols, count) {
+    const candidates = [];
+    for (let c = 1; c <= cols - 2; c += 1)
+        candidates.push(c);
+    for (let i = candidates.length - 1; i > 0; i -= 1) {
+        const j = randInt(rng, 0, i);
+        const tmp = candidates[i];
+        candidates[i] = candidates[j];
+        candidates[j] = tmp;
+    }
+    return candidates.slice(0, Math.max(0, Math.min(count, candidates.length))).sort((a, b) => a - b);
+}
+/**
+ * Generate a solvable depth-puzzle lock: a "Tumbler's Path" board with a guaranteed solution
+ * path carved first, an open-row forgiveness band wrapped around it, tumbler gate columns that
+ * pinch to a single exact row, and optional ward-traps that look open but jam on contact.
+ * Deterministic: the same (seed, tier) always yields the same board.
+ *
+ * @capability lockpick a solvable grid depth-puzzle with fog-of-war, gates, and hidden traps
+ */
+export function generateLock(seed, tier) {
+    const rng = seededRng(seed);
+    const rows = tier.rows;
+    const cols = tier.cols;
+    const deltas = legalDeltas(tier);
+    const path = new Array(cols);
+    path[0] = randInt(rng, 0, rows - 1);
+    for (let c = 1; c < cols; c += 1) {
+        const legal = deltas.filter((d) => path[c - 1] + d >= 0 && path[c - 1] + d <= rows - 1);
+        path[c] = path[c - 1] + (legal.length > 0 ? legal[randInt(rng, 0, legal.length - 1)] : 0);
+    }
+    const gates = sampleGateColumns(rng, cols, tier.gateCount);
+    const gateSet = new Set(gates);
+    const open = new Array(cols);
+    for (let c = 0; c < cols; c += 1) {
+        if (c === cols - 1 || gateSet.has(c)) {
+            open[c] = [path[c]];
+            continue;
+        }
+        const band = [];
+        for (let r = path[c] - tier.width; r <= path[c] + tier.width; r += 1) {
+            if (r >= 0 && r <= rows - 1)
+                band.push(r);
+        }
+        open[c] = band;
+    }
+    for (let c = 1; c < cols; c += 1) {
+        const prev = open[c - 1];
+        open[c] = open[c].filter((r) => prev.some((pr) => deltas.includes(r - pr)));
+    }
+    for (let c = cols - 2; c >= 0; c -= 1) {
+        const next = open[c + 1];
+        open[c] = open[c].filter((r) => next.some((nr) => deltas.includes(nr - r)));
+    }
+    const traps = open.map(() => []);
+    const trapBudget = Math.max(0, tier.trapCount ?? 0);
+    if (trapBudget > 0) {
+        const candidates = [];
+        for (let c = 1; c < cols - 1; c += 1) {
+            if (gateSet.has(c))
+                continue;
+            for (const r of open[c])
+                if (r !== path[c])
+                    candidates.push([c, r]);
+        }
+        for (let i = candidates.length - 1; i > 0; i -= 1) {
+            const j = randInt(rng, 0, i);
+            const tmp = candidates[i];
+            candidates[i] = candidates[j];
+            candidates[j] = tmp;
+        }
+        for (const [c, r] of candidates.slice(0, Math.min(trapBudget, candidates.length)))
+            traps[c].push(r);
+        for (const t of traps)
+            t.sort((a, b) => a - b);
+    }
+    return { seed, tier, open, gates, traps, startRow: path[0], seatRow: path[cols - 1] };
+}
+/** Return a concrete row-per-column solution, or null if the board is unsolvable. */
+export function solveLockPath(spec) {
+    const deltas = legalDeltas(spec.tier);
+    const cols = spec.open.length;
+    const safe = (c, r) => spec.open[c].includes(r) && !spec.traps[c]?.includes(r);
+    if (!safe(0, spec.startRow))
+        return null;
+    const parents = [];
+    let reach = new Set([spec.startRow]);
+    parents[0] = new Map();
+    for (let c = 1; c < cols; c += 1) {
+        const next = new Set();
+        const par = new Map();
+        for (const r of reach) {
+            for (const d of deltas) {
+                const nr = r + d;
+                if (safe(c, nr) && !par.has(nr)) {
+                    par.set(nr, r);
+                    next.add(nr);
+                }
+            }
+        }
+        parents[c] = par;
+        reach = next;
+        if (reach.size === 0)
+            return null;
+    }
+    if (!reach.has(spec.seatRow))
+        return null;
+    const path = new Array(cols);
+    path[cols - 1] = spec.seatRow;
+    for (let c = cols - 1; c > 0; c -= 1)
+        path[c - 1] = parents[c].get(path[c]);
+    return path;
+}
+/** Whether the board has a path from the start row to the bolt seat at all. */
+export function solveLock(spec) {
+    return solveLockPath(spec) !== null;
+}
+/** Authoritative single step. The caller owns the lives economy: a slip/bind/trap does not
+ * advance the pick and should cost a life; advanced/success move the pick. */
+export function stepLock(spec, col, row, action) {
+    const rows = spec.tier.rows;
+    const newRow = Math.max(0, Math.min(rows - 1, row + LOCK_ACTION_DELTA[action]));
+    const newCol = col + 1;
+    const colOpen = spec.open[newCol];
+    if (colOpen === undefined || !colOpen.includes(newRow)) {
+        const isGate = spec.gates.includes(newCol);
+        return { result: isGate ? "bind" : "slip", col, row };
+    }
+    if (spec.traps[newCol]?.includes(newRow) === true) {
+        return { result: "trap", col, row };
+    }
+    if (newCol === spec.open.length - 1 && newRow === spec.seatRow) {
+        return { result: "success", col: newCol, row: newRow };
+    }
+    return { result: "advanced", col: newCol, row: newRow };
+}
+/** The render-safe slice: every open cell in columns [0, col + window]. The single source of
+ * truth for fog and the anti-cheat boundary — never serialize the full spec to a client. */
+export function visibleCells(spec, col, window) {
+    const last = spec.open.length - 1;
+    const maxCol = window >= spec.tier.cols ? last : Math.min(last, col + window);
+    const cells = [];
+    for (let c = 0; c <= maxCol; c += 1) {
+        const trapRows = spec.traps[c];
+        for (const r of spec.open[c]) {
+            const kind = c === last ? "seat" : spec.gates.includes(c) ? "gate" : trapRows?.includes(r) === true ? "trap" : "open";
+            cells.push({ col: c, row: r, kind });
+        }
+    }
+    return cells;
+}

package/dist/interaction/proximityPrompt.d.ts

@@ -46,6 +46,8 @@ export interface PositionedPrompt {
  * Nearest prompt strictly within its radius wins; a higher-priority prompt in
  * range beats any lower-priority one regardless of distance; equal priority
  * and distance keep the earliest prompt in the list.
+ *
+ * @capability proximity-prompt a "press E" contextual prompt shown near an interactable
  */
 export declare function resolveActivePrompt<T extends PositionedPrompt>(playerPosition: PromptPoint, prompts: readonly T[]): T | null;
 export declare function promptDisplaysEqual(a: ProximityPromptDisplay, b: ProximityPromptDisplay): boolean;

package/dist/interaction/proximityPrompt.js

@@ -17,6 +17,8 @@ export function proximityPrompt({ radius, display, invoke = null }) {
  * Nearest prompt strictly within its radius wins; a higher-priority prompt in
  * range beats any lower-priority one regardless of distance; equal priority
  * and distance keep the earliest prompt in the list.
+ *
+ * @capability proximity-prompt a "press E" contextual prompt shown near an interactable
  */
 export function resolveActivePrompt(playerPosition, prompts) {
     let active = null;

package/dist/interaction/qte.d.ts

@@ -15,6 +15,11 @@ export type QteOutcome = {
     atStep: string;
     reason: "missed-window" | "wrong-action" | "too-early";
 };
+/**
+ * Evaluate a quick-time-event input sequence against timed hit windows.
+ *
+ * @capability qte a quick-time-event timed input sequence with hit windows
+ */
 export declare function evaluateQteSequence(steps: readonly QteStep[], inputs: readonly QteInputEvent[]): QteOutcome;
 export declare function pendingQteStep(steps: readonly QteStep[], elapsedSeconds: number): QteStep | null;
 export declare function qteProgress(steps: readonly QteStep[], elapsedSeconds: number): number;

package/dist/interaction/qte.js

@@ -1,3 +1,8 @@
+/**
+ * Evaluate a quick-time-event input sequence against timed hit windows.
+ *
+ * @capability qte a quick-time-event timed input sequence with hit windows
+ */
 export function evaluateQteSequence(steps, inputs) {
     for (let index = 0; index < steps.length; index += 1) {
         const step = steps[index];

package/dist/interaction/skillCheck.d.ts

@@ -16,5 +16,10 @@ export interface SkillCheckResult {
     zone: SkillCheckZone;
 }
 export declare function skillCheckMarkerPosition(config: SkillCheckConfig, elapsedSeconds: number): number;
+/**
+ * A timing-bar skill check that succeeds when the moving marker is released inside the target zone.
+ *
+ * @capability skill-check a timing-bar skill check where you release inside a zone
+ */
 export declare function skillCheckZoneAt(config: SkillCheckConfig, elapsedSeconds: number): SkillCheckZone;
 export declare function evaluateSkillCheck(config: SkillCheckConfig, elapsedSeconds: number): SkillCheckResult;

package/dist/interaction/skillCheck.js

@@ -8,6 +8,11 @@ function bounce(t, period, max) {
 export function skillCheckMarkerPosition(config, elapsedSeconds) {
     return bounce(Math.max(0, elapsedSeconds), config.markerPeriod, config.trackWidth);
 }
+/**
+ * A timing-bar skill check that succeeds when the moving marker is released inside the target zone.
+ *
+ * @capability skill-check a timing-bar skill check where you release inside a zone
+ */
 export function skillCheckZoneAt(config, elapsedSeconds) {
     const drift = config.zoneDriftPerSecond ?? 0;
     if (drift === 0)

package/dist/inventory/encumbrance.d.ts

@@ -0,0 +1,69 @@
+/** One carried stack: an item id and how many of it the carrier holds. */
+export interface LoadEntry {
+    itemId: string;
+    quantity: number;
+}
+/** Resolves the per-unit mass of an item id. Injected so mass tables stay decoupled from this module. */
+export type MassResolver = (itemId: string) => number;
+/**
+ * Tuning for where the encumbrance bands sit and how hard the carrier is slowed.
+ * Both fields are load *fractions* / multipliers in `0..1`, never absolute mass.
+ */
+export interface EncumbranceConfig {
+    /**
+     * Load fraction at/above which the carrier becomes encumbered (loses sprint & jump and
+     * starts slowing). Below it the carrier is unencumbered. Default `0.85`.
+     */
+    soft?: number;
+    /**
+     * Move-speed multiplier reached as load approaches full capacity (fraction → 1), the floor
+     * the progressive slow curve bottoms out at just before immobility. Default `0.5`.
+     */
+    floor?: number;
+}
+/** Coarse carry state: free-moving, slowed, or pinned in place. */
+export type EncumbranceTier = "unencumbered" | "encumbered" | "immobile";
+/** Serializable snapshot of a carrier's load versus capacity and the movement consequences. */
+export interface EncumbranceState {
+    /** Total carried mass (never negative). */
+    mass: number;
+    /** Carrying capacity this load was measured against. */
+    capacity: number;
+    /** `mass / capacity`, clamped to be finite and non-negative; may exceed 1 when overloaded. */
+    fraction: number;
+    tier: EncumbranceTier;
+    /** Movement speed scalar in `0..1`: 1 when unencumbered, decays toward `floor`, 0 when immobile. */
+    moveMultiplier: number;
+    canSprint: boolean;
+    canJump: boolean;
+    immobile: boolean;
+}
+/**
+ * Sum the mass of every carried stack using an injected per-unit mass resolver. Bounded by the
+ * number of entries; allocates nothing. Missing or negative unit masses are treated as 0.
+ *
+ * @param entries carried stacks (`{ itemId, quantity }`, compatible with any inventory listing).
+ * @param massOf per-unit mass lookup for an item id.
+ * @capability carry-load sum carried mass from item stacks via an injected mass resolver
+ */
+export declare function totalLoad(entries: readonly LoadEntry[], massOf: MassResolver): number;
+/**
+ * Progressive move-speed multiplier for a raw load fraction: 1 while at/below `soft`, a linear
+ * decay from 1 down toward `floor` across the `soft..1` band, and 0 once at/over capacity.
+ * Pure and side-effect free — the curve `resolveEncumbrance` reads for `moveMultiplier`.
+ *
+ * @capability encumbrance-move-curve progressive move-speed multiplier from a carry-load fraction
+ */
+export declare function encumbranceMoveMultiplier(fraction: number, config?: EncumbranceConfig): number;
+/**
+ * Resolve carried mass against carrying capacity into a serializable encumbrance state: load
+ * fraction, tier, and the movement consequences (`canSprint`/`canJump`/`immobile` gates plus a
+ * progressive `moveMultiplier`). Below `soft` the carrier is unencumbered and unhindered; from
+ * `soft` up to capacity it is encumbered — no sprint or jump, and speed decays from 1 toward
+ * `floor`; at or above capacity it is immobile (multiplier 0). Deterministic and allocation-light;
+ * pair with {@link totalLoad} to derive `mass` from an inventory and a mass table. A capacity of 0
+ * or less pins any positive load as immobile (`fraction` 1) so the state stays finite/serializable.
+ *
+ * @capability carry-encumbrance carried mass vs capacity into movement penalty tiers and a speed multiplier
+ */
+export declare function resolveEncumbrance(mass: number, capacity: number, config?: EncumbranceConfig): EncumbranceState;

package/dist/inventory/encumbrance.js

@@ -0,0 +1,68 @@
+const DEFAULT_SOFT = 0.85;
+const DEFAULT_FLOOR = 0.5;
+/**
+ * Sum the mass of every carried stack using an injected per-unit mass resolver. Bounded by the
+ * number of entries; allocates nothing. Missing or negative unit masses are treated as 0.
+ *
+ * @param entries carried stacks (`{ itemId, quantity }`, compatible with any inventory listing).
+ * @param massOf per-unit mass lookup for an item id.
+ * @capability carry-load sum carried mass from item stacks via an injected mass resolver
+ */
+export function totalLoad(entries, massOf) {
+    let total = 0;
+    for (const entry of entries) {
+        if (entry.quantity <= 0)
+            continue;
+        const unit = massOf(entry.itemId);
+        if (unit > 0)
+            total += unit * entry.quantity;
+    }
+    return total;
+}
+/**
+ * Progressive move-speed multiplier for a raw load fraction: 1 while at/below `soft`, a linear
+ * decay from 1 down toward `floor` across the `soft..1` band, and 0 once at/over capacity.
+ * Pure and side-effect free — the curve `resolveEncumbrance` reads for `moveMultiplier`.
+ *
+ * @capability encumbrance-move-curve progressive move-speed multiplier from a carry-load fraction
+ */
+export function encumbranceMoveMultiplier(fraction, config) {
+    const soft = config?.soft ?? DEFAULT_SOFT;
+    const floor = config?.floor ?? DEFAULT_FLOOR;
+    if (fraction >= 1)
+        return 0;
+    if (fraction <= soft)
+        return 1;
+    const span = 1 - soft;
+    const t = span > 0 ? (fraction - soft) / span : 1;
+    return 1 - (1 - floor) * t;
+}
+/**
+ * Resolve carried mass against carrying capacity into a serializable encumbrance state: load
+ * fraction, tier, and the movement consequences (`canSprint`/`canJump`/`immobile` gates plus a
+ * progressive `moveMultiplier`). Below `soft` the carrier is unencumbered and unhindered; from
+ * `soft` up to capacity it is encumbered — no sprint or jump, and speed decays from 1 toward
+ * `floor`; at or above capacity it is immobile (multiplier 0). Deterministic and allocation-light;
+ * pair with {@link totalLoad} to derive `mass` from an inventory and a mass table. A capacity of 0
+ * or less pins any positive load as immobile (`fraction` 1) so the state stays finite/serializable.
+ *
+ * @capability carry-encumbrance carried mass vs capacity into movement penalty tiers and a speed multiplier
+ */
+export function resolveEncumbrance(mass, capacity, config) {
+    const soft = config?.soft ?? DEFAULT_SOFT;
+    const safeMass = mass > 0 ? mass : 0;
+    const fraction = capacity > 0 ? safeMass / capacity : safeMass > 0 ? 1 : 0;
+    const immobile = fraction >= 1;
+    const tier = immobile ? "immobile" : fraction >= soft ? "encumbered" : "unencumbered";
+    const unencumbered = tier === "unencumbered";
+    return {
+        mass: safeMass,
+        capacity,
+        fraction,
+        tier,
+        moveMultiplier: encumbranceMoveMultiplier(fraction, config),
+        canSprint: unencumbered,
+        canJump: unencumbered,
+        immobile,
+    };
+}

package/dist/inventory/inventoryModel.d.ts

@@ -35,13 +35,24 @@ export type MoveResult = {
     status: "rejected";
     reason: "invalid-slot" | "empty-slot" | "wrong-kind" | "no-space";
 };
+/**
+ * A bag of stackable items supporting add, remove, count, and move — the base inventory model.
+ *
+ * @capability inventory-grid a bag of stackable items with add, remove, and move
+  * @internal
+  */
 export declare function createEmptyInventory(layout: InventoryLayout): InventoryState;
+/** @internal */
 export declare function putItem(state: InventoryState, layout: InventoryLayout, traits: ItemTraits, itemId: string, count: number, options?: {
     slot?: number;
 }): PutResult;
+/** @internal */
 export declare function takeItem(state: InventoryState, itemId: string, count: number): TakeResult;
+/** @internal */
 export declare function countItem(state: InventoryState, itemId: string): number;
+/** @internal */
 export declare function hasItem(state: InventoryState, itemId: string, count: number): boolean;
+/** @internal */
 export declare function moveItem(from: InventoryState, fromSlot: number, to: InventoryState, toLayout: InventoryLayout, traits: ItemTraits, toSlot?: number): MoveResult;
 export interface InventorySet<TId extends string> {
     put(id: TId, itemId: string, count: number, options?: {
@@ -54,4 +65,5 @@ export interface InventorySet<TId extends string> {
     state(id: TId): InventoryState;
     replaceState(id: TId, state: InventoryState): void;
 }
+/** @internal */
 export declare function createInventorySet<TId extends string>(layouts: Record<TId, InventoryLayout>, traits: ItemTraits): InventorySet<TId>;

package/dist/inventory/inventoryModel.js

@@ -1,3 +1,9 @@
+/**
+ * A bag of stackable items supporting add, remove, count, and move — the base inventory model.
+ *
+ * @capability inventory-grid a bag of stackable items with add, remove, and move
+  * @internal
+  */
 export function createEmptyInventory(layout) {
     return { slots: new Array(layout.slots).fill(null) };
 }
@@ -76,11 +82,13 @@ function explicitPut(state, layout, traits, itemId, count, slot) {
     slots[slot] = { itemId, count: newCount };
     return { status: "ok", state: { slots } };
 }
+/** @internal */
 export function putItem(state, layout, traits, itemId, count, options) {
     if (options?.slot !== undefined)
         return explicitPut(state, layout, traits, itemId, count, options.slot);
     return autoPut(state, layout, traits, itemId, count);
 }
+/** @internal */
 export function takeItem(state, itemId, count) {
     if (count <= 0)
         return { status: "ok", state };
@@ -99,6 +107,7 @@ export function takeItem(state, itemId, count) {
     }
     return { status: "ok", state: { slots } };
 }
+/** @internal */
 export function countItem(state, itemId) {
     let total = 0;
     for (const slot of state.slots)
@@ -106,9 +115,11 @@ export function countItem(state, itemId) {
             total += slot.count;
     return total;
 }
+/** @internal */
 export function hasItem(state, itemId, count) {
     return countItem(state, itemId) >= count;
 }
+/** @internal */
 export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
     if (fromSlot < 0 || fromSlot >= from.slots.length)
         return { status: "rejected", reason: "invalid-slot" };
@@ -160,6 +171,7 @@ export function moveItem(from, fromSlot, to, toLayout, traits, toSlot) {
         to: sameInventory ? { slots: fromSlots } : { slots: toSlots },
     };
 }
+/** @internal */
 export function createInventorySet(layouts, traits) {
     const states = new Map();
     for (const id of Object.keys(layouts)) {

package/dist/inventory/shapedGrid.d.ts

@@ -29,14 +29,28 @@ export interface ShapedRejected {
     detail?: string;
 }
 export type ShapedResult<T> = ShapedPlaceResult<T> | ShapedRejected;
+/** @internal */
 export declare function normalizeFootprint(footprint: Footprint): Footprint;
+/** @internal */
 export declare function rotateFootprint(footprint: Footprint, rotation: Rotation): Footprint;
+/** @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.
+ *
+ * @capability tetris-inventory a spatial grid inventory holding shaped multi-cell items
+  * @internal
+  */
 export declare function createShapedGrid<T>(width: number, height: number): ShapedGrid<T>;
+/** @internal */
 export declare function canPlace<T>(grid: ShapedGrid<T>, footprint: Footprint, origin: Cell, rotation: Rotation, ignoreId?: string): ShapedRejection | null;
+/** @internal */
 export declare function placeShaped<T>(grid: ShapedGrid<T>, item: ShapedItem<T>, origin: Cell, rotation?: Rotation): ShapedResult<T>;
+/** @internal */
 export declare function removeShaped<T>(grid: ShapedGrid<T>, id: string): ShapedResult<T>;
+/** @internal */
 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;
 export interface GridAdjacencyQuery {
     cellsOf(id: string): readonly Cell[];
@@ -44,9 +58,11 @@ export interface GridAdjacencyQuery {
     touching(idA: string, idB: string): boolean;
     adjacentCells(cells: readonly Cell[]): readonly Cell[];
 }
+/** @internal */
 export declare function gridAdjacencyQuery<T>(grid: ShapedGrid<T>, options?: {
     diagonal?: boolean;
 }): GridAdjacencyQuery;
+/** @internal */
 export declare function cellFromPoint(point: {
     x: number;
     y: number;

package/dist/inventory/shapedGrid.js

@@ -1,6 +1,7 @@
 function cellKey(cell) {
     return `${cell[0]},${cell[1]}`;
 }
+/** @internal */
 export function normalizeFootprint(footprint) {
     if (footprint.length === 0)
         return [];
@@ -25,6 +26,7 @@ export function normalizeFootprint(footprint) {
     }
     return out;
 }
+/** @internal */
 export function rotateFootprint(footprint, rotation) {
     const turns = ((rotation % 4) + 4) % 4;
     let cells = footprint.map(([c, r]) => [c, r]);
@@ -33,10 +35,17 @@ export function rotateFootprint(footprint, rotation) {
     }
     return normalizeFootprint(cells);
 }
+/** @internal */
 export function occupiedCells(footprint, origin, rotation) {
     const rotated = rotateFootprint(footprint, 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.
+ *
+ * @capability tetris-inventory a spatial grid inventory holding shaped multi-cell items
+  * @internal
+  */
 export function createShapedGrid(width, height) {
     if (width <= 0 || height <= 0)
         throw new Error("shaped grid needs positive dimensions");
@@ -56,6 +65,7 @@ function occupancyMap(grid, ignoreId) {
     }
     return map;
 }
+/** @internal */
 export function canPlace(grid, footprint, origin, rotation, ignoreId) {
     const cells = occupiedCells(footprint, origin, rotation);
     if (!inBounds(grid, cells))
@@ -67,6 +77,7 @@ export function canPlace(grid, footprint, origin, rotation, ignoreId) {
     }
     return null;
 }
+/** @internal */
 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 };
@@ -83,12 +94,14 @@ export function placeShaped(grid, item, origin, rotation = 0) {
     };
     return { status: "ok", grid: { ...grid, placements: [...grid.placements, placement] } };
 }
+/** @internal */
 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 */
 export function moveShaped(grid, id, origin, rotation) {
     const existing = grid.placements.find((p) => p.id === id);
     if (existing === undefined)
@@ -105,6 +118,7 @@ export function moveShaped(grid, id, origin, rotation) {
         },
     };
 }
+/** @internal */
 export function cellOccupant(grid, cell) {
     return occupancyMap(grid).get(cellKey(cell)) ?? null;
 }
@@ -120,6 +134,7 @@ const DIAGONAL = [
     [-1, 1],
     [-1, -1],
 ];
+/** @internal */
 export function gridAdjacencyQuery(grid, options = {}) {
     const directions = options.diagonal ? [...ORTHOGONAL, ...DIAGONAL] : ORTHOGONAL;
     const cellsById = new Map();
@@ -168,6 +183,7 @@ export function gridAdjacencyQuery(grid, options = {}) {
         },
     };
 }
+/** @internal */
 export function cellFromPoint(point, cellSize, gridOrigin = { x: 0, y: 0 }) {
     return [
         Math.floor((point.x - gridOrigin.x) / cellSize),

package/dist/inventory/slotModel.d.ts

@@ -7,13 +7,23 @@ export type SlotResult<T> = {
     status: "rejected";
     reason: "invalid-slot" | "slot-occupied" | "empty-slot";
 };
+/** @internal */
 export declare function createSlots<T>(size: number): Slot<T>[];
+/** @internal */
 export declare function normalizeSlots<T>(values: SlotGrid<T>, size: number): Slot<T>[];
+/** @internal */
 export declare function placeAt<T>(grid: SlotGrid<T>, index: number, value: T): SlotResult<T>;
+/** @internal */
 export declare function removeAt<T>(grid: SlotGrid<T>, index: number): SlotResult<T>;
+/** @internal */
 export declare function moveSlot<T>(grid: SlotGrid<T>, from: number, to: number): SlotResult<T>;
+/** @internal */
 export declare function firstEmpty<T>(grid: SlotGrid<T>): number | null;
+/** @internal */
 export declare function insertFirst<T>(grid: SlotGrid<T>, value: T): SlotResult<T>;
+/** @internal */
 export declare function compactSlots<T>(grid: SlotGrid<T>): Slot<T>[];
+/** @internal */
 export declare function countFilled<T>(grid: SlotGrid<T>): number;
+/** @internal */
 export declare function indexOfSlot<T>(grid: SlotGrid<T>, match: (value: T, index: number) => boolean): number | null;