@jgengine/core 0.9.0 → 0.11.0

package/dist/scene/assetDiagnostics.js

@@ -0,0 +1,110 @@
+/**
+ * Pure, zero-dependency classification of a model-asset fetch before it reaches
+ * a GLTF parser. Runtime loaders hand the raw response (status, content type,
+ * and the first bytes) to {@link classifyAssetResponse} so a missing or
+ * mis-served file surfaces as an actionable diagnostic naming the broken asset
+ * contract, instead of the opaque "Unexpected token < in JSON" parse error a
+ * dev-server HTML fallback otherwise produces. No `fetch`, DOM, or three.js
+ * dependency lives here — callers supply the already-read bytes.
+ */
+/** GLB little-endian magic — the ASCII "glTF" at byte 0 of a binary glTF container. @internal */
+export const GLB_MAGIC_ASCII = "glTF";
+function startsWithAscii(bytes, ascii) {
+    if (bytes.length < ascii.length)
+        return false;
+    for (let i = 0; i < ascii.length; i += 1) {
+        if (bytes[i] !== ascii.charCodeAt(i))
+            return false;
+    }
+    return true;
+}
+/** Skip a UTF-8 BOM and leading ASCII whitespace, returning the index of the first meaningful byte. */
+function firstNonBlank(bytes) {
+    let i = 0;
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        i = 3;
+    while (i < bytes.length) {
+        const b = bytes[i];
+        // space, tab, CR, LF
+        if (b === 0x20 || b === 0x09 || b === 0x0d || b === 0x0a)
+            i += 1;
+        else
+            break;
+    }
+    return i;
+}
+/**
+ * Classify the leading bytes of a response body by their format signature, with
+ * no HTTP context. Recognizes GLB (`glTF` magic), glTF-JSON (a leading `{`), an
+ * HTML fallback page (`<!doctype`, `<html`, or a bare `<`), and a few common
+ * non-model binaries (PNG, JPEG, ZIP) so they can be reported as unsupported
+ * rather than corrupt.
+ */
+export function readByteSignature(bytes) {
+    if (bytes.length === 0)
+        return "empty";
+    if (startsWithAscii(bytes, GLB_MAGIC_ASCII))
+        return "glb";
+    if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        return "png";
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "jpeg";
+    if (bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b && bytes[2] === 0x03 && bytes[3] === 0x04) {
+        return "zip";
+    }
+    const start = firstNonBlank(bytes);
+    const head = bytes[start];
+    if (head === undefined)
+        return "empty";
+    // '<' — an HTML document served where a model was expected.
+    if (head === 0x3c)
+        return "html";
+    // '{' — glTF-JSON (the non-binary .gltf form) is a parseable model.
+    if (head === 0x7b)
+        return "gltf-json";
+    return "unknown";
+}
+function describe(logicalId, url) {
+    return logicalId === undefined ? `"${url}"` : `"${logicalId}" (${url})`;
+}
+/**
+ * Turn a {@link AssetResponseProbe} into an {@link AssetLoadDiagnosis}. HTTP
+ * status is checked first (a `>= 400` or `0` status is `missing`), then the
+ * `Content-Type` and byte signature decide between an HTML fallback, a
+ * parseable model (`ok`), an unsupported-but-recognizable format, and otherwise
+ * corrupt bytes. The returned `message` always names the asset and URL and, for
+ * failures, points at the likely fix (provision the pack, check the serving path).
+ *
+ * @capability asset-load-diagnostics classify a model fetch (missing / HTML fallback / corrupt / unsupported) before parsing
+ */
+export function classifyAssetResponse(probe) {
+    const { url, logicalId, status, statusText, contentType, bytes } = probe;
+    const signature = bytes === undefined ? "empty" : readByteSignature(bytes);
+    const who = describe(logicalId, url);
+    const finish = (kind, message) => ({
+        kind,
+        ok: kind === "ok",
+        url,
+        ...(logicalId === undefined ? {} : { logicalId }),
+        byteSignature: signature,
+        message,
+    });
+    if (status !== undefined && (status === 0 || status >= 400)) {
+        const suffix = statusText === undefined || statusText.length === 0 ? "" : ` ${statusText}`;
+        return finish("missing", `Asset ${who} did not load: HTTP ${status}${suffix}. The file is not being served — provision the pack (e.g. \`assets pull <source>\`) or check the model path.`);
+    }
+    const htmlContentType = contentType !== undefined && contentType.toLowerCase().includes("text/html");
+    if (signature === "html" || (htmlContentType && signature !== "glb" && signature !== "gltf-json")) {
+        return finish("html", `Asset ${who} resolved to an HTML page, not a model — the dev server returned its fallback document because the file is missing. Provision the pack (\`assets pull <source>\`) so the bytes exist under the served path.`);
+    }
+    if (signature === "glb" || signature === "gltf-json")
+        return finish("ok", `Asset ${who} loaded (${signature}).`);
+    if (signature === "png" || signature === "jpeg" || signature === "zip") {
+        return finish("unsupported", `Asset ${who} is a ${signature} file, not a GLB/glTF model — the reference points at the wrong file or the wrong loader is being used.`);
+    }
+    if (signature === "empty") {
+        return finish("corrupt", `Asset ${who} returned an empty body — the file exists but has no bytes. Re-provision the pack or remove the reference.`);
+    }
+    return finish("corrupt", `Asset ${who} is not a recognizable GLB/glTF model (leading bytes do not match any known signature). The file is likely truncated or corrupt — re-provision the pack.`);
+}

package/dist/scene/assetGenerator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The generator-asset seam: register a parametric asset generator (`generate(params, seed) → parts`)
+ * so a slider-driven prop (a bookcase with width/shelves/book-density, a building with floors/bays)
+ * lives in the catalog alongside static GLBs. A placed instance stores only `{ assetId, params, seed }`
+ * — the geometry is re-resolved at runtime, never baked. Schema drives the inspector via #809. The
+ * generic seam is engine; concrete generators (building, bookcase) are adopters registered from
+ * game/example code — the building generator is the one engine adopter, as a proof it composes.
+ *
+ * @capability asset-generator seeded parametric geometry registered as a placeable asset
+ */
+import { type ParamSchema, type ParsedParams } from "./sceneKinds.js";
+/** One generated primitive part — a box/panel placed in the asset's local space. */
+export interface GeneratedPart {
+    id: string;
+    /** Optional semantic tag (shelf, board, book, wall, window …) for materials/inspection. */
+    kind?: string;
+    /** Local-space center. */
+    position: readonly [number, number, number];
+    /** Full box dimensions (w, h, d) in meters. */
+    size: readonly [number, number, number];
+    rotationY?: number;
+    /** Hex color; the renderer falls back to a neutral material when absent. */
+    color?: string;
+}
+/** A resolved generator asset: its parts plus the overall local-space bounds (min/max corners). */
+export interface GeneratedAsset {
+    parts: GeneratedPart[];
+    bounds: {
+        min: readonly [number, number, number];
+        max: readonly [number, number, number];
+    };
+    /**
+     * The declared local-space direction the asset's "front" faces (a bookcase's open/book face, a
+     * building's entrance) — so a camera rig or placement tool can orient it without hand-tuned
+     * `rotationY`. Omit to use the convention default, +Z (`DEFAULT_FORWARD` in `./facing`); every
+     * generator should build its front toward +Z unless it declares otherwise.
+     */
+    forward?: readonly [number, number, number];
+}
+/** A registered asset generator — schema drives the inspector; `generate` is a pure seeded function. */
+export interface AssetGeneratorDefinition {
+    id: string;
+    label: string;
+    schema: ParamSchema;
+    /** Deterministic geometry from validated params + a seed string. Same inputs → same parts. */
+    generate: (params: ParsedParams, seed: string) => GeneratedAsset;
+}
+/** Register a parametric asset generator. Idempotent per id (last wins); call at module load. */
+export declare function registerAssetGenerator(definition: AssetGeneratorDefinition): void;
+/** The registered generator for an id, or undefined. @internal */
+export declare function getAssetGenerator(id: string): AssetGeneratorDefinition | undefined;
+/** Every registered generator, in registration order. @internal */
+export declare function listAssetGenerators(): AssetGeneratorDefinition[];
+/**
+ * Compute bounds from parts (each part is an axis-aligned box at its center) — a helper generators
+ * return so callers can frame/ground the asset without re-deriving it.
+ */
+export declare function partsBounds(parts: readonly GeneratedPart[]): GeneratedAsset["bounds"];
+/**
+ * Re-resolve a placed generator instance from its stored `meta` (`{ assetId, seed, ...params }`): look
+ * up the generator, parse its params off `meta` against the schema, and generate. Returns null when
+ * `assetId` names no registered generator. This is what a runtime renderer calls per placed instance.
+ * @internal
+ */
+export declare function resolveGeneratorAsset(meta: Record<string, unknown> | undefined): GeneratedAsset | null;

package/dist/scene/assetGenerator.js

@@ -0,0 +1,64 @@
+/**
+ * The generator-asset seam: register a parametric asset generator (`generate(params, seed) → parts`)
+ * so a slider-driven prop (a bookcase with width/shelves/book-density, a building with floors/bays)
+ * lives in the catalog alongside static GLBs. A placed instance stores only `{ assetId, params, seed }`
+ * — the geometry is re-resolved at runtime, never baked. Schema drives the inspector via #809. The
+ * generic seam is engine; concrete generators (building, bookcase) are adopters registered from
+ * game/example code — the building generator is the one engine adopter, as a proof it composes.
+ *
+ * @capability asset-generator seeded parametric geometry registered as a placeable asset
+ */
+import { parseParams } from "./sceneKinds.js";
+const generators = new Map();
+/** Register a parametric asset generator. Idempotent per id (last wins); call at module load. */
+export function registerAssetGenerator(definition) {
+    generators.set(definition.id, definition);
+}
+/** The registered generator for an id, or undefined. @internal */
+export function getAssetGenerator(id) {
+    return generators.get(id);
+}
+/** Every registered generator, in registration order. @internal */
+export function listAssetGenerators() {
+    return [...generators.values()];
+}
+/**
+ * Compute bounds from parts (each part is an axis-aligned box at its center) — a helper generators
+ * return so callers can frame/ground the asset without re-deriving it.
+ */
+export function partsBounds(parts) {
+    if (parts.length === 0)
+        return { min: [0, 0, 0], max: [0, 0, 0] };
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (const part of parts) {
+        minX = Math.min(minX, part.position[0] - part.size[0] / 2);
+        minY = Math.min(minY, part.position[1] - part.size[1] / 2);
+        minZ = Math.min(minZ, part.position[2] - part.size[2] / 2);
+        maxX = Math.max(maxX, part.position[0] + part.size[0] / 2);
+        maxY = Math.max(maxY, part.position[1] + part.size[1] / 2);
+        maxZ = Math.max(maxZ, part.position[2] + part.size[2] / 2);
+    }
+    return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+}
+/**
+ * Re-resolve a placed generator instance from its stored `meta` (`{ assetId, seed, ...params }`): look
+ * up the generator, parse its params off `meta` against the schema, and generate. Returns null when
+ * `assetId` names no registered generator. This is what a runtime renderer calls per placed instance.
+ * @internal
+ */
+export function resolveGeneratorAsset(meta) {
+    const assetId = typeof meta?.["assetId"] === "string" ? meta["assetId"] : undefined;
+    if (assetId === undefined)
+        return null;
+    const generator = generators.get(assetId);
+    if (generator === undefined)
+        return null;
+    const seed = typeof meta?.["seed"] === "string" ? meta["seed"] : assetId;
+    const params = parseParams(generator.schema, meta);
+    return generator.generate(params, seed);
+}

package/dist/scene/assetSpace.d.ts

@@ -0,0 +1,137 @@
+import type { Aabb, Footprint, Vec2 } from "../world/geometry.js";
+/**
+ * Wrap `degrees` into `[0, 360)` — the canonical heading range every policy and conversion here works
+ * in. Non-finite input collapses to `0` so bad metadata never leaks a `NaN` heading downstream.
+ * @capability asset-heading normalize a placement heading into the engine's degree convention
+ */
+export declare function normalizeDegrees(degrees: number): number;
+/**
+ * Convert a compass heading (degrees, `0` = engine north, increasing clockwise) into the Three.js
+ * Y-rotation (radians, wrapped to `(-PI, PI]`) a renderer applies. Sign matches
+ * `world/placementController.quarterTurnsToRotationY`, so heading `90` equals one clockwise quarter
+ * turn. This is the one place degrees cross into the private radian space Three.js requires.
+ * @capability asset-heading turn a north-relative degree heading into a Three.js Y-rotation
+ */
+export declare function headingToRotationY(headingDegrees: number): number;
+/**
+ * Inverse of {@link headingToRotationY}: recover the `[0, 360)` compass heading from a Three.js
+ * Y-rotation. Lets a gizmo or inspector present radians as the degrees authors edit.
+ * @capability asset-heading read a Three.js Y-rotation back as a north-relative degree heading
+ */
+export declare function rotationYToHeading(rotationY: number): number;
+/** Bridge the legacy 0–3 quarter-turn placement model onto degrees (each turn is 90 degrees clockwise). @internal */
+export declare function quarterTurnsToHeading(quarterTurns: number): number;
+/**
+ * A per-asset/per-tool rotation constraint, authored as data instead of hardcoded in build code:
+ * `locked` pins every placement to one heading, `snap` quantizes to an increment (15, 45, …), and
+ * `free` allows any heading. Serializable — this is the shape stored on a catalog entry or a tool.
+ */
+export type PlacementRotationPolicy = {
+    readonly mode: "locked";
+    readonly degrees?: number;
+} | {
+    readonly mode: "snap";
+    readonly snapDegrees: number;
+} | {
+    readonly mode: "free";
+};
+/**
+ * Quantize `degrees` to the nearest multiple of `increment` (both in the `[0, 360)` convention). A
+ * non-positive increment is treated as free rotation and only normalizes. The math behind a
+ * `snap`-mode {@link PlacementRotationPolicy}.
+ * @capability placement-rotation snap a heading to a fixed degree increment
+ */
+export declare function snapHeading(degrees: number, increment: number): number;
+/**
+ * Resolve a raw drag/scroll heading through a {@link PlacementRotationPolicy} into the heading a
+ * placement should actually commit: `locked` ignores the input for its fixed heading, `snap` quantizes,
+ * `free` (or an absent policy) normalizes. Deterministic — the single interpreter preview, editor
+ * placement, and runtime spawning share instead of each re-implementing the modes.
+ * @capability placement-rotation apply a rotation policy to a candidate placement heading
+ */
+export declare function applyRotationPolicy(degrees: number, policy: PlacementRotationPolicy | undefined): number;
+/**
+ * Where a model's pivot sits within its footprint: `center` (origin at the footprint center),
+ * `corner` (origin at the min-X/min-Z corner), or a normalized `{ x, z }` fraction in `[-0.5, 0.5]`.
+ */
+export type AssetAnchor = "center" | "corner" | {
+    readonly x: number;
+    readonly z: number;
+};
+/**
+ * Catalog-level asset-space metadata: how a model is authored relative to the engine, owned by the
+ * catalog entry rather than re-derived per game. Every field is optional so an unmeasured asset stays
+ * valid; {@link resolveFacingRotationY}/{@link assetUnitScale}/{@link resolveAnchorOffset} supply the
+ * documented defaults.
+ */
+export interface AssetSpace {
+    /** Compass heading (degrees, `0` = north) the model's front visually points at `rotationY = 0`. Default `0`. */
+    forwardDegrees?: number;
+    /** Multiply source-space lengths by this to reach engine meters (a kit's native tile size correction). Default `1`. */
+    unitScale?: number;
+    /** Authored footprint in engine meters — the grid/placement extent, independent of the raw mesh bounds. */
+    footprint?: Footprint;
+    /** Authored grid cell size in engine meters this asset snaps to. */
+    gridSize?: number;
+    /** Where the model origin sits within {@link footprint}. Default `center`. */
+    anchor?: AssetAnchor;
+    /** Optional asset-local placement bounds (XZ) a tool clamps a drop position into. */
+    bounds?: Aabb;
+    /** Default rotation constraint when this asset is placed. Absent means free rotation. */
+    rotation?: PlacementRotationPolicy;
+}
+/**
+ * The Three.js Y-rotation that makes a model whose front is authored at `forwardDegrees` visually point
+ * `headingDegrees` (engine north = `0`). This is the catalog-owned replacement for per-game corrective
+ * yaw: a model authored facing south (`forwardDegrees: 180`) placed toward north resolves to `Math.PI`.
+ * @capability asset-facing resolve a placement heading into a Three.js Y-rotation using canonical forward
+ */
+export declare function resolveFacingRotationY(headingDegrees: number, space?: Pick<AssetSpace, "forwardDegrees">): number;
+/** The effective, guarded unit scale for an asset — a finite positive `unitScale`, else `1`. @internal */
+export declare function assetUnitScale(space?: Pick<AssetSpace, "unitScale">): number;
+/**
+ * Convert a source-space length to engine meters through the asset's {@link AssetSpace.unitScale} — the
+ * data-owned replacement for per-game scale constants (a native ~4-unit kit tile down to a 1-unit grid).
+ * @capability asset-units convert a source-space length to engine meters via catalog unit scale
+ */
+export declare function toEngineUnits(sourceValue: number, space?: Pick<AssetSpace, "unitScale">): number;
+/**
+ * The pivot's offset from the footprint center, in engine meters, implied by {@link AssetSpace.anchor}
+ * and {@link AssetSpace.footprint}. `center` yields `[0, 0]`; `corner` yields the min corner; a
+ * normalized `{ x, z }` scales by the footprint. Subtract it to seat a footprint centered on a point.
+ * @capability asset-anchor resolve a model's pivot offset from its footprint center
+ */
+export declare function resolveAnchorOffset(space?: Pick<AssetSpace, "anchor" | "footprint">): Vec2;
+/**
+ * The axis-aligned footprint extent after rotating a rectangular {@link Footprint} by `headingDegrees`
+ * — footprint-aware placement: a 90-degree turn swaps width/depth, and arbitrary headings grow the
+ * bounding box so overlap and snap checks see the space the rotated asset truly occupies.
+ * @capability asset-footprint rotate a rectangular footprint into its axis-aligned extent
+ */
+export declare function rotatedFootprint(footprint: Footprint, headingDegrees: number): Footprint;
+/** One problem found by {@link validateAssetSpace}: which metadata field and why it is invalid. */
+export interface AssetSpaceIssue {
+    field: string;
+    message: string;
+}
+/**
+ * Report contradictory or malformed asset-space metadata so catalog generation can reject it before it
+ * reaches a tool: non-finite headings, non-positive scales/sizes, inverted bounds, unknown anchors, and
+ * ill-formed rotation policies (a `snap` with a non-positive increment, an unknown `mode`). An empty
+ * array means valid. Validation lives here so tools consume resolved metadata instead of reinterpreting.
+ * @capability asset-space validate catalog asset-space metadata during index generation
+ */
+export declare function validateAssetSpace(raw: unknown): AssetSpaceIssue[];
+/**
+ * Parse an untrusted rotation policy (from a scene document or catalog JSON) into a valid
+ * {@link PlacementRotationPolicy}, defaulting to `free` when absent or malformed. The lenient companion
+ * to {@link validateAssetSpace} for the read path.
+ * @capability placement-rotation parse a serialized rotation policy, defaulting to free
+ */
+export declare function parseRotationPolicy(raw: unknown): PlacementRotationPolicy;
+/**
+ * Parse untrusted JSON into an {@link AssetSpace}, dropping malformed fields, or `undefined` when
+ * nothing valid remains — the round-trippable read path for serialized catalog/scene metadata.
+ * @capability asset-space parse serialized asset-space metadata into a validated shape
+ */
+export declare function parseAssetSpace(raw: unknown): AssetSpace | undefined;

package/dist/scene/assetSpace.js

@@ -0,0 +1,259 @@
+/**
+ * Asset-space metadata + placement rotation policy: the catalog-owned description of how a model sits
+ * in its source space and how a placement tool may rotate it. Games author scenes against engine north
+ * (heading `0` degrees, increasing clockwise) instead of transplanting per-game yaw offsets and magic
+ * scales; the catalog entry ({@link "scene/assetCatalog".ModelAssetRef}) is the upstream owner of the
+ * correction. Public APIs speak degrees; the only radians here are the private Three.js Y-rotation this
+ * module converts to, matching `world/placementController`'s `quarterTurnsToRotationY` sign so a
+ * quarter turn still equals 90 degrees clockwise. Pure and serializable — no three.js, no allocation of
+ * shared state — so preview, placement, and runtime spawning share one interpretation.
+ */
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+const FULL_TURN = 360;
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+/**
+ * Wrap `degrees` into `[0, 360)` — the canonical heading range every policy and conversion here works
+ * in. Non-finite input collapses to `0` so bad metadata never leaks a `NaN` heading downstream.
+ * @capability asset-heading normalize a placement heading into the engine's degree convention
+ */
+export function normalizeDegrees(degrees) {
+    if (!Number.isFinite(degrees))
+        return 0;
+    const wrapped = degrees % FULL_TURN;
+    return wrapped < 0 ? wrapped + FULL_TURN : wrapped;
+}
+function wrapRadians(radians) {
+    let r = radians % (2 * Math.PI);
+    if (r <= -Math.PI)
+        r += 2 * Math.PI;
+    if (r > Math.PI)
+        r -= 2 * Math.PI;
+    return r + 0; // normalize -0 to 0
+}
+/**
+ * Convert a compass heading (degrees, `0` = engine north, increasing clockwise) into the Three.js
+ * Y-rotation (radians, wrapped to `(-PI, PI]`) a renderer applies. Sign matches
+ * `world/placementController.quarterTurnsToRotationY`, so heading `90` equals one clockwise quarter
+ * turn. This is the one place degrees cross into the private radian space Three.js requires.
+ * @capability asset-heading turn a north-relative degree heading into a Three.js Y-rotation
+ */
+export function headingToRotationY(headingDegrees) {
+    return wrapRadians(-normalizeDegrees(headingDegrees) * DEG2RAD);
+}
+/**
+ * Inverse of {@link headingToRotationY}: recover the `[0, 360)` compass heading from a Three.js
+ * Y-rotation. Lets a gizmo or inspector present radians as the degrees authors edit.
+ * @capability asset-heading read a Three.js Y-rotation back as a north-relative degree heading
+ */
+export function rotationYToHeading(rotationY) {
+    return normalizeDegrees(-rotationY * RAD2DEG);
+}
+/** Bridge the legacy 0–3 quarter-turn placement model onto degrees (each turn is 90 degrees clockwise). @internal */
+export function quarterTurnsToHeading(quarterTurns) {
+    return normalizeDegrees(Math.round(quarterTurns) * 90);
+}
+/**
+ * Quantize `degrees` to the nearest multiple of `increment` (both in the `[0, 360)` convention). A
+ * non-positive increment is treated as free rotation and only normalizes. The math behind a
+ * `snap`-mode {@link PlacementRotationPolicy}.
+ * @capability placement-rotation snap a heading to a fixed degree increment
+ */
+export function snapHeading(degrees, increment) {
+    if (!(increment > 0))
+        return normalizeDegrees(degrees);
+    return normalizeDegrees(Math.round(normalizeDegrees(degrees) / increment) * increment);
+}
+/**
+ * Resolve a raw drag/scroll heading through a {@link PlacementRotationPolicy} into the heading a
+ * placement should actually commit: `locked` ignores the input for its fixed heading, `snap` quantizes,
+ * `free` (or an absent policy) normalizes. Deterministic — the single interpreter preview, editor
+ * placement, and runtime spawning share instead of each re-implementing the modes.
+ * @capability placement-rotation apply a rotation policy to a candidate placement heading
+ */
+export function applyRotationPolicy(degrees, policy) {
+    if (policy === undefined || policy.mode === "free")
+        return normalizeDegrees(degrees);
+    if (policy.mode === "locked")
+        return normalizeDegrees(policy.degrees ?? 0);
+    return snapHeading(degrees, policy.snapDegrees);
+}
+/**
+ * The Three.js Y-rotation that makes a model whose front is authored at `forwardDegrees` visually point
+ * `headingDegrees` (engine north = `0`). This is the catalog-owned replacement for per-game corrective
+ * yaw: a model authored facing south (`forwardDegrees: 180`) placed toward north resolves to `Math.PI`.
+ * @capability asset-facing resolve a placement heading into a Three.js Y-rotation using canonical forward
+ */
+export function resolveFacingRotationY(headingDegrees, space) {
+    return headingToRotationY(headingDegrees - (space?.forwardDegrees ?? 0));
+}
+/** The effective, guarded unit scale for an asset — a finite positive `unitScale`, else `1`. @internal */
+export function assetUnitScale(space) {
+    const s = space?.unitScale;
+    return typeof s === "number" && Number.isFinite(s) && s > 0 ? s : 1;
+}
+/**
+ * Convert a source-space length to engine meters through the asset's {@link AssetSpace.unitScale} — the
+ * data-owned replacement for per-game scale constants (a native ~4-unit kit tile down to a 1-unit grid).
+ * @capability asset-units convert a source-space length to engine meters via catalog unit scale
+ */
+export function toEngineUnits(sourceValue, space) {
+    return sourceValue * assetUnitScale(space);
+}
+/**
+ * The pivot's offset from the footprint center, in engine meters, implied by {@link AssetSpace.anchor}
+ * and {@link AssetSpace.footprint}. `center` yields `[0, 0]`; `corner` yields the min corner; a
+ * normalized `{ x, z }` scales by the footprint. Subtract it to seat a footprint centered on a point.
+ * @capability asset-anchor resolve a model's pivot offset from its footprint center
+ */
+export function resolveAnchorOffset(space) {
+    const w = space?.footprint?.w ?? 0;
+    const d = space?.footprint?.d ?? 0;
+    const anchor = space?.anchor ?? "center";
+    let fx = 0;
+    let fz = 0;
+    if (anchor === "corner") {
+        fx = -0.5;
+        fz = -0.5;
+    }
+    else if (typeof anchor === "object") {
+        fx = clamp(anchor.x, -0.5, 0.5);
+        fz = clamp(anchor.z, -0.5, 0.5);
+    }
+    return [fx * w, fz * d];
+}
+/**
+ * The axis-aligned footprint extent after rotating a rectangular {@link Footprint} by `headingDegrees`
+ * — footprint-aware placement: a 90-degree turn swaps width/depth, and arbitrary headings grow the
+ * bounding box so overlap and snap checks see the space the rotated asset truly occupies.
+ * @capability asset-footprint rotate a rectangular footprint into its axis-aligned extent
+ */
+export function rotatedFootprint(footprint, headingDegrees) {
+    const rad = normalizeDegrees(headingDegrees) * DEG2RAD;
+    const cos = Math.abs(Math.cos(rad));
+    const sin = Math.abs(Math.sin(rad));
+    return {
+        w: footprint.w * cos + footprint.d * sin,
+        d: footprint.w * sin + footprint.d * cos,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function finitePositive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function validateRotationPolicy(raw) {
+    if (!isRecord(raw))
+        return [{ field: "mode", message: "expected an object" }];
+    if (raw.mode === "free")
+        return [];
+    if (raw.mode === "locked") {
+        return raw.degrees !== undefined && (typeof raw.degrees !== "number" || !Number.isFinite(raw.degrees))
+            ? [{ field: "degrees", message: "expected a finite number" }]
+            : [];
+    }
+    if (raw.mode === "snap") {
+        return finitePositive(raw.snapDegrees) ? [] : [{ field: "snapDegrees", message: "expected a positive number" }];
+    }
+    return [{ field: "mode", message: "expected 'locked', 'snap', or 'free'" }];
+}
+/**
+ * Report contradictory or malformed asset-space metadata so catalog generation can reject it before it
+ * reaches a tool: non-finite headings, non-positive scales/sizes, inverted bounds, unknown anchors, and
+ * ill-formed rotation policies (a `snap` with a non-positive increment, an unknown `mode`). An empty
+ * array means valid. Validation lives here so tools consume resolved metadata instead of reinterpreting.
+ * @capability asset-space validate catalog asset-space metadata during index generation
+ */
+export function validateAssetSpace(raw) {
+    const issues = [];
+    if (!isRecord(raw)) {
+        issues.push({ field: "", message: "expected an object" });
+        return issues;
+    }
+    if (raw.forwardDegrees !== undefined && (typeof raw.forwardDegrees !== "number" || !Number.isFinite(raw.forwardDegrees))) {
+        issues.push({ field: "forwardDegrees", message: "expected a finite number" });
+    }
+    if (raw.unitScale !== undefined && !finitePositive(raw.unitScale)) {
+        issues.push({ field: "unitScale", message: "expected a positive number" });
+    }
+    if (raw.gridSize !== undefined && !finitePositive(raw.gridSize)) {
+        issues.push({ field: "gridSize", message: "expected a positive number" });
+    }
+    if (raw.footprint !== undefined) {
+        const fp = raw.footprint;
+        if (!isRecord(fp) || !finitePositive(fp.w) || !finitePositive(fp.d)) {
+            issues.push({ field: "footprint", message: "expected { w > 0, d > 0 }" });
+        }
+    }
+    if (raw.anchor !== undefined) {
+        const a = raw.anchor;
+        const named = a === "center" || a === "corner";
+        const explicit = isRecord(a) && typeof a.x === "number" && typeof a.z === "number";
+        if (!named && !explicit)
+            issues.push({ field: "anchor", message: "expected 'center', 'corner', or { x, z }" });
+    }
+    if (raw.bounds !== undefined) {
+        const b = raw.bounds;
+        if (!isRecord(b) || typeof b.minX !== "number" || typeof b.maxX !== "number" || typeof b.minZ !== "number" || typeof b.maxZ !== "number") {
+            issues.push({ field: "bounds", message: "expected an Aabb" });
+        }
+        else if (b.maxX < b.minX || b.maxZ < b.minZ) {
+            issues.push({ field: "bounds", message: "max must be >= min" });
+        }
+    }
+    if (raw.rotation !== undefined) {
+        issues.push(...validateRotationPolicy(raw.rotation).map((m) => ({ field: `rotation.${m.field}`, message: m.message })));
+    }
+    return issues;
+}
+/**
+ * Parse an untrusted rotation policy (from a scene document or catalog JSON) into a valid
+ * {@link PlacementRotationPolicy}, defaulting to `free` when absent or malformed. The lenient companion
+ * to {@link validateAssetSpace} for the read path.
+ * @capability placement-rotation parse a serialized rotation policy, defaulting to free
+ */
+export function parseRotationPolicy(raw) {
+    if (isRecord(raw)) {
+        if (raw.mode === "locked") {
+            return typeof raw.degrees === "number" && Number.isFinite(raw.degrees)
+                ? { mode: "locked", degrees: normalizeDegrees(raw.degrees) }
+                : { mode: "locked" };
+        }
+        if (raw.mode === "snap" && finitePositive(raw.snapDegrees))
+            return { mode: "snap", snapDegrees: raw.snapDegrees };
+    }
+    return { mode: "free" };
+}
+/**
+ * Parse untrusted JSON into an {@link AssetSpace}, dropping malformed fields, or `undefined` when
+ * nothing valid remains — the round-trippable read path for serialized catalog/scene metadata.
+ * @capability asset-space parse serialized asset-space metadata into a validated shape
+ */
+export function parseAssetSpace(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const out = {};
+    if (typeof raw.forwardDegrees === "number" && Number.isFinite(raw.forwardDegrees))
+        out.forwardDegrees = normalizeDegrees(raw.forwardDegrees);
+    if (finitePositive(raw.unitScale))
+        out.unitScale = raw.unitScale;
+    if (finitePositive(raw.gridSize))
+        out.gridSize = raw.gridSize;
+    if (isRecord(raw.footprint) && finitePositive(raw.footprint.w) && finitePositive(raw.footprint.d)) {
+        out.footprint = { w: raw.footprint.w, d: raw.footprint.d };
+    }
+    if (raw.anchor === "center" || raw.anchor === "corner")
+        out.anchor = raw.anchor;
+    else if (isRecord(raw.anchor) && typeof raw.anchor.x === "number" && typeof raw.anchor.z === "number") {
+        out.anchor = { x: raw.anchor.x, z: raw.anchor.z };
+    }
+    if (isRecord(raw.bounds) && typeof raw.bounds.minX === "number" && typeof raw.bounds.maxX === "number" && typeof raw.bounds.minZ === "number" && typeof raw.bounds.maxZ === "number") {
+        out.bounds = { minX: raw.bounds.minX, maxX: raw.bounds.maxX, minZ: raw.bounds.minZ, maxZ: raw.bounds.maxZ };
+    }
+    if (isRecord(raw.rotation))
+        out.rotation = parseRotationPolicy(raw.rotation);
+    return Object.keys(out).length === 0 ? undefined : out;
+}