@jgengine/core 0.19.0 → 0.22.0

package/dist/game/saveStore.js

@@ -1,47 +1,45 @@
-import { defaultKeyValueStorage } from "./keyValueStore.js";
-function readSafe(storage, key) {
-    if (storage === null)
-        return null;
-    try {
-        return storage.getItem(key);
-    }
-    catch {
-        return null;
-    }
-}
+import { defaultKeyValueStorage, reportStorageFailure } from "./keyValueStore.js";
 /**
  * A {@link SaveBackend} over a synchronous {@link KeyValueStorage} — the
  * browser's `localStorage` by default (offline, on-device saves), a test stub,
- * or `null` for memory-only. Storage errors (quota exceeded, private mode, no
- * DOM) degrade to no-ops, so a save never throws into a game tick.
+ * or `null` for a no-op backend. Default fallback ignores failures; `errorMode: "throw"`
+ * rejects failed operations and unavailable storage, so SaveStore status/onError can report them.
+ * Use {@link memorySaveBackend} for deliberate ephemeral persistence.
  *
  * @capability local-save persist a game to on-device localStorage (offline)
  */
-export function localSaveBackend(storage) {
-    const store = storage === undefined ? defaultKeyValueStorage() : storage;
+export function localSaveBackend(storage, policy = {}) {
+    const resolve = () => {
+        const store = storage === undefined ? defaultKeyValueStorage((error) => { throw error; }) : storage;
+        if (store === null)
+            throw new Error("Local storage is unavailable");
+        return store;
+    };
     return {
-        read: (key) => Promise.resolve(readSafe(store, key)),
-        write: (key, value) => {
-            if (store !== null) {
-                try {
-                    store.setItem(key, value);
-                }
-                catch {
-                    // storage rejected the write; the store keeps the value in memory
-                }
+        async read(key) {
+            try {
+                return resolve().getItem(key);
+            }
+            catch (error) {
+                reportStorageFailure(policy, { operation: "read", key, error });
+                return null;
             }
-            return Promise.resolve();
         },
-        remove: (key) => {
-            if (store !== null) {
-                try {
-                    store.removeItem(key);
-                }
-                catch {
-                    // ignore removal failure
-                }
+        async write(key, value) {
+            try {
+                resolve().setItem(key, value);
+            }
+            catch (error) {
+                reportStorageFailure(policy, { operation: "write", key, error });
+            }
+        },
+        async remove(key) {
+            try {
+                resolve().removeItem(key);
+            }
+            catch (error) {
+                reportStorageFailure(policy, { operation: "remove", key, error });
             }
-            return Promise.resolve();
         },
     };
 }
@@ -143,10 +141,10 @@ export function createSaveStore(config) {
         return parsed;
     }
     async function readSlots() {
+        const raw = await backend.read(indexKey());
+        if (raw === null)
+            return [];
         try {
-            const raw = await backend.read(indexKey());
-            if (raw === null)
-                return [];
             const parsed = JSON.parse(raw);
             return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === "string") : [];
         }
@@ -155,26 +153,16 @@ export function createSaveStore(config) {
         }
     }
     async function rememberSlot(slot) {
-        try {
-            const list = await readSlots();
-            if (list.includes(slot))
-                return;
-            await backend.write(indexKey(), JSON.stringify([...list, slot]));
-        }
-        catch (error) {
-            reportError(error);
-        }
+        const list = await readSlots();
+        if (list.includes(slot))
+            return;
+        await backend.write(indexKey(), JSON.stringify([...list, slot]));
     }
     async function forgetSlot(slot) {
-        try {
-            const list = await readSlots();
-            if (!list.includes(slot))
-                return;
-            await backend.write(indexKey(), JSON.stringify(list.filter((entry) => entry !== slot)));
-        }
-        catch (error) {
-            reportError(error);
-        }
+        const list = await readSlots();
+        if (!list.includes(slot))
+            return;
+        await backend.write(indexKey(), JSON.stringify(list.filter((entry) => entry !== slot)));
     }
     function clearTimer() {
         if (pendingTimer !== null) {
@@ -243,7 +231,10 @@ export function createSaveStore(config) {
             firstDirtyAt = null;
             setStatus("idle");
             emit();
-            void rememberSlot(currentSlot);
+            void rememberSlot(currentSlot).catch((error) => {
+                setStatus("error");
+                reportError(error);
+            });
             return current;
         }
         catch (error) {
@@ -298,7 +289,16 @@ export function createSaveStore(config) {
             firstDirtyAt = null;
             return load();
         },
-        slots: readSlots,
+        async slots() {
+            try {
+                return await readSlots();
+            }
+            catch (error) {
+                setStatus("error");
+                reportError(error);
+                return [];
+            }
+        },
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);

package/dist/game/systemRuntime.d.ts

@@ -15,14 +15,14 @@ export interface InstalledSystems {
     tick(ctx: GameContext, dt: number): void;
     /** Invoke every system's `reset` (scenario/run wipe). */
     reset(ctx: GameContext): void;
-    /** Invoke every system's `dispose` in reverse install order. */
+    /** Retire once in reverse order; finish cleanup before rethrowing the first error. */
     dispose(ctx: GameContext): void;
     /** Run one manual system by id (no-op if missing or not manual). */
     runManual(ctx: GameContext, id: string, dt?: number): void;
 }
 /**
  * Install systems on a live context: `create` → bind events → register save/replicate → `start`.
- * Call once per world boot (from the composed loop's `onInit`).
+ * Call once per world boot. Failed installation retires entered systems and listeners, then rethrows the startup error.
  * @internal
  */
 export declare function installSystems(ctx: GameContext, systems: readonly SystemDefinition[], options?: CompileSystemScheduleOptions & {

package/dist/game/systemRuntime.js

@@ -7,7 +7,7 @@ function resolveModule(spec, ctx) {
 }
 /**
  * Install systems on a live context: `create` → bind events → register save/replicate → `start`.
- * Call once per world boot (from the composed loop's `onInit`).
+ * Call once per world boot. Failed installation retires entered systems and listeners, then rethrows the startup error.
  * @internal
  */
 export function installSystems(ctx, systems, options) {
@@ -16,29 +16,41 @@ export function installSystems(ctx, systems, options) {
     const unsubs = [];
     const intervalAcc = new Map();
     const fixedAcc = new Map();
-    for (const system of list) {
-        system.create?.(ctx);
-    }
-    for (const system of list) {
-        if (system.events !== undefined) {
-            for (const [name, handler] of Object.entries(system.events)) {
-                if (handler === undefined)
-                    continue;
-                const off = ctx.game.events.on(name, ((event) => {
-                    handler(ctx, event);
-                }));
-                unsubs.push(off);
+    const acquired = [];
+    let disposed = false;
+    try {
+        for (const system of list) {
+            acquired.push(system);
+            system.create?.(ctx);
+        }
+        for (const system of list) {
+            if (system.events !== undefined) {
+                for (const [name, handler] of Object.entries(system.events)) {
+                    if (handler === undefined)
+                        continue;
+                    const off = ctx.game.events.on(name, ((event) => {
+                        handler(ctx, event);
+                    }));
+                    unsubs.push(off);
+                }
             }
+            const save = resolveModule(system.save, ctx);
+            if (save !== undefined)
+                options?.modules?.registerSave(save);
+            const replicate = resolveModule(system.replicate, ctx);
+            if (replicate !== undefined)
+                options?.modules?.registerReplicate(replicate);
+        }
+        for (const system of list) {
+            system.start?.(ctx);
         }
-        const save = resolveModule(system.save, ctx);
-        if (save !== undefined)
-            options?.modules?.registerSave(save);
-        const replicate = resolveModule(system.replicate, ctx);
-        if (replicate !== undefined)
-            options?.modules?.registerReplicate(replicate);
     }
-    for (const system of list) {
-        system.start?.(ctx);
+    catch (error) {
+        try {
+            dispose(ctx);
+        }
+        catch { /* The startup error remains the first failure. */ }
+        throw error;
     }
     for (const group of schedule.fixed) {
         fixedAcc.set(group.rate, 0);
@@ -52,7 +64,7 @@ export function installSystems(ctx, systems, options) {
         }
     }
     function tick(ctx, dt) {
-        if (!(dt > 0))
+        if (disposed || !(dt > 0))
             return;
         for (const group of schedule.fixed) {
             const step = 1 / group.rate;
@@ -79,6 +91,8 @@ export function installSystems(ctx, systems, options) {
         }
     }
     function reset(ctx) {
+        if (disposed)
+            return;
         for (const system of list)
             system.reset?.(ctx);
         for (const group of schedule.fixed)
@@ -87,14 +101,33 @@ export function installSystems(ctx, systems, options) {
             intervalAcc.set(interval.id, 0);
     }
     function dispose(ctx) {
-        for (const off of unsubs)
-            off();
+        if (disposed)
+            return;
+        disposed = true;
+        let failure;
+        for (const off of unsubs) {
+            try {
+                off();
+            }
+            catch (error) {
+                failure ??= { error };
+            }
+        }
         unsubs.length = 0;
-        for (let i = list.length - 1; i >= 0; i -= 1) {
-            list[i]?.dispose?.(ctx);
+        for (let i = acquired.length - 1; i >= 0; i -= 1) {
+            try {
+                acquired[i]?.dispose?.(ctx);
+            }
+            catch (error) {
+                failure ??= { error };
+            }
         }
+        if (failure !== undefined)
+            throw failure.error;
     }
     function runManual(ctx, id, dt = 0) {
+        if (disposed)
+            return;
         if (!schedule.manual.includes(id))
             return;
         schedule.systemsById.get(id)?.update?.(ctx, dt);
@@ -119,17 +152,18 @@ export function composeGameLoop(systems, loop, options) {
     if (systems === undefined || systems.length === 0) {
         return loop ?? {};
     }
-    let installed;
+    const retired = new WeakSet();
     const loopBefore = options?.loopBeforeSystems === true;
     return {
         onInit(ctx) {
+            retired.delete(ctx);
             const modules = ctx.game.registerSave !== undefined && ctx.game.registerReplicate !== undefined
                 ? {
                     registerSave: (m) => ctx.game.registerSave(m),
                     registerReplicate: (m) => ctx.game.registerReplicate(m),
                 }
                 : undefined;
-            installed = installSystems(ctx, systems, { ...options, modules });
+            const installed = installSystems(ctx, systems, { ...options, modules });
             installedByCtx.set(ctx, installed);
             loop?.onInit?.(ctx);
         },
@@ -139,10 +173,10 @@ export function composeGameLoop(systems, loop, options) {
         onTick(ctx, dt) {
             if (loopBefore) {
                 loop?.onTick?.(ctx, dt);
-                installed?.tick(ctx, dt);
+                installedByCtx.get(ctx)?.tick(ctx, dt);
             }
             else {
-                installed?.tick(ctx, dt);
+                installedByCtx.get(ctx)?.tick(ctx, dt);
                 loop?.onTick?.(ctx, dt);
             }
         },
@@ -150,13 +184,30 @@ export function composeGameLoop(systems, loop, options) {
             loop?.onPlayerLeave?.(ctx, player);
         },
         onReset(ctx) {
-            installed?.reset(ctx);
+            installedByCtx.get(ctx)?.reset(ctx);
             loop?.onReset?.(ctx);
         },
         onDispose(ctx) {
-            installed?.dispose(ctx);
+            if (retired.has(ctx))
+                return;
+            retired.add(ctx);
+            const installed = installedByCtx.get(ctx);
             installedByCtx.delete(ctx);
-            loop?.onDispose?.(ctx);
+            let failure;
+            try {
+                installed?.dispose(ctx);
+            }
+            catch (error) {
+                failure = { error };
+            }
+            try {
+                loop?.onDispose?.(ctx);
+            }
+            catch (error) {
+                failure ??= { error };
+            }
+            if (failure !== undefined)
+                throw failure.error;
         },
     };
 }

package/dist/gameplay.d.ts

@@ -31,6 +31,7 @@ export { medalFor, rankLeaderboard, type RankLeaderboardOptions, type RankableRo
 export { createLevelSequence, type LevelSequence } from "./game/levelSequence.js";
 export { createLoadouts, type LoadoutDef } from "./game/loadout.js";
 export { evaluateLootFilter, lootFilter, type LootFilterRule } from "./game/lootFilter.js";
+export { timeScaledRarity, type TimeScaledRarityOptions } from "./game/lootModifiers.js";
 export { createLootPipeline, defineLootPipeline, type LootDropProvenance, type LootModifier, type LootPipeline, type LootPipelineDef, type LootPipelineDeps, type LootPlanEntry, type LootResolution, type LootResolveContext, type LootRollPlan, type LootStage, type LootStageKind, type LootStageStatus, type LootStageTrace, } from "./game/lootPipeline.js";
 export { createLootRegistry, lootTable, type Drop, type LootTableDef } from "./game/lootTable.js";
 export { resolveOneShotClip } from "./game/modelAnimation.js";
@@ -100,5 +101,7 @@ export { createMultiRegionHealth, type MultiRegionHealth } from "./survival/regi
 export { createCommitController } from "./turn/commit.js";
 export { createIntentBoard } from "./turn/intent.js";
 export { createTurnLoop, type TurnLoop } from "./turn/turnLoop.js";
+export { dispatchExpedition, recallExpedition, returnExpeditionNow, settleExpedition, type ExpeditionConfig, type ExpeditionDispatch, type ExpeditionEvent, type ExpeditionHazard, type ExpeditionState, type ExpeditionSupplyRule, } from "./work/expedition.js";
 export { activeJobs, cancelJob, createWorkQueue, enqueue, fifoOrdering, jobById, jobProgress, pauseJob, priorityOrdering, queueSize, queuedJobs, resumeJob, tick, type CancelResult, type EnqueueOptions, type EnqueueResult, type Job, type JobId, type JobOrdering, type JobStatus, type JobValidation, type TickResult, type WorkQueueConfig, type WorkQueueEvent, type WorkQueueState, } from "./work/jobQueue.js";
+export { stationOutputRate, type StaffedStation, type StationRateTuning, type StationWorker, } from "./work/staffedStation.js";
 export { unitTrainingConfig, type ResourceCost, type TrainableUnitDef, type UnitReservation, type UnitSpawnOrder, type UnitTrainingOptions, type UnitTrainingSpec, } from "./work/unitTraining.js";

package/dist/gameplay.js

@@ -31,6 +31,7 @@ export { medalFor, rankLeaderboard, } from "./game/leaderboardRank.js";
 export { createLevelSequence } from "./game/levelSequence.js";
 export { createLoadouts } from "./game/loadout.js";
 export { evaluateLootFilter, lootFilter } from "./game/lootFilter.js";
+export { timeScaledRarity } from "./game/lootModifiers.js";
 export { createLootPipeline, defineLootPipeline, } from "./game/lootPipeline.js";
 export { createLootRegistry, lootTable } from "./game/lootTable.js";
 export { resolveOneShotClip } from "./game/modelAnimation.js";
@@ -100,5 +101,7 @@ export { createMultiRegionHealth } from "./survival/regionHealth.js";
 export { createCommitController } from "./turn/commit.js";
 export { createIntentBoard } from "./turn/intent.js";
 export { createTurnLoop } from "./turn/turnLoop.js";
+export { dispatchExpedition, recallExpedition, returnExpeditionNow, settleExpedition, } from "./work/expedition.js";
 export { activeJobs, cancelJob, createWorkQueue, enqueue, fifoOrdering, jobById, jobProgress, pauseJob, priorityOrdering, queueSize, queuedJobs, resumeJob, tick, } from "./work/jobQueue.js";
+export { stationOutputRate, } from "./work/staffedStation.js";
 export { unitTrainingConfig, } from "./work/unitTraining.js";

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;