@jgengine/core 0.18.1 → 0.21.0

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;
+}

package/dist/material/materialAsset.d.ts

@@ -0,0 +1,162 @@
+/** Physical surface families; these describe appearance, never geometry or simulation. */
+export type MaterialFamily = "standard" | "fabric" | "hair" | "glass" | "metal" | "skin" | "stone" | "plastic";
+/** Renderer features an authored material explicitly requires. */
+export type MaterialCapability = "pbr" | "sheen" | "anisotropy" | "clearcoat" | "specular" | "transmission" | "volume" | "iridescence" | "alpha";
+/** Sparse surface edits. Omitted values preserve the imported material. Angles are radians. */
+export interface MaterialSurfaceParameters {
+    color?: string;
+    metalness?: number;
+    roughness?: number;
+    emissive?: string;
+    emissiveIntensity?: number;
+    normalScale?: [number, number];
+    alphaMode?: "opaque" | "mask" | "blend";
+    alphaCutoff?: number;
+    opacity?: number;
+    doubleSided?: boolean;
+    sheen?: number;
+    sheenColor?: string;
+    sheenRoughness?: number;
+    anisotropy?: number;
+    anisotropyRotation?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    ior?: number;
+    specularIntensity?: number;
+    specularColor?: string;
+    transmission?: number;
+    thickness?: number;
+    attenuationColor?: string;
+    /** Positive metres. Omit for no volume attenuation; Infinity is not serializable. */
+    attenuationDistance?: number;
+    iridescence?: number;
+    iridescenceIOR?: number;
+    iridescenceThicknessRange?: [number, number];
+}
+/** Supported texture semantics; packed channels follow glTF and Three's PBR shaders. */
+export type MaterialTextureRole = "color" | "normal" | "roughness" | "metalness" | "ao" | "emissive" | "alpha" | "height" | "sheenColor" | "sheenRoughness" | "anisotropy" | "clearcoat" | "clearcoatRoughness" | "clearcoatNormal" | "specularIntensity" | "specularColor" | "transmission" | "thickness" | "iridescence" | "iridescenceThickness";
+/** Texture channels used by the pinned standard/physical shader path. */
+export type MaterialTextureChannel = "r" | "g" | "b" | "a" | "rgb" | "rgba";
+/** Portable material or image authorship. */
+export interface MaterialProvenance {
+    author: string;
+    license: string;
+    sourceUrl?: string;
+    description?: string;
+}
+/** Serializable sampling and UV metadata; metres are descriptive, UV transforms drive rendering. */
+export interface MaterialTextureMetadata {
+    url: string;
+    colorSpace: "srgb" | "linear";
+    channel?: MaterialTextureChannel;
+    uvSet?: 0 | 1 | 2 | 3;
+    transform?: {
+        offset?: [number, number];
+        scale?: [number, number];
+        rotation?: number;
+    };
+    physicalSize?: [number, number];
+    normalConvention?: "opengl" | "directx";
+    sampler?: {
+        wrapS?: "repeat" | "clamp" | "mirror";
+        wrapT?: "repeat" | "clamp" | "mirror";
+        minFilter?: "nearest" | "linear" | "nearest-mipmap-nearest" | "nearest-mipmap-linear" | "linear-mipmap-nearest" | "linear-mipmap-linear";
+        magFilter?: "nearest" | "linear";
+        anisotropy?: number;
+    };
+    compression?: "none" | "ktx2" | "basisu" | "webp";
+    provenance?: MaterialProvenance;
+}
+/** Shared, versioned authoring data. IDs survive rename, save and export. */
+export interface MaterialAsset {
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    family: MaterialFamily;
+    capabilities: readonly MaterialCapability[];
+    provenance?: MaterialProvenance;
+    surface: MaterialSurfaceParameters;
+    textures?: Partial<Record<MaterialTextureRole, MaterialTextureMetadata>>;
+    fabric?: FabricAppearance;
+    hair?: HairAppearance;
+}
+/** Procedural cloth surface response; this does not create or bend cloth geometry. */
+export interface FabricAppearance {
+    construction: "woven" | "fuzzy";
+    weaveDirection?: number;
+    threadScale?: number;
+    normalStrength?: number;
+    variation?: number;
+}
+/** Anisotropic surface approximation for existing hair cards or strand meshes, without grooming. */
+export interface HairAppearance {
+    geometry: "cards" | "strands";
+    /** Radians from UV U; cards generated by hairCards use V for strand length (PI/2). */
+    strandDirection?: number;
+    /** Thin-sheet direct-light approximation on cards, independent of physical transmission. */
+    backlightStrength?: number;
+    backlightColor?: string;
+}
+/** Names constrain mesh and imported material slot independently; all provided tests must match. */
+export interface MaterialSelector {
+    mesh?: string;
+    slot?: string;
+    /** Index in this mesh's material array, independent of the glTF global material index. */
+    slotIndex?: number;
+}
+/** A reusable asset reference with an optional instance-only sparse edit. */
+export interface MaterialAssignment {
+    materialId: string;
+    selector: MaterialSelector;
+    overrides?: MaterialSurfaceParameters;
+}
+/**
+ * Exact name/index selector matching shared by authoring and rendering.
+ * @capability material-slot-selection match named meshes and imported material slots independently
+ */
+export declare function matchesMaterialSelector(selector: MaterialSelector, mesh: string, slot: string, slotIndex: number): boolean;
+/** Shader channel defaults; standalone alpha maps use green, base-color alpha stays in its color map. */
+export declare const MATERIAL_TEXTURE_SEMANTICS: Readonly<Record<MaterialTextureRole, {
+    colorSpace: "srgb" | "linear";
+    channel: MaterialTextureChannel;
+}>>;
+/** An actionable authoring/import diagnostic. */
+export interface MaterialDiagnostic {
+    severity: "error" | "warning";
+    code: string;
+    path: string;
+    message: string;
+}
+/** Feature declarations required by each sparse physical parameter. */
+export declare const MATERIAL_SURFACE_CAPABILITIES: Partial<Record<keyof MaterialSurfaceParameters, MaterialCapability>>;
+/** Feature declarations required by authored texture roles. */
+export declare const MATERIAL_TEXTURE_CAPABILITIES: Readonly<Partial<Record<MaterialTextureRole, MaterialCapability>>>;
+/** Determine feature requirements from authored fields, including intentional zero values. */
+export declare function materialCapabilitiesForSurface(surface: MaterialSurfaceParameters): MaterialCapability[];
+/**
+ * Determine required shader features from surface fields, maps and appearance adapters without editing them.
+ * @capability material-feature-requirements Declare material shader requirements when authors add maps or appearance adapters.
+ */
+export declare function materialCapabilitiesForAsset(asset: Pick<MaterialAsset, "surface" | "textures" | "fabric" | "hair">): MaterialCapability[];
+/**
+ * Validate sparse surface edits without mutating them or guessing unsupported fields.
+ * @capability material-surface-validation diagnose unsupported or physically invalid sparse surface edits
+ */
+export declare function validateMaterialSurface(value: unknown, path?: string): MaterialDiagnostic[];
+/** Validate material JSON and renderer prerequisites before saving or assigning it. */
+export declare function validateMaterialAsset(value: unknown): MaterialDiagnostic[];
+/** Parse assignment JSON at editor/RPC boundaries. Invalid data fails with an actionable path. */
+export declare function parseMaterialAssignments(value: unknown): MaterialAssignment[];
+/** Optional renderer limits; ordinary model assignment accepts every supported texture role. */
+export interface MaterialAssignmentValidationOptions {
+    disallowedTextureRoles?: readonly MaterialTextureRole[];
+}
+/**
+ * Validate references and selectors without accepting accidental whole-model assignment.
+ * @capability material-slot-selection validate reusable asset references and explicit per-slot selectors
+ */
+export declare function validateMaterialAssignments(assignments: readonly MaterialAssignment[], assets: readonly MaterialAsset[], options?: MaterialAssignmentValidationOptions): MaterialDiagnostic[];
+/** Editable engine-authored surface starting points, independent of any game's palette or assets. */
+export type MaterialTemplate = "wool" | "cotton" | "silk" | "brushed-metal" | "glass" | "coated-plastic" | "stone" | "hair-cards";
+/** Create fresh, serializable material data with provenance; templates create no textures or geometry. */
+export declare function createMaterialTemplate(template: MaterialTemplate, id: string, name?: MaterialTemplate): MaterialAsset;