@jgengine/core 0.12.0 → 0.14.0

package/dist/scene/collisionMesh.js

@@ -500,6 +500,54 @@ function buildBvh(positions, indices) {
         triOrder,
     };
 }
+/**
+ * Build a prepared BVH mesh straight from a runtime triangle soup (float positions + indices) —
+ * the renderer-fed counterpart to {@link prepareCollisionMesh}, feeding
+ * `ctx.scene.entity.reportCollisionMesh` / `ctx.scene.object.reportCollisionMesh` without a
+ * quantize/encode round-trip. Copies and sanitizes the input: triangles referencing out-of-range,
+ * non-finite, or repeated vertices are dropped. Returns `null` when no triangle survives.
+ */
+export function prepareCollisionMeshSource(source) {
+    const raw = source.positions;
+    const rawIndices = source.indices;
+    if (raw.length < 9 || raw.length % 3 !== 0)
+        return null;
+    if (rawIndices.length < 3 || rawIndices.length % 3 !== 0)
+        return null;
+    const vertexCount = raw.length / 3;
+    const positions = new Float32Array(raw.length);
+    const finite = new Uint8Array(vertexCount);
+    for (let v = 0; v < vertexCount; v += 1) {
+        const x = raw[v * 3];
+        const y = raw[v * 3 + 1];
+        const z = raw[v * 3 + 2];
+        if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+            continue;
+        positions[v * 3] = x;
+        positions[v * 3 + 1] = y;
+        positions[v * 3 + 2] = z;
+        finite[v] = 1;
+    }
+    const triangles = [];
+    for (let t = 0; t + 2 < rawIndices.length; t += 3) {
+        const a = rawIndices[t];
+        const b = rawIndices[t + 1];
+        const c = rawIndices[t + 2];
+        if (!Number.isInteger(a) || a < 0 || a >= vertexCount || finite[a] === 0)
+            continue;
+        if (!Number.isInteger(b) || b < 0 || b >= vertexCount || finite[b] === 0)
+            continue;
+        if (!Number.isInteger(c) || c < 0 || c >= vertexCount || finite[c] === 0)
+            continue;
+        if (a === b || b === c || a === c)
+            continue;
+        triangles.push(a, b, c);
+    }
+    if (triangles.length === 0)
+        return null;
+    const indices = new Uint32Array(triangles);
+    return { positions, indices, ...buildBvh(positions, indices) };
+}
 const preparedCache = new WeakMap();
 /**
  * Decode a stored collision mesh and index it with a BVH. Memoized per data object, so the shell and

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/scene/sceneKinds.d.ts

@@ -145,6 +145,19 @@ export interface ParamSchema {
 export declare function findSchemaPreset(schema: ParamSchema, id: string): ParamPreset | undefined;
 /** Parsed params after `parseParams`: every schema field present with a validated, defaulted value. */
 export type ParsedParams = Record<string, number | boolean | string | WeightedParamEntry[]>;
+/**
+ * Marks a kind as *scatterable* — it fills an authored area with instances at one density under a
+ * bounded budget — so the editor renders the shared `CoverageSection` (Area → Assets → Density slider
+ * + budget note) that gives grass/scatter/city one authoring gesture. `spec` selects the unit + budget
+ * from `@jgengine/core/world/scatterCoverage`; `densityKey` is the single density slider hoisted into
+ * the coverage header (and hidden from the schema body below); `assetsKey` is the optional weighted
+ * "what fills it" palette summarized in the header.
+ */
+export interface SceneKindCoverage {
+    spec: import("../world/scatterCoverage.js").ScatterCoverageKind;
+    densityKey: string;
+    assetsKey?: string;
+}
 /**
  * Parse a raw `meta` bag against a schema into typed params — every field present, invalid/missing
  * values replaced by the field default, numbers clamped to their range. The single parser every
@@ -201,6 +214,12 @@ export interface SceneKindDefinition<TResolved = unknown> {
     resolve?: (object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => TResolved;
     /** Optional one-line readout under the inspector fields (estimate, dimensions) — owned by the studio. */
     note?: (object: SceneKindObject, params: ParsedParams) => string;
+    /**
+     * Optional scatterable-coverage descriptor. When set, the editor leads this kind's inspector with
+     * the shared Area / Assets / Density `CoverageSection` and surfaces the budget clamp-and-warn note,
+     * giving every scatterable kind (grass/scatter/city) one authoring pattern.
+     */
+    coverage?: SceneKindCoverage;
 }
 /** The raw document object a resolver receives — shape shared by markers, volumes, and paths. */
 export interface SceneKindObject {

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/hudScale.d.ts

@@ -37,7 +37,22 @@ export interface HudOverflow {
 }
 /** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
 export declare function rectOverflow(rect: HudRect, viewport: HudSize, tolerance?: number): Omit<HudOverflow, "id"> | null;
-/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+/**
+ * True when at least `minVisiblePx²` of `rect` actually falls inside `viewport`.
+ * The boundary check uses this to tell a *shown* surface from a *closed* one: a
+ * mail drawer parked fully off-screen (or a menu that has not been opened) never
+ * intersects the viewport, so it is not "escaping" — it is simply not on screen.
+ * Only a surface that is partly visible and partly past an edge is a real defect.
+ *
+ * @internal Consumed transitively through {@link overflowingPanels}; exported for unit tests.
+ */
+export declare function rectIntersectsViewport(rect: HudRect, viewport: HudSize, minVisiblePx?: number): boolean;
+/**
+ * Every panel rect that escapes the viewport — the data behind the HUD overflow
+ * gate. A rect is only reported when it is partly visible *and* crosses an edge;
+ * a fully off-screen (closed/hidden) surface is skipped, so parked drawers and
+ * unopened menus never raise a false alarm.
+ */
 export declare function overflowingPanels(panels: readonly {
     id: string;
     rect: HudRect;

package/dist/ui/hudScale.js

@@ -43,10 +43,31 @@ export function rectOverflow(rect, viewport, tolerance = 1.5) {
     const round = (n) => Math.round(n * 10) / 10;
     return { left: round(left), top: round(top), right: round(right), bottom: round(bottom) };
 }
-/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+/**
+ * True when at least `minVisiblePx²` of `rect` actually falls inside `viewport`.
+ * The boundary check uses this to tell a *shown* surface from a *closed* one: a
+ * mail drawer parked fully off-screen (or a menu that has not been opened) never
+ * intersects the viewport, so it is not "escaping" — it is simply not on screen.
+ * Only a surface that is partly visible and partly past an edge is a real defect.
+ *
+ * @internal Consumed transitively through {@link overflowingPanels}; exported for unit tests.
+ */
+export function rectIntersectsViewport(rect, viewport, minVisiblePx = 1) {
+    const visibleWidth = Math.min(rect.x + rect.width, viewport.width) - Math.max(rect.x, 0);
+    const visibleHeight = Math.min(rect.y + rect.height, viewport.height) - Math.max(rect.y, 0);
+    return visibleWidth >= minVisiblePx && visibleHeight >= minVisiblePx;
+}
+/**
+ * Every panel rect that escapes the viewport — the data behind the HUD overflow
+ * gate. A rect is only reported when it is partly visible *and* crosses an edge;
+ * a fully off-screen (closed/hidden) surface is skipped, so parked drawers and
+ * unopened menus never raise a false alarm.
+ */
 export function overflowingPanels(panels, viewport, tolerance = 1.5) {
     const out = [];
     for (const panel of panels) {
+        if (!rectIntersectsViewport(panel.rect, viewport))
+            continue;
         const overflow = rectOverflow(panel.rect, viewport, tolerance);
         if (overflow !== null)
             out.push({ id: panel.id, ...overflow });

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[];

package/dist/ui/panelModel.js

@@ -0,0 +1,168 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function createPanelState(defs) {
+    const meta = {};
+    for (const def of defs) {
+        const entry = {};
+        if (def.group !== undefined)
+            entry.group = def.group;
+        if (def.closable !== undefined)
+            entry.closable = def.closable;
+        meta[def.id] = entry;
+    }
+    let state = { open: {}, z: {}, pos: {}, meta, nextZ: 1 };
+    for (const def of defs) {
+        if (def.initial === true)
+            state = openPanel(state, def.id);
+    }
+    return state;
+}
+/** Whether panel `id` is currently open. */
+export function isOpen(state, id) {
+    return state.open[id] === true;
+}
+/** @internal Whether panel `id` may be closed by the player (default true). */
+function isClosable(state, id) {
+    return state.meta[id]?.closable !== false;
+}
+/**
+ * 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 function openPanel(state, id) {
+    const group = state.meta[id]?.group;
+    const open = { ...state.open };
+    const z = { ...state.z };
+    let nextZ = state.nextZ;
+    if (group !== undefined) {
+        for (const otherId of Object.keys(open)) {
+            if (otherId !== id && state.meta[otherId]?.group === group) {
+                delete open[otherId];
+                delete z[otherId];
+            }
+        }
+    }
+    open[id] = true;
+    z[id] = nextZ++;
+    return { ...state, open, z, nextZ };
+}
+/**
+ * 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 function closePanel(state, id) {
+    if (state.open[id] !== true)
+        return state;
+    const open = { ...state.open };
+    const z = { ...state.z };
+    delete open[id];
+    delete z[id];
+    return { ...state, open, z };
+}
+/**
+ * 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 function togglePanel(state, id) {
+    return isOpen(state, id) ? closePanel(state, id) : openPanel(state, id);
+}
+/**
+ * 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 function focusPanel(state, id) {
+    if (state.open[id] !== true)
+        return state;
+    if (topPanel(state) === id)
+        return state;
+    return { ...state, z: { ...state.z, [id]: state.nextZ }, nextZ: state.nextZ + 1 };
+}
+/** @internal The id of the top (highest-z) open panel, or null when none are open. */
+function topPanel(state) {
+    let top = null;
+    let topZ = -Infinity;
+    for (const id of Object.keys(state.open)) {
+        const value = state.z[id] ?? 0;
+        if (value > topZ) {
+            topZ = value;
+            top = id;
+        }
+    }
+    return top;
+}
+/**
+ * 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 function closeTopPanel(state) {
+    const ordered = orderedOpenIds(state);
+    for (let i = ordered.length - 1; i >= 0; i--) {
+        const id = ordered[i];
+        if (isClosable(state, id))
+            return closePanel(state, id);
+    }
+    return state;
+}
+/** @internal Open panel ids sorted ascending by z (render order — last is on top). */
+function orderedOpenIds(state) {
+    return Object.keys(state.open).sort((a, b) => (state.z[a] ?? 0) - (state.z[b] ?? 0));
+}
+/**
+ * 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 function panelByHotkey(defs, code) {
+    const needle = code.toLowerCase();
+    for (const def of defs) {
+        if (def.hotkey !== undefined && def.hotkey.toLowerCase() === needle)
+            return def.id;
+    }
+    return 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 function movePanel(state, id, pos) {
+    return { ...state, pos: { ...state.pos, [id]: { x: pos.x, y: pos.y } } };
+}
+/**
+ * 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 function orderedOpen(state, defs) {
+    return defs
+        .filter((def) => state.open[def.id] === true)
+        .sort((a, b) => (state.z[a.id] ?? 0) - (state.z[b.id] ?? 0));
+}

package/dist/ui.d.ts

@@ -10,6 +10,7 @@ export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPan
 export { HUD_ANCHOR_FRACTIONS, type HudAnchor, type HudLayoutStore, type HudPlacement, type HudSize, } from "./ui/hudLayout.js";
 export { hudScaleForViewport, overflowingPanels, resolveHudFit, type HudPlatform, type HudViewportConfig, } from "./ui/hudScale.js";
 export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, type LayoutOrientation, } from "./ui/orientation.js";
+export { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen, movePanel, openPanel, orderedOpen, panelByHotkey, togglePanel, type PanelDef, type PanelPosition, type PanelState, } from "./ui/panelModel.js";
 export { moveSelectionFocus, selectionWindow, summarizeSelection, type EntitySummaryDef, type EntityVital, type SelectionFocusDirection, type SelectionGroup, type SelectionView, type SelectionWindow, type SummarizeSelectionOptions, } from "./ui/selectionModel.js";
 export { swingTimerState, type SwingTargetInput } from "./ui/swingTimer.js";
 export { actionTooltip, placePopover, type PopoverOptions, type PopoverPlacement, type PopoverSide, type TooltipContent, type UiRect, type UiSize, } from "./ui/tooltipModel.js";

package/dist/ui.js

@@ -10,6 +10,7 @@ export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPan
 export { HUD_ANCHOR_FRACTIONS, } from "./ui/hudLayout.js";
 export { hudScaleForViewport, overflowingPanels, resolveHudFit, } from "./ui/hudScale.js";
 export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "./ui/orientation.js";
+export { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen, movePanel, openPanel, orderedOpen, panelByHotkey, togglePanel, } from "./ui/panelModel.js";
 export { moveSelectionFocus, selectionWindow, summarizeSelection, } from "./ui/selectionModel.js";
 export { swingTimerState } from "./ui/swingTimer.js";
 export { actionTooltip, placePopover, } from "./ui/tooltipModel.js";

package/dist/world/buildingLots.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Street-aware building placement: derive building LOTS along ROAD FRONTAGE. Given road segments
+ * (centerline + width) and a district area, walk each road by arc length and emit lots on both
+ * sides at a consistent setback — a curb + sidewalk strip — with each lot carrying the yaw that
+ * makes the building FRONT face its road. Unlike `cityBlocks` (which needs a CLOSED street network
+ * to extract planar block faces), this works on a sparse set of segments — the common authoring
+ * case — so buildings line the streets instead of scattering on plinths around a center point.
+ *
+ * Pure seeded math over `cityGeometry` `Vec2` primitives: no rendering, deterministic from the
+ * inputs, bounded by `maxLots`.
+ *
+ * @capability world-environment lots aligned to and facing road frontage, with a setback sidewalk strip
+ */
+import type { Vec2 } from "./cityGeometry.js";
+import type { WorldBounds } from "./features.js";
+/** One road the frontage placer lines with buildings: a centerline polyline and its full width. */
+export interface RoadFrontage {
+    /** Road centerline vertices in world XZ; at least two points. */
+    path: readonly Vec2[];
+    /** Road full width in world units; lots set back from `width / 2`. */
+    width: number;
+}
+/** Rectangular clip region lots must fall within (world center + half-extents). */
+export interface LotArea {
+    /** World-space center of the region; default `[0, 0]`. */
+    center?: Vec2;
+    /** Half-extents along world x and z. */
+    halfExtents: Vec2;
+}
+/** Options for {@link deriveBuildingLots}. */
+export interface BuildingLotOptions {
+    /** Roads whose frontage is lined with lots. */
+    roads: readonly RoadFrontage[];
+    /** Lot footprint: `w` is frontage width (along the road), `d` is depth (into the block). Default `{ w: 12, d: 10 }`. */
+    footprint?: WorldBounds;
+    /** Gap between neighbouring lots along a frontage, world units. Default 2. */
+    spacing?: number;
+    /** Sidewalk strip between the curb (`width / 2`) and the building front, world units. Default 3. */
+    setback?: number;
+    /** Place lots on both sides of each road. Default true. */
+    bothSides?: boolean;
+    /** Clip region; lots whose center falls outside are dropped. Omit to keep every lot. */
+    area?: LotArea;
+    /**
+     * Seed forwarded by callers for parity with other feature configs. Lot GEOMETRY is fully
+     * determined by the roads and dials (so a layout is identical without it); per-building variation
+     * (floors, massing) is seeded downstream where the lots become buildings.
+     */
+    seed?: string;
+    /** Hard cap on emitted lots so a long network stays bounded. Default 400. */
+    maxLots?: number;
+}
+/** One placed building lot: where a building stands and how it is turned to face its road. */
+export interface PlacedBuildingLot {
+    /** Lot (building footprint) center in world XZ. */
+    center: Vec2;
+    /** Building yaw (radians) so its FRONT (+z local face) points at the road. */
+    rotationY: number;
+    /** Footprint of the lot: `w` along the frontage, `d` into the block. */
+    footprint: WorldBounds;
+    /** Index into the input `roads`. */
+    road: number;
+    /** Which side of the road: +1 = left normal, -1 = right normal. */
+    side: 1 | -1;
+    /** Distance from the lot's front face to the road centerline (= `width / 2 + setback`). */
+    frontDistance: number;
+}
+/**
+ * Yaw that turns the building FRONT (local +z) to face the road. The lot center sits at
+ * `roadPoint + outwardNormal * d`, so the road lies along `-outwardNormal` from the center. In the
+ * engine's Y-rotation convention a local +z of `(0, 1)` maps to world `(sin y, cos y)`; setting
+ * that equal to `-outwardNormal` gives `y = atan2(-nx, -nz)`.
+ * @internal
+ */
+export declare function facingRotation(outwardNormal: Vec2): number;
+/**
+ * Derive street-aligned building lots from road frontage. Lots are stepped along each road at
+ * `footprint.w + spacing`, offset to each side by `width / 2 + setback + footprint.d / 2`, and
+ * turned to face the road. Cross-road overlaps are rejected by a bounded nearest-neighbour test, so
+ * two roads meeting at a corner don't stack buildings. Deterministic: identical inputs (including
+ * seed) always yield the identical list.
+ * @capability building-lots derive street-facing building lots from road frontage
+ */
+export declare function deriveBuildingLots(options: BuildingLotOptions): PlacedBuildingLot[];