@jgengine/shell 0.19.0 → 0.21.0

package/dist/render/materialAsset.js

@@ -0,0 +1,454 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLoader, useThree } from "@react-three/fiber";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { MATERIAL_TEXTURE_SEMANTICS, validateMaterialAsset, validateMaterialAssignments } from "@jgengine/core/material/materialAsset";
+import { applyMaterialOverrideToMaterial, MATERIAL_TEXTURE_PROPERTIES, requiresPhysicalMaterial } from "../materialOverride.js";
+import { configureAuthoredSurface } from "./authoredSurfaceMaterial.js";
+import { ownModelMaterial } from "./modelRender.js";
+import { useDisposable } from "./useDisposable.js";
+import { detectKtx2Support, materialKtx2Loader } from "./modelLoad.js";
+import { resolveAssetBaseUrl } from "./assetBase.js";
+/** Shares the model transcoder and loader cache while loading native authored images normally. @internal */
+export class MaterialTextureLoader extends THREE.Loader {
+    load(url, onLoad, onProgress, onError) {
+        const resolved = resolveAssetBaseUrl(url);
+        if (/\.ktx2(?:[?#]|$)/i.test(url))
+            return materialKtx2Loader().load(resolved, texture => onLoad?.(texture), onProgress, onError);
+        new THREE.TextureLoader(this.manager).load(resolved, onLoad, onProgress, onError);
+    }
+}
+const wrapping = { repeat: THREE.RepeatWrapping, clamp: THREE.ClampToEdgeWrapping, mirror: THREE.MirroredRepeatWrapping };
+const filters = { nearest: THREE.NearestFilter, linear: THREE.LinearFilter, "nearest-mipmap-nearest": THREE.NearestMipmapNearestFilter, "nearest-mipmap-linear": THREE.NearestMipmapLinearFilter, "linear-mipmap-nearest": THREE.LinearMipmapNearestFilter, "linear-mipmap-linear": THREE.LinearMipmapLinearFilter };
+/**
+ * Validate and configure an owned texture view while retaining the loader's immutable source.
+ * @capability material-texture-metadata configure owned map views with semantic color space, packed channels, UV transforms and sampling
+ */
+export function configureMaterialTexture(role, metadata, source) {
+    const expected = MATERIAL_TEXTURE_SEMANTICS[role].channel;
+    if (metadata.channel !== undefined && metadata.channel !== expected && !(role === "color" && metadata.channel === "rgb"))
+        throw new Error(`Texture ${role} requires ${expected} channels in Three.js; repack ${metadata.url}`);
+    if (metadata.compression !== undefined && (metadata.compression === "ktx2" || metadata.compression === "basisu") && !source.isCompressedTexture)
+        throw new Error(`Compressed texture ${metadata.url} requires the KTX2 loader; embed it in glTF or use an uncompressed authored map`);
+    const color = ["color", "emissive", "sheenColor", "specularColor"].includes(role);
+    if (metadata.colorSpace !== (color ? "srgb" : "linear"))
+        throw new Error(`Texture ${role} requires ${color ? "srgb" : "linear"} color space`);
+    const texture = source.clone();
+    texture.colorSpace = color ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+    texture.channel = metadata.uvSet ?? 0;
+    if (metadata.transform !== undefined) {
+        texture.offset.set(...metadata.transform.offset ?? [0, 0]);
+        texture.repeat.set(...metadata.transform.scale ?? [1, 1]);
+        texture.rotation = metadata.transform.rotation ?? 0;
+    }
+    if (metadata.sampler?.wrapS !== undefined)
+        texture.wrapS = wrapping[metadata.sampler.wrapS];
+    if (metadata.sampler?.wrapT !== undefined)
+        texture.wrapT = wrapping[metadata.sampler.wrapT];
+    if (metadata.sampler?.minFilter !== undefined)
+        texture.minFilter = filters[metadata.sampler.minFilter];
+    if (metadata.sampler?.magFilter !== undefined)
+        texture.magFilter = filters[metadata.sampler.magFilter];
+    texture.anisotropy = metadata.sampler?.anisotropy ?? 1;
+    texture.needsUpdate = true;
+    return texture;
+}
+/**
+ * Physical defaults adapt a declared construction; explicit authored parameters remain authoritative.
+ * @capability material-assets resolve fabric and hair construction into sparse physical appearance parameters
+ */
+export function materialAssetSurface(asset, overrides = {}) {
+    const errors = validateMaterialAsset(asset).filter(diagnostic => diagnostic.severity === "error");
+    if (errors.length > 0)
+        throw new Error(`Material ${asset.id}: ${errors.map(error => `${error.path}: ${error.message}`).join("; ")}`);
+    const fabric = asset.fabric;
+    const hair = asset.hair;
+    return {
+        ...(fabric?.construction === "fuzzy" ? { sheen: 1, sheenColor: asset.surface.color ?? "#ffffff", sheenRoughness: 0.8 } : {}),
+        ...(fabric?.construction === "woven" ? { anisotropy: 0.65, anisotropyRotation: fabric.weaveDirection ?? 0 } : {}),
+        ...(hair !== undefined ? { anisotropy: 0.8, anisotropyRotation: hair.strandDirection ?? Math.PI / 2, ...(hair.geometry === "cards" ? { alphaMode: "mask", alphaCutoff: 0.5, doubleSided: true } : {}) } : {}),
+        ...asset.surface,
+        ...overrides,
+    };
+}
+const materialAssetBases = new WeakMap();
+function applyNormalConventions(material, asset) {
+    if (asset.textures?.normal?.normalConvention === "directx")
+        material.normalScale.y *= -1;
+    if (asset.textures?.clearcoatNormal?.normalConvention === "directx")
+        material.clearcoatNormalScale.y *= -1;
+}
+function applyFabric(material, asset) {
+    const fabric = asset.fabric;
+    if (fabric?.construction !== "woven")
+        return;
+    const direction = fabric.weaveDirection ?? 0;
+    const scale = fabric.threadScale ?? 80;
+    const strength = fabric.normalStrength ?? 0.12;
+    const variation = fabric.variation ?? 0.05;
+    if (![direction, scale, strength, variation].every(Number.isFinite) || scale <= 0)
+        throw new Error(`Fabric ${asset.id} requires finite weave settings and positive threadScale`);
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey();
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        shader.uniforms.uJgFabric = { value: new THREE.Vector4(scale, strength, variation, direction) };
+        shader.vertexShader = shader.vertexShader.replace("#include <common>", "#include <common>\nvarying vec2 vJgFabricUv;").replace("#include <uv_vertex>", "#include <uv_vertex>\nvJgFabricUv = uv;");
+        shader.fragmentShader = shader.fragmentShader.replace("#include <common>", "#include <common>\nvarying vec2 vJgFabricUv;\nuniform vec4 uJgFabric;")
+            .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>
+float jgCos = cos(uJgFabric.w), jgSin = sin(uJgFabric.w);
+mat2 jgRotation = mat2(jgCos, -jgSin, jgSin, jgCos);
+vec2 jgThreads = jgRotation * vJgFabricUv * uJgFabric.x * 6.28318530718;
+vec2 jgThreadFilter = 1.0 - smoothstep(vec2(1.0), vec2(3.14159265359), fwidth(jgThreads));
+roughnessFactor = clamp(roughnessFactor + sin(jgThreads.x) * sin(jgThreads.y) * jgThreadFilter.x * jgThreadFilter.y * uJgFabric.z, 0.04, 1.0);`)
+            .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+vec3 jgDx = dFdx(-vViewPosition), jgDy = dFdy(-vViewPosition);
+vec2 jgUvDx = dFdx(vJgFabricUv), jgUvDy = dFdy(vJgFabricUv);
+vec3 jgT = jgDx * jgUvDy.y - jgDy * jgUvDx.y;
+vec3 jgB = -jgDx * jgUvDy.x + jgDy * jgUvDx.x;
+float jgFrameLength = max(max(length(jgT), length(jgB)), 0.000001);
+vec2 jgSlope = transpose(jgRotation) * (cos(jgThreads) * jgThreadFilter * uJgFabric.y);
+normal = normalize(normal + (jgT * jgSlope.x + jgB * jgSlope.y) / jgFrameLength);`);
+    };
+    material.customProgramCacheKey = () => `${previousKey}|jg-fabric:v1`;
+    material.needsUpdate = true;
+}
+function applyHair(material, asset) {
+    const hair = asset.hair;
+    if (hair?.geometry !== "cards")
+        return;
+    const strength = hair.backlightStrength ?? 0.25;
+    if (strength === 0)
+        return;
+    const tint = new THREE.Color(hair.backlightColor ?? asset.surface.color ?? "#ffffff");
+    material.userData.jgHairBacklightStrength = strength;
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey();
+    material.onBeforeCompile = function (shader, renderer) {
+        previousCompile.call(this, shader, renderer);
+        const uniform = { value: strength * (this.userData.jgHairLightExposure ?? 1) };
+        this.userData.jgHairBacklightUniform = uniform;
+        shader.uniforms.uJgHairBacklight = uniform;
+        shader.uniforms.uJgHairTint = { value: tint };
+        const directLighting = /void\s+RE_Direct_Physical\s*\([^)]*\)\s*\{/;
+        const chunk = THREE.ShaderChunk.lights_physical_pars_fragment;
+        if (!directLighting.test(chunk))
+            throw new Error(`Three.js r${THREE.REVISION} physical shader lacks RE_Direct_Physical for the hair-card backlight adapter`);
+        shader.fragmentShader = shader.fragmentShader.replace("#include <common>", "#include <common>\nuniform float uJgHairBacklight;\nuniform vec3 uJgHairTint;")
+            .replace("#include <lights_physical_pars_fragment>", chunk.replace(directLighting, declaration => `${declaration}
+float jgHairBack = saturate(-dot(geometryNormal, directLight.direction));
+float jgHairForward = pow(saturate(dot(-directLight.direction, geometryViewDir)), 4.0);
+reflectedLight.directDiffuse += directLight.color * uJgHairTint * (jgHairBack * mix(0.25, 1.0, jgHairForward) * uJgHairBacklight * RECIPROCAL_PI);`));
+    };
+    material.customProgramCacheKey = () => `${previousKey}|jg-hair-cards:v2`;
+    material.needsUpdate = true;
+}
+/**
+ * Apply one reusable material's parameters, map views and construction to an imported PBR slot.
+ * @capability material-assets clone and configure an imported PBR slot while retaining its omitted physical features and maps
+ */
+export function applyMaterialAsset(material, asset, textures, overrides) {
+    const surface = materialAssetSurfaceForSlot(material, asset, overrides);
+    const source = materialAssetBases.get(material) ?? material;
+    const target = applyMaterialOverrideToMaterial(source, surface, true, textures);
+    try {
+        materialAssetBases.set(target, source);
+        applyNormalConventions(target, asset);
+        applyFabric(target, asset);
+        applyHair(target, asset);
+        target.userData = { ...target.userData, jgMaterialAsset: asset.id };
+        return target;
+    }
+    catch (error) {
+        try {
+            target.dispose();
+        }
+        finally {
+            throw error;
+        }
+    }
+}
+function materialAssetSurfaceForSlot(material, asset, overrides, baseAlphaMode) {
+    if (!material.isMeshStandardMaterial)
+        throw new Error(`Material ${asset.id} requires an imported standard or physical PBR slot`);
+    const source = materialAssetBases.get(material) ?? material;
+    const surface = materialAssetSurface(asset, overrides);
+    const transparent = baseAlphaMode === undefined ? source.transparent : baseAlphaMode === "blend";
+    if ((surface.transmission ?? 0) > 0 && surface.alphaMode === undefined && transparent)
+        throw new Error(`Material ${asset.id} transmission requires an explicit opaque or mask alphaMode on the imported blended slot`);
+    return surface;
+}
+/**
+ * Check selectors, PBR slots, UVs and construction prerequisites before allocating material or texture views.
+ * Optional role restrictions apply only to referenced assets; imported maps remain untouched.
+ * @capability material-slot-selection preflight native model assignments without allocating or changing imported resources
+ */
+export function validateMaterialAssignmentTargets(root, assets, assignments, options = {}) {
+    materialAssignmentTargets(root, assets, assignments, options);
+}
+function materialAssignmentTargets(root, assets, assignments, options = {}) {
+    if (options.disallowedTextureRoles?.length) {
+        const errors = validateMaterialAssignments(assignments, assets, options).filter(diagnostic => diagnostic.code === "unsupported-texture-role");
+        if (errors.length > 0)
+            throw new Error(errors.map(error => error.message).join("; "));
+    }
+    const byId = new Map(assets.map(asset => [asset.id, asset]));
+    const matches = assignments.map(assignment => {
+        const asset = byId.get(assignment.materialId);
+        if (asset === undefined)
+            throw new Error(`Unknown material asset ${assignment.materialId}`);
+        const selected = [];
+        root.traverse(node => {
+            const mesh = node;
+            if (!mesh.isMesh || (assignment.selector.mesh !== undefined && mesh.name !== assignment.selector.mesh))
+                return;
+            const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+            materials.forEach((material, index) => {
+                if (assignment.selector.slot !== undefined && material.name !== assignment.selector.slot)
+                    return;
+                if (assignment.selector.slotIndex !== undefined && index !== assignment.selector.slotIndex)
+                    return;
+                if (!material.isMeshStandardMaterial)
+                    throw new Error(`Slot ${mesh.name}/${index} is not a supported PBR material`);
+                if ((asset.fabric?.construction === "woven" || asset.hair !== undefined || (materialAssetSurface(asset, assignment.overrides).anisotropy ?? 0) > 0) && (mesh.geometry.getAttribute("uv") === undefined || mesh.geometry.getAttribute("normal") === undefined))
+                    throw new Error(`Directional material ${asset.id} requires mesh UVs and normals`);
+                for (const [role, metadata] of Object.entries(asset.textures ?? {})) {
+                    const uv = metadata.uvSet ?? 0;
+                    if (mesh.geometry.getAttribute(uv === 0 ? "uv" : `uv${uv}`) === undefined)
+                        throw new Error(`Texture ${role} on ${mesh.name} requires UV set ${uv}`);
+                }
+                selected.push({ mesh, index });
+            });
+        });
+        if (selected.length === 0)
+            throw new Error(`Material selector ${JSON.stringify(assignment.selector)} matched no slots`);
+        return { assignment, asset, selected };
+    });
+    const final = new Map();
+    for (const { assignment, asset, selected } of matches)
+        for (const { mesh, index } of selected) {
+            let slots = final.get(mesh);
+            if (slots === undefined) {
+                slots = new Map();
+                final.set(mesh, slots);
+            }
+            slots.set(index, { assignment, asset });
+        }
+    for (const [mesh, slots] of final)
+        for (const [index, { assignment, asset }] of slots) {
+            const source = Array.isArray(mesh.material) ? mesh.material[index] : mesh.material;
+            materialAssetSurfaceForSlot(source, asset, assignment.overrides, options.baseAlphaMode);
+        }
+    return final;
+}
+/**
+ * Apply intersecting mesh/slot selectors without changing omitted imported slots. Returns caller-owned replacements; model clones register them only after success.
+ * @capability material-assets assign reusable physical assets to independent imported model slots
+ */
+export function applyMaterialAssignments(root, assets, assignments, textures = new Map()) {
+    const final = materialAssignmentTargets(root, assets, assignments);
+    const owned = [];
+    const originals = [];
+    try {
+        for (const [mesh, slots] of final)
+            for (const [index, { assignment, asset }] of slots) {
+                const source = Array.isArray(mesh.material) ? mesh.material[index] : mesh.material;
+                const target = applyMaterialAsset(source, asset, textures.get(asset.id), assignment.overrides);
+                originals.push({ mesh, index, source });
+                owned.push(target);
+                if (Array.isArray(mesh.material))
+                    mesh.material[index] = target;
+                else
+                    mesh.material = target;
+            }
+        for (const material of owned)
+            ownModelMaterial(root, material);
+        return owned;
+    }
+    catch (error) {
+        for (const { mesh, index, source } of originals) {
+            if (Array.isArray(mesh.material))
+                mesh.material[index] = source;
+            else
+                mesh.material = source;
+        }
+        for (const material of owned) {
+            try {
+                material.dispose();
+            }
+            catch { /* Preserve the construction error while draining every owned target. */ }
+        }
+        throw error;
+    }
+}
+/**
+ * Load map views, own their cleanup and build the same physical shader used by model assignments.
+ * @capability material-assets own a serializable material asset's textures and runtime physical shader for a custom renderer
+ */
+export function useMaterialAssetMaterial(asset, options = {}) {
+    const key = JSON.stringify([asset, options]);
+    const entries = useMemo(() => Object.entries(asset.textures ?? {}), [key]);
+    const renderer = useThree(state => state.gl);
+    if (entries.some(([, metadata]) => /\.ktx2(?:[?#]|$)/i.test(metadata.url)))
+        detectKtx2Support(renderer);
+    const loaded = useLoader(MaterialTextureLoader, entries.map(([, metadata]) => metadata.url));
+    const resources = useDisposable(() => {
+        const textures = {};
+        let material;
+        try {
+            entries.forEach(([role, metadata], index) => { textures[role] = configureMaterialTexture(role, metadata, loaded[index]); });
+            const surface = materialAssetSurface(asset, options.overrides);
+            material = requiresPhysicalMaterial(surface, textures) ? new THREE.MeshPhysicalMaterial() : new THREE.MeshStandardMaterial();
+            configureAuthoredSurface(material, { ...surface, anisotropy: undefined, surfaceAnisotropy: surface.anisotropy, repeatMetres: options.repeatMetres }, textures, options.shape ?? "box");
+            applyNormalConventions(material, asset);
+            applyFabric(material, asset);
+            applyHair(material, asset);
+            material.userData.jgMaterialAsset = asset.id;
+            return [material, ...Object.values(textures)];
+        }
+        catch (error) {
+            material?.dispose();
+            Object.values(textures).forEach(texture => texture.dispose());
+            throw error;
+        }
+    }, [key, loaded]);
+    return resources[0];
+}
+/**
+ * Mount a serializable material asset on an authored primitive, sharing model-slot rendering and owned resource cleanup.
+ * @capability material-assets render authored physical surfaces, woven detail and approximate hair-card appearance
+ */
+export function MaterialAssetSurface({ asset, ...options }) {
+    const material = useMaterialAssetMaterial(asset, options);
+    return _jsx("primitive", { object: material, attach: "material" });
+}
+/**
+ * Estimate texture allocation from loaded dimensions/mips and report pass/coverage risks. Compressed maps count actual mip bytes; uncompressed bytes bound texture views that may share uploads. This does not measure pixel overdraw.
+ * @capability material-resource-metrics inspect loaded texture byte bounds and physical, coverage and transmission participation
+ */
+export function materialResourceMetrics(materials) {
+    const unique = new Set(materials);
+    const textures = new Set();
+    let textureBytes = 0, unknownTextureSizes = 0, blendedMaterials = 0, maskedMaterials = 0, transmissionMaterials = 0, doubleSidedMaterials = 0, physicalMaterials = 0;
+    for (const material of unique) {
+        if (material.transparent)
+            blendedMaterials++;
+        if (material.alphaTest > 0)
+            maskedMaterials++;
+        if (material.side === THREE.DoubleSide)
+            doubleSidedMaterials++;
+        if (material.isMeshPhysicalMaterial)
+            physicalMaterials++;
+        if (material.transmission > 0)
+            transmissionMaterials++;
+        for (const property of Object.values(MATERIAL_TEXTURE_PROPERTIES)) {
+            const texture = material[property];
+            if (texture instanceof THREE.Texture)
+                textures.add(texture);
+        }
+    }
+    for (const texture of textures) {
+        if (texture.isCompressedTexture) {
+            textureBytes += texture.mipmaps.reduce((sum, mip) => sum + mip.data.byteLength, 0);
+            continue;
+        }
+        const image = texture.image;
+        if (image?.width === undefined || image.height === undefined) {
+            unknownTextureSizes++;
+            continue;
+        }
+        const components = texture.format === THREE.RedFormat ? 1 : texture.format === THREE.RGFormat ? 2 : 4;
+        const bytes = texture.type === THREE.FloatType ? 4 : texture.type === THREE.HalfFloatType || texture.type === THREE.UnsignedShortType ? 2 : 1;
+        let width = image.width, height = image.height;
+        do {
+            textureBytes += width * height * components * bytes;
+            if (!texture.generateMipmaps || (width === 1 && height === 1))
+                break;
+            width = Math.max(1, Math.floor(width / 2));
+            height = Math.max(1, Math.floor(height / 2));
+        } while (true);
+    }
+    return { materials: unique.size, textures: textures.size, textureBytes, unknownTextureSizes, blendedMaterials, maskedMaterials, transmissionMaterials, doubleSidedMaterials, physicalMaterials };
+}
+/**
+ * Inspect imported names, local slot indices and directional/map prerequisites without mutating the source.
+ * @capability material-slots discover exact imported mesh and material selectors with UV and tangent prerequisites
+ */
+export function inspectModelMaterialSlots(root) {
+    const result = [];
+    root.traverse(node => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        const uvSets = [0, 1, 2, 3].filter(index => mesh.geometry.getAttribute(index === 0 ? "uv" : `uv${index}`) !== undefined);
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        materials.forEach((material, slotIndex) => result.push({ mesh: mesh.name, slot: material.name, slotIndex, materialType: material.type, uvSets, tangents: mesh.geometry.getAttribute("tangent") !== undefined, physical: material.isMeshPhysicalMaterial === true }));
+    });
+    return result;
+}
+/** Loaded, owned map views for one model configuration. Loader sources and imported maps remain borrowed. @internal */
+export function useModelMaterialTextures(model) {
+    const ids = new Set(model.materialAssignments?.map(assignment => assignment.materialId));
+    const referenced = (model.materialAssets ?? []).filter(asset => ids.has(asset.id));
+    const key = JSON.stringify([model.material?.maps, referenced]);
+    const entries = useMemo(() => {
+        const result = [];
+        const maps = model.material?.maps ?? {};
+        for (const [role, url] of Object.entries(maps))
+            if (url !== undefined)
+                result.push({ role: role, metadata: { url, colorSpace: MATERIAL_TEXTURE_SEMANTICS[role].colorSpace } });
+        for (const asset of referenced)
+            for (const [role, metadata] of Object.entries(asset.textures ?? {}))
+                result.push({ assetId: asset.id, role: role, metadata: metadata });
+        return result;
+    }, [key]);
+    const renderer = useThree(state => state.gl);
+    if (entries.some(entry => /\.ktx2(?:[?#]|$)/i.test(entry.metadata.url)))
+        detectKtx2Support(renderer);
+    const loaded = useLoader(MaterialTextureLoader, entries.map(entry => entry.metadata.url));
+    const views = useDisposable(() => {
+        const owned = [];
+        try {
+            entries.forEach((entry, index) => {
+                const view = configureMaterialTexture(entry.role, entry.metadata, loaded[index]);
+                view.flipY = false;
+                owned.push(view);
+            });
+            return owned;
+        }
+        catch (error) {
+            owned.forEach(texture => texture.dispose());
+            throw error;
+        }
+    }, [entries, loaded]);
+    return useMemo(() => {
+        const global = {};
+        const assets = new Map();
+        entries.forEach((entry, index) => {
+            if (entry.assetId === undefined)
+                global[entry.role] = views[index];
+            else {
+                let textures = assets.get(entry.assetId);
+                if (textures === undefined) {
+                    textures = {};
+                    assets.set(entry.assetId, textures);
+                }
+                textures[entry.role] = views[index];
+            }
+        });
+        return { global, assets };
+    }, [entries, views]);
+}
+/**
+ * Gate the existing thin-sheet hair-card scatter by sampled local light exposure, without changing scene exposure.
+ * @capability material-appearance-signals apply sampled local exposure to the hair-card backlight approximation without global lighting edits
+ */
+export function setHairCardLightExposure(material, exposure) {
+    if (!Number.isFinite(exposure))
+        throw new Error("Hair light exposure must be finite");
+    const value = Math.max(0, Math.min(1, exposure));
+    material.userData.jgHairLightExposure = value;
+    const uniform = material.userData.jgHairBacklightUniform;
+    if (uniform !== undefined)
+        uniform.value = material.userData.jgHairBacklightStrength * value;
+}

package/dist/render/measureBounds.js

@@ -4,18 +4,21 @@ import { useRef } from "react";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
+import { modelBindPosePositions } from "./modelBindPose.js";
 /** Subtrees flagged with this userData key are excluded from bounds measurement — debug gizmos,
  * selection quads, effect billboards that should not inflate the hitbox. Sprites and invisible
  * subtrees are always excluded. */
 export const MEASURE_EXCLUDE_KEY = "jgMeasureExclude";
 const IDENTITY = new THREE.Matrix4();
 const tmpBox = new THREE.Box3();
+const tmpVertex = new THREE.Vector3();
 /**
  * Measure the meshes under `root` in `root`'s own frame (root's transform is the measuring frame,
  * children compose their local matrices below it). Returns `null` when nothing measurable is
  * mounted. Skinned meshes measure at bind pose — the standard engine approximation.
  */
 export function measureLocalBounds(root) {
+    root.updateMatrixWorld(true);
     const box = new THREE.Box3();
     box.makeEmpty();
     const meshCount = collectBounds(root, null, box);
@@ -46,9 +49,19 @@ function collectBounds(object, parentMatrix, into) {
     const mesh = object;
     if (mesh.isMesh === true && mesh.geometry !== undefined) {
         const geometry = mesh.geometry;
-        if (geometry.boundingBox === null)
-            geometry.computeBoundingBox();
-        const bounds = geometry.boundingBox;
+        let bounds;
+        if (mesh.isSkinnedMesh === true) {
+            tmpBox.makeEmpty();
+            const positions = modelBindPosePositions(mesh);
+            for (let index = 0; index < positions.length; index += 3)
+                tmpBox.expandByPoint(tmpVertex.fromArray(positions, index));
+            bounds = tmpBox;
+        }
+        else {
+            if (geometry.boundingBox === null)
+                geometry.computeBoundingBox();
+            bounds = geometry.boundingBox;
+        }
         if (bounds !== null && !bounds.isEmpty()) {
             tmpBox.copy(bounds);
             if (matrix !== null)

package/dist/render/measureCollisionMesh.js

@@ -1,5 +1,6 @@
 import * as THREE from "three";
 import { MEASURE_EXCLUDE_KEY } from "./measureBounds.js";
+import { modelBindPosePositions } from "./modelBindPose.js";
 /** Above this the model is too dense to double as its own hitbox — keep the fitted box instead of
  * paying BVH build + per-ray traversal on a hero-detail mesh. Game-ready low-poly assets sit far under it. */
 const MAX_COLLISION_TRIANGLES = 60_000;
@@ -29,8 +30,13 @@ function collectTriangles(object, parentMatrix, sink) {
         if (positionAttribute !== undefined && positionAttribute.itemSize === 3 && positionAttribute.count >= 3) {
             const base = sink.positions.length / 3;
             const applied = matrix ?? IDENTITY;
+            const bindPositions = mesh.isSkinnedMesh === true ? modelBindPosePositions(mesh) : null;
             for (let v = 0; v < positionAttribute.count; v += 1) {
-                tmpVec.fromBufferAttribute(positionAttribute, v).applyMatrix4(applied);
+                if (bindPositions === null)
+                    tmpVec.fromBufferAttribute(positionAttribute, v);
+                else
+                    tmpVec.fromArray(bindPositions, v * 3);
+                tmpVec.applyMatrix4(applied);
                 sink.positions.push(tmpVec.x, tmpVec.y, tmpVec.z);
             }
             const index = geometry.getIndex();
@@ -66,6 +72,7 @@ function collectTriangles(object, parentMatrix, sink) {
  * triangle budget — callers keep their box fallback.
  */
 export function measureLocalCollisionTriangles(root, transform) {
+    root.updateMatrixWorld(true);
     const sink = { positions: [], indices: [], meshCount: 0, triangleCount: 0, overflow: false };
     collectTriangles(root, null, sink);
     if (sink.overflow || sink.meshCount === 0 || sink.triangleCount === 0)

package/dist/render/modelAssets.d.ts

@@ -0,0 +1,8 @@
+import type { ModelConfig, ModelMaterialMaps } from "@jgengine/core/game/playableGame";
+/** Stable loader keys shared by preloading and material application. @internal */
+export declare function modelMapEntries(maps: ModelMaterialMaps): Record<string, string>;
+/** Start composed model dependencies together instead of discovering them after each parent commits. @internal */
+export declare function modelAssetRequests(model: ModelConfig): {
+    models: string[];
+    textureGroups: string[][];
+};

package/dist/render/modelAssets.js

@@ -0,0 +1,43 @@
+import { MATERIAL_TEXTURE_SEMANTICS } from "@jgengine/core/material/materialAsset";
+const legacyMapRoles = ["color", "normal", "roughness", "ao", "metalness", "emissive", "height"];
+const modelMapRoles = [...legacyMapRoles, ...Object.keys(MATERIAL_TEXTURE_SEMANTICS).filter(role => !legacyMapRoles.includes(role))];
+/** Stable loader keys shared by preloading and material application. @internal */
+export function modelMapEntries(maps) {
+    const entries = {};
+    for (const key of modelMapRoles) {
+        if (maps[key] !== undefined)
+            entries[key] = maps[key];
+    }
+    return entries;
+}
+/** Start composed model dependencies together instead of discovering them after each parent commits. @internal */
+export function modelAssetRequests(model) {
+    const models = new Set();
+    const textureGroups = new Map();
+    const visited = new Set();
+    const visit = (next) => {
+        if (visited.has(next))
+            return;
+        visited.add(next);
+        models.add(next.url);
+        if (next.material?.maps !== undefined) {
+            const urls = Object.values(modelMapEntries(next.material.maps));
+            if (urls.length > 0)
+                textureGroups.set(JSON.stringify(urls), urls);
+        }
+        const referencedIds = new Set(next.materialAssignments?.map(assignment => assignment.materialId));
+        for (const asset of next.materialAssets ?? []) {
+            if (!referencedIds.has(asset.id))
+                continue;
+            const urls = Object.values(asset.textures ?? {}).map(metadata => metadata.url);
+            if (urls.length > 0)
+                textureGroups.set(JSON.stringify(urls), urls);
+        }
+        for (const child of [...(next.parts ?? []), ...(next.attachments ?? [])]) {
+            if (typeof child.model !== "string")
+                visit(child.model);
+        }
+    };
+    visit(model);
+    return { models: [...models], textureGroups: [...textureGroups.values()] };
+}

package/dist/render/modelBindPose.d.ts

@@ -0,0 +1,5 @@
+import * as THREE from "three";
+/** Skin-applied vertices captured before animation, shared by a loaded model's clones. @internal */
+export declare function modelBindPosePositions(mesh: THREE.SkinnedMesh): Float32Array;
+/** Retain the imported pose for normalization and colliders without sampling a live animation. @internal */
+export declare function copyModelBindPose(source: THREE.Object3D, clone: THREE.Object3D): void;

package/dist/render/modelBindPose.js

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+const positionsByMesh = new WeakMap();
+const vertex = new THREE.Vector3();
+/** Skin-applied vertices captured before animation, shared by a loaded model's clones. @internal */
+export function modelBindPosePositions(mesh) {
+    let positions = positionsByMesh.get(mesh);
+    if (positions !== undefined)
+        return positions;
+    const attribute = mesh.geometry.getAttribute("position");
+    const skinned = mesh.geometry.getAttribute("skinIndex") !== undefined && mesh.geometry.getAttribute("skinWeight") !== undefined;
+    positions = new Float32Array(attribute.count * 3);
+    for (let index = 0; index < attribute.count; index++) {
+        if (skinned)
+            mesh.getVertexPosition(index, vertex);
+        else
+            vertex.fromBufferAttribute(attribute, index);
+        vertex.toArray(positions, index * 3);
+    }
+    positionsByMesh.set(mesh, positions);
+    return positions;
+}
+/** Retain the imported pose for normalization and colliders without sampling a live animation. @internal */
+export function copyModelBindPose(source, clone) {
+    source.updateMatrixWorld(true);
+    const positions = [];
+    source.traverse((node) => {
+        if (node.isSkinnedMesh === true)
+            positions.push(modelBindPosePositions(node));
+    });
+    let index = 0;
+    clone.traverse((node) => {
+        if (node.isSkinnedMesh === true)
+            positionsByMesh.set(node, positions[index++]);
+    });
+}

package/dist/render/modelLoad.d.ts

@@ -1,5 +1,6 @@
 import * as THREE from "three";
 import { GLTFLoader, type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
 import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
 /**
  * The shared GLB {@link THREE.LoadingManager}'s `onError` sink. It fires for EVERY item the manager
@@ -111,6 +112,8 @@ export interface ModelLoaderConfig {
 export declare function configureModelLoaders(options?: ModelLoaderConfig): Readonly<Required<ModelLoaderConfig>>;
 /** Detects GPU support for the configured KTX2 transcoder after a renderer exists. */
 export declare function detectKtx2Support(renderer: THREE.WebGLRenderer): void;
+/** Shared transcoder for authored material maps; GPU support is detected by the canvas. @internal */
+export declare function materialKtx2Loader(): KTX2Loader;
 /**
  * How long the shared GLB loader has been idle, in ms — `0` while any model is still
  * in flight. A capture host reads this to wait for streaming to finish instead of