@jgengine/core 0.10.0 → 0.12.0

package/dist/work/unitTraining.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Thin unit-training composition over the generic {@link WorkQueueConfig}. Turns a
+ * catalog of trainable units into a queue config whose reservation is the unit's
+ * cost/population, whose duration is its train time, and whose completion output is
+ * a plain spawn descriptor. The queue never spawns or moves anything: routing the
+ * descriptor to a spawn primitive (and rally movement) is the caller's completion
+ * adapter, keeping this genre-agnostic across RTS producers, respawn bays, and any
+ * "make one of X after T seconds" flow.
+ */
+import type { JobValidation, WorkQueueConfig, WorkQueueState } from "./jobQueue.js";
+/** Resource costs keyed by currency/resource id. */
+export type ResourceCost = Readonly<Record<string, number>>;
+/** A unit the producer can train. */
+export interface TrainableUnitDef {
+    /** Catalog id of the produced unit. */
+    readonly id: string;
+    /** Seconds to train. */
+    readonly trainSeconds: number;
+    /** Resources reserved at enqueue. */
+    readonly cost?: ResourceCost;
+    /** Population/supply reserved at enqueue. */
+    readonly population?: number;
+}
+/** What the caller asks the queue to build. */
+export interface UnitTrainingSpec {
+    readonly unitId: string;
+}
+/** Reservation stored on a training job — the inputs to charge and refund. */
+export interface UnitReservation {
+    readonly cost: ResourceCost;
+    readonly population: number;
+}
+/** Completion payload: everything a spawn/rally adapter needs, and nothing it doesn't. */
+export interface UnitSpawnOrder {
+    readonly unitId: string;
+    readonly reservation: UnitReservation;
+}
+/** Config knobs for {@link unitTrainingConfig}. */
+export interface UnitTrainingOptions {
+    /** Trainable units by id. */
+    readonly units: Record<string, TrainableUnitDef>;
+    /** Producers building at once (default 1 — a classic single build queue). */
+    readonly concurrency?: number;
+    /** Max queued+building units. */
+    readonly capacity?: number;
+    /** Refund fraction of cost on cancel (0 = none, 1 = full). Defaults to 1. */
+    readonly refundFraction?: number;
+    /** Extra pre-enqueue gate (affordability, tech, population cap). */
+    readonly canEnqueue?: (spec: UnitTrainingSpec, state: WorkQueueState<UnitTrainingSpec, UnitReservation>) => JobValidation;
+}
+/**
+ * Build a {@link WorkQueueConfig} for training units from a catalog. Reservation is
+ * the unit's cost + population; duration is its train time; completion output is a
+ * {@link UnitSpawnOrder} for the caller to route to its spawn primitive.
+ *
+ * @capability unit-training compose a timed work queue that trains catalog units into spawn orders
+ */
+export declare function unitTrainingConfig(options: UnitTrainingOptions): WorkQueueConfig<UnitTrainingSpec, UnitReservation, UnitSpawnOrder>;

package/dist/work/unitTraining.js

@@ -0,0 +1,52 @@
+/**
+ * Thin unit-training composition over the generic {@link WorkQueueConfig}. Turns a
+ * catalog of trainable units into a queue config whose reservation is the unit's
+ * cost/population, whose duration is its train time, and whose completion output is
+ * a plain spawn descriptor. The queue never spawns or moves anything: routing the
+ * descriptor to a spawn primitive (and rally movement) is the caller's completion
+ * adapter, keeping this genre-agnostic across RTS producers, respawn bays, and any
+ * "make one of X after T seconds" flow.
+ */
+function scaleCost(cost, fraction) {
+    if (fraction >= 1)
+        return cost;
+    if (fraction <= 0)
+        return {};
+    const out = {};
+    for (const [resource, amount] of Object.entries(cost))
+        out[resource] = Math.floor(amount * fraction);
+    return out;
+}
+/**
+ * Build a {@link WorkQueueConfig} for training units from a catalog. Reservation is
+ * the unit's cost + population; duration is its train time; completion output is a
+ * {@link UnitSpawnOrder} for the caller to route to its spawn primitive.
+ *
+ * @capability unit-training compose a timed work queue that trains catalog units into spawn orders
+ */
+export function unitTrainingConfig(options) {
+    const refundFraction = options.refundFraction ?? 1;
+    const unitFor = (unitId) => options.units[unitId];
+    return {
+        concurrency: options.concurrency,
+        capacity: options.capacity,
+        duration: (spec) => Math.max(0, unitFor(spec.unitId)?.trainSeconds ?? 0),
+        reserve: (spec) => {
+            const def = unitFor(spec.unitId);
+            return { cost: def?.cost ?? {}, population: def?.population ?? 0 };
+        },
+        validate: (spec, state) => {
+            if (unitFor(spec.unitId) === undefined)
+                return { ok: false, reason: "unknown-unit" };
+            return options.canEnqueue?.(spec, state) ?? { ok: true };
+        },
+        output: (job) => ({
+            unitId: job.spec.unitId,
+            reservation: job.reservation,
+        }),
+        refund: (job) => ({
+            cost: scaleCost(job.reservation.cost, refundFraction),
+            population: job.reservation.population,
+        }),
+    };
+}

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

@@ -0,0 +1,72 @@
+import type { SceneMarkerLike } from "./sceneShapes.js";
+/**
+ * One authored catalog prop resolved from an editor marker — grounded at `x`/`z` with yaw, ready
+ * for `ctx.scene.object.place` or {@link placeAuthoredObjects}.
+ */
+export interface AuthoredObject {
+    catalogId: string;
+    x: number;
+    z: number;
+    rotationY: number;
+    instanceId: string;
+    /** Extra lift in meters from the marker (`catalogId` field / meta), applied on top of terrain height. */
+    verticalOffset: number;
+}
+/** Minimal marker shape {@link resolveAuthoredObjects} reads; any `EditorMarker` satisfies it. */
+export interface AuthoredObjectMarkerLike extends SceneMarkerLike {
+    catalogId?: string;
+    rotationY?: number;
+}
+/** Minimal document shape {@link resolveAuthoredObjects} walks; any `EditorDocument` satisfies it. */
+export interface AuthoredObjectsDocumentLike {
+    markers: readonly AuthoredObjectMarkerLike[];
+}
+/** Structural place target — any `ObjectStore` satisfies it. */
+export interface AuthoredObjectPlaceTarget {
+    place(catalogId: string, x: number, y: number, z: number, options?: {
+        instanceId?: string;
+        rotation?: number;
+        onExisting?: "throw" | "replace" | "keep";
+    }): string;
+}
+/** Options for {@link placeAuthoredObjects}. */
+export interface PlaceAuthoredObjectsOptions {
+    /** Extra lift in meters applied to every placement after terrain height + per-object offset. */
+    verticalOffset?: number;
+    /** How to treat instance ids already in the store. Default `"throw"` (ObjectStore default). */
+    onExisting?: "throw" | "replace" | "keep";
+}
+/**
+ * Catalog id for a marker: first-class `catalogId` field, else `meta.catalogId` migration alias.
+ * Returns null when the marker is not an authored catalog prop (spawn, mob, generator, …).
+ * @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, 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).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export declare function placeAuthoredObjects(store: AuthoredObjectPlaceTarget, objects: readonly AuthoredObject[], sampleHeight: (x: number, z: number) => number, options?: PlaceAuthoredObjectsOptions): string[];
+/** Convenience: resolve a document then place every authored catalog prop. */
+export declare function placeAuthoredObjectsFromDocument(store: AuthoredObjectPlaceTarget, document: AuthoredObjectsDocumentLike, sampleHeight: (x: number, z: number) => number, options?: PlaceAuthoredObjectsOptions): string[];

package/dist/world/authoredObjects.js

@@ -0,0 +1,81 @@
+function metaString(meta, key) {
+    const value = meta?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function metaNumber(meta, key) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Catalog id for a marker: first-class `catalogId` field, else `meta.catalogId` migration alias.
+ * Returns null when the marker is not an authored catalog prop (spawn, mob, generator, …).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function markerCatalogId(marker) {
+    if (typeof marker.catalogId === "string" && marker.catalogId.length > 0)
+        return marker.catalogId;
+    return metaString(marker.meta, "catalogId");
+}
+function markerVerticalOffset(marker) {
+    const fromMeta = metaNumber(marker.meta, "verticalOffset") ??
+        metaNumber(marker.meta, "offsetY") ??
+        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, 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;
+        out.push({
+            catalogId,
+            x: marker.position.x,
+            z: marker.position.z,
+            rotationY: marker.rotationY ?? 0,
+            instanceId: marker.id,
+            verticalOffset: markerVerticalOffset(marker),
+        });
+    }
+    return out;
+}
+/**
+ * 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).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function placeAuthoredObjects(store, objects, sampleHeight, options = {}) {
+    const lift = options.verticalOffset ?? 0;
+    const onExisting = options.onExisting;
+    const ids = [];
+    for (const object of objects) {
+        const y = sampleHeight(object.x, object.z) + object.verticalOffset + lift;
+        ids.push(store.place(object.catalogId, object.x, y, object.z, {
+            instanceId: object.instanceId,
+            rotation: object.rotationY,
+            ...(onExisting === undefined ? {} : { onExisting }),
+        }));
+    }
+    return ids;
+}
+/** Convenience: resolve a document then place every authored catalog prop. */
+export function placeAuthoredObjectsFromDocument(store, document, sampleHeight, options = {}) {
+    return placeAuthoredObjects(store, resolveAuthoredObjects(document), sampleHeight, options);
+}

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;