@jgengine/shell 0.19.0 → 0.22.0

package/dist/render/EnvironmentLighting.js

@@ -1,3 +1,4 @@
+import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
 import { useThree } from "@react-three/fiber";
 import { useEffect } from "react";
 import * as THREE from "three";
@@ -20,6 +21,27 @@ export function EnvironmentLighting({ source, intensity = 0.35, skyColor = "#87b
         let target;
         let loadedTexture;
         let cancelled = false;
+        let appliedRotation;
+        let appliedRotationValue;
+        const previous = scene.environment;
+        const previousRotation = scene.environmentRotation;
+        const previousIntensity = scene.environmentIntensity;
+        const appliedIntensity = source?.intensity ?? intensity;
+        scene.environmentIntensity = appliedIntensity;
+        const release = () => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            if (target !== undefined && scene.environment === target.texture)
+                scene.environment = previous;
+            if (appliedRotation !== undefined && scene.environmentRotation === appliedRotation && appliedRotation.equals(appliedRotationValue))
+                scene.environmentRotation = previousRotation;
+            if (scene.environmentIntensity === appliedIntensity)
+                scene.environmentIntensity = previousIntensity;
+            pmrem.dispose();
+            target?.dispose();
+            loadedTexture?.dispose();
+        };
         const effective = source?.kind === "gradient" ? source : undefined;
         const apply = (next, rotation) => {
             if (cancelled) {
@@ -28,44 +50,61 @@ export function EnvironmentLighting({ source, intensity = 0.35, skyColor = "#87b
             }
             target = next;
             scene.environment = next.texture;
-            if (rotation !== undefined)
-                scene.environmentRotation = new THREE.Euler(0, rotation, 0);
+            if (rotation !== undefined) {
+                appliedRotation = new THREE.Euler(0, rotation, 0);
+                appliedRotationValue = appliedRotation.clone();
+                scene.environmentRotation = appliedRotation;
+            }
         };
-        const previous = scene.environment;
-        const previousRotation = scene.environmentRotation;
-        if (source?.kind === "hdri") {
-            const Loader = /\.exr(?:$|\?)/i.test(source.url) ? EXRLoader : RGBELoader;
-            new Loader().loadAsync(source.url).then((texture) => {
-                loadedTexture = texture;
-                texture.mapping = THREE.EquirectangularReflectionMapping;
-                apply(pmrem.fromEquirectangular(texture), source.rotation);
-            }).catch(() => undefined);
-        }
-        else if (source?.kind === "cube") {
-            new THREE.CubeTextureLoader().loadAsync(source.urls).then((texture) => {
-                loadedTexture = texture;
-                apply(pmrem.fromCubemap(texture));
-            }).catch(() => undefined);
+        try {
+            if (source?.kind === "hdri") {
+                const Loader = /\.exr(?:$|\?)/i.test(source.url) ? EXRLoader : RGBELoader;
+                new Loader().loadAsync(source.url).then((texture) => {
+                    if (cancelled) {
+                        texture.dispose();
+                        return;
+                    }
+                    loadedTexture = texture;
+                    texture.mapping = THREE.EquirectangularReflectionMapping;
+                    apply(pmrem.fromEquirectangular(texture), source.rotation);
+                }).catch((error) => {
+                    if (cancelled)
+                        return;
+                    reportTextureLoadError(source.url);
+                    console.warn(`[jgengine] environment illumination failed: ${source.url}`, error);
+                });
+            }
+            else if (source?.kind === "cube") {
+                new THREE.CubeTextureLoader().loadAsync(source.urls).then((texture) => {
+                    if (cancelled) {
+                        texture.dispose();
+                        return;
+                    }
+                    loadedTexture = texture;
+                    apply(pmrem.fromCubemap(texture));
+                }).catch((error) => {
+                    if (cancelled)
+                        return;
+                    for (const url of source.urls)
+                        reportTextureLoadError(url);
+                    console.warn(`[jgengine] cube environment illumination failed: ${source.urls.join(", ")}`, error);
+                });
+            }
+            else {
+                const probe = buildSkyProbeScene({ skyColor: effective?.sky ?? skyColor, groundColor: effective?.ground ?? groundColor, sunDirection, sunColor: effective?.sun ?? sunColor });
+                try {
+                    apply(pmrem.fromScene(probe, 0.04));
+                }
+                finally {
+                    disposeScene(probe);
+                }
+            }
         }
-        else {
-            const probe = buildSkyProbeScene({ skyColor: effective?.sky ?? skyColor, groundColor: effective?.ground ?? groundColor, sunDirection, sunColor: effective?.sun ?? sunColor });
-            apply(pmrem.fromScene(probe, 0.04));
-            disposeScene(probe);
+        catch (error) {
+            release();
+            throw error;
         }
-        const sceneWithIntensity = scene;
-        const previousIntensity = sceneWithIntensity.environmentIntensity;
-        sceneWithIntensity.environmentIntensity = source?.intensity ?? intensity;
-        return () => {
-            cancelled = true;
-            pmrem.dispose();
-            target?.dispose();
-            loadedTexture?.dispose();
-            scene.environment = previous;
-            if (previousRotation !== undefined)
-                scene.environmentRotation = previousRotation;
-            if (previousIntensity !== undefined)
-                sceneWithIntensity.environmentIntensity = previousIntensity;
-        };
+        return release;
     }, [gl, scene, source, intensity, skyColor, groundColor, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
     return null;
 }

package/dist/render/HairCards.d.ts

@@ -0,0 +1,7 @@
+import { type HairCardAuthoring } from "@jgengine/core/material/hairCards";
+import type { MaterialAsset } from "@jgengine/core/material/materialAsset";
+/** Render authored guide ribbons with explicit UVs and strand tangents; motion and collision remain caller-owned. */
+export declare function HairCards({ cards, material }: {
+    cards: HairCardAuthoring;
+    material: MaterialAsset;
+}): import("react").JSX.Element;

package/dist/render/HairCards.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { buildHairCards } from "@jgengine/core/material/hairCards";
+import { MaterialAssetSurface } from "./materialAsset.js";
+import { useDisposable } from "./useDisposable.js";
+/** Render authored guide ribbons with explicit UVs and strand tangents; motion and collision remain caller-owned. */
+export function HairCards({ cards, material }) {
+    const key = JSON.stringify(cards);
+    const mesh = useMemo(() => buildHairCards(cards), [key]);
+    const geometry = useDisposable(() => {
+        const next = new THREE.BufferGeometry();
+        next.setAttribute("position", new THREE.Float32BufferAttribute(mesh.positions, 3));
+        next.setAttribute("normal", new THREE.Float32BufferAttribute(mesh.normals, 3));
+        next.setAttribute("tangent", new THREE.Float32BufferAttribute(mesh.tangents, 4));
+        next.setAttribute("uv", new THREE.Float32BufferAttribute(mesh.uvs, 2));
+        next.setIndex(mesh.indices);
+        next.computeBoundingBox();
+        next.computeBoundingSphere();
+        return next;
+    }, [mesh]);
+    return _jsx("mesh", { geometry: geometry, castShadow: true, receiveShadow: true, children: _jsx(MaterialAssetSurface, { asset: material }) });
+}

package/dist/render/SceneModels.js

@@ -1,20 +1,25 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useFrame, useLoader } from "@react-three/fiber";
-import { useTexture } from "@react-three/drei";
-import { Component, Suspense, useEffect, useMemo, useRef } from "react";
+import { useFrame, useLoader, useThree } from "@react-three/fiber";
+import { Component, Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility";
 import { createSpriteClipPlayer } from "@jgengine/core/render/sprite2d";
 import { reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
 import { useOptionalGameContext } from "@jgengine/react/provider";
-import { sharedGltfLoader } from "./modelLoad.js";
+import { detectKtx2Support, sharedGltfLoader } from "./modelLoad.js";
+import { modelAssetRequests } from "./modelAssets.js";
 import { measureLocalBounds, reportMeasuredBounds } from "./measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
-import { useModelAnimation } from "./useModelAnimation.js";
+import { useModelInstance } from "./useModelInstance.js";
+import { applyMaterialAssignments, useModelMaterialTextures, MaterialTextureLoader, validateMaterialAssignmentTargets } from "./materialAsset.js";
 import { useFootIk } from "./useFootIk.js";
+import { resolveRigNode } from "./rigNode.js";
 import { PartMotionRig } from "./PartMotion.js";
+import { syncSpriteFrame } from "./spriteRender.js";
 import { applyMaterialOverride } from "../materialOverride.js";
-import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeClonedMaterials, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
+import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeModelScene, ownModelMaterial, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
 export function EntitySprite({ sprite }) {
+    const invalidate = useThree((state) => state.invalidate);
     const texture = useLoader(THREE.TextureLoader, sprite.clip?.atlas.image ?? sprite.url);
     const map = useMemo(() => texture.clone(), [texture]);
     const player = useMemo(() => (sprite.clip === undefined ? null : createSpriteClipPlayer(sprite.clip.atlas)), [sprite.clip]);
@@ -28,7 +33,11 @@ export function EntitySprite({ sprite }) {
     useEffect(() => {
         if (player !== null && animation !== undefined)
             player.play(animation);
-    }, [player, animation]);
+        const frame = player?.frame();
+        if (frame !== undefined && sprite.clip !== undefined)
+            syncSpriteFrame(map, frame, sprite.clip.atlas.size);
+        invalidate();
+    }, [player, animation, map, sprite.clip, invalidate]);
     useFrame((_state, delta) => {
         if (player === null || sprite.clip === undefined)
             return;
@@ -36,10 +45,7 @@ export function EntitySprite({ sprite }) {
         const frame = player.frame();
         if (frame === undefined)
             return;
-        const [atlasWidth, atlasHeight] = sprite.clip.atlas.size;
-        map.repeat.set(frame.w / atlasWidth, frame.h / atlasHeight);
-        map.offset.set(frame.x / atlasWidth, 1 - (frame.y + frame.h) / atlasHeight);
-        map.needsUpdate = true;
+        syncSpriteFrame(map, frame, sprite.clip.atlas.size);
     });
     useEffect(() => {
         if (player === null) {
@@ -97,13 +103,14 @@ function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
     const rz = rotation?.[2] ?? 0;
     const s = scale ?? 1;
     useEffect(() => {
-        const bone = rig.getObjectByName(slot);
-        if (bone === undefined) {
+        const resolved = resolveRigNode(rig, slot);
+        if (resolved.node === undefined) {
             if (typeof console !== "undefined") {
-                console.warn(`[jgengine] entityModels attachment: bone/slot "${slot}" not found on the rig`);
+                console.warn(`[jgengine] entityModels attachment: ${resolved.diagnostic.message}`);
             }
             return;
         }
+        const bone = resolved.node;
         weaponScene.position.set(px, py, pz);
         weaponScene.rotation.set(rx, ry, rz);
         weaponScene.scale.setScalar(s);
@@ -112,80 +119,47 @@ function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
             bone.remove(weaponScene);
         };
     }, [rig, weaponScene, slot, px, py, pz, rx, ry, rz, s]);
-    useEffect(() => () => disposeClonedMaterials(weaponScene), [weaponScene]);
+    useEffect(() => () => disposeModelScene(weaponScene), [weaponScene]);
     return null;
 }
 /** Renders a static kit-of-parts child at a fixed local offset under the parent model — no bone/rig lookup, unlike `BoneAttachment`. The nested `EntityModel` still applies its own `dims`/anchor centering, so scale/pivot sanity carries over per part. */
 function ModelPartGroup({ model, position, rotation, scale, }) {
     return (_jsx("group", { position: position ?? [0, 0, 0], rotation: rotation ?? [0, 0, 0], scale: scale ?? 1, children: _jsx(IsolatedModelPart, { model: model, children: _jsx(EntityModel, { model: model }) }) }));
 }
-function ModelMaterialMapsApplier({ scene, maps }) {
-    const entries = useMemo(() => {
-        const record = {};
-        if (maps.color !== undefined)
-            record.color = maps.color;
-        if (maps.normal !== undefined)
-            record.normal = maps.normal;
-        if (maps.roughness !== undefined)
-            record.roughness = maps.roughness;
-        if (maps.ao !== undefined)
-            record.ao = maps.ao;
-        if (maps.metalness !== undefined)
-            record.metalness = maps.metalness;
-        if (maps.emissive !== undefined)
-            record.emissive = maps.emissive;
-        if (maps.height !== undefined)
-            record.height = maps.height;
-        return record;
-    }, [maps.color, maps.normal, maps.roughness, maps.ao, maps.metalness, maps.emissive, maps.height]);
-    const textures = useTexture(entries);
-    useEffect(() => {
-        if (textures.color !== undefined)
-            textures.color.colorSpace = THREE.SRGBColorSpace;
-        applyMaterialOverride(scene, {}, { clone: false, textures });
-    }, [scene, textures]);
-    return null;
-}
 export function EntityModel({ model, instanceId, measure, }) {
-    const gltf = useLoader(sharedGltfLoader, model.url);
+    parseModelHiddenNodes(model.hiddenNodes);
+    const renderer = useThree(state => state.gl);
+    if (renderer.isWebGLRenderer)
+        detectKtx2Support(renderer);
+    const assets = modelAssetRequests(model);
+    for (const url of assets.models)
+        useLoader.preload(sharedGltfLoader, url);
     // Optional, not required: measured bounds and paint strokes are live-world extras, and a model
     // that threw without a running game could not be inspected outside one — which is how a broken
     // composition stayed undiagnosable in `EntityPreview` (#1588).
     const ctx = useOptionalGameContext();
     const material = model.material;
+    const materialAssetKey = JSON.stringify((model.materialAssets ?? []).filter(asset => model.materialAssignments?.some(assignment => assignment.materialId === asset.id)));
+    const materialAssets = useMemo(() => (model.materialAssets ?? []).filter(asset => model.materialAssignments?.some(assignment => assignment.materialId === asset.id)), [materialAssetKey]);
+    const materialAssignments = model.materialAssignments;
+    const assignmentSource = useLoader(sharedGltfLoader, materialAssignments?.length ? [model.url] : [])[0]?.scene;
+    const assignmentKey = JSON.stringify(materialAssignments);
+    useMemo(() => {
+        if (assignmentSource !== undefined)
+            validateMaterialAssignmentTargets(assignmentSource, materialAssets, materialAssignments, { baseAlphaMode: material?.alphaMode });
+    }, [assignmentSource, materialAssets, assignmentKey, material?.alphaMode]);
+    for (const urls of assets.textureGroups)
+        useLoader.preload(MaterialTextureLoader, urls);
+    const materialTextures = useModelMaterialTextures(model);
     const baseY = model.y ?? 0;
     const dims = model.dims;
-    const shadows = model.shadows;
-    const scene = useMemo(() => {
-        const cloned = cloneModelScene(gltf.scene, { shadows });
+    const configure = useCallback((content) => {
         if (material !== undefined)
-            applyMaterialOverride(cloned, material, { clone: false });
-        return cloned;
-    }, [gltf, material, shadows]);
-    const measured = useMemo(() => {
-        if (model.targetHeight === undefined)
-            return null;
-        const box = new THREE.Box3().setFromObject(scene);
-        const height = box.max.y - box.min.y;
-        if (!Number.isFinite(height) || height <= 0)
-            return null;
-        return {
-            normalize: model.targetHeight / height,
-            minY: box.min.y,
-            centerX: (box.min.x + box.max.x) / 2,
-            centerZ: (box.min.z + box.max.z) / 2,
-        };
-    }, [scene, model.targetHeight]);
-    const scale = (model.scale ?? 1) * (measured?.normalize ?? 1);
-    const centered = (model.anchor ?? "center") === "center" && dims !== undefined;
-    const position = measured !== null
-        ? [-scale * measured.centerX, baseY - scale * measured.minY, -scale * measured.centerZ]
-        : centered
-            ? [-scale * dims.center.x, baseY - scale * dims.minY, -scale * dims.center.z]
-            : [0, baseY, 0];
-    useEffect(() => () => {
-        disposeClonedMaterials(scene);
-    }, [scene]);
+            applyMaterialOverride(content, material, { clone: false, textures: materialTextures.global, ownMaterial: replacement => ownModelMaterial(content, replacement) });
+        if (materialAssignments !== undefined)
+            applyMaterialAssignments(content, materialAssets ?? [], materialAssignments, materialTextures.assets);
+    }, [material, materialTextures, materialAssets, materialAssignments]);
+    const { scene, scale, position } = useModelInstance(model, { instanceId, configure });
     // A model without index-measured dims can't drive the fitted-collider path, so report the live
     // measurement (the primitive mounts with only this uniform scale + position) instead of letting
     // the kind fall back to a fixed-size box. Index dims keep priority — skip when they exist.
@@ -193,7 +167,8 @@ export function EntityModel({ model, instanceId, measure, }) {
     const measureKey = measure?.key;
     const dimsMaxY = dims?.maxY;
     const [positionX, positionY, positionZ] = position;
-    useEffect(() => {
+    // Measure before the instance hook's passive animation effects can move imported root nodes.
+    useLayoutEffect(() => {
         if (ctx === null || measureTarget === undefined || measureKey === undefined || dimsMaxY !== undefined)
             return;
         const raw = measureLocalBounds(scene);
@@ -207,7 +182,7 @@ export function EntityModel({ model, instanceId, measure, }) {
     }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey, dimsMaxY]);
     // Runs with or without index dims: the loaded geometry upgrades whatever box the kind resolved
     // (fitted or measured) to a hitbox that raycasts the model's own triangles.
-    useEffect(() => {
+    useLayoutEffect(() => {
         if (ctx === null || measureTarget === undefined || measureKey === undefined)
             return;
         const triangles = measureLocalCollisionTriangles(scene, {
@@ -217,7 +192,6 @@ export function EntityModel({ model, instanceId, measure, }) {
         if (triangles !== null)
             reportMeasuredCollisionMesh(ctx, measureTarget, measureKey, triangles);
     }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey]);
-    useModelAnimation(scene, gltf.animations, model.animation, instanceId);
     useFootIk(scene, model.ik, ctx, instanceId, baseY);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
@@ -255,7 +229,7 @@ export function EntityModel({ model, instanceId, measure, }) {
         }
         paintDrawnCountRef.current = syncPaintCanvas(paintCanvasRef.current, cache.seedColor, strokes, paintDrawnCountRef.current);
     });
-    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? (_jsx(IsolatedModelPart, { model: model, children: _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) })) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(IsolatedModelPart, { model: attachment.model, children: _jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }) }, `${attachment.slot}-${index}`)))] }));
+    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(IsolatedModelPart, { model: attachment.model, children: _jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }) }, `${attachment.slot}-${index}`)))] }));
     const parts = model.parts ?? [];
     // Any role-tagged part switches the composition onto the procedural part-motion rig:
     // root bob/flinch/topple plus per-role limb swing, driven from the entity's live state.

package/dist/render/authoredSurfaceMaterial.d.ts

@@ -0,0 +1,43 @@
+import * as THREE from "three";
+import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
+import { type MaterialOverrideTextures } from "../materialOverride.js";
+/** Serializable PBR settings for an authored primitive surface. Map roles use the model-material contract. */
+export interface AuthoredSurfaceConfig extends Omit<ModelMaterialOverride, "anisotropy" | "normalScale"> {
+    /** Physical metres per texture tile on unit boxes/cylinders, including instance and parent scale. Omit to retain authored UVs. */
+    repeatMetres?: number;
+    /** Texture sampler policy on owned clones; defaults to repeat on both axes and anisotropy 1. */
+    wrapping?: "repeat" | "clamp" | "mirror";
+    anisotropy?: number;
+    /** Physical directional highlight strength [0,1]; `anisotropy` remains the legacy texture sampler setting. */
+    surfaceAnisotropy?: number;
+    normalScale?: readonly [number, number];
+    /** Normalized [0,1] height maps displace in local shape units (Three defaults: scale 1, bias 0). */
+    displacementScale?: number;
+    displacementBias?: number;
+    transparent?: boolean;
+    opacity?: number;
+    depthWrite?: boolean;
+}
+/** Primitive UV layout whose physical dimensions drive `repeatMetres`. */
+export type SurfaceShape = "box" | "cylinder";
+/** Stable material identity, independent of object/map property insertion order. @internal */
+export declare function authoredSurfaceKey(config: AuthoredSurfaceConfig): string;
+/** Configure owned map clones without changing textures retained in a loader cache. @internal */
+export declare function authoredSurfaceTextures(entries: Record<string, string>, sources: readonly THREE.Texture[], config?: AuthoredSurfaceConfig): MaterialOverrideTextures;
+/** Apply PBR settings and optional metre UVs to an owned standard material. @internal */
+export declare function configureAuthoredSurface(material: THREE.MeshStandardMaterial, config: AuthoredSurfaceConfig, textures: MaterialOverrideTextures, shape: SurfaceShape): void;
+/**
+ * Load declared surface-map roles and own the material/map clones (cached textures remain untouched).
+ * Colour, emissive, sheen-colour and specular-colour maps are sRGB; numeric maps are linear. Cylinder side metres use the RMS ellipse circumference approximation.
+ * Static batches and custom meshes share this lifecycle.
+ * @capability authored-surface-material render declared PBR maps with colour-space handling and metre-scale box/cylinder UVs
+ */
+export declare function useAuthoredSurfaceMaterial(config: AuthoredSurfaceConfig, shape?: SurfaceShape): THREE.MeshStandardMaterial;
+/**
+ * Mount an owned PBR surface material on a mesh.
+ * @capability authored-surface-material mount an owned PBR surface material on a mesh
+ */
+export declare function AuthoredSurfaceMaterial({ surface, shape }: {
+    surface: AuthoredSurfaceConfig;
+    shape?: SurfaceShape;
+}): import("react").JSX.Element;

package/dist/render/authoredSurfaceMaterial.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLoader } from "@react-three/fiber";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { MATERIAL_TEXTURE_SEMANTICS } from "@jgengine/core/material/materialAsset";
+import { applyMaterialOverrideToMaterial, requiresPhysicalMaterial } from "../materialOverride.js";
+import { modelMapEntries } from "./modelAssets.js";
+import { useDisposable } from "./useDisposable.js";
+/** Stable material identity, independent of object/map property insertion order. @internal */
+export function authoredSurfaceKey(config) {
+    return JSON.stringify(Object.entries({ ...config, maps: modelMapEntries(config.maps ?? {}) }).sort(([a], [b]) => a.localeCompare(b)));
+}
+/** Configure owned map clones without changing textures retained in a loader cache. @internal */
+export function authoredSurfaceTextures(entries, sources, config = {}) {
+    const wrapping = config.wrapping === "clamp" ? THREE.ClampToEdgeWrapping : config.wrapping === "mirror" ? THREE.MirroredRepeatWrapping : THREE.RepeatWrapping;
+    return Object.fromEntries(Object.keys(entries).map((role, index) => {
+        const texture = sources[index].clone();
+        texture.colorSpace = MATERIAL_TEXTURE_SEMANTICS[role]?.colorSpace === "srgb" ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+        texture.wrapS = wrapping;
+        texture.wrapT = wrapping;
+        texture.anisotropy = config.anisotropy ?? 1;
+        texture.needsUpdate = true;
+        return [role, texture];
+    }));
+}
+/** Apply PBR settings and optional metre UVs to an owned standard material. @internal */
+export function configureAuthoredSurface(material, config, textures, shape) {
+    const tile = config.repeatMetres;
+    if (tile !== undefined && (!Number.isFinite(tile) || tile <= 0))
+        throw new Error("repeatMetres must be finite and positive");
+    if (config.normalScale?.some(value => !Number.isFinite(value)))
+        throw new Error("normalScale must be finite");
+    if (config.anisotropy !== undefined && (!Number.isFinite(config.anisotropy) || config.anisotropy < 1))
+        throw new Error("anisotropy must be finite and >= 1");
+    if ([config.displacementScale, config.displacementBias].some(value => value !== undefined && !Number.isFinite(value)))
+        throw new Error("displacement settings must be finite");
+    const { anisotropy: _samplerAnisotropy, surfaceAnisotropy, ...surface } = config;
+    if (requiresPhysicalMaterial({ ...surface, normalScale: surface.normalScale === undefined ? undefined : [...surface.normalScale], anisotropy: surfaceAnisotropy }, textures) && !material.isMeshPhysicalMaterial)
+        throw new Error("Physical authored surface settings require MeshPhysicalMaterial");
+    applyMaterialOverrideToMaterial(material, { ...surface, normalScale: surface.normalScale === undefined ? undefined : [...surface.normalScale], anisotropy: surfaceAnisotropy }, false, textures);
+    if (config.displacementScale !== undefined)
+        material.displacementScale = config.displacementScale;
+    if (config.displacementBias !== undefined)
+        material.displacementBias = config.displacementBias;
+    if (config.transparent !== undefined)
+        material.transparent = config.transparent;
+    if (config.opacity !== undefined)
+        material.opacity = config.opacity;
+    if (config.depthWrite !== undefined)
+        material.depthWrite = config.depthWrite;
+    if (config.normalScale !== undefined)
+        material.normalScale.set(...config.normalScale);
+    if (tile === undefined)
+        return;
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey();
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        shader.vertexShader = shader.vertexShader.replace("#include <uv_vertex>", `#include <uv_vertex>
+mat4 surfaceTransform = modelMatrix;
+#ifdef USE_INSTANCING
+ surfaceTransform = modelMatrix * instanceMatrix;
+#endif
+vec3 surfaceExtent = vec3(length(surfaceTransform[0].xyz), length(surfaceTransform[1].xyz), length(surfaceTransform[2].xyz));
+vec2 surfaceRepeat = ${shape === "box"
+            ? "abs(normal.x) > 0.5 ? surfaceExtent.zy : abs(normal.y) > 0.5 ? surfaceExtent.xz : surfaceExtent.xy"
+            : "abs(normal.y) > 0.5 ? surfaceExtent.xz * 2.0 : vec2(6.28318530718 * sqrt((surfaceExtent.x * surfaceExtent.x + surfaceExtent.z * surfaceExtent.z) * 0.5), surfaceExtent.y)"};
+surfaceRepeat /= ${tile.toExponential(8)};
+${Object.entries({ MAP: "vMapUv", NORMALMAP: "vNormalMapUv", ROUGHNESSMAP: "vRoughnessMapUv", AOMAP: "vAoMapUv", METALNESSMAP: "vMetalnessMapUv", EMISSIVEMAP: "vEmissiveMapUv", DISPLACEMENTMAP: "vDisplacementMapUv", ALPHAMAP: "vAlphaMapUv", SHEENCOLORMAP: "vSheenColorMapUv", SHEENROUGHNESSMAP: "vSheenRoughnessMapUv", ANISOTROPYMAP: "vAnisotropyMapUv", CLEARCOATMAP: "vClearcoatMapUv", CLEARCOATROUGHNESSMAP: "vClearcoatRoughnessMapUv", CLEARCOATNORMALMAP: "vClearcoatNormalMapUv", SPECULARINTENSITYMAP: "vSpecularIntensityMapUv", SPECULARCOLORMAP: "vSpecularColorMapUv", TRANSMISSIONMAP: "vTransmissionMapUv", THICKNESSMAP: "vThicknessMapUv", IRIDESCENCEMAP: "vIridescenceMapUv", IRIDESCENCETHICKNESSMAP: "vIridescenceThicknessMapUv" }).map(([role, name]) => {
+            return `#ifdef USE_${role}\n ${name} *= surfaceRepeat;\n#endif`;
+        }).join("\n")}`);
+    };
+    material.customProgramCacheKey = () => `${previousKey}|authored-surface:${shape}:${tile}`;
+}
+/**
+ * Load declared surface-map roles and own the material/map clones (cached textures remain untouched).
+ * Colour, emissive, sheen-colour and specular-colour maps are sRGB; numeric maps are linear. Cylinder side metres use the RMS ellipse circumference approximation.
+ * Static batches and custom meshes share this lifecycle.
+ * @capability authored-surface-material render declared PBR maps with colour-space handling and metre-scale box/cylinder UVs
+ */
+export function useAuthoredSurfaceMaterial(config, shape = "box") {
+    const key = authoredSurfaceKey(config);
+    const entries = useMemo(() => modelMapEntries(config.maps ?? {}), [key]);
+    const loaded = useLoader(THREE.TextureLoader, Object.values(entries));
+    const resources = useDisposable(() => {
+        const textures = authoredSurfaceTextures(entries, loaded, config);
+        const { anisotropy: _samplerAnisotropy, surfaceAnisotropy, ...surface } = config;
+        const material = requiresPhysicalMaterial({ ...surface, normalScale: surface.normalScale === undefined ? undefined : [...surface.normalScale], anisotropy: surfaceAnisotropy }, textures) ? new THREE.MeshPhysicalMaterial() : new THREE.MeshStandardMaterial();
+        try {
+            configureAuthoredSurface(material, config, textures, shape);
+        }
+        catch (error) {
+            material.dispose();
+            Object.values(textures).forEach(texture => texture.dispose());
+            throw error;
+        }
+        return [material, ...Object.values(textures)];
+    }, [key, entries, loaded, shape]);
+    return resources[0];
+}
+/**
+ * Mount an owned PBR surface material on a mesh.
+ * @capability authored-surface-material mount an owned PBR surface material on a mesh
+ */
+export function AuthoredSurfaceMaterial({ surface, shape = "box" }) {
+    const material = useAuthoredSurfaceMaterial(surface, shape);
+    return _jsx("primitive", { object: material, attach: "material" });
+}

package/dist/render/materialAppearanceSignals.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from "three";
+import { type MaterialAppearanceBaseline, type MaterialAppearancePolicy, type MaterialAppearanceResponse } from "@jgengine/core/material/appearanceSignals";
+import type { EnvironmentSample } from "@jgengine/core/world/envField";
+/** Immutable resolved baseline for one caller-owned assigned material, including its original card exposure. */
+export interface RenderMaterialAppearanceBaseline extends MaterialAppearanceBaseline {
+    cardBacklightExposure: number;
+}
+/**
+ * Capture once after assignment; recapture after an authored change. Never capture an already wet material.
+ * @capability material-appearance-signals capture immutable resolved dry values from one owned assigned material
+ */
+export declare function captureMaterialAppearanceBaseline(material: THREE.MeshStandardMaterial): RenderMaterialAppearanceBaseline;
+/**
+ * Apply one sample to an already owned material. Imported/cache materials must be cloned before use.
+ * Allocates no textures or materials; clearcoat/sheen require an existing physical material and opt-in policy.
+ * @capability material-appearance-signals update one owned material from wetness and local card exposure without global lighting edits
+ */
+export declare function applyMaterialAppearanceSignals(material: THREE.MeshStandardMaterial, baseline: MaterialAppearanceBaseline, sample: EnvironmentSample, policy?: MaterialAppearancePolicy): MaterialAppearanceResponse;
+/**
+ * Restore the dry baseline when removing an appearance binding; maps and unrelated imported features remain borrowed.
+ * @capability material-appearance-signals restore dry material response when removing an environment appearance binding
+ */
+export declare function restoreMaterialAppearanceBaseline(material: THREE.MeshStandardMaterial, baseline: RenderMaterialAppearanceBaseline): void;

package/dist/render/materialAppearanceSignals.js

@@ -0,0 +1,58 @@
+import * as THREE from "three";
+import { resolveMaterialAppearance } from "@jgengine/core/material/appearanceSignals";
+import { setHairCardLightExposure } from "./materialAsset.js";
+/**
+ * Capture once after assignment; recapture after an authored change. Never capture an already wet material.
+ * @capability material-appearance-signals capture immutable resolved dry values from one owned assigned material
+ */
+export function captureMaterialAppearanceBaseline(material) {
+    const physical = material;
+    return Object.freeze({
+        roughness: material.roughness,
+        colorLinear: Object.freeze([material.color.r, material.color.g, material.color.b]),
+        ...(physical.isMeshPhysicalMaterial ? { sheen: physical.sheen, clearcoat: physical.clearcoat, clearcoatRoughness: physical.clearcoatRoughness } : {}),
+        cardBacklightExposure: material.userData.jgHairLightExposure ?? 1,
+    });
+}
+/**
+ * Apply one sample to an already owned material. Imported/cache materials must be cloned before use.
+ * Allocates no textures or materials; clearcoat/sheen require an existing physical material and opt-in policy.
+ * @capability material-appearance-signals update one owned material from wetness and local card exposure without global lighting edits
+ */
+export function applyMaterialAppearanceSignals(material, baseline, sample, policy = {}) {
+    if ((policy.wetness?.sheen !== undefined || policy.wetness?.clearcoat !== undefined) && !material.isMeshPhysicalMaterial)
+        throw new TypeError("Wet sheen or clearcoat requires an owned MeshPhysicalMaterial; declare the capability when assigning it.");
+    const response = resolveMaterialAppearance(sample, baseline, policy);
+    const physical = material;
+    if (response.surface.roughness !== undefined)
+        material.roughness = response.surface.roughness;
+    if (response.colorLinear !== undefined)
+        material.color.setRGB(...response.colorLinear, THREE.LinearSRGBColorSpace);
+    if (response.surface.sheen !== undefined)
+        physical.sheen = response.surface.sheen;
+    if (response.surface.clearcoat !== undefined)
+        physical.clearcoat = response.surface.clearcoat;
+    if (response.surface.clearcoatRoughness !== undefined)
+        physical.clearcoatRoughness = response.surface.clearcoatRoughness;
+    if (response.backlightExposure !== undefined)
+        setHairCardLightExposure(material, response.backlightExposure);
+    return response;
+}
+/**
+ * Restore the dry baseline when removing an appearance binding; maps and unrelated imported features remain borrowed.
+ * @capability material-appearance-signals restore dry material response when removing an environment appearance binding
+ */
+export function restoreMaterialAppearanceBaseline(material, baseline) {
+    if ((baseline.sheen !== undefined || baseline.clearcoat !== undefined) && !material.isMeshPhysicalMaterial)
+        throw new TypeError("The appearance baseline belongs to a physical material.");
+    material.roughness = baseline.roughness;
+    material.color.setRGB(...baseline.colorLinear, THREE.LinearSRGBColorSpace);
+    const physical = material;
+    if (baseline.sheen !== undefined)
+        physical.sheen = baseline.sheen;
+    if (baseline.clearcoat !== undefined)
+        physical.clearcoat = baseline.clearcoat;
+    if (baseline.clearcoatRoughness !== undefined)
+        physical.clearcoatRoughness = baseline.clearcoatRoughness;
+    setHairCardLightExposure(material, baseline.cardBacklightExposure);
+}