@jgengine/core 0.11.0 → 0.13.0

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

@@ -0,0 +1,29 @@
+import { ENTITY_MARKER_KINDS, type AuthoredObjectMarkerLike } from "./authoredObjects.js";
+/** Marker kinds {@link authoredEntitySpawns} treats as spawnable entities by default. Re-exported from `authoredObjects` as the single source of truth (the same kinds `resolveAuthoredObjects` skips). */
+export { ENTITY_MARKER_KINDS };
+/** The minimal marker shape entity spawns read; any `EditorMarker` satisfies it. */
+export type AuthoredEntityMarkerLike = AuthoredObjectMarkerLike;
+/** The minimal document shape {@link authoredEntitySpawns} walks; any `EditorDocument` satisfies it. */
+export interface AuthoredEntityDocumentLike {
+    markers: readonly AuthoredEntityMarkerLike[];
+}
+/** One resolved entity to spawn from the authored scene — its marker id, catalog id, and pose. */
+export interface AuthoredEntitySpawn {
+    /** The marker's id — a stable spawn id, so re-spawning the same marker is idempotent. */
+    markerId: string;
+    /** The entity catalog id to spawn (join key into `content.entityById`). */
+    catalogId: string;
+    /** World-space spawn position as a spawn-ready `[x, y, z]` tuple. */
+    position: [number, number, number];
+    /** Facing (yaw radians), 0 when the marker has none. */
+    rotationY: number;
+}
+/**
+ * Every authored entity marker (`mob`/`boss` by default) that carries a `catalogId`, as a spawn plan
+ * the runtime feeds to `ctx.scene.entity.spawn(catalogId, { id, position })`. Reads the same document
+ * the editor authors, so placing a mob and setting its catalog id in the editor is all it takes to
+ * spawn it — no coordinates or spawn tables copied into game code. Markers without a catalog id are
+ * skipped (they are placement-only, e.g. a boss arena marker a game handles specially).
+ * @capability authored-entities spawn authored mob/boss markers from the editor document at runtime
+ */
+export declare function authoredEntitySpawns(document: AuthoredEntityDocumentLike, kinds?: readonly string[]): AuthoredEntitySpawn[];

package/dist/world/authoredEntities.js

@@ -0,0 +1,29 @@
+import { ENTITY_MARKER_KINDS, markerCatalogId } from "./authoredObjects.js";
+/** Marker kinds {@link authoredEntitySpawns} treats as spawnable entities by default. Re-exported from `authoredObjects` as the single source of truth (the same kinds `resolveAuthoredObjects` skips). */
+export { ENTITY_MARKER_KINDS };
+/**
+ * Every authored entity marker (`mob`/`boss` by default) that carries a `catalogId`, as a spawn plan
+ * the runtime feeds to `ctx.scene.entity.spawn(catalogId, { id, position })`. Reads the same document
+ * the editor authors, so placing a mob and setting its catalog id in the editor is all it takes to
+ * spawn it — no coordinates or spawn tables copied into game code. Markers without a catalog id are
+ * skipped (they are placement-only, e.g. a boss arena marker a game handles specially).
+ * @capability authored-entities spawn authored mob/boss markers from the editor document at runtime
+ */
+export function authoredEntitySpawns(document, kinds = ENTITY_MARKER_KINDS) {
+    const wanted = new Set(kinds);
+    const spawns = [];
+    for (const marker of document.markers) {
+        if (!wanted.has(marker.kind))
+            continue;
+        const catalogId = markerCatalogId(marker);
+        if (catalogId === null)
+            continue;
+        spawns.push({
+            markerId: marker.id,
+            catalogId,
+            position: [marker.position.x, marker.position.y, marker.position.z],
+            rotationY: marker.rotationY ?? 0,
+        });
+    }
+    return spawns;
+}

package/dist/world/authoredObjects.d.ts

@@ -42,12 +42,26 @@ export interface PlaceAuthoredObjectsOptions {
  * @capability authored-objects place catalog mesh props from an editor document
  */
 export declare function markerCatalogId(marker: AuthoredObjectMarkerLike): string | null;
+/**
+ * Marker kinds that are spawnable entities (materialized by `authoredEntitySpawns`), not static
+ * catalog props. {@link resolveAuthoredObjects} skips them by default so a placed `mob`/`boss` is
+ * spawned once as an entity and never also placed as a static mesh.
+ * @capability authored-objects marker kinds resolved as entity spawns, not static props
+ */
+export declare const ENTITY_MARKER_KINDS: readonly string[];
+/** Options for {@link resolveAuthoredObjects}. */
+export interface ResolveAuthoredObjectsOptions {
+    /** Marker kinds to skip (they are handled elsewhere). Default {@link ENTITY_MARKER_KINDS}. */
+    excludeKinds?: readonly string[];
+}
 /**
  * Every marker carrying a catalog id, as placeable props — pure, no terrain sample. Parallel to
  * {@link resolveScatter}: games and headless tests read the same list `<AuthoredObjects>` places.
+ * Entity-spawn kinds (`mob`/`boss`) are skipped by default — they carry a `catalogId` for their
+ * entity definition, but are spawned via `authoredEntitySpawns`, not placed as static meshes.
  * @capability authored-objects place catalog mesh props from an editor document
  */
-export declare function resolveAuthoredObjects(document: AuthoredObjectsDocumentLike): AuthoredObject[];
+export declare function resolveAuthoredObjects(document: AuthoredObjectsDocumentLike, options?: ResolveAuthoredObjectsOptions): AuthoredObject[];
 /**
  * Places resolved authored objects into an object store, grounding each on `sampleHeight(x,z)` plus
  * per-object and options vertical offsets. Returns the instance ids that were placed (or kept).

package/dist/world/authoredObjects.js

@@ -22,14 +22,26 @@ function markerVerticalOffset(marker) {
         metaNumber(marker.meta, "yOffset");
     return fromMeta ?? 0;
 }
+/**
+ * Marker kinds that are spawnable entities (materialized by `authoredEntitySpawns`), not static
+ * catalog props. {@link resolveAuthoredObjects} skips them by default so a placed `mob`/`boss` is
+ * spawned once as an entity and never also placed as a static mesh.
+ * @capability authored-objects marker kinds resolved as entity spawns, not static props
+ */
+export const ENTITY_MARKER_KINDS = ["mob", "boss"];
 /**
  * Every marker carrying a catalog id, as placeable props — pure, no terrain sample. Parallel to
  * {@link resolveScatter}: games and headless tests read the same list `<AuthoredObjects>` places.
+ * Entity-spawn kinds (`mob`/`boss`) are skipped by default — they carry a `catalogId` for their
+ * entity definition, but are spawned via `authoredEntitySpawns`, not placed as static meshes.
  * @capability authored-objects place catalog mesh props from an editor document
  */
-export function resolveAuthoredObjects(document) {
+export function resolveAuthoredObjects(document, options = {}) {
+    const excluded = new Set(options.excludeKinds ?? ENTITY_MARKER_KINDS);
     const out = [];
     for (const marker of document.markers) {
+        if (excluded.has(marker.kind))
+            continue;
         const catalogId = markerCatalogId(marker);
         if (catalogId === null)
             continue;

package/dist/world/authoredSpawn.d.ts

@@ -0,0 +1,39 @@
+import type { SceneMarkerLike } from "./sceneShapes.js";
+/** Minimal marker shape spawn queries read; any `EditorMarker` satisfies it. */
+export interface AuthoredSpawnMarkerLike extends SceneMarkerLike {
+    rotationY?: number;
+}
+/** Minimal document shape spawn queries walk; any `EditorDocument` satisfies it. */
+export interface AuthoredSpawnDocumentLike {
+    markers: readonly AuthoredSpawnMarkerLike[];
+}
+/** Marker kind {@link authoredSpawnPosition} resolves by default. */
+export declare const PLAYER_SPAWN_KIND = "player_spawn";
+/**
+ * Every marker of `kind`, in document order — the generic query behind gameplay that references
+ * authored markers by kind instead of copying coordinates into code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export declare function markersOfKind<TMarker extends AuthoredSpawnMarkerLike>(document: {
+    markers: readonly TMarker[];
+}, kind: string): TMarker[];
+/** Options for {@link authoredSpawnPosition}: pick a specific marker id or a non-default kind. */
+export interface AuthoredSpawnOptions {
+    /** Marker kind to resolve. Default {@link PLAYER_SPAWN_KIND}. */
+    kind?: string;
+    /** Exact marker id; when set, kind only filters among markers with this id's kind. */
+    id?: string;
+}
+/**
+ * Position of the authored spawn marker as a spawn-ready `[x, y, z]` tuple, or null when the
+ * document has none. Reads the first `player_spawn` marker by default, so dragging the marker in
+ * the editor moves where players spawn — no coordinates copied into game code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export declare function authoredSpawnPosition(document: AuthoredSpawnDocumentLike, options?: AuthoredSpawnOptions): [number, number, number] | null;
+/**
+ * Facing (yaw radians) of the authored spawn marker, or 0 when the document has none — pair with
+ * {@link authoredSpawnPosition} to spawn players where and how the editor placed them.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export declare function authoredSpawnRotation(document: AuthoredSpawnDocumentLike, options?: AuthoredSpawnOptions): number;

package/dist/world/authoredSpawn.js

@@ -0,0 +1,37 @@
+/** Marker kind {@link authoredSpawnPosition} resolves by default. */
+export const PLAYER_SPAWN_KIND = "player_spawn";
+/**
+ * Every marker of `kind`, in document order — the generic query behind gameplay that references
+ * authored markers by kind instead of copying coordinates into code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export function markersOfKind(document, kind) {
+    return document.markers.filter((marker) => marker.kind === kind);
+}
+/**
+ * Position of the authored spawn marker as a spawn-ready `[x, y, z]` tuple, or null when the
+ * document has none. Reads the first `player_spawn` marker by default, so dragging the marker in
+ * the editor moves where players spawn — no coordinates copied into game code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export function authoredSpawnPosition(document, options = {}) {
+    const kind = options.kind ?? PLAYER_SPAWN_KIND;
+    const marker = options.id === undefined
+        ? document.markers.find((entry) => entry.kind === kind)
+        : document.markers.find((entry) => entry.id === options.id && entry.kind === kind);
+    if (marker === undefined)
+        return null;
+    return [marker.position.x, marker.position.y, marker.position.z];
+}
+/**
+ * Facing (yaw radians) of the authored spawn marker, or 0 when the document has none — pair with
+ * {@link authoredSpawnPosition} to spawn players where and how the editor placed them.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export function authoredSpawnRotation(document, options = {}) {
+    const kind = options.kind ?? PLAYER_SPAWN_KIND;
+    const marker = options.id === undefined
+        ? document.markers.find((entry) => entry.kind === kind)
+        : document.markers.find((entry) => entry.id === options.id && entry.kind === kind);
+    return marker?.rotationY ?? 0;
+}

package/dist/world/buildSockets.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Data-driven modular build-piece snap system: a catalog of piece types, each declaring named
+ * sockets (local position + outward facing + a generic "kind"), plus a connection-rule table saying
+ * which socket kinds may mate. Given a placed piece and a candidate type it resolves every valid
+ * snap — the world transform that lands the candidate's socket exactly on the placed piece's socket,
+ * facing back into it. Genre-agnostic: foundation/wall/ceiling/pillar/edge snapping falls out of the
+ * catalog data, with no game-specific piece names baked in. Pure and serializable; composes with
+ * `world/footprintGrid` occupancy (via an injected `isFree` predicate — never imported) and with
+ * `scene/modelSockets` named attach points (via {@link pieceSocketsFromModel}).
+ */
+/** A local- or world-space position/offset, matching the `[x, y, z]` triple used across core. */
+export type SocketVec3 = readonly [number, number, number];
+/** One named socket on a piece: where it sits and which horizontal direction it faces (yaw about Y). */
+export interface SocketDef {
+    /** Stable socket name, unique within its piece. */
+    name: string;
+    /** Generic connection kind — e.g. "top", "bottom", "edge", "side". Matched by the rule table. */
+    kind: string;
+    /** Local offset from the piece origin. */
+    position: SocketVec3;
+    /** Outward-facing yaw in radians (rotation about +Y), local to the piece. Default `0`. */
+    yaw?: number;
+}
+/** A rectangular footprint (world units) a piece occupies on the build grid — the occupancy bridge. */
+export interface BuildFootprint {
+    w: number;
+    d: number;
+}
+/** A registered piece type: its named sockets and, optionally, the footprint it claims when placed. */
+export interface BuildPieceDef {
+    /** Stable piece-type id, unique within the catalog. */
+    type: string;
+    sockets: readonly SocketDef[];
+    /** Grid footprint for occupancy checks; omit for pieces that don't reserve cells. */
+    footprint?: BuildFootprint;
+}
+/** Declares that two socket kinds may snap together; `mutual` (default `true`) also allows `b`→`a`. */
+export interface ConnectionRule {
+    a: string;
+    b: string;
+    /** When `false` the rule is directional: an `a`-kind candidate socket may mate onto a `b`-kind placed socket, but not the reverse. */
+    mutual?: boolean;
+}
+/** World transform of a placed piece: position plus a yaw about +Y. */
+export interface PieceTransform {
+    position: SocketVec3;
+    /** Rotation about +Y in radians. Default `0`. */
+    yaw?: number;
+}
+/** An already-placed piece the resolver snaps candidates against. */
+export interface PlacedPiece {
+    type: string;
+    transform: PieceTransform;
+}
+/** A piece's socket resolved into world space. */
+export interface PlacedSocket {
+    name: string;
+    kind: string;
+    /** World-space socket position. */
+    position: SocketVec3;
+    /** World-space outward facing yaw (radians). */
+    yaw: number;
+}
+/** One integer grid cell — structurally the `GridCell` of `world/footprintGrid` (no import needed). */
+export interface BuildCell {
+    col: number;
+    row: number;
+}
+/** A resolved snap: which sockets mate and the world transform that lands the candidate onto the target. */
+export interface SnapCandidate {
+    candidateType: string;
+    /** Name of the socket on the already-placed piece. */
+    targetSocket: string;
+    /** Name of the candidate's socket that mates onto it. */
+    candidateSocket: string;
+    /** Where to place the candidate so its socket aligns onto the target socket. */
+    transform: {
+        position: SocketVec3;
+        yaw: number;
+    };
+    /** Shared world position of the mated sockets. */
+    point: SocketVec3;
+    /** Distance from the resolve `cursor` to `point`, or `0` when no cursor was given. */
+    distance: number;
+}
+/** Options for {@link BuildSocketCatalog.resolveSnaps}. */
+export interface ResolveSnapsOptions {
+    /** Cursor point; when given, candidates are ordered nearest-first by mate-point distance. */
+    cursor?: SocketVec3;
+    /**
+     * Occupancy predicate — return `false` to reject a snap whose target cells are taken. Only applied
+     * to candidate pieces that declare a `footprint`. Compose with `world/footprintGrid` via
+     * `(cell) => grid.isFree([cell])`; the catalog never imports the grid.
+     */
+    isFree?: (cell: BuildCell) => boolean;
+}
+/** Serializable catalog config; also the shape returned by {@link BuildSocketCatalog.toJSON}. */
+export interface BuildSocketCatalogConfig {
+    pieces: readonly BuildPieceDef[];
+    rules: readonly ConnectionRule[];
+    /** World units per grid cell for footprint occupancy. Default `1`. */
+    cellSize?: number;
+}
+/** Handle returned by {@link createBuildSocketCatalog}. */
+export interface BuildSocketCatalog {
+    readonly cellSize: number;
+    has(type: string): boolean;
+    piece(type: string): BuildPieceDef | null;
+    /** Registered piece-type ids, in declaration order. */
+    types(): readonly string[];
+    /** True when a `candidateKind` socket may mate onto a `placedKind` socket. */
+    canConnect(candidateKind: string, placedKind: string): boolean;
+    /** Every socket of `placed` resolved into world space. */
+    worldSockets(placed: PlacedPiece): PlacedSocket[];
+    /** Every valid snap of `candidateType` onto `placed`, ordered deterministically. */
+    resolveSnaps(placed: PlacedPiece, candidateType: string, options?: ResolveSnapsOptions): SnapCandidate[];
+    /** Plain, serializable snapshot — feed straight back into {@link createBuildSocketCatalog}. */
+    toJSON(): BuildSocketCatalogConfig;
+}
+/**
+ * The grid cells a piece `footprint` centered on `position` (world units) covers, honoring `yaw`
+ * (snapped to the nearest quarter turn). Mirrors `world/footprintGrid`'s `cellsFor` so a game can
+ * feed the result straight into `grid.isFree`/`grid.reserve` after committing a resolved snap —
+ * without this module importing the grid.
+ *
+ * @capability build-footprint-cells grid cells a snapped build piece footprint covers (footprintGrid occupancy bridge)
+ */
+export declare function footprintCells(position: SocketVec3, footprint: BuildFootprint, yaw?: number, cellSize?: number): BuildCell[];
+/** A `{ name, offset }` attach point — structurally the `ModelSocket` of `scene/modelSockets`. */
+export interface ModelSocketLike {
+    name: string;
+    offset: SocketVec3;
+}
+/**
+ * Turn a model's named attach points (from `scene/modelSockets`' `readNamedSockets`) into
+ * {@link SocketDef}s, classifying each into a connection `kind` via `kindOf` and, optionally, an
+ * outward `yaw` via `yawOf`. Lets an artist author snap sockets as empties in a GLB instead of by
+ * hand in the catalog. Pure and structural — no three.js or scene import.
+ *
+ * @capability piece-sockets-from-model derive build-piece snap sockets from a model's named attach points
+ */
+export declare function pieceSocketsFromModel(sockets: readonly ModelSocketLike[], kindOf: (name: string) => string, yawOf?: (name: string) => number): SocketDef[];
+/**
+ * Build a modular snap catalog from piece definitions and a connection-rule table. Resolves the set
+ * of valid snap transforms when hovering a candidate piece near a placed one: for every compatible
+ * socket pair it computes the world transform that seats the candidate's socket onto the placed
+ * socket, oriented to face back into it. Deterministic ordering (nearest a cursor when given, else
+ * declaration order) and an optional occupancy predicate keep it drop-in for a build-mode controller.
+ *
+ * @capability build-socket-catalog data-driven named-socket snap catalog for modular base building
+ */
+export declare function createBuildSocketCatalog(config: BuildSocketCatalogConfig): BuildSocketCatalog;