@jgengine/shell 0.18.1 → 0.21.0

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/displayColor.d.ts

@@ -0,0 +1,33 @@
+import { type Color, type ToneMapping } from "three";
+type Rgb = [number, number, number];
+/**
+ * three.js r182's tone-mapping curve for `mode`, applied to a linear scene color at `exposure`.
+ * Mirrors `tonemapping_pars_fragment`; `NoToneMapping` and custom curves pass through.
+ * @internal
+ */
+export declare function toneMapColor(color: readonly [number, number, number], mode: ToneMapping, exposure?: number): Rgb;
+/**
+ * The linear scene color that `mode` at `exposure` displays as `display` (linear sRGB, 0..1).
+ * Sky and fog colors are picked as on-screen swatches, but the output pass tone-maps them like
+ * lit surfaces, which turns a pale horizon grey. Solved by fixed-point iteration because AgX and
+ * ACES mix channels; a swatch a curve cannot reach (pure white, a saturated highlight under AgX)
+ * lands on the closest color it can show.
+ * @internal
+ */
+export declare function sceneColorForDisplay(display: readonly [number, number, number], mode: ToneMapping, exposure?: number): Rgb;
+/**
+ * Writes the scene color that displays as `display` into `target`, recomputing only when the
+ * swatch or the renderer's tone mapping changes, so per-frame sky drivers stay allocation-free.
+ * @internal
+ */
+export declare class DisplayColorWriter {
+    private hex;
+    private mode;
+    private exposure;
+    private scene;
+    write(target: Color, display: Color, renderer: {
+        toneMapping: ToneMapping;
+        toneMappingExposure: number;
+    }): void;
+}
+export {};

package/dist/render/displayColor.js

@@ -0,0 +1,138 @@
+import { ACESFilmicToneMapping, AgXToneMapping, CineonToneMapping, LinearToneMapping, NeutralToneMapping, ReinhardToneMapping, } from "three";
+const saturate = (x) => Math.min(1, Math.max(0, x));
+/** GLSL `mat3(c0, c1, c2) * v` with the columns three's tonemapping chunk declares. */
+function mat3(c, v) {
+    return [
+        c[0][0] * v[0] + c[1][0] * v[1] + c[2][0] * v[2],
+        c[0][1] * v[0] + c[1][1] * v[1] + c[2][1] * v[2],
+        c[0][2] * v[0] + c[1][2] * v[1] + c[2][2] * v[2],
+    ];
+}
+const ACES_IN = [[0.59719, 0.076, 0.0284], [0.35458, 0.90834, 0.13383], [0.04823, 0.01566, 0.83777]];
+const ACES_OUT = [[1.60475, -0.10208, -0.00327], [-0.53108, 1.10813, -0.07276], [-0.07367, -0.00605, 1.07602]];
+const REC2020_TO_SRGB = [[1.6605, -0.1246, -0.0182], [-0.5876, 1.1329, -0.1006], [-0.0728, -0.0083, 1.1187]];
+const SRGB_TO_REC2020 = [[0.6274, 0.0691, 0.0164], [0.3293, 0.9195, 0.088], [0.0433, 0.0113, 0.8956]];
+const AGX_INSET = [
+    [0.856627153315983, 0.137318972929847, 0.11189821299995],
+    [0.0951212405381588, 0.761241990602591, 0.0767994186031903],
+    [0.0482516061458583, 0.101439036467562, 0.811302368396859],
+];
+const AGX_OUTSET = [
+    [1.1271005818144368, -0.1413297634984383, -0.14132976349843826],
+    [-0.11060664309660323, 1.157823702216272, -0.11060664309660294],
+    [-0.016493938717834573, -0.016493938717834257, 1.2519364065950405],
+];
+const AGX_MIN_EV = -12.47393;
+const AGX_MAX_EV = 4.026069;
+function aces(c) {
+    const v = mat3(ACES_IN, [c[0] / 0.6, c[1] / 0.6, c[2] / 0.6]);
+    const fit = v.map((x) => (x * (x + 0.0245786) - 0.000090537) / (x * (0.983729 * x + 0.432951) + 0.238081));
+    return mat3(ACES_OUT, fit).map(saturate);
+}
+function agx(c) {
+    const inset = mat3(AGX_INSET, mat3(SRGB_TO_REC2020, c));
+    const curved = inset.map((x) => {
+        const t = saturate((Math.log2(Math.max(x, 1e-10)) - AGX_MIN_EV) / (AGX_MAX_EV - AGX_MIN_EV));
+        const t2 = t * t;
+        const t4 = t2 * t2;
+        return 15.5 * t4 * t2 - 40.14 * t4 * t + 31.96 * t4 - 6.868 * t2 * t + 0.4298 * t2 + 0.1191 * t - 0.00232;
+    });
+    const out = mat3(AGX_OUTSET, curved).map((x) => Math.pow(Math.max(0, x), 2.2));
+    return mat3(REC2020_TO_SRGB, out).map(saturate);
+}
+function neutral(input) {
+    const x = Math.min(input[0], input[1], input[2]);
+    const offset = x < 0.08 ? x - 6.25 * x * x : 0.04;
+    const c = input.map((v) => v - offset);
+    const peak = Math.max(c[0], c[1], c[2]);
+    const start = 0.76;
+    if (peak < start)
+        return c;
+    const d = 1 - start;
+    const newPeak = 1 - (d * d) / (peak + d - start);
+    const g = 1 - 1 / (0.15 * (peak - newPeak) + 1);
+    return c.map((v) => v * (newPeak / peak) * (1 - g) + newPeak * g);
+}
+/**
+ * three.js r182's tone-mapping curve for `mode`, applied to a linear scene color at `exposure`.
+ * Mirrors `tonemapping_pars_fragment`; `NoToneMapping` and custom curves pass through.
+ * @internal
+ */
+export function toneMapColor(color, mode, exposure = 1) {
+    const c = [color[0] * exposure, color[1] * exposure, color[2] * exposure];
+    switch (mode) {
+        case LinearToneMapping:
+            return c.map(saturate);
+        case ReinhardToneMapping:
+            return c.map((x) => saturate(x / (1 + x)));
+        case CineonToneMapping:
+            return c.map((v) => {
+                const x = Math.max(0, v - 0.004);
+                return Math.pow((x * (6.2 * x + 0.5)) / (x * (6.2 * x + 1.7) + 0.06), 2.2);
+            });
+        case ACESFilmicToneMapping:
+            return aces(c);
+        case AgXToneMapping:
+            return agx(c);
+        case NeutralToneMapping:
+            return neutral(c);
+        default:
+            return c;
+    }
+}
+const CURVED = new Set([ReinhardToneMapping, CineonToneMapping, ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping]);
+/** Keeps a compensated sky inside half-float range; the brightest pastel under AgX needs ~13. */
+const MAX_SCENE_VALUE = 32;
+/**
+ * The linear scene color that `mode` at `exposure` displays as `display` (linear sRGB, 0..1).
+ * Sky and fog colors are picked as on-screen swatches, but the output pass tone-maps them like
+ * lit surfaces, which turns a pale horizon grey. Solved by fixed-point iteration because AgX and
+ * ACES mix channels; a swatch a curve cannot reach (pure white, a saturated highlight under AgX)
+ * lands on the closest color it can show.
+ * @internal
+ */
+export function sceneColorForDisplay(display, mode, exposure = 1) {
+    const target = [saturate(display[0]), saturate(display[1]), saturate(display[2])];
+    if (mode === LinearToneMapping)
+        return target.map((v) => v / Math.max(exposure, 1e-6));
+    if (!CURVED.has(mode))
+        return target;
+    const scene = [...target];
+    let best = [...target];
+    let bestError = Number.POSITIVE_INFINITY;
+    for (let iteration = 0; iteration < 48; iteration += 1) {
+        const shown = toneMapColor(scene, mode, exposure);
+        const error = Math.abs(shown[0] - target[0]) + Math.abs(shown[1] - target[1]) + Math.abs(shown[2] - target[2]);
+        if (error < bestError) {
+            bestError = error;
+            best = [scene[0], scene[1], scene[2]];
+        }
+        for (let channel = 0; channel < 3; channel += 1) {
+            // Clamped so a channel a curve's toe or shoulder cannot reach does not blow up its neighbors.
+            const ratio = Math.min(2, Math.max(0.5, Math.max(target[channel], 1e-5) / Math.max(shown[channel], 1e-5)));
+            scene[channel] = Math.min(MAX_SCENE_VALUE, Math.max(1e-5, scene[channel] * Math.pow(ratio, 0.8)));
+        }
+    }
+    return best;
+}
+/**
+ * Writes the scene color that displays as `display` into `target`, recomputing only when the
+ * swatch or the renderer's tone mapping changes, so per-frame sky drivers stay allocation-free.
+ * @internal
+ */
+export class DisplayColorWriter {
+    hex = -1;
+    mode = -1;
+    exposure = Number.NaN;
+    scene = [0, 0, 0];
+    write(target, display, renderer) {
+        const hex = display.getHex();
+        if (hex !== this.hex || renderer.toneMapping !== this.mode || renderer.toneMappingExposure !== this.exposure) {
+            this.hex = hex;
+            this.mode = renderer.toneMapping;
+            this.exposure = renderer.toneMappingExposure;
+            this.scene = sceneColorForDisplay([display.r, display.g, display.b], this.mode, this.exposure);
+        }
+        target.setRGB(this.scene[0], this.scene[1], this.scene[2]);
+    }
+}

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

package/dist/render/materialAsset.d.ts

@@ -0,0 +1,98 @@
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import * as THREE from "three";
+import { type MaterialAsset, type MaterialAssignment, type MaterialAssignmentValidationOptions, type MaterialSurfaceParameters, type MaterialTextureMetadata, type MaterialTextureRole } from "@jgengine/core/material/materialAsset";
+import { type MaterialOverrideTextures } from "../materialOverride.js";
+import { type SurfaceShape } from "./authoredSurfaceMaterial.js";
+/** Shares the model transcoder and loader cache while loading native authored images normally. @internal */
+export declare class MaterialTextureLoader extends THREE.Loader<THREE.Texture> {
+    load(url: string, onLoad?: (texture: THREE.Texture) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
+}
+/**
+ * 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 declare function configureMaterialTexture(role: MaterialTextureRole, metadata: MaterialTextureMetadata, source: THREE.Texture): THREE.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 declare function materialAssetSurface(asset: MaterialAsset, overrides?: MaterialSurfaceParameters): MaterialSurfaceParameters;
+/**
+ * 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 declare function applyMaterialAsset(material: THREE.Material, asset: MaterialAsset, textures?: MaterialOverrideTextures, overrides?: MaterialSurfaceParameters): THREE.MeshStandardMaterial;
+/** Read-only target validation policy; source coverage can reflect an earlier all-slot override. */
+export interface MaterialAssignmentTargetOptions extends MaterialAssignmentValidationOptions {
+    /** Coverage applied to every imported slot before named assignments; never mutates the source. */
+    baseAlphaMode?: MaterialSurfaceParameters["alphaMode"];
+}
+/**
+ * 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 declare function validateMaterialAssignmentTargets(root: THREE.Object3D, assets: readonly MaterialAsset[], assignments: readonly MaterialAssignment[], options?: MaterialAssignmentTargetOptions): void;
+/**
+ * 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 declare function applyMaterialAssignments(root: THREE.Object3D, assets: readonly MaterialAsset[], assignments: readonly MaterialAssignment[], textures?: ReadonlyMap<string, MaterialOverrideTextures>): THREE.Material[];
+/** Reusable primitive surface options; physical metre UVs reuse the instanced surface renderer. */
+export interface MaterialAssetSurfaceOptions {
+    shape?: SurfaceShape;
+    repeatMetres?: number;
+    overrides?: MaterialSurfaceParameters;
+}
+/**
+ * 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 declare function useMaterialAssetMaterial(asset: MaterialAsset, options?: MaterialAssetSurfaceOptions): THREE.MeshStandardMaterial;
+/**
+ * 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 declare function MaterialAssetSurface({ asset, ...options }: {
+    asset: MaterialAsset;
+} & MaterialAssetSurfaceOptions): import("react").JSX.Element;
+/**
+ * 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 declare function materialResourceMetrics(materials: readonly THREE.Material[]): {
+    materials: number;
+    textures: number;
+    textureBytes: number;
+    unknownTextureSizes: number;
+    blendedMaterials: number;
+    maskedMaterials: number;
+    transmissionMaterials: number;
+    doubleSidedMaterials: number;
+    physicalMaterials: number;
+};
+/** Runtime imported-slot inventory for precise authoring selectors; indices address the mesh material array. */
+export interface ModelMaterialSlotInfo {
+    mesh: string;
+    slot: string;
+    slotIndex: number;
+    materialType: string;
+    uvSets: number[];
+    tangents: boolean;
+    physical: boolean;
+}
+/**
+ * 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 declare function inspectModelMaterialSlots(root: THREE.Object3D): ModelMaterialSlotInfo[];
+/** Loaded, owned map views for one model configuration. Loader sources and imported maps remain borrowed. @internal */
+export declare function useModelMaterialTextures(model: Pick<ModelConfig, "material" | "materialAssets" | "materialAssignments">): {
+    global: MaterialOverrideTextures;
+    assets: ReadonlyMap<string, MaterialOverrideTextures>;
+};
+/**
+ * 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 declare function setHairCardLightExposure(material: THREE.Material, exposure: number): void;