@jgengine/core 0.12.0 → 0.13.0

package/dist/runtime/gameContext.js

@@ -6,6 +6,7 @@ import { createGameFeed } from "../game/feed.js";
 import { setGamePhase } from "../game/gamePhase.js";
 import { createLootRegistry, grantDrops } from "../game/lootTable.js";
 import { createSocial } from "../game/social.js";
+import { splitStack } from "../inventory/inventoryModel.js";
 import { createItemUse } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
 import {} from "../scene/entityStats.js";
@@ -55,7 +56,7 @@ export function createGameContext(options) {
         ...(occluder !== undefined ? { occluder } : {}),
         ...(options.models !== undefined ? { models: options.models } : {}),
     });
-    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
+    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, reportEntityBounds, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
     // --- Shared game services (weapon, feed, features bag, commands, item use) ---
     const weapon = createWeaponStats((itemId) => content.itemById?.(itemId));
     const feed = createGameFeed(definition.feed);
@@ -114,6 +115,45 @@ export function createGameContext(options) {
     });
     const { inventoryIds, inventoryByUser, inventoryFor, layouts, wallets, walletOf, economy, putIntoAnyInventory, playerStatsFor, pose, possession, motionByUser, motionFor, loadouts, seedUserPool, } = playerSys;
     scene.setOnAfterDespawn((instanceId) => pose.clear(instanceId));
+    // Built-in inventory mutation commands so a HUD grid drives moves/splits through the notifying
+    // command path (a raw InventorySet mutation would not re-render React). Each resolves the acting
+    // user's own inventory, so it respects `privatePerUser` replication.
+    const knownInventory = (inventoryId) => layouts[inventoryId] !== undefined;
+    const slotInRange = (inventoryId, slot) => typeof slot === "number" && Number.isInteger(slot) && slot >= 0 && slot < layouts[inventoryId].slots;
+    commandRegistry.define("inventory.move", {
+        validate(_state, input) {
+            if (!knownInventory(input.inventoryId))
+                return { reason: `unknown inventory "${input.inventoryId}"` };
+            if (!slotInRange(input.inventoryId, input.from) || !slotInRange(input.inventoryId, input.to)) {
+                return { reason: "invalid-slot" };
+            }
+            return null;
+        },
+        apply(_state, input) {
+            const inventory = inventoryFor(activeUserId());
+            // A rejected move (empty source, wrong-kind, no-space) is a harmless no-op: the item bounces back.
+            inventory.move(input.inventoryId, input.from, input.inventoryId, input.to);
+        },
+    });
+    commandRegistry.define("inventory.split", {
+        validate(_state, input) {
+            if (!knownInventory(input.inventoryId))
+                return { reason: `unknown inventory "${input.inventoryId}"` };
+            if (!slotInRange(input.inventoryId, input.slot))
+                return { reason: "invalid-slot" };
+            if (input.toSlot !== undefined && !slotInRange(input.inventoryId, input.toSlot)) {
+                return { reason: "invalid-slot" };
+            }
+            return null;
+        },
+        apply(_state, input) {
+            const inventory = inventoryFor(activeUserId());
+            const result = splitStack(inventory.state(input.inventoryId), input.slot, input.amount, input.toSlot);
+            if (result.status === "rejected")
+                return;
+            inventory.replaceState(input.inventoryId, result.state);
+        },
+    });
     const loot = {
         register: lootRegistry.register,
         has: lootRegistry.has,
@@ -328,6 +368,7 @@ export function createGameContext(options) {
                     signal.notify();
                 },
                 collidersOf: entityCollidersOf,
+                reportBounds: reportEntityBounds,
                 visualScaleOf: entityVisualScaleOf,
                 form: forms,
                 paint: paintLayer,
@@ -472,16 +513,21 @@ function saveKey(name) {
     const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
     return `jgengine:save:${slug === "" ? "game" : slug}`;
 }
-/** Explicit `options.save` wins (the shell can inject any backend, e.g. cloud); otherwise `defineGame({ persist })` auto-wires a localStorage save for offline/single-player worlds only. */
+/**
+ * Explicit `options.save` wins (the shell can inject any backend, e.g. cloud); otherwise an offline /
+ * single-player world auto-wires a `localStorage` whole-world save **by default** — a game gets `ctx.game.save`
+ * and autosave without touching `persist`. Only an explicit `persist: false` opts out; a host-authoritative
+ * multiplayer world never persists to `localStorage` (its host owns persistence) regardless of `persist`.
+ */
 function resolveSaveOptions(definition, options) {
     if (options.save !== undefined)
         return options.save;
     const persist = definition.persist;
-    if (persist === undefined || persist === false)
+    if (persist === false)
         return undefined;
     if (!isOffline(definition.multiplayer))
         return undefined;
-    const config = persist === true ? {} : persist;
+    const config = persist === undefined || persist === true ? {} : persist;
     return {
         backend: config.storage === "memory" ? memorySaveBackend() : localSaveBackend(),
         mode: config.mode,

package/dist/runtime/gameContextTypes.d.ts

@@ -2,6 +2,7 @@ import type { CardPile, CardPileConfig } from "../cards/cardPile.js";
 import type { EffectInput, EffectResult, EffectVia, ReceiveMap, SingleTargetEffectInput } from "../combat/effects.js";
 import type { ProjectileSystem } from "../combat/projectiles.js";
 import type { HitReaction, HitReactionConfig, ImpactPresetName } from "../combat/hitReaction.js";
+import type { VfxPresetName } from "../combat/vfxPresets.js";
 import type { TelegraphShape } from "../combat/telegraph.js";
 import type { CommandDefinition, CommandResult } from "../commands/commandRegistry.js";
 import type { ChargeOptions as WalletChargeOptions } from "../economy/wallet.js";
@@ -33,7 +34,7 @@ import type { PaintLayer } from "../scene/paintLayer.js";
 import type { EntityStatsApi, StatCatalog } from "../scene/entityStats.js";
 import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
 import type { Forms } from "../scene/form.js";
-import type { EntityColliderSet, ModelBodySource } from "../scene/colliders.js";
+import type { EntityColliderSet, MeasuredBounds, ModelBodySource } from "../scene/colliders.js";
 import type { ObjectRaycastHit, ObjectRaycastInput } from "../scene/objectQuery.js";
 import type { ObjectStore } from "../scene/objectStore.js";
 import type { Roster } from "../scene/roster.js";
@@ -135,6 +136,15 @@ export interface SceneObjectContext extends ObjectStore {
     raycastAll(input: ObjectRaycastInput): readonly ObjectRaycastHit[];
     setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
     collidersOf(instanceId: string): EntityColliderSet | null;
+    /**
+     * Report the entity-local AABB the renderer actually mounted for `catalogId` — stored per catalog
+     * id as a blocking physical body and consulted after authored `colliders` and index-`dims` fitted
+     * models, before the visual-scale fallback. The shell reports custom `renderObject` content and
+     * dims-less models automatically, so a placed prop's body wraps its real rendered shape instead of
+     * a unit-cube guess. Pass `null` to clear. Returns `false` when the bounds are degenerate.
+     * @capability measured-colliders hitboxes and blocking bodies wrap what the renderer actually mounted — custom render props and dims-less models stop falling back to fixed-size boxes.
+     */
+    reportBounds(catalogId: string, bounds: MeasuredBounds | null): boolean;
     /**
      * Per-instance selection/highlight state for placed objects — the reactive counterpart to
      * `worldHealthBars`/`nameplates` (entities), so a build-mode or RTS selection ring reads
@@ -156,10 +166,22 @@ export interface FloatTextInput {
     crit?: boolean;
     scale?: number;
 }
-/** Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`. */
+/**
+ * Request a transient spell/ability VFX burst. The easy path is a named `preset` —
+ * `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color
+ * or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"`
+ * and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id
+ * (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`,
+ * `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color`
+ * yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
+ */
 export interface VfxInput {
-    kind: VfxKind;
-    color: number;
+    /** A named visual flavor from {@link vfxPresets}. Fills in `kind`/`color`/defaults; explicit fields below still win. */
+    preset?: VfxPresetName | (string & {});
+    /** Visual archetype. Optional when `preset` is given; required otherwise. */
+    kind?: VfxKind;
+    /** `0xRRGGBB` tint. Optional when `preset` is given; required otherwise. */
+    color?: number;
     from?: string | readonly [number, number, number];
     to?: string | readonly [number, number, number];
     radius?: number;
@@ -242,6 +264,17 @@ export interface SceneEntityContext {
     invalidateSpatial: SpatialApi["invalidate"];
     setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
     collidersOf(instanceId: string): EntityColliderSet | null;
+    /**
+     * Report the entity-local AABB the renderer actually mounted for `kind` — stored per kind as a
+     * tight damage hitbox and consulted after authored `colliders` and index-`dims` fitted models,
+     * before the scale/humanoid-default fallbacks. The shell reports custom `renderEntity` content and
+     * dims-less models automatically, so hitboxes wrap the rendered mesh instead of the fixed
+     * 0.7×1.8×0.7 box. Runtime-measured on the client; authoritative hosts that never render should
+     * author `colliders` or model `dims` instead. Pass `null` to clear. Returns `false` when the
+     * bounds are degenerate.
+     * @capability measured-hitboxes an entity rendered with a custom mesh takes hits in a box matching its rendered bounds, not the fixed humanoid rectangle.
+     */
+    reportBounds(kind: string, bounds: MeasuredBounds | null): boolean;
     /** Uniform visual scale from the entity's catalog entry (1 when unscaled). */
     visualScaleOf(instanceId: string): number;
     form: Forms;

package/dist/runtime/headlessRunner.d.ts

@@ -36,6 +36,17 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
     /** Render-model lookup for collider auto-fit — pass what the shell would derive from `entityModels`/`objectModels` so headless raycasts hit the same boxes as play. */
     models?: GameContextModels;
 }
+/** Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`. */
+export interface HeadlessCommandInterface {
+    /** Invoke a registered command/intent by name against the live context. Throws on `unknown-command` or a validation rejection so a headless UI-flow test fails loudly instead of silently no-op'ing. */
+    invoke(name: string, input?: unknown): void;
+    /** Non-throwing {@link invoke} returning the raw command result (inspect `status`). */
+    tryInvoke(name: string, input?: unknown): ReturnType<GameContext["game"]["commands"]["run"]>;
+    /** Registered command names. */
+    names(): string[];
+    /** Is a command registered? */
+    has(name: string): boolean;
+}
 /**
  * A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init
  * hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole
@@ -58,5 +69,7 @@ export interface HeadlessRunner {
     step(dtSeconds: number, input?: HeadlessInput): number;
     /** Publish input without advancing — for pre-seeding the held set before the first {@link step}. */
     publishInput(input: HeadlessInput): void;
+    /** Drive the game's own UI commands / intents headlessly — the same registry `ctx.game.commands` and the shell's command sink dispatch into. No renderer, no pointer simulation: dispatch an intent, then read reactive state off `ctx`. */
+    readonly ui: HeadlessCommandInterface;
 }
 export declare function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner;

package/dist/runtime/headlessRunner.js

@@ -29,6 +29,20 @@ export function createHeadlessRunner(options) {
         input: ctx.input,
         userId: player.userId,
         publishInput,
+        ui: {
+            invoke(name, input) {
+                const result = ctx.game.commands.run(name, input);
+                if (result.status === "unknown-command") {
+                    throw new Error(`headless ui.invoke: unknown command "${name}" — define it via ctx.game.commands.define`);
+                }
+                if (result.status === "rejected") {
+                    throw new Error(`headless ui.invoke: command "${name}" rejected — ${result.reason}`);
+                }
+            },
+            tryInvoke: (name, input) => ctx.game.commands.run(name, input),
+            names: () => ctx.game.commands.names(),
+            has: (name) => ctx.game.commands.has(name),
+        },
         step(dtSeconds, input) {
             if (input !== undefined)
                 publishInput(input);

package/dist/scene/assetCatalog.d.ts

@@ -22,6 +22,8 @@ export interface ModelAssetRef {
     collisionMesh?: CollisionMeshData;
     /** Authored asset-space metadata — canonical facing (degrees), source-unit scale, footprint, anchor, bounds, and rotation policy. The upstream owner of placement corrections; see {@link "scene/assetSpace".AssetSpace}. */
     space?: AssetSpace;
+    /** Animation clip names read from the GLB at asset reindex. Lets the shell auto-animate rigged catalog assets (semantic clip roles → default idle/walk/run + one-shots) with no game-side clip strings. */
+    clips?: readonly string[];
 }
 /**
  * A catalog entry backed by a registered {@link registerAssetGenerator} instead of a GLB URL — a

package/dist/scene/colliders.d.ts

@@ -107,6 +107,27 @@ export declare function fittedEntityColliders(model: ModelBodySource): EntityCol
  * @internal
  */
 export declare function fittedObjectColliders(model: ModelBodySource): EntityColliderSet | null;
+/**
+ * Entity-local AABB of what the renderer actually mounted for a kind — the runtime counterpart to
+ * index-measured `dims`. Reported through `ctx.scene.entity.reportBounds` /
+ * `ctx.scene.object.reportBounds` (the shell does this automatically for custom
+ * `renderEntity`/`renderObject` content and models without index dims) so collider resolution can
+ * wrap the real rendered shape instead of a fixed-size guess.
+ */
+export interface MeasuredBounds {
+    min: EntityPosition;
+    max: EntityPosition;
+}
+/** Damage hitbox exactly wrapping runtime-measured render bounds — what `reportBounds` stores for an
+ * entity kind. `null` when the bounds are degenerate, keeping the caller's existing fallback.
+ * @internal
+ */
+export declare function measuredEntityColliders(bounds: MeasuredBounds): EntityColliderSet | null;
+/** Blocking physical body exactly wrapping runtime-measured render bounds — what `reportBounds`
+ * stores for an object catalog id. `null` when the bounds are degenerate.
+ * @internal
+ */
+export declare function measuredObjectColliders(bounds: MeasuredBounds): EntityColliderSet | null;
 /** @internal */
 export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
 /** @internal */

package/dist/scene/colliders.js

@@ -188,6 +188,68 @@ export function fittedObjectColliders(model) {
         },
     };
 }
+/** Thin measured axes (decals, blades, flat panels) keep at least this half-extent so the box stays hittable. */
+const MIN_MEASURED_HALF_EXTENT = 0.01;
+/** Tight AABB from measured bounds — `null` when inverted, non-finite, or a degenerate point. */
+function measuredBox(bounds) {
+    const { min, max } = bounds;
+    let volume = 0;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const lo = min[axis];
+        const hi = max[axis];
+        if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi < lo)
+            return null;
+        volume = Math.max(volume, hi - lo);
+    }
+    if (!(volume > 0))
+        return null;
+    return {
+        halfExtents: [
+            Math.max((max[0] - min[0]) / 2, MIN_MEASURED_HALF_EXTENT),
+            Math.max((max[1] - min[1]) / 2, MIN_MEASURED_HALF_EXTENT),
+            Math.max((max[2] - min[2]) / 2, MIN_MEASURED_HALF_EXTENT),
+        ],
+        offset: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2],
+    };
+}
+/** Damage hitbox exactly wrapping runtime-measured render bounds — what `reportBounds` stores for an
+ * entity kind. `null` when the bounds are degenerate, keeping the caller's existing fallback.
+ * @internal
+ */
+export function measuredEntityColliders(bounds) {
+    const box = measuredBox(bounds);
+    if (box === null)
+        return null;
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape: { kind: "aabb", halfExtents: box.halfExtents, offset: box.offset },
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+/** Blocking physical body exactly wrapping runtime-measured render bounds — what `reportBounds`
+ * stores for an object catalog id. `null` when the bounds are degenerate.
+ * @internal
+ */
+export function measuredObjectColliders(bounds) {
+    const box = measuredBox(bounds);
+    if (box === null)
+        return null;
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape: { kind: "aabb", halfExtents: box.halfExtents, offset: box.offset },
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
 /** @internal */
 export function resolveColliders(set) {
     if (set === null || set === undefined)

package/dist/scene/entityStats.js

@@ -19,6 +19,11 @@ export function applyPoolDelta(map, statId, amount) {
     }
     const change = changeStatPool(existing, amount);
     const stat = change.pool;
+    // No-op change: `changeStatPool` handed back the same pool reference, so keep
+    // the existing map too — callers can guard on reference identity.
+    if (stat === existing) {
+        return { status: "ok", map, stat, hitMin: change.hitMin, hitMax: change.hitMax };
+    }
     return {
         status: "ok",
         map: { ...map, [statId]: stat },
@@ -81,10 +86,13 @@ export function createEntityStatsApi(resolve) {
             const map = resolve(instanceId);
             if (map === undefined)
                 return { reason: `unknown instance "${instanceId}"` };
+            const existing = map[statId];
             const result = applyPoolDelta(map, statId, amount);
             if (result.status === "rejected")
                 return { reason: result.reason };
-            map[statId] = result.stat;
+            // Skip the store write when nothing moved so reference guards stay stable.
+            if (result.stat !== existing)
+                map[statId] = result.stat;
             return null;
         },
     };

package/dist/stats/statModifiers.d.ts

@@ -6,6 +6,17 @@ export type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatMo
 export interface CreateStatsOptions {
     now?: () => number;
 }
+/** One serializable modifier source in a {@link StatsSnapshot}. */
+interface StatModifierSourceSnapshot<TStat extends string> {
+    id: string;
+    modifiers: StatModifierSet<TStat>;
+    expiresAtMs?: number;
+}
+/** Complete plain-data state for a {@link Stats} runtime. */
+export interface StatsSnapshot<TStat extends string> {
+    base: Record<TStat, number>;
+    sources: StatModifierSourceSnapshot<TStat>[];
+}
 export interface Stats<TStat extends string> {
     setBase(stat: TStat, value: number): void;
     getBase(stat: TStat): number;
@@ -17,6 +28,10 @@ export interface Stats<TStat extends string> {
     get(stat: TStat, nowMs?: number): number;
     pruneExpired(nowMs: number): string[];
     sources(): string[];
+    /** Return a detached JSON-serializable copy of base values and modifier sources. */
+    snapshot(): StatsSnapshot<TStat>;
+    /** Replace all runtime state from caller-owned decoded snapshot data. */
+    restore(snapshot: StatsSnapshot<TStat>): void;
 }
 /**
  * A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
@@ -24,3 +39,4 @@ export interface Stats<TStat extends string> {
  * @capability stat-block base stats with stacking, expiring buffs and debuffs applied on read
  */
 export declare function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat>;
+export {};

package/dist/stats/statModifiers.js

@@ -1,10 +1,19 @@
+function cloneModifierSet(modifiers) {
+    const copy = {};
+    for (const stat of Object.keys(modifiers)) {
+        const modifier = modifiers[stat];
+        if (modifier !== undefined)
+            copy[stat] = { ...modifier };
+    }
+    return copy;
+}
 /**
  * A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
  *
  * @capability stat-block base stats with stacking, expiring buffs and debuffs applied on read
  */
 export function createStats(base, options) {
-    const baseValues = { ...base };
+    let baseValues = { ...base };
     const sourceEntries = new Map();
     const clock = options?.now;
     function resolveNow(nowMs) {
@@ -75,5 +84,25 @@ export function createStats(base, options) {
         sources() {
             return Array.from(sourceEntries.keys());
         },
+        snapshot() {
+            return {
+                base: { ...baseValues },
+                sources: Array.from(sourceEntries, ([id, entry]) => ({
+                    id,
+                    modifiers: cloneModifierSet(entry.modifiers),
+                    ...(entry.expiresAtMs === undefined ? {} : { expiresAtMs: entry.expiresAtMs }),
+                })),
+            };
+        },
+        restore(snapshot) {
+            baseValues = { ...snapshot.base };
+            sourceEntries.clear();
+            for (const source of snapshot.sources) {
+                sourceEntries.set(source.id, {
+                    modifiers: cloneModifierSet(source.modifiers),
+                    expiresAtMs: source.expiresAtMs,
+                });
+            }
+        },
     };
 }

package/dist/stats/statPool.js

@@ -33,10 +33,13 @@ export function patchStatPool(pool, patch) {
  */
 export function changeStatPool(pool, amount) {
     const next = patchStatPool(pool, { current: pool.current + amount });
+    const applied = next.current - pool.current;
     return {
         previous: pool,
-        pool: next,
-        applied: next.current - pool.current,
+        // Preserve the input reference on a no-op change (regen at max, damage at 0,
+        // clamp to a bound) so reference-equality guards in HUD hooks don't churn.
+        pool: applied === 0 ? pool : next,
+        applied,
         hitMin: next.current === next.min,
         hitMax: next.current === next.max,
     };

package/dist/ui/panelModel.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Headless, serializable model for a set of player-toggled windows/panels — the data layer behind a
+ * WoW-style UI where B opens the bag, C the character sheet, and ESC closes the topmost window. It
+ * carries *which panels are open*, their focus/z stacking order, per-panel position overrides, and
+ * exclusive-group membership, with zero rendering opinion. The React chrome in
+ * `@jgengine/react/panels` consumes this; a game keeps layout, skin, keybinds, and window content
+ * caller-owned. Pure and immutable: every reducer returns a new state and never mutates its input.
+ */
+/** A pixel position override for a panel (top-left, relative to the host surface). */
+export interface PanelPosition {
+    x: number;
+    y: number;
+}
+/**
+ * A caller-authored panel/window declaration — the DATA input to the model. Only `id` is required so
+ * a bag, a character sheet, and a one-off dialog all share the shape.
+ */
+export interface PanelDef {
+    id: string;
+    /** Human title shown in the window's title bar; falls back to `id`. */
+    title?: string;
+    /** Keybind that opens/toggles the panel — a `KeyboardEvent.code` (`"KeyB"`) or key (`"b"`), matched case-insensitively by {@link panelByHotkey}. */
+    hotkey?: string;
+    /** Open on {@link createPanelState} (default false). */
+    initial?: boolean;
+    /** Exclusive group: opening one panel in a group closes the others in it (e.g. only one center window). */
+    group?: string;
+    /** Whether the player can close it (title-bar button / ESC). Default true; `false` pins it open. */
+    closable?: boolean;
+}
+/** @internal Serializable per-panel metadata lifted from {@link PanelDef} so reducers stay `(state, id)` pure. */
+export interface PanelMeta {
+    group?: string;
+    closable?: boolean;
+}
+/**
+ * Serializable state for a set of panels: which are `open`, their `z` focus stack (higher renders on
+ * top), optional per-panel `pos` overrides, and the `meta` registry (group/closable) captured from
+ * the defs so the reducers below need no defs argument. Plain JSON — persist and rehydrate it freely.
+ */
+export interface PanelState {
+    /** Open panels, keyed by id (`true` for open). Closed panels are absent. */
+    open: Record<string, true>;
+    /** z / focus order per open panel — the panel with the highest value is focused/on top. */
+    z: Record<string, number>;
+    /** Per-panel position overrides; remembered across close/reopen. */
+    pos: Record<string, PanelPosition>;
+    /** Group/closable metadata captured from the defs at construction. */
+    meta: Record<string, PanelMeta>;
+    /** Next z value to assign on open/focus — monotonic so focus order is deterministic. */
+    nextZ: number;
+}
+/**
+ * Build the initial {@link PanelState} from the panel defs: panels flagged `initial` start open (in
+ * declaration order, respecting group exclusivity), and every def's group/closable is captured into
+ * the state so later reducers need no defs.
+ *
+ * @capability panel-state serializable open/z/position state for a set of toggleable game windows
+ */
+export declare function createPanelState(defs: readonly PanelDef[]): PanelState;
+/** Whether panel `id` is currently open. */
+export declare function isOpen(state: PanelState, id: string): boolean;
+/**
+ * Open panel `id`, raising it to the top of the focus stack. If it belongs to a `group`, the other
+ * open panels in that group are closed (exclusive windows). Opening an already-open panel just
+ * refocuses it. Position overrides are preserved.
+ *
+ * @capability panel-open open a window, raise its z, and enforce exclusive-group membership
+ */
+export declare function openPanel(state: PanelState, id: string): PanelState;
+/**
+ * Close panel `id`. No-op if it is already closed. Its position override is kept so reopening restores
+ * the last placement.
+ *
+ * @capability panel-close close a window while remembering its last position
+ */
+export declare function closePanel(state: PanelState, id: string): PanelState;
+/**
+ * Toggle panel `id` — open it (with group exclusivity) if closed, close it if open. The one-key
+ * behavior behind a keybind like `B` for the bag.
+ *
+ * @capability panel-toggle toggle a window open/closed from a single keybind
+ */
+export declare function togglePanel(state: PanelState, id: string): PanelState;
+/**
+ * Raise open panel `id` to the top of the focus stack (assign it the highest z). No-op if it is
+ * closed or already on top, so a pointer-down that refocuses the top window returns the same state.
+ *
+ * @capability panel-focus raise a window to the top of the focus/z stack
+ */
+export declare function focusPanel(state: PanelState, id: string): PanelState;
+/**
+ * Close the topmost closable open panel — the ESC handler. Skips panels pinned with `closable: false`
+ * and returns the same state when nothing closable is open.
+ *
+ * @capability panel-close-top close the focused (topmost) closable window — the ESC behavior
+ */
+export declare function closeTopPanel(state: PanelState): PanelState;
+/**
+ * Find the panel whose `hotkey` matches `code`, case-insensitively — the keybind router. `code` may be
+ * a `KeyboardEvent.code` (`"KeyB"`) or key (`"b"`); it is compared verbatim to each def's `hotkey`, so
+ * author the hotkey in whichever form the caller feeds in. Returns the first match's id, or null.
+ *
+ * @capability panel-hotkey resolve a keybind (code or key) to the panel id it toggles
+ */
+export declare function panelByHotkey(defs: readonly PanelDef[], code: string): string | null;
+/**
+ * Set panel `id`'s position override — the drag commit. Does not require the panel to be open, so a
+ * caller can pre-place a window before it is shown.
+ *
+ * @capability panel-move override a window's on-surface position (the drag commit)
+ */
+export declare function movePanel(state: PanelState, id: string, pos: PanelPosition): PanelState;
+/**
+ * The open panels' defs sorted ascending by z — the render order for a window host (map to elements
+ * so the last, highest-z window paints on top). Defs unknown to the state are skipped.
+ *
+ * @capability panel-ordered-open open panels' defs in z/render order for a window host
+ */
+export declare function orderedOpen(state: PanelState, defs: readonly PanelDef[]): PanelDef[];