@jgengine/core 0.19.0 → 0.22.0

package/dist/inventory/shapedGrid.js

@@ -41,16 +41,28 @@ export function occupiedCells(footprint, origin, rotation) {
     return rotated.map(([c, r]) => [c + origin[0], r + origin[1]]);
 }
 /**
- * A spatial grid inventory that holds shaped multi-cell items, Resident-Evil/Tarkov style.
+ * An immutable spatial inventory board holding caller-defined multi-cell items.
  *
- * @capability tetris-inventory a spatial grid inventory holding shaped multi-cell items
-  * @internal
-  */
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function createShapedGrid(width, height) {
-    if (width <= 0 || height <= 0)
-        throw new Error("shaped grid needs positive dimensions");
+    requireDimensions(width, height);
     return { width, height, placements: [] };
 }
+function requireDimensions(width, height) {
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) {
+        throw new RangeError("shaped grid needs positive integer dimensions");
+    }
+}
+function validCell(cell) {
+    return Number.isSafeInteger(cell[0]) && Number.isSafeInteger(cell[1]);
+}
+function validFootprint(footprint) {
+    return footprint.length > 0 && footprint.every(validCell);
+}
+function validRotation(rotation) {
+    return Number.isInteger(rotation) && rotation >= 0 && rotation <= 3;
+}
 function inBounds(grid, cells) {
     return cells.every(([c, r]) => c >= 0 && r >= 0 && c < grid.width && r < grid.height);
 }
@@ -65,8 +77,16 @@ function occupancyMap(grid, ignoreId) {
     }
     return map;
 }
-/** @internal */
+/**
+ * Check bounds and overlap for a discrete footprint, optionally ignoring the item being moved.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function canPlace(grid, footprint, origin, rotation, ignoreId) {
+    requireDimensions(grid.width, grid.height);
+    if (!validFootprint(footprint) || !validRotation(rotation))
+        return "invalid-footprint";
+    if (!validCell(origin))
+        return "invalid-origin";
     const cells = occupiedCells(footprint, origin, rotation);
     if (!inBounds(grid, cells))
         return "out-of-bounds";
@@ -77,7 +97,40 @@ export function canPlace(grid, footprint, origin, rotation, ignoreId) {
     }
     return null;
 }
-/** @internal */
+/**
+ * Find the first legal placement without mutating the board; occupancy is indexed once per search.
+ *
+ * @capability shaped-placement find a shaped inventory item's first fit with ordered rotations, row-major placement, and an explicit search budget
+ */
+export function findShapedPlacement(grid, footprint, options = {}) {
+    requireDimensions(grid.width, grid.height);
+    const rotations = options.rotations ?? [0, 1, 2, 3];
+    const maxChecks = options.maxChecks ?? 4096;
+    if (!validFootprint(footprint) || !rotations.every(validRotation))
+        throw new RangeError("invalid footprint or rotation");
+    if (!Number.isSafeInteger(maxChecks) || maxChecks < 0)
+        throw new RangeError("invalid placement search budget");
+    const occupied = occupancyMap(grid, options.ignoreId);
+    let checks = 0;
+    for (const rotation of rotations) {
+        const cells = rotateFootprint(footprint, rotation);
+        for (let row = 0; row < grid.height; row += 1) {
+            for (let column = 0; column < grid.width; column += 1) {
+                if (checks >= maxChecks)
+                    return { status: "budget-exceeded", checks };
+                checks += 1;
+                if (cells.every(([c, r]) => column + c < grid.width && row + r < grid.height && !occupied.has(cellKey([column + c, row + r])))) {
+                    return { status: "found", origin: [column, row], rotation, checks };
+                }
+            }
+        }
+    }
+    return { status: "no-space", checks };
+}
+/**
+ * Place a caller-defined item without mutating the source board; duplicate ids reject.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function placeShaped(grid, item, origin, rotation = 0) {
     if (grid.placements.some((p) => p.id === item.id)) {
         return { status: "rejected", reason: "duplicate-id", detail: item.id };
@@ -94,14 +147,20 @@ export function placeShaped(grid, item, origin, rotation = 0) {
     };
     return { status: "ok", grid: { ...grid, placements: [...grid.placements, placement] } };
 }
-/** @internal */
+/**
+ * Remove one placement without mutating the source board.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function removeShaped(grid, id) {
     if (!grid.placements.some((p) => p.id === id)) {
         return { status: "rejected", reason: "unknown-id", detail: id };
     }
     return { status: "ok", grid: { ...grid, placements: grid.placements.filter((p) => p.id !== id) } };
 }
-/** @internal */
+/**
+ * Move or rotate one placement, ignoring its current cells during overlap checks.
+ * @capability shaped-grid a serializable inventory board with arbitrary cell footprints, rotation, overlap checks, and immutable placement
+ */
 export function moveShaped(grid, id, origin, rotation) {
     const existing = grid.placements.find((p) => p.id === id);
     if (existing === undefined)

package/dist/item/durability.js

@@ -21,6 +21,8 @@ export function wearAmount(spec, kind) {
  * @capability durability track item wear, breakage, and repair
  */
 export function applyWear(state, amount) {
+    if (Number.isNaN(amount))
+        throw new RangeError("Wear amount must not be NaN.");
     if (amount <= 0)
         return state;
     return { current: clamp(state.current - amount, 0, state.max), max: state.max };
@@ -40,6 +42,8 @@ export function repairQuote(spec, state, options) {
         return null;
     if (repair.station !== undefined && repair.station !== options?.station)
         return null;
+    if (options?.to !== undefined && !Number.isFinite(options.to))
+        return null;
     const loss = repair.qualityLossPerRepair ?? 0;
     const newMax = Math.max(1, state.max - loss);
     const capped = Math.min(state.current, newMax);

package/dist/item/itemInstanceRegistry.d.ts

@@ -1,3 +1,26 @@
+/** Save data for a registry; definitions must be structured-cloneable and use the caller's serialization format. */
+export interface ItemInstanceRegistryState<TDef> {
+    prefix: string;
+    sequence: number;
+    entries: [string, TDef][];
+}
+/** Caller-owned synchronous storage; `entries()` must stream without materializing the collection. */
+export interface ItemInstanceStorage<TDef> {
+    get(id: string): TDef | undefined;
+    has(id: string): boolean;
+    set(id: string, def: TDef): void;
+    delete(id: string): void;
+    count(): number;
+    entries(): Iterable<[string, TDef]>;
+    /** Consume entries completely and atomically replace storage; any failure must preserve previous data. */
+    replace(entries: Iterable<[string, TDef]>): void;
+}
+/** Inject storage and its saved allocator sequence when attaching an existing collection. */
+export interface ItemInstanceRegistryOptions<TDef> {
+    storage?: ItemInstanceStorage<TDef>;
+    /** Nonnegative safe integer; defaults to zero. Retain it across releases and storage reattachment. */
+    sequence?: number;
+}
 /**
  * A runtime store for procedurally generated item instances — a rolled unique gun, a rolled
  * affixed relic — keyed by a generated id distinct from any static catalog id. The counterpart a
@@ -5,6 +28,14 @@
  * rolls never need a hand-rolled parallel registry (#536.1).
  */
 export interface ItemInstanceRegistry<TDef> {
+    /** Detached definitions and allocator state, including ids of released instances in the sequence. */
+    state(): ItemInstanceRegistryState<TDef>;
+    /** Detached batches of at most `pageSize` entries; throws if the registry changes during iteration. Keep external storage and definitions unchanged until finished. */
+    statePages(pageSize: number): IterableIterator<ItemInstanceRegistryState<TDef>>;
+    /** Replace the registry; returns false without mutation when the prefix or allocator is invalid. */
+    restore(next: ItemInstanceRegistryState<TDef>): boolean;
+    /** Stream detached pages through atomic storage replacement. All pages must share prefix and sequence; malformed pages or storage failures throw without changing state. Empty saves require one empty page. */
+    restorePages(pages: Iterable<ItemInstanceRegistryState<TDef>>): boolean;
     /** Stores `def` under a fresh generated id derived from `baseId`; returns that id. */
     register(baseId: string, def: TDef): string;
     get(id: string): TDef | undefined;
@@ -19,7 +50,7 @@ export interface ItemInstanceRegistry<TDef> {
  *
  * @capability item-instance-registry a runtime store for procedurally generated item instances
  */
-export declare function createItemInstanceRegistry<TDef>(prefix?: string): ItemInstanceRegistry<TDef>;
+export declare function createItemInstanceRegistry<TDef>(prefix?: string, options?: ItemInstanceRegistryOptions<TDef>): ItemInstanceRegistry<TDef>;
 /**
  * Bridges any procedural roller into a `LootEntry.generate` callback: rolls a `{ baseId, def }` pair
  * and registers it, returning the runtime id the loot roll hands back as the drop's `item`.

package/dist/item/itemInstanceRegistry.js

@@ -4,20 +4,124 @@
  *
  * @capability item-instance-registry a runtime store for procedurally generated item instances
  */
-export function createItemInstanceRegistry(prefix = "item") {
-    let seq = 0;
-    const store = new Map();
+export function createItemInstanceRegistry(prefix = "item", options = {}) {
+    let seq = options.sequence ?? 0;
+    if (!Number.isSafeInteger(seq) || seq < 0)
+        throw new RangeError("Invalid item allocation sequence");
+    let revision = 0;
+    let memory = new Map();
+    const store = options.storage ?? {
+        get: (id) => memory.get(id),
+        has: (id) => memory.has(id),
+        set: (id, def) => void memory.set(id, def),
+        delete: (id) => void memory.delete(id),
+        count: () => memory.size,
+        entries: () => memory.entries(),
+        replace: (entries) => { memory = new Map(entries); },
+    };
+    const validHeader = (next) => next.prefix === prefix && Number.isSafeInteger(next.sequence) && next.sequence >= 0;
     return {
+        state: () => ({ prefix, sequence: seq, entries: structuredClone(Array.from(store.entries())) }),
+        statePages(pageSize) {
+            if (!Number.isSafeInteger(pageSize) || pageSize < 1)
+                throw new RangeError("Invalid item page size");
+            const sequence = seq;
+            const expectedRevision = revision;
+            return (function* () {
+                const entries = store.entries()[Symbol.iterator]();
+                let done = false;
+                let first = true;
+                try {
+                    while (!done) {
+                        if (revision !== expectedRevision)
+                            throw new Error("Item registry changed during export");
+                        const batch = [];
+                        while (batch.length < pageSize) {
+                            const next = entries.next();
+                            if (next.done) {
+                                done = true;
+                                break;
+                            }
+                            batch.push(next.value);
+                        }
+                        const detached = structuredClone(batch);
+                        if (revision !== expectedRevision)
+                            throw new Error("Item registry changed during export");
+                        if (first || detached.length > 0)
+                            yield { prefix, sequence, entries: detached };
+                        first = false;
+                    }
+                }
+                finally {
+                    entries.return?.();
+                }
+            })();
+        },
+        restore(next) {
+            if (!validHeader(next))
+                return false;
+            const entries = structuredClone(next.entries);
+            store.replace(entries);
+            seq = next.sequence;
+            revision += 1;
+            return true;
+        },
+        restorePages(pages) {
+            const iterator = pages[Symbol.iterator]();
+            let closed = false;
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                iterator.return?.();
+            };
+            try {
+                const first = iterator.next();
+                if (first.done || !validHeader(first.value))
+                    return false;
+                const sequence = first.value.sequence;
+                store.replace((function* () {
+                    let page = first;
+                    try {
+                        while (!page.done) {
+                            if (!validHeader(page.value) || page.value.sequence !== sequence) {
+                                throw new Error("Inconsistent item registry pages");
+                            }
+                            yield* structuredClone(page.value.entries);
+                            page = iterator.next();
+                        }
+                    }
+                    finally {
+                        close();
+                    }
+                })());
+                seq = sequence;
+                revision += 1;
+                return true;
+            }
+            finally {
+                close();
+            }
+        },
         register(baseId, def) {
-            seq += 1;
-            const id = `${prefix}:${baseId}:${seq}`;
+            let id;
+            do {
+                if (seq === Number.MAX_SAFE_INTEGER)
+                    throw new RangeError("Item allocation sequence exhausted");
+                seq += 1;
+                revision += 1;
+                id = `${prefix}:${baseId}:${seq}`;
+            } while (store.has(id));
             store.set(id, def);
             return id;
         },
         get: (id) => store.get(id),
         has: (id) => store.has(id),
-        release: (id) => void store.delete(id),
-        count: () => store.size,
+        release(id) {
+            store.delete(id);
+            revision += 1;
+        },
+        count: () => store.count(),
     };
 }
 /**

package/dist/item/itemgen.d.ts

@@ -148,7 +148,7 @@ export interface GenSchema {
 }
 /** Per-call options for {@link generate}. */
 export interface GenerateOptions {
-    /** Force a step to a specific option id, consuming no rng for it (a requested rarity or family). */
+    /** Fix a step to an option id that still must satisfy its pool and constraint, consuming no rng for it. */
     pin?: Readonly<Record<string, string>>;
 }
 /**

package/dist/item/itemgen.js

@@ -41,7 +41,7 @@ export function generate(schema, rng, options = {}) {
             const pinId = pin?.[step.id];
             if (pinId !== undefined) {
                 const option = poolFor(step.pool, view).find((candidate) => candidate.id === pinId);
-                if (option === undefined)
+                if (option === undefined || (step.accept !== undefined && !step.accept(option, view)))
                     return false;
                 chosen.push({
                     step: step.id,

package/dist/item/modularItem.js

@@ -48,7 +48,13 @@ export function isComplete(def, installed) {
     return missingRequiredSlots(def, installed).length === 0;
 }
 export function createModularItem(def, initial = []) {
-    let installed = initial;
+    let installed = [];
+    for (const { slotId, part } of initial) {
+        const result = install(def, installed, slotId, part);
+        if (result.status === "rejected")
+            throw new Error(`Invalid initial part in slot ${slotId}: ${result.reason}`);
+        installed = result.installed;
+    }
     return {
         def,
         parts() {

package/dist/material/appearanceSignals.d.ts

@@ -0,0 +1,53 @@
+import type { EnvironmentField, EnvironmentSample } from "../world/envField.js";
+import type { MaterialSurfaceParameters } from "./materialAsset.js";
+/** Resolved dry values from one assigned surface, after imported and instance edits. RGB is linear. */
+export interface MaterialAppearanceBaseline {
+    roughness: number;
+    colorLinear: readonly [number, number, number];
+    sheen?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+}
+/** Opt-in wet endpoints. Color retention multiplies linear albedo; it never replaces the authored hue. */
+export interface MaterialWetnessPolicy {
+    influence?: number;
+    roughness?: number;
+    colorRetention?: number;
+    sheen?: number;
+    /** Requires an already physical material; omitting this preserves imported coat without enabling a new one. */
+    clearcoat?: {
+        strength: number;
+        roughness?: number;
+    };
+}
+/** Local appearance only. Wind is a separate geometry/simulation input, and no field creates motion. */
+export interface MaterialAppearancePolicy {
+    wetness?: MaterialWetnessPolicy;
+    /** Sky-exposure attenuation of existing hair-card backlighting; this is not a shadow or scattering model. */
+    cardBacklightExposure?: boolean;
+}
+/** Sparse edits for one sample. Unrequested imported parameters, textures, coverage and transmission stay intact. */
+export interface MaterialAppearanceResponse {
+    surface: MaterialSurfaceParameters;
+    colorLinear?: [number, number, number];
+    backlightExposure?: number;
+    wetness: number;
+}
+/**
+ * Resolve one surface from an immutable dry baseline, avoiding cumulative drift. Wetness already includes
+ * field shelter; neither exposure nor sheltered is multiplied into it again. No accumulation or drying simulation.
+ * @capability material-appearance-signals adapt selected surface response to sampled wetness and local card exposure
+ */
+export declare function resolveMaterialAppearance(sample: EnvironmentSample, baseline: MaterialAppearanceBaseline, policy?: MaterialAppearancePolicy): MaterialAppearanceResponse;
+/** Explicit sample position; callers schedule a bounded set of visible or relevant targets. */
+export interface MaterialAppearanceTarget {
+    x: number;
+    z: number;
+    y?: number;
+    time: number;
+}
+/**
+ * Exactly one field sample per target; no traversal, subscription, hidden tick, or full-world scan.
+ * @capability material-appearance-signals sample one explicitly scheduled appearance target from the shared environment field
+ */
+export declare function sampleMaterialAppearance(field: Pick<EnvironmentField, "sample">, target: MaterialAppearanceTarget, baseline: MaterialAppearanceBaseline, policy?: MaterialAppearancePolicy): MaterialAppearanceResponse;

package/dist/material/appearanceSignals.js

@@ -0,0 +1,47 @@
+function unit(value, path) {
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+        throw new TypeError(`${path}: expected a finite value from 0 to 1.`);
+    return value;
+}
+function target(baseline, endpoint, wetness, path) {
+    if (baseline === undefined)
+        throw new TypeError(`${path}: resolve the original physical material value before adapting it.`);
+    const start = unit(baseline, `baseline.${path}`);
+    const end = unit(endpoint, `policy.${path}`);
+    return wetness === 0 ? start : wetness === 1 ? end : start + (end - start) * wetness;
+}
+/**
+ * Resolve one surface from an immutable dry baseline, avoiding cumulative drift. Wetness already includes
+ * field shelter; neither exposure nor sheltered is multiplied into it again. No accumulation or drying simulation.
+ * @capability material-appearance-signals adapt selected surface response to sampled wetness and local card exposure
+ */
+export function resolveMaterialAppearance(sample, baseline, policy = {}) {
+    const wet = policy.wetness;
+    const wetness = unit(sample.wetness, "sample.wetness") * unit(wet?.influence ?? 1, "policy.wetness.influence");
+    const result = { surface: {}, wetness };
+    if (wet?.roughness !== undefined)
+        result.surface.roughness = target(baseline.roughness, wet.roughness, wetness, "roughness");
+    if (wet?.colorRetention !== undefined) {
+        const retention = 1 + (unit(wet.colorRetention, "policy.wetness.colorRetention") - 1) * wetness;
+        if (baseline.colorLinear.some(value => !Number.isFinite(value) || value < 0))
+            throw new TypeError("baseline.colorLinear: expected finite nonnegative linear RGB.");
+        result.colorLinear = baseline.colorLinear.map(value => value * retention);
+    }
+    if (wet?.sheen !== undefined)
+        result.surface.sheen = target(baseline.sheen, wet.sheen, wetness, "sheen");
+    if (wet?.clearcoat !== undefined) {
+        result.surface.clearcoat = target(baseline.clearcoat, wet.clearcoat.strength, wetness, "clearcoat");
+        if (wet.clearcoat.roughness !== undefined)
+            result.surface.clearcoatRoughness = target(baseline.clearcoatRoughness, wet.clearcoat.roughness, wetness, "clearcoatRoughness");
+    }
+    if (policy.cardBacklightExposure)
+        result.backlightExposure = unit(sample.lightExposure, "sample.lightExposure");
+    return result;
+}
+/**
+ * Exactly one field sample per target; no traversal, subscription, hidden tick, or full-world scan.
+ * @capability material-appearance-signals sample one explicitly scheduled appearance target from the shared environment field
+ */
+export function sampleMaterialAppearance(field, target, baseline, policy = {}) {
+    return resolveMaterialAppearance(field.sample(target.x, target.z, target.time, target.y), baseline, policy);
+}

package/dist/material/hairCards.d.ts

@@ -0,0 +1,47 @@
+import type { MaterialDiagnostic } from "./materialAsset.js";
+/** Tangents follow card width (UV U); strand length follows UV V. Angles are radians. */
+export declare const HAIR_CARD_STRAND_ROTATION: number;
+/** An authored centreline, in model-local metres, with root-to-tip points. */
+export interface HairCardGuide {
+    id: string;
+    points: readonly (readonly [number, number, number])[];
+    width: number;
+    tipWidth?: number;
+    /** Desired front-facing normal; must not be parallel to the strand direction. */
+    facing: readonly [number, number, number];
+    /** Atlas rectangle [uMin,vMin,uMax,vMax]; U is width and V is root to tip. */
+    uvRect?: readonly [number, number, number, number];
+}
+/** Serializable geometry authoring, independent of materials, grooming physics and collisions. */
+export interface HairCardAuthoring {
+    guides: readonly HairCardGuide[];
+    subdivisionsPerSegment?: number;
+    /** Allocation ceiling for offline/editor generation; default 65,536 vertices. */
+    maxVertices?: number;
+}
+/** Renderer-neutral indexed ribbons with an explicit tangent frame and guide ranges. */
+export interface HairCardMesh {
+    positions: number[];
+    normals: number[];
+    tangents: number[];
+    uvs: number[];
+    indices: number[];
+    bounds: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    guides: {
+        id: string;
+        vertexStart: number;
+        vertexCount: number;
+        indexStart: number;
+        indexCount: number;
+    }[];
+}
+/**
+ * Validate finite guides, tangent frames and bounded generation; crossing/collision is not solved.
+ * @capability hair-card-geometry validate authored ribbon guides and their vertex allocation ceiling
+ */
+export declare function validateHairCardAuthoring(value: unknown): MaterialDiagnostic[];
+/** Build deterministic model-local ribbon geometry; guides remain separately editable source data. */
+export declare function buildHairCards(input: HairCardAuthoring): HairCardMesh;

package/dist/material/hairCards.js

@@ -0,0 +1,136 @@
+/** Tangents follow card width (UV U); strand length follows UV V. Angles are radians. */
+export const HAIR_CARD_STRAND_ROTATION = Math.PI / 2;
+function vec(value) { return Array.isArray(value) && value.length === 3 && value.every((item) => typeof item === "number" && Number.isFinite(item)); }
+function subtract(a, b) { return [a[0] - b[0], a[1] - b[1], a[2] - b[2]]; }
+function cross(a, b) { return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]; }
+function length(v) { return Math.hypot(...v); }
+function normalized(v) { const magnitude = length(v); return [v[0] / magnitude, v[1] / magnitude, v[2] / magnitude]; }
+/**
+ * Validate finite guides, tangent frames and bounded generation; crossing/collision is not solved.
+ * @capability hair-card-geometry validate authored ribbon guides and their vertex allocation ceiling
+ */
+export function validateHairCardAuthoring(value) {
+    const diagnostics = [];
+    const error = (path, message) => diagnostics.push({ severity: "error", code: "invalid-hair-guide", path, message });
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return [{ severity: "error", code: "invalid-hair-guide", path: "", message: "Expected hair card authoring data." }];
+    const input = value;
+    for (const key of Object.keys(input))
+        if (!["guides", "subdivisionsPerSegment", "maxVertices"].includes(key))
+            error(key, "Unsupported hair geometry field.");
+    const subdivisions = input.subdivisionsPerSegment ?? 1;
+    const maxVertices = input.maxVertices ?? 65_536;
+    if (typeof subdivisions !== "number" || !Number.isInteger(subdivisions) || subdivisions < 1 || subdivisions > 256)
+        error("subdivisionsPerSegment", "Expected an integer from 1 to 256.");
+    if (typeof maxVertices !== "number" || !Number.isInteger(maxVertices) || maxVertices < 4 || maxVertices > 1_000_000)
+        error("maxVertices", "Expected a vertex ceiling from 4 to 1,000,000.");
+    if (!Array.isArray(input.guides) || input.guides.length === 0 || input.guides.length > 10_000) {
+        error("guides", "Expected 1 to 10,000 authored guides.");
+        return diagnostics;
+    }
+    const ids = new Set();
+    let vertexCount = 0;
+    for (let index = 0; index < input.guides.length; index++) {
+        const guide = input.guides[index];
+        const path = `guides.${index}`;
+        if (typeof guide !== "object" || guide === null || Array.isArray(guide)) {
+            error(path, "Expected a guide object.");
+            continue;
+        }
+        for (const key of Object.keys(guide))
+            if (!["id", "points", "width", "tipWidth", "facing", "uvRect"].includes(key))
+                error(`${path}.${key}`, "Unsupported guide field.");
+        if (typeof guide.id !== "string" || guide.id.trim().length === 0 || ids.has(guide.id))
+            error(`${path}.id`, "Expected a unique stable guide ID.");
+        else
+            ids.add(guide.id);
+        if (typeof guide.width !== "number" || !Number.isFinite(guide.width) || guide.width <= 0)
+            error(`${path}.width`, "Expected a positive width in metres.");
+        if (guide.tipWidth !== undefined && (typeof guide.tipWidth !== "number" || !Number.isFinite(guide.tipWidth) || guide.tipWidth < 0))
+            error(`${path}.tipWidth`, "Expected a nonnegative tip width in metres.");
+        const facingValid = vec(guide.facing) && length(guide.facing) > 1e-8;
+        if (!facingValid)
+            error(`${path}.facing`, "Expected a finite nonzero facing vector.");
+        if (!Array.isArray(guide.points) || guide.points.length < 2 || guide.points.length > 10_000) {
+            error(`${path}.points`, "Expected 2 to 10,000 finite model-local points.");
+            continue;
+        }
+        vertexCount += 2 * ((guide.points.length - 1) * (typeof subdivisions === "number" ? subdivisions : 1) + 1);
+        const ceiling = typeof maxVertices === "number" && Number.isFinite(maxVertices) ? Math.min(maxVertices, 1_000_000) : 65_536;
+        if (vertexCount > ceiling) {
+            error("maxVertices", `Guides require at least ${vertexCount} vertices, above the ${ceiling} ceiling.`);
+            return diagnostics;
+        }
+        if (!guide.points.every(vec)) {
+            error(`${path}.points`, "Expected finite model-local points.");
+            continue;
+        }
+        for (let point = 1; point < guide.points.length; point++) {
+            const direction = subtract(guide.points[point], guide.points[point - 1]);
+            if (length(direction) <= 1e-8)
+                error(`${path}.points.${point}`, "Adjacent guide points must be distinct.");
+            else if (facingValid && length(cross(normalized(direction), normalized(guide.facing))) <= 1e-6)
+                error(`${path}.facing`, "Facing is parallel to a guide segment; choose a different card orientation.");
+            if (point < guide.points.length - 1 && length(subtract(guide.points[point + 1], guide.points[point - 1])) <= 1e-8)
+                error(`${path}.points.${point}`, "A reversing guide has no stable tangent at its bend.");
+        }
+        if (guide.uvRect !== undefined && (!Array.isArray(guide.uvRect) || guide.uvRect.length !== 4 || !guide.uvRect.every((item) => typeof item === "number" && Number.isFinite(item) && item >= 0 && item <= 1) || guide.uvRect[0] >= guide.uvRect[2] || guide.uvRect[1] >= guide.uvRect[3]))
+            error(`${path}.uvRect`, "Expected an ordered atlas rectangle within 0 to 1.");
+    }
+    if (typeof maxVertices === "number" && vertexCount > maxVertices)
+        error("maxVertices", `Guides require ${vertexCount} vertices, above the ${maxVertices} ceiling.`);
+    return diagnostics;
+}
+/** Build deterministic model-local ribbon geometry; guides remain separately editable source data. */
+export function buildHairCards(input) {
+    const errors = validateHairCardAuthoring(input);
+    if (errors.length > 0)
+        throw new TypeError(errors.map((item) => `${item.path}: ${item.message}`).join("; "));
+    const mesh = { positions: [], normals: [], tangents: [], uvs: [], indices: [], bounds: { min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] }, guides: [] };
+    const subdivisions = input.subdivisionsPerSegment ?? 1;
+    for (const guide of input.guides) {
+        const vertexStart = mesh.positions.length / 3;
+        const indexStart = mesh.indices.length;
+        const samples = [[...guide.points[0]]];
+        for (let segment = 1; segment < guide.points.length; segment++) {
+            const from = guide.points[segment - 1], to = guide.points[segment];
+            for (let step = 1; step <= subdivisions; step++) {
+                const t = step / subdivisions;
+                samples.push([from[0] + (to[0] - from[0]) * t, from[1] + (to[1] - from[1]) * t, from[2] + (to[2] - from[2]) * t]);
+            }
+        }
+        const distances = [0];
+        for (let index = 1; index < samples.length; index++)
+            distances.push(distances[index - 1] + length(subtract(samples[index], samples[index - 1])));
+        const totalLength = distances[distances.length - 1];
+        const atlas = guide.uvRect ?? [0, 0, 1, 1];
+        for (let index = 0; index < samples.length; index++) {
+            const tangent = normalized(subtract(samples[Math.min(index + 1, samples.length - 1)], samples[Math.max(index - 1, 0)]));
+            const widthDirection = cross(tangent, normalized(guide.facing));
+            if (length(widthDirection) <= 1e-6 || !widthDirection.every(Number.isFinite))
+                throw new TypeError(`Guide ${guide.id} has an unstable tangent frame at sample ${index}; change its bend or facing.`);
+            const across = normalized(widthDirection);
+            const normal = normalized(cross(across, tangent));
+            const t = distances[index] / totalLength;
+            const halfWidth = (guide.width + ((guide.tipWidth ?? guide.width * 0.1) - guide.width) * t) / 2;
+            for (let side = 0; side < 2; side++) {
+                const sign = side === 0 ? -1 : 1;
+                const position = [samples[index][0] + sign * across[0] * halfWidth, samples[index][1] + sign * across[1] * halfWidth, samples[index][2] + sign * across[2] * halfWidth];
+                mesh.positions.push(...position);
+                mesh.normals.push(...normal);
+                mesh.tangents.push(...across, 1);
+                mesh.uvs.push(side === 0 ? atlas[0] : atlas[2], atlas[1] + (atlas[3] - atlas[1]) * t);
+                for (let axis = 0; axis < 3; axis++) {
+                    mesh.bounds.min[axis] = Math.min(mesh.bounds.min[axis], position[axis]);
+                    mesh.bounds.max[axis] = Math.max(mesh.bounds.max[axis], position[axis]);
+                }
+            }
+            if (index < samples.length - 1) {
+                const left = vertexStart + index * 2;
+                mesh.indices.push(left, left + 1, left + 2, left + 1, left + 3, left + 2);
+            }
+        }
+        mesh.guides.push({ id: guide.id, vertexStart, vertexCount: samples.length * 2, indexStart, indexCount: mesh.indices.length - indexStart });
+    }
+    return mesh;
+}