@jgengine/core 0.9.0 → 0.11.0

package/dist/input/touchScheme.js

@@ -3,9 +3,11 @@
  * capture layer renders a virtual joystick, on-screen buttons, and a gesture
  * surface, and feeds synthetic `touch:<action>` codes into the same
  * ActionStateTracker the keyboard uses, so games gain touch play without any
- * per-game input code. Games refine the derived defaults through
- * TouchControlsConfig (gesture bindings, button curation) or opt out entirely
- * with `touch: false`.
+ * per-game input code. Session-lifecycle actions (start/restart/pause/menu/…)
+ * are left off the derived dock — they live in the start screen, pause menu, or
+ * settings sheet, never as a chip over live play. Games refine the derived
+ * defaults through TouchControlsConfig (gesture bindings, button curation) or
+ * opt out entirely with `touch: false`.
  */
 import { isHotbarSlotAction } from "./actionBindings.js";
 export const TOUCH_CODE_PREFIX = "touch:";
@@ -31,7 +33,68 @@ export function withTouchCodes(map) {
     }
     return result;
 }
+/** Every touch skin id, in menu order. */
+export const TOUCH_STYLES = ["glass", "arcade", "mechanical", "minimal"];
+/** Touch skins as `{ value, label }` rows for the Settings → Controls selector. */
+export const TOUCH_STYLE_OPTIONS = [
+    { value: "glass", label: "Glass" },
+    { value: "arcade", label: "Arcade" },
+    { value: "mechanical", label: "Mechanical" },
+    { value: "minimal", label: "Minimal" },
+];
+/** Skin used when neither the game nor the player picks one. */
+export const DEFAULT_TOUCH_STYLE = "glass";
 const DEFAULT_LOOK_SENSITIVITY = 0.005;
+const DEFAULT_TOUCH_LAYOUT = {
+    movement: "bottom-left",
+    actions: "bottom-right",
+    utility: "bottom-center",
+};
+const SHAPE_BY_ACTION = new Map([
+    ["brake", "pedal"],
+    ["accelerate", "pedal"],
+    ["throttle", "pedal"],
+    ["throttleUp", "pedal"],
+    ["throttleDown", "pedal"],
+    ["gas", "pedal"],
+    ["clutch", "pedal"],
+    ["handbrake", "lever"],
+    ["gearUp", "lever"],
+    ["gearDown", "lever"],
+    ["shift", "lever"],
+    ["boost", "lever"],
+    ["fire", "trigger"],
+    ["shoot", "trigger"],
+    ["attack", "trigger"],
+    ["primaryFire", "trigger"],
+    ["secondaryFire", "trigger"],
+    ["steer", "wheel"],
+    ["inventory", "square"],
+    ["bag", "square"],
+    ["spellbook", "square"],
+]);
+const WHEEL_PREFIXES = ["steer"];
+/** Slot-like verbs read as square tiles (inventory, spell/item/ability slots). */
+const SQUARE_PREFIXES = ["spell", "slot", "item"];
+/**
+ * Default silhouette for an action; `circle` when nothing more specific fits.
+ *
+ * @capability touch-controls default on-screen button silhouette for a touch action
+ */
+export function touchButtonShape(action) {
+    const direct = SHAPE_BY_ACTION.get(action);
+    if (direct !== undefined)
+        return direct;
+    for (const prefix of WHEEL_PREFIXES) {
+        if (action.startsWith(prefix))
+            return "wheel";
+    }
+    for (const prefix of SQUARE_PREFIXES) {
+        if (action.startsWith(prefix))
+            return "square";
+    }
+    return "circle";
+}
 const JOYSTICK_AXES = {
     up: ["moveForward", "moveUp", "forward", "accelerate", "throttleUp", "pitchUp", "climb"],
     down: ["moveBack", "moveBackward", "moveDown", "backward", "reverse", "brake", "throttleDown", "pitchDown", "dive"],
@@ -60,6 +123,27 @@ const UTILITY_ACTIONS = new Set([
     "leaderboard",
 ]);
 const UTILITY_PREFIXES = ["toggle", "cycle", "switch", "open", "close", "show", "hide", "zoom"];
+/**
+ * Session-lifecycle and menu-chrome actions never auto-derive an on-screen
+ * touch button: they belong to the start screen, pause menu, or settings sheet
+ * (surfaced via `settings.actions` plus a `<SettingsTrigger>`), not the live
+ * control dock — a `restart` chip stapled over play is the anti-pattern, and a
+ * mis-tap on it wrecks the match. A game that truly wants one docked lists it
+ * explicitly in `touch.buttons`, which bypasses derivation entirely.
+ */
+const LIFECYCLE_ACTIONS = new Set([
+    "start",
+    "restart",
+    "reset",
+    "retry",
+    "pause",
+    "resume",
+    "menu",
+    "quit",
+    "exit",
+    "settings",
+    "options",
+]);
 export function touchButtonKind(action) {
     if (UTILITY_ACTIONS.has(action))
         return "utility";
@@ -103,17 +187,20 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
     const joystickMapped = new Set();
     let joystick = null;
     if (config?.movement !== false) {
-        const resolveAxis = (candidates) => {
+        const axis = config?.movement?.axis ?? "both";
+        const resolveAxis = (candidates, enabled) => {
+            if (!enabled)
+                return null;
             const action = candidates.find((candidate) => bound.has(candidate)) ?? null;
             if (action !== null)
                 joystickMapped.add(action);
             return action;
         };
         const axes = {
-            up: resolveAxis(JOYSTICK_AXES.up),
-            down: resolveAxis(JOYSTICK_AXES.down),
-            left: resolveAxis(JOYSTICK_AXES.left),
-            right: resolveAxis(JOYSTICK_AXES.right),
+            up: resolveAxis(JOYSTICK_AXES.up, axis !== "horizontal"),
+            down: resolveAxis(JOYSTICK_AXES.down, axis !== "horizontal"),
+            left: resolveAxis(JOYSTICK_AXES.left, axis !== "vertical"),
+            right: resolveAxis(JOYSTICK_AXES.right, axis !== "vertical"),
         };
         joystick = axes.up === null && axes.down === null && axes.left === null && axes.right === null ? null : axes;
     }
@@ -123,12 +210,23 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
     let buttons;
     if (config?.buttons !== undefined) {
         buttons = config.buttons.map((spec) => typeof spec === "string"
-            ? { action: spec, label: touchActionLabel(spec), icon: null, kind: touchButtonKind(spec) }
+            ? {
+                action: spec,
+                label: touchActionLabel(spec),
+                icon: null,
+                kind: touchButtonKind(spec),
+                shape: touchButtonShape(spec),
+                anchor: null,
+                image: null,
+            }
             : {
                 action: spec.action,
                 label: spec.label ?? touchActionLabel(spec.action),
                 icon: spec.icon ?? null,
                 kind: spec.kind ?? touchButtonKind(spec.action),
+                shape: spec.shape ?? touchButtonShape(spec.action),
+                anchor: spec.anchor ?? null,
+                image: spec.image ?? null,
             });
     }
     else {
@@ -137,8 +235,17 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
             .filter((action) => !isHotbarSlotAction(action))
             .filter((action) => !consumedByGestures.has(action))
             .filter((action) => !hidden.has(action))
+            .filter((action) => !LIFECYCLE_ACTIONS.has(action))
             .filter((action) => !reserved.has(action) || BUTTONABLE_RESERVED.has(action))
-            .map((action) => ({ action, label: touchActionLabel(action), icon: null, kind: touchButtonKind(action) }));
+            .map((action) => ({
+            action,
+            label: touchActionLabel(action),
+            icon: null,
+            kind: touchButtonKind(action),
+            shape: touchButtonShape(action),
+            anchor: null,
+            image: null,
+        }));
     }
     const look = config?.look ?? firstPerson;
     if (joystick === null && buttons.length === 0 && gestures === null && !look)
@@ -149,5 +256,11 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
         gestures,
         look,
         lookSensitivity: config?.lookSensitivity ?? DEFAULT_LOOK_SENSITIVITY,
+        layout: {
+            movement: config?.layout?.movement ?? DEFAULT_TOUCH_LAYOUT.movement,
+            actions: config?.layout?.actions ?? DEFAULT_TOUCH_LAYOUT.actions,
+            utility: config?.layout?.utility ?? DEFAULT_TOUCH_LAYOUT.utility,
+        },
+        style: config?.style ?? DEFAULT_TOUCH_STYLE,
     };
 }

package/dist/interaction/contextMenu.d.ts

@@ -7,6 +7,7 @@ export interface ContextVerb {
     /** Greyed-out and non-dispatchable when true (e.g. requirement unmet). */
     disabled?: boolean;
 }
+/** Builds a {@link ContextVerb} for a right-click menu entry. */
 export declare function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb;
 export interface ContextMenu {
     kind: ContextTargetKind;

package/dist/interaction/contextMenu.js

@@ -1,3 +1,4 @@
+/** Builds a {@link ContextVerb} for a right-click menu entry. */
 export function contextVerb(label, command, args) {
     return args === undefined ? { label, command } : { label, command, args };
 }

package/dist/interaction/lockpick.d.ts

@@ -0,0 +1,61 @@
+/** One discrete pick move: how far the pick drives into the lock this step. */
+export type LockAction = "hardSet" | "set" | "steady" | "ease" | "drop";
+/** Vertical row delta applied to the pick for each action. Row 0 is the shallow/top row. */
+export declare const LOCK_ACTION_DELTA: Readonly<Record<LockAction, number>>;
+/** The five pick actions, in display order (shallow → deep). */
+export declare const LOCK_ACTIONS: readonly LockAction[];
+/** Difficulty dials for one lock: board size, forgiveness band, gates, fog window, traps. */
+export interface LockTierSpec {
+    cols: number;
+    rows: number;
+    width: number;
+    gateCount: number;
+    visibilityWindow: number;
+    allowedActions: readonly LockAction[];
+    trapCount?: number;
+}
+/** A generated lock board. `open[col]` holds every enterable row in that column. */
+export interface LockSpec {
+    seed: string | number;
+    tier: LockTierSpec;
+    open: readonly (readonly number[])[];
+    gates: readonly number[];
+    traps: readonly (readonly number[])[];
+    startRow: number;
+    seatRow: number;
+}
+/** Outcome of one {@link stepLock} call: `advanced`/`success` move the pick, `slip`/`bind`/`trap`
+ * do not and should cost a life. */
+export type LockStepResult = "advanced" | "slip" | "bind" | "trap" | "success";
+/** What a revealed cell renders as: a plain open notch, an exact tumbler gate, the bolt seat
+ * (win condition), or a ward-trap that looks open but jams on contact. */
+export type LockCellKind = "open" | "gate" | "seat" | "trap";
+/** One cell inside the fogged {@link visibleCells} window: its board position and kind. */
+export interface LockCell {
+    col: number;
+    row: number;
+    kind: LockCellKind;
+}
+/**
+ * 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 declare function generateLock(seed: string | number, tier: LockTierSpec): LockSpec;
+/** Return a concrete row-per-column solution, or null if the board is unsolvable. */
+export declare function solveLockPath(spec: LockSpec): number[] | null;
+/** Whether the board has a path from the start row to the bolt seat at all. */
+export declare function solveLock(spec: LockSpec): boolean;
+/** 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 declare function stepLock(spec: LockSpec, col: number, row: number, action: LockAction): {
+    result: LockStepResult;
+    col: number;
+    row: number;
+};
+/** 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 declare function visibleCells(spec: LockSpec, col: number, window: number): LockCell[];

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

@@ -5,6 +5,8 @@ export interface PromptPoint {
 export interface KeybindPromptDisplay {
     kind: "keybind";
     actionId: string;
+    /** What the interaction does, shown beside the key glyph (e.g. `"Open Chest"`, `"Talk"`); omit for key-only. */
+    label?: string;
 }
 export interface GaugePromptDisplay {
     kind: "gauge";
@@ -15,7 +17,7 @@ export interface LabelPromptDisplay {
     text: string;
 }
 export type ProximityPromptDisplay = KeybindPromptDisplay | GaugePromptDisplay | LabelPromptDisplay;
-export declare function keybind(actionId: string): KeybindPromptDisplay;
+export declare function keybind(actionId: string, label?: string): KeybindPromptDisplay;
 export declare function gauge(gaugeId: string): GaugePromptDisplay;
 export declare function label(text: string): LabelPromptDisplay;
 export interface PromptCommand {
@@ -44,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

@@ -1,5 +1,5 @@
-export function keybind(actionId) {
-    return { kind: "keybind", actionId };
+export function keybind(actionId, label) {
+    return label === undefined ? { kind: "keybind", actionId } : { kind: "keybind", actionId, label };
 }
 export function gauge(gaugeId) {
     return { kind: "gauge", gaugeId };
@@ -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;
@@ -39,7 +41,7 @@ export function promptDisplaysEqual(a, b) {
     if (a === b)
         return true;
     if (a.kind === "keybind")
-        return b.kind === "keybind" && a.actionId === b.actionId;
+        return b.kind === "keybind" && a.actionId === b.actionId && a.label === b.label;
     if (a.kind === "gauge")
         return b.kind === "gauge" && a.gaugeId === b.gaugeId;
     return b.kind === "label" && a.text === b.text;

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