@jgengine/core 0.19.0 → 0.22.0

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;

package/dist/material/materialAsset.js

@@ -0,0 +1,382 @@
+/**
+ * Exact name/index selector matching shared by authoring and rendering.
+ * @capability material-slot-selection match named meshes and imported material slots independently
+ */
+export function matchesMaterialSelector(selector, mesh, slot, slotIndex) {
+    return (selector.mesh === undefined || selector.mesh === mesh)
+        && (selector.slot === undefined || selector.slot === slot)
+        && (selector.slotIndex === undefined || selector.slotIndex === slotIndex);
+}
+/** Shader channel defaults; standalone alpha maps use green, base-color alpha stays in its color map. */
+export const MATERIAL_TEXTURE_SEMANTICS = {
+    color: { colorSpace: "srgb", channel: "rgba" },
+    normal: { colorSpace: "linear", channel: "rgb" },
+    roughness: { colorSpace: "linear", channel: "g" },
+    metalness: { colorSpace: "linear", channel: "b" },
+    ao: { colorSpace: "linear", channel: "r" },
+    emissive: { colorSpace: "srgb", channel: "rgb" },
+    alpha: { colorSpace: "linear", channel: "g" },
+    height: { colorSpace: "linear", channel: "r" },
+    sheenColor: { colorSpace: "srgb", channel: "rgb" },
+    sheenRoughness: { colorSpace: "linear", channel: "a" },
+    anisotropy: { colorSpace: "linear", channel: "rgb" },
+    clearcoat: { colorSpace: "linear", channel: "r" },
+    clearcoatRoughness: { colorSpace: "linear", channel: "g" },
+    clearcoatNormal: { colorSpace: "linear", channel: "rgb" },
+    specularIntensity: { colorSpace: "linear", channel: "a" },
+    specularColor: { colorSpace: "srgb", channel: "rgb" },
+    transmission: { colorSpace: "linear", channel: "r" },
+    thickness: { colorSpace: "linear", channel: "g" },
+    iridescence: { colorSpace: "linear", channel: "r" },
+    iridescenceThickness: { colorSpace: "linear", channel: "g" },
+};
+const FAMILIES = ["standard", "fabric", "hair", "glass", "metal", "skin", "stone", "plastic"];
+const CAPABILITIES = ["pbr", "sheen", "anisotropy", "clearcoat", "specular", "transmission", "volume", "iridescence", "alpha"];
+/** Feature declarations required by each sparse physical parameter. */
+export const MATERIAL_SURFACE_CAPABILITIES = {
+    sheen: "sheen", sheenColor: "sheen", sheenRoughness: "sheen", anisotropy: "anisotropy", anisotropyRotation: "anisotropy",
+    clearcoat: "clearcoat", clearcoatRoughness: "clearcoat", ior: "specular", specularIntensity: "specular", specularColor: "specular",
+    transmission: "transmission", thickness: "volume", attenuationColor: "volume", attenuationDistance: "volume",
+    iridescence: "iridescence", iridescenceIOR: "iridescence", iridescenceThicknessRange: "iridescence",
+    alphaMode: "alpha", alphaCutoff: "alpha", opacity: "alpha",
+};
+/** Feature declarations required by authored texture roles. */
+export const MATERIAL_TEXTURE_CAPABILITIES = Object.fromEntries(Object.keys(MATERIAL_TEXTURE_SEMANTICS).flatMap((role) => {
+    const capability = MATERIAL_SURFACE_CAPABILITIES[role]
+        ?? (role === "clearcoatNormal" ? "clearcoat" : role === "iridescenceThickness" ? "iridescence" : role === "alpha" ? "alpha" : undefined);
+    return capability === undefined ? [] : [[role, capability]];
+}));
+const FABRIC_CAPABILITIES = { fuzzy: ["sheen"], woven: ["sheen", "anisotropy"] };
+const HAIR_CAPABILITIES = { cards: ["anisotropy", "alpha"], strands: ["anisotropy"] };
+/** Determine feature requirements from authored fields, including intentional zero values. */
+export function materialCapabilitiesForSurface(surface) {
+    const capabilities = new Set(["pbr"]);
+    for (const key of Object.keys(surface)) {
+        const capability = MATERIAL_SURFACE_CAPABILITIES[key];
+        if (capability !== undefined && surface[key] !== undefined)
+            capabilities.add(capability);
+    }
+    return [...capabilities];
+}
+/**
+ * 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 function materialCapabilitiesForAsset(asset) {
+    const capabilities = new Set(materialCapabilitiesForSurface(asset.surface));
+    for (const role of Object.keys(asset.textures ?? {})) {
+        const capability = MATERIAL_TEXTURE_CAPABILITIES[role];
+        if (asset.textures?.[role] !== undefined && capability !== undefined)
+            capabilities.add(capability);
+    }
+    if (asset.fabric)
+        for (const capability of FABRIC_CAPABILITIES[asset.fabric.construction])
+            capabilities.add(capability);
+    if (asset.hair)
+        for (const capability of HAIR_CAPABILITIES[asset.hair.geometry])
+            capabilities.add(capability);
+    return [...capabilities];
+}
+const UNIT_FIELDS = ["metalness", "roughness", "alphaCutoff", "opacity", "sheen", "sheenRoughness", "anisotropy", "clearcoat", "clearcoatRoughness", "specularIntensity", "transmission", "iridescence"];
+const COLOR_FIELDS = ["color", "emissive", "sheenColor", "specularColor", "attenuationColor"];
+const NONNEGATIVE_FIELDS = ["emissiveIntensity", "thickness"];
+const SUPPORTED_FIELDS = new Set([...UNIT_FIELDS, ...COLOR_FIELDS, ...NONNEGATIVE_FIELDS, "normalScale", "alphaMode", "doubleSided", "anisotropyRotation", "ior", "attenuationDistance", "iridescenceIOR", "iridescenceThicknessRange"]);
+function record(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function finite(value) { return typeof value === "number" && Number.isFinite(value); }
+function pair(value) { return Array.isArray(value) && value.length === 2 && value.every(finite); }
+function validateProvenance(value, path) {
+    if (!record(value) || typeof value.author !== "string" || value.author.trim().length === 0 || typeof value.license !== "string" || value.license.trim().length === 0)
+        return [{ severity: "error", code: "invalid-provenance", path, message: "Expected author and license attribution." }];
+    if (Object.keys(value).some((key) => !["author", "license", "sourceUrl", "description"].includes(key)) || (value.description !== undefined && typeof value.description !== "string"))
+        return [{ severity: "error", code: "invalid-provenance", path, message: "Unsupported or invalid attribution field." }];
+    if (value.sourceUrl !== undefined && (typeof value.sourceUrl !== "string" || !/^https?:\/\//i.test(value.sourceUrl)))
+        return [{ severity: "error", code: "invalid-provenance", path: `${path}.sourceUrl`, message: "Expected an HTTP source URL." }];
+    return [];
+}
+/**
+ * Validate sparse surface edits without mutating them or guessing unsupported fields.
+ * @capability material-surface-validation diagnose unsupported or physically invalid sparse surface edits
+ */
+export function validateMaterialSurface(value, path = "surface") {
+    const errors = [];
+    const error = (key, message) => errors.push({ severity: "error", code: "invalid-surface", path: `${path}.${key}`, message });
+    if (!record(value))
+        return [{ severity: "error", code: "invalid-surface", path, message: "Expected a surface object." }];
+    for (const [key, field] of Object.entries(value)) {
+        if (!SUPPORTED_FIELDS.has(key))
+            error(key, "Unsupported surface parameter.");
+        else if (UNIT_FIELDS.includes(key) && (!finite(field) || field < 0 || field > 1))
+            error(key, "Expected a finite value from 0 to 1.");
+        else if (COLOR_FIELDS.includes(key) && (typeof field !== "string" || !/^#[0-9a-f]{6}$/i.test(field)))
+            error(key, "Expected an sRGB #rrggbb color.");
+        else if (NONNEGATIVE_FIELDS.includes(key) && (!finite(field) || field < 0))
+            error(key, "Expected a finite nonnegative value.");
+        else if (key === "alphaMode" && !["opaque", "mask", "blend"].includes(field))
+            error(key, "Expected opaque, mask or blend.");
+        else if (key === "doubleSided" && typeof field !== "boolean")
+            error(key, "Expected a boolean.");
+        else if (key === "anisotropyRotation" && !finite(field))
+            error(key, "Expected a finite angle in radians.");
+        else if ((key === "ior" || key === "iridescenceIOR") && (!finite(field) || field < 1 || field > 2.333))
+            error(key, "Expected IOR from 1 to 2.333.");
+        else if (key === "attenuationDistance" && (!finite(field) || field <= 0))
+            error(key, "Expected a finite positive distance in metres.");
+        else if (key === "normalScale" && !pair(field))
+            error(key, "Expected two finite normal strengths.");
+        else if (key === "iridescenceThicknessRange" && (!pair(field) || field[0] < 0 || field[1] < field[0]))
+            error(key, "Expected an ordered nonnegative nanometre range.");
+    }
+    return errors;
+}
+/** Validate material JSON and renderer prerequisites before saving or assigning it. */
+export function validateMaterialAsset(value) {
+    const errors = [];
+    const error = (path, message, code = "invalid-material") => errors.push({ severity: "error", code, path, message });
+    if (!record(value))
+        return [{ severity: "error", code: "invalid-material", path: "", message: "Expected a material object." }];
+    if (value.schemaVersion !== 1)
+        error("schemaVersion", "Expected material schema version 1.");
+    for (const key of Object.keys(value))
+        if (!["schemaVersion", "id", "name", "family", "capabilities", "provenance", "surface", "textures", "fabric", "hair"].includes(key))
+            error(key, "Unsupported material asset metadata.");
+    if (typeof value.id !== "string" || value.id.trim().length === 0)
+        error("id", "Expected a stable nonempty material ID.");
+    if (typeof value.name !== "string" || value.name.trim().length === 0)
+        error("name", "Expected a material name.");
+    if (!FAMILIES.includes(value.family))
+        error("family", "Unknown material family.");
+    if (value.provenance !== undefined)
+        errors.push(...validateProvenance(value.provenance, "provenance"));
+    const capabilities = Array.isArray(value.capabilities) ? value.capabilities : [];
+    if (!Array.isArray(value.capabilities) || capabilities.some((item) => !CAPABILITIES.includes(item)))
+        error("capabilities", "Expected an explicit list of supported material capabilities.");
+    errors.push(...validateMaterialSurface(value.surface));
+    if (record(value.surface)) {
+        for (const [field, capability] of Object.entries(MATERIAL_SURFACE_CAPABILITIES)) {
+            if (value.surface[field] !== undefined && !capabilities.includes(capability))
+                error(`surface.${field}`, `Declare the ${capability} capability.`, "missing-capability");
+        }
+        if (typeof value.surface.transmission === "number" && value.surface.transmission > 0 && value.surface.alphaMode === "blend")
+            error("surface.alphaMode", "Use opaque or mask coverage with transmission; alpha blending and physical transmission are distinct paths.", "unsupported-combination");
+    }
+    if (value.fabric !== undefined) {
+        if (!record(value.fabric) || !["woven", "fuzzy"].includes(value.fabric.construction))
+            error("fabric", "Expected woven or fuzzy fabric construction.");
+        else {
+            for (const [field, item] of Object.entries(value.fabric)) {
+                if (field === "construction")
+                    continue;
+                if (value.fabric.construction === "fuzzy") {
+                    error(`fabric.${field}`, "Thread controls require woven construction; use normal maps and surface normals for fuzzy cloth detail.");
+                    continue;
+                }
+                if (field === "weaveDirection" ? !finite(item) : field === "threadScale" ? !finite(item) || item <= 0 : field === "normalStrength" || field === "variation" ? !finite(item) || item < 0 || item > 1 : true)
+                    error(`fabric.${field}`, "Unsupported or invalid fabric parameter.");
+            }
+            for (const capability of FABRIC_CAPABILITIES[value.fabric.construction]) {
+                if (!capabilities.includes(capability))
+                    error("fabric", `Fabric appearance requires the ${capability} capability.`, "missing-capability");
+            }
+        }
+    }
+    if (value.hair !== undefined) {
+        if (!record(value.hair) || !["cards", "strands"].includes(value.hair.geometry))
+            error("hair", "Expected cards or strands geometry.");
+        else
+            for (const [field, item] of Object.entries(value.hair)) {
+                if (field === "geometry")
+                    continue;
+                if (field === "strandDirection" ? !finite(item) : field === "backlightStrength" ? !finite(item) || item < 0 || item > 1 : field === "backlightColor" ? typeof item !== "string" || !/^#[0-9a-f]{6}$/i.test(item) : true)
+                    error(`hair.${field}`, "Unsupported or invalid hair parameter.");
+                if (value.hair.geometry !== "cards" && (field === "backlightStrength" || field === "backlightColor"))
+                    error(`hair.${field}`, "Thin-sheet backlighting supports hair cards only.");
+            }
+        if (record(value.hair) && ["cards", "strands"].includes(value.hair.geometry)) {
+            for (const capability of HAIR_CAPABILITIES[value.hair.geometry]) {
+                if (!capabilities.includes(capability))
+                    error("hair", `Hair approximation requires the ${capability} capability.`, "missing-capability");
+            }
+        }
+    }
+    if (value.textures !== undefined) {
+        if (!record(value.textures))
+            error("textures", "Expected a texture-role object.");
+        else
+            for (const [role, texture] of Object.entries(value.textures)) {
+                const semantics = MATERIAL_TEXTURE_SEMANTICS[role];
+                const path = `textures.${role}`;
+                if (semantics === undefined) {
+                    error(path, "Unsupported texture role.");
+                    continue;
+                }
+                if (!record(texture)) {
+                    error(path, "Expected texture metadata.");
+                    continue;
+                }
+                for (const field of Object.keys(texture))
+                    if (!["url", "colorSpace", "channel", "uvSet", "transform", "physicalSize", "normalConvention", "sampler", "compression", "provenance"].includes(field))
+                        error(`${path}.${field}`, "Unsupported texture metadata.");
+                if (texture.provenance !== undefined)
+                    errors.push(...validateProvenance(texture.provenance, `${path}.provenance`));
+                const feature = MATERIAL_TEXTURE_CAPABILITIES[role];
+                if (feature !== undefined && !capabilities.includes(feature))
+                    error(path, `Declare the ${feature} capability.`, "missing-capability");
+                if (typeof texture.url !== "string" || texture.url.trim().length === 0 || /^\s*(?:javascript|file):/i.test(texture.url))
+                    error(`${path}.url`, "Expected a runtime asset URL.");
+                if (texture.colorSpace !== semantics.colorSpace)
+                    error(`${path}.colorSpace`, `The ${role} role requires ${semantics.colorSpace} color space.`, "texture-color-space");
+                if (texture.channel !== undefined && texture.channel !== semantics.channel && !(role === "color" && texture.channel === "rgb"))
+                    error(`${path}.channel`, `The shader samples ${semantics.channel} for ${role}; repack this texture.`, "texture-channel");
+                if (texture.uvSet !== undefined && ![0, 1, 2, 3].includes(texture.uvSet))
+                    error(`${path}.uvSet`, "Expected UV set 0, 1, 2 or 3.");
+                if (texture.physicalSize !== undefined && (!pair(texture.physicalSize) || texture.physicalSize.some((n) => n <= 0)))
+                    error(`${path}.physicalSize`, "Expected positive metre dimensions.");
+                if (texture.normalConvention !== undefined && (!["opengl", "directx"].includes(texture.normalConvention) || !["normal", "clearcoatNormal"].includes(role)))
+                    error(`${path}.normalConvention`, "Normal conventions apply only to normal textures.");
+                if (texture.compression !== undefined && !["none", "ktx2", "basisu", "webp"].includes(texture.compression))
+                    error(`${path}.compression`, "Unknown texture compression.");
+                if (texture.transform !== undefined) {
+                    if (!record(texture.transform))
+                        error(`${path}.transform`, "Expected a UV transform object.");
+                    else
+                        for (const [field, item] of Object.entries(texture.transform)) {
+                            if ((field === "offset" || field === "scale") ? !pair(item) : field === "rotation" ? !finite(item) : true)
+                                error(`${path}.transform.${field}`, "Unsupported or invalid UV transform.");
+                        }
+                }
+                if (texture.sampler !== undefined) {
+                    if (!record(texture.sampler))
+                        error(`${path}.sampler`, "Expected a sampler object.");
+                    else
+                        for (const [field, item] of Object.entries(texture.sampler)) {
+                            const valid = field === "wrapS" || field === "wrapT" ? ["repeat", "clamp", "mirror"].includes(item)
+                                : field === "minFilter" ? ["nearest", "linear", "nearest-mipmap-nearest", "nearest-mipmap-linear", "linear-mipmap-nearest", "linear-mipmap-linear"].includes(item)
+                                    : field === "magFilter" ? ["nearest", "linear"].includes(item)
+                                        : field === "anisotropy" && finite(item) && item >= 1;
+                            if (!valid)
+                                error(`${path}.sampler.${field}`, "Unsupported or invalid sampler setting.");
+                        }
+                }
+            }
+    }
+    if (value.family === "hair")
+        errors.push({ severity: "warning", code: "hair-approximation", path: "family", message: "Anisotropy and card backlighting approximate hair surfaces; this material creates no groom, strand multiscattering or simulation." });
+    if (record(value.surface) && typeof value.surface.anisotropy === "number" && value.surface.anisotropy > 0)
+        errors.push({ severity: "warning", code: "direction-prerequisite", path: "surface.anisotropy", message: "Directional highlights require suitable UVs or mesh tangents; verify their orientation on the imported mesh." });
+    return errors;
+}
+/** Parse assignment JSON at editor/RPC boundaries. Invalid data fails with an actionable path. */
+export function parseMaterialAssignments(value) {
+    if (!Array.isArray(value))
+        throw new TypeError("materialAssignments: expected an array.");
+    return value.map((item, index) => {
+        const path = `materialAssignments.${index}`;
+        if (!record(item) || typeof item.materialId !== "string" || item.materialId.trim().length === 0)
+            throw new TypeError(`${path}.materialId: expected a stable material ID.`);
+        if (Object.keys(item).some((key) => !["materialId", "selector", "overrides"].includes(key)))
+            throw new TypeError(`${path}: unsupported assignment field.`);
+        if (!record(item.selector) || Object.keys(item.selector).length === 0)
+            throw new TypeError(`${path}.selector: choose a mesh, slot or slotIndex.`);
+        const selector = {};
+        for (const [key, field] of Object.entries(item.selector)) {
+            if (key === "mesh" || key === "slot") {
+                if (typeof field !== "string" || field.trim().length === 0)
+                    throw new TypeError(`${path}.selector.${key}: expected a nonempty name.`);
+                selector[key] = field;
+            }
+            else if (key === "slotIndex" && typeof field === "number" && Number.isInteger(field) && field >= 0)
+                selector.slotIndex = field;
+            else
+                throw new TypeError(`${path}.selector.${key}: unsupported selector or invalid index.`);
+        }
+        const diagnostics = item.overrides === undefined ? [] : validateMaterialSurface(item.overrides, `${path}.overrides`);
+        if (diagnostics.length > 0)
+            throw new TypeError(`${diagnostics[0].path}: ${diagnostics[0].message}`);
+        return { materialId: item.materialId, selector, ...(item.overrides === undefined ? {} : { overrides: { ...item.overrides } }) };
+    });
+}
+/**
+ * Validate references and selectors without accepting accidental whole-model assignment.
+ * @capability material-slot-selection validate reusable asset references and explicit per-slot selectors
+ */
+export function validateMaterialAssignments(assignments, assets, options = {}) {
+    const diagnostics = [];
+    const byId = new Map();
+    for (const asset of assets) {
+        if (byId.has(asset.id))
+            diagnostics.push({ severity: "error", code: "duplicate-material", path: asset.id, message: "Material IDs must be unique." });
+        byId.set(asset.id, asset);
+    }
+    assignments.forEach((assignment, index) => {
+        const path = `materialAssignments.${index}`;
+        if (!byId.has(assignment.materialId))
+            diagnostics.push({ severity: "error", code: "missing-material", path: `${path}.materialId`, message: `Material ${assignment.materialId} is not in the asset library.` });
+        const asset = byId.get(assignment.materialId);
+        for (const role of options.disallowedTextureRoles ?? [])
+            if (asset?.textures?.[role] !== undefined)
+                diagnostics.push({ severity: "error", code: "unsupported-texture-role", path: `${path}.materialId`, message: `Material ${assignment.materialId} uses ${role} maps unsupported on this rendering path.` });
+        const selector = assignment.selector;
+        if (!selector || Object.keys(selector).length === 0 || (selector.mesh === undefined && selector.slot === undefined && selector.slotIndex === undefined))
+            diagnostics.push({ severity: "error", code: "empty-selector", path: `${path}.selector`, message: "Choose a named mesh, material slot or slot index." });
+        if (selector?.slotIndex !== undefined && (!Number.isInteger(selector.slotIndex) || selector.slotIndex < 0))
+            diagnostics.push({ severity: "error", code: "invalid-selector", path: `${path}.selector.slotIndex`, message: "Expected a nonnegative slot index." });
+        if (assignment.overrides !== undefined)
+            diagnostics.push(...validateMaterialSurface(assignment.overrides, `${path}.overrides`));
+    });
+    return diagnostics;
+}
+/** Create fresh, serializable material data with provenance; templates create no textures or geometry. */
+export function createMaterialTemplate(template, id, name = template) {
+    let family;
+    let surface;
+    let fabric;
+    let hair;
+    switch (template) {
+        case "wool":
+            family = "fabric";
+            surface = { roughness: 0.9, sheen: 0.8, sheenColor: "#ffffff", sheenRoughness: 0.85 };
+            fabric = { construction: "fuzzy" };
+            break;
+        case "cotton":
+            family = "fabric";
+            surface = { roughness: 0.8, sheen: 0.35, sheenColor: "#ffffff", sheenRoughness: 0.8, anisotropy: 0.15 };
+            fabric = { construction: "woven", weaveDirection: 0, threadScale: 100, normalStrength: 0.2, variation: 0.08 };
+            break;
+        case "silk":
+            family = "fabric";
+            surface = { roughness: 0.28, sheen: 0.7, sheenColor: "#ffffff", sheenRoughness: 0.3, anisotropy: 0.7 };
+            fabric = { construction: "woven", weaveDirection: 0, threadScale: 150, normalStrength: 0.05, variation: 0.03 };
+            break;
+        case "brushed-metal":
+            family = "metal";
+            surface = { metalness: 1, roughness: 0.3, anisotropy: 0.7, anisotropyRotation: 0 };
+            break;
+        case "glass":
+            family = "glass";
+            surface = { roughness: 0.05, metalness: 0, transmission: 1, ior: 1.5, thickness: 0.05, attenuationColor: "#ffffff", attenuationDistance: 2 };
+            break;
+        case "coated-plastic":
+            family = "plastic";
+            surface = { metalness: 0, roughness: 0.45, clearcoat: 1, clearcoatRoughness: 0.1 };
+            break;
+        case "stone":
+            family = "stone";
+            surface = { metalness: 0, roughness: 0.95 };
+            break;
+        case "hair-cards":
+            family = "hair";
+            surface = { roughness: 0.4, anisotropy: 0.8, alphaMode: "mask", alphaCutoff: 0.5, doubleSided: true };
+            hair = { geometry: "cards", strandDirection: Math.PI / 2, backlightStrength: 0.25 };
+            break;
+        default: throw new TypeError(`Unsupported material template: ${template}`);
+    }
+    const asset = {
+        schemaVersion: 1, id, name, family, surface, capabilities: materialCapabilitiesForAsset({ surface, fabric, hair }),
+        provenance: { author: "JGengine contributors", license: "Apache-2.0", sourceUrl: "https://github.com/Noisemaker111/jgengine", description: "Original editable parameter starting point. Geometry, textures and simulation are authored separately." },
+        ...(fabric === undefined ? {} : { fabric }), ...(hair === undefined ? {} : { hair }),
+    };
+    const errors = validateMaterialAsset(asset).filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0)
+        throw new TypeError(`${errors[0].path}: ${errors[0].message}`);
+    return asset;
+}

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.19.0";
+export declare const VERSION = "0.22.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];