@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/src/rock-shader/rockShaderRuntime.js

@@ -3,12 +3,26 @@ import {
   createToonRockMaterial,
   normalizeToonLabRockProfile,
 } from './rockMaterial.js';
+import { applyRockGeometryDetail } from './rockGeometryDetail.js';
+
+/**
+ * Weight of the concavity channel in the moss moisture term.
+ *
+ * `moisture = clamp(slope + cavity * strength)`. At 1.6 a fully concave crevice
+ * reaches saturation on its own, so moss grows in a vertical cleft that the
+ * slope term scores at zero, while an exposed convex face still depends on
+ * slope alone and stays bare.
+ */
+export const ROCK_MOSS_CAVITY_STRENGTH = 1.6;
 import { createRockShaderSettings } from './rockShaderSettings.js';
 import { markFactoryStyleMaterial } from '../styles/styleMetadata.js';
+import { withoutDegenerateDetailMaps } from './rockTextureIntegrity.js';
+import { inspectRockRegionBindings } from './rockRegionRuntime.js';
+import { sanitizeRockTangents } from './rockTangentIntegrity.js';
 
 const ORIGINAL_MATERIALS = new WeakMap();
 const ORIGINAL_SHADOW_FLAGS = new WeakMap();
-let defaultTextureSet = null;
+const textureSetsByVariation = new Map();
 
 function clamp01(value) {
   return Math.min(1, Math.max(0, Number(value) || 0));
@@ -77,16 +91,22 @@ function makeProceduralTexture({
 }
 
 /**
- * Creates the neutral, deterministic fallback texture set used by the
- * Call Me Sensei rock shader. Applications can replace any map with authored
- * or licensed textures without changing the shader preset.
+ * Offsets every fallback map's seed by a variation index.
+ *
+ * Two rocks that resolve to the same fallback maps render with identical
+ * surface breakup. That reads as one rock duplicated — the failure §13 calls a
+ * "repeated prop pattern" — so a scene placing several rocks from one family
+ * needs a way to decorrelate them without authoring bespoke textures for each.
+ * Seed 0 reproduces the reviewed first-party set exactly.
  */
-export function createDefaultRockShaderTextureSet() {
-  if (defaultTextureSet) return defaultTextureSet;
+function variationSeed(base, variation) {
+  return base + (variation * 101);
+}
 
-  defaultTextureSet = Object.freeze({
+function buildRockShaderTextureSet(variation) {
+  return Object.freeze({
     rock: makeProceduralTexture({
-      seed: 3,
+      seed: variationSeed(3, variation),
       // Measured sRGB mean of the captured first-party T_RockClassic_BC input
       // (179.70, 179.92, 178.98). Keeping the deterministic fallback anchored
       // to that source lets the shader produce its reviewed grey sun face and
@@ -97,61 +117,85 @@ export function createDefaultRockShaderTextureSet() {
       variation: 0.18,
     }),
     rockNormal: makeProceduralTexture({
-      seed: 5,
+      seed: variationSeed(5, variation),
       color: [0.5, 0.5, 1],
       variation: 0,
       colorSpace: THREE.NoColorSpace,
       channel: 'normal',
     }),
     smoothness: makeProceduralTexture({
-      seed: 7,
+      seed: variationSeed(7, variation),
       color: [0.33, 0.33, 0.33],
       variation: 0.12,
       colorSpace: THREE.NoColorSpace,
       channel: 'mask',
     }),
     stripe: makeProceduralTexture({
-      seed: 13,
+      seed: variationSeed(13, variation),
       color: [0.58, 0.55, 0.5],
       variation: 0.2,
     }),
     moss: makeProceduralTexture({
-      seed: 17,
+      seed: variationSeed(17, variation),
       color: [0.3, 0.42, 0.2],
       variation: 0.16,
     }),
     grass: makeProceduralTexture({
-      seed: 19,
+      seed: variationSeed(19, variation),
       color: [0.32, 0.48, 0.19],
       variation: 0.14,
     }),
     snow: makeProceduralTexture({
-      seed: 23,
+      seed: variationSeed(23, variation),
       color: [0.88, 0.91, 0.94],
       variation: 0.06,
     }),
     sand: makeProceduralTexture({
-      seed: 29,
+      seed: variationSeed(29, variation),
       color: [0.7, 0.58, 0.39],
       variation: 0.1,
     }),
     sandNormal: makeProceduralTexture({
-      seed: 31,
+      seed: variationSeed(31, variation),
       color: [0.5, 0.5, 1],
       variation: 0,
       colorSpace: THREE.NoColorSpace,
       channel: 'normal',
     }),
     topMask: makeProceduralTexture({
-      seed: 37,
+      seed: variationSeed(37, variation),
       color: [0.56, 0.56, 0.56],
       variation: 0.3,
       colorSpace: THREE.NoColorSpace,
       channel: 'mask',
     }),
   });
+}
 
-  return defaultTextureSet;
+/**
+ * Creates the neutral, deterministic fallback texture set used by the
+ * Call Me Sensei rock shader. Applications can replace any map with authored
+ * or licensed textures without changing the shader preset.
+ *
+ * `variation` decorrelates the generated maps so several rocks sharing one
+ * catalog family do not render with identical surface breakup. Sets are
+ * memoized per variation index and are deterministic: the same index always
+ * yields the same maps. Index 0 is the reviewed first-party set.
+ *
+ * @param {{variation?: number}} [options]
+ */
+export function createRockShaderTextureSet({ variation = 0 } = {}) {
+  const index = Number.isFinite(Number(variation)) ? Math.trunc(Number(variation)) : 0;
+  const existing = textureSetsByVariation.get(index);
+  if (existing) return existing;
+  const set = buildRockShaderTextureSet(index);
+  textureSetsByVariation.set(index, set);
+  return set;
+}
+
+/** The reviewed first-party fallback set (`variation: 0`). */
+export function createDefaultRockShaderTextureSet() {
+  return createRockShaderTextureSet({ variation: 0 });
 }
 
 function tintArray(value, fallback) {
@@ -211,60 +255,59 @@ export function rockShaderSettingsToProfile(input = {}) {
     lighting: {
       exposure: lighting.exposure,
       ambientFloor: lighting.ambientFloor,
+      skyColorInfluence: lighting.skyColorInfluence,
       skyFillStrength: lighting.skyFillStrength,
       skyFillTint: tintArray(lighting.skyFillTint, [1, 1, 1]),
+      shadowFill: lighting.shadowFill,
+      shadowFillTint: tintArray(lighting.shadowFillTint, [1, 1, 1]),
     },
-    shoreline: {
-      wetBandWidth: shoreline.wetBandWidth,
-      wetBandDarkening: shoreline.wetBandDarkening,
-      wetRoughness: shoreline.wetRoughness,
-    },
-    normals: {
-      distance: normals.distance,
-      nearFlatten: normals.nearFlatten,
-      farFlatten: normals.farFlatten,
-      useSmoothed: normals.useSmoothed,
-      normalGreenSign: normals.normalGreenSign,
-    },
+    // SPREAD, not an allow-list — the same trap the moss group was carrying.
+    // These two settings groups map onto identically named profile groups, so
+    // naming each field bought nothing and cost a silent drop for any field
+    // added later. See the longer note on `moss` below.
+    shoreline: { ...shoreline },
+    normals: { ...normals },
     moss: {
-      enabled: moss.enabled,
-      size: moss.size,
-      sharpness: moss.sharpness,
-      offset: moss.offset,
-      multiply: moss.multiply,
-      colorPower: moss.colorPower,
+      // SPREAD, not an allow-list. This mapping used to name every field, so
+      // a field added to the settings schema was silently dropped here —
+      // between validation and the shader — with no error anywhere. Adding a
+      // moss capability then required edits in four separate files and failed
+      // invisibly if you missed one. The settings object is already
+      // schema-validated and clamped by `createRockShaderSettings`, so
+      // forwarding it wholesale is both safer and correct; the entries below
+      // exist only to coerce types the profile wants in a different shape.
+      // `scripts/verify-rock-shader.mjs` asserts schema/profile parity so this
+      // cannot silently regress.
+      ...moss,
       lowColor: tintArray(moss.lowColor, [0.18, 0.28, 0.09]),
       highColor: tintArray(moss.highColor, [0.42, 0.55, 0.2]),
     },
+    // The layer groups DO get renamed on the way through — the settings schema
+    // exposes `layerMask` / `grassLayer` / `snowLayer` / `sandLayer` and the
+    // profile wants `layers.{maskEnabled, sharpness, offset, grass, snow,
+    // sand}` — so the group names are mapped explicitly. The FIELDS inside each
+    // group are spread, because those names are shared and an allow-list there
+    // is the same silent-drop trap the moss group was carrying: a new sand or
+    // grass field would pass validation, be clamped, and then vanish before the
+    // shader with no error at any layer. Only `useAssetMask` -> `maskEnabled`
+    // is genuinely renamed, and the `tint` entries coerce a shape the profile
+    // wants differently. `scripts/verify-rock-shader.mjs` asserts parity for
+    // every group so this cannot silently regress again.
     layers: {
-      maskEnabled: layerMask.useAssetMask,
       sharpness: layerMask.sharpness,
       offset: layerMask.offset,
+      maskEnabled: layerMask.useAssetMask,
       grass: {
-        enabled: grassLayer.enabled,
-        useGroundShader: grassLayer.useGroundShader,
-        scale: grassLayer.scale,
+        ...grassLayer,
         tint: tintArray(grassLayer.tint, [0.48, 0.65, 0.3]),
-        saturation: grassLayer.saturation,
-        emission: grassLayer.emission,
       },
       snow: {
-        enabled: snowLayer.enabled,
-        scale: snowLayer.scale,
+        ...snowLayer,
         tint: tintArray(snowLayer.tint, [0.9, 0.93, 0.96]),
-        saturation: snowLayer.saturation,
-        emission: snowLayer.emission,
       },
       sand: {
-        enabled: sandLayer.enabled,
-        useGroundShader: sandLayer.useGroundShader,
-        scale: sandLayer.scale,
+        ...sandLayer,
         tint: tintArray(sandLayer.tint, [0.72, 0.59, 0.4]),
-        saturation: sandLayer.saturation,
-        emission: sandLayer.emission,
-        normalScale: sandLayer.normalScale,
-        normalStrength: sandLayer.normalStrength,
-        normalRotationDegrees: sandLayer.normalRotationDegrees,
       },
     },
   });
@@ -294,20 +337,91 @@ function disposeOwnedMaterial(material) {
 }
 
 function createMaterialForSource({
+  vertexCavityStrength = 0,
+  rockRegionEnabled = false,
   sourceMaterial,
   settings,
   profile,
   textures,
   name,
+  variation = 0,
+  degenerateMaps = null,
+  surfaceState = 'source',
 }) {
-  const fallback = createDefaultRockShaderTextureSet();
+  const semantic = sourceMaterial?.userData?.toonlabRockSemanticMaterial ?? null;
+  const fallback = semantic ? {} : createRockShaderTextureSet({ variation });
+  // A placeholder in a real slot is worse than an empty slot: it silently
+  // displaces the deterministic fallback, which is a usable surface. Drop
+  // degenerate maps here so every consumer of the shader is protected, not
+  // only the ones that remembered to filter before calling.
+  const provided = withoutDegenerateDetailMaps(textures);
+  if (degenerateMaps && provided.rejected.length > 0) {
+    degenerateMaps.push(...provided.rejected);
+  }
   const textureSet = {
     ...fallback,
-    ...textures,
+    ...(semantic?.textures ?? {}),
+    ...provided.textures,
   };
 
+  let materialProfile = profile;
+  if (semantic) {
+    materialProfile = structuredClone(semantic.profile);
+    // Scene state and coordinated lighting remain style-owned; source material
+    // identity (projection, PBR, masks, and layer inputs) remains set-owned.
+    materialProfile.lighting = structuredClone(profile.lighting);
+    materialProfile.shoreline = structuredClone(profile.shoreline);
+    materialProfile.base = {
+      ...materialProfile.base,
+      closeTintDistance: profile.base.closeTintDistance,
+      distantTint: profile.base.distantTint,
+      distantTintMix: profile.base.distantTintMix,
+      farTintDistance: profile.base.farTintDistance,
+      nearDetailDistance: profile.base.nearDetailDistance,
+      nearDetailScale: profile.base.nearDetailScale,
+      nearDetailStrength: profile.base.nearDetailStrength,
+    };
+    const selected = surfaceState === 'source'
+      ? null
+      : ['none', 'grass', 'sand', 'snow'].includes(surfaceState)
+        ? surfaceState
+        : (() => { throw new TypeError(`Unknown rock surface state: ${surfaceState}`); })();
+    if (selected !== null) {
+      for (const role of ['grass', 'sand', 'snow']) {
+        materialProfile.layers[role].enabled = selected === role;
+      }
+      if (selected !== 'none') {
+        // An explicit replacement state is a ToonLab-authored cap, not the
+        // source graph's often-disabled top-layer default. Keep all four mask
+        // signals active while using a production-visible coverage range.
+        materialProfile.layers.maskEnabled = true;
+        materialProfile.layers.offset = 0.2;
+        materialProfile.layers.sharpness = 4;
+        materialProfile.layers.heightStart = 0.15;
+        materialProfile.layers.heightEnd = 0.7;
+        materialProfile.layers.cavityStrength = Math.max(
+          0.2,
+          Number(materialProfile.layers.cavityStrength ?? 0),
+        );
+        materialProfile.layers.exposureStrength = Math.max(
+          0.2,
+          Number(materialProfile.layers.exposureStrength ?? 0),
+        );
+        materialProfile.layers.semanticMaskStrength = Math.max(
+          0.15,
+          Number(materialProfile.layers.semanticMaskStrength ?? 0),
+        );
+      }
+      if (selected !== 'none' && !textureSet[selected]?.isTexture) {
+        throw new Error(
+          `Rock material set ${semantic.materialSetId} has no faithful ${selected} layer input.`,
+        );
+      }
+    }
+  }
+
   const sourceAlbedoMode = settings.assetIntegration.sourceAlbedoMode;
-  const sourceAlbedoStrength = sourceAlbedoMode === 'retain'
+  const sourceAlbedoStrength = semantic ? 0 : sourceAlbedoMode === 'retain'
     ? 1
     : sourceAlbedoMode === 'blend'
       ? settings.assetIntegration.sourceAlbedoStrength
@@ -316,11 +430,27 @@ function createMaterialForSource({
     textureSet.sourceRock = sourceMaterial.map;
   }
   if (settings.assetIntegration.sourceNormalStrength > 0 && sourceMaterial?.normalMap) {
-    textureSet.sourceNormal = sourceMaterial.normalMap;
+    const sourceNormals = withoutDegenerateDetailMaps({
+      sourceNormal: sourceMaterial.normalMap,
+    });
+    if (sourceNormals.textures.sourceNormal) {
+      textureSet.sourceNormal = sourceNormals.textures.sourceNormal;
+    } else if (degenerateMaps) {
+      degenerateMaps.push(...sourceNormals.rejected);
+    }
   }
   if (sourceAlbedoStrength > 0 && sourceMaterial?.roughnessMap) {
     textureSet.sourceRoughness = sourceMaterial.roughnessMap;
   }
+  if (sourceAlbedoStrength > 0 && sourceMaterial?.metalnessMap) {
+    textureSet.sourceMetalness = sourceMaterial.metalnessMap;
+  }
+  if (sourceAlbedoStrength > 0 && sourceMaterial?.specularIntensityMap) {
+    textureSet.sourceSpecular = sourceMaterial.specularIntensityMap;
+  }
+  if (sourceAlbedoStrength > 0 && sourceMaterial?.emissiveMap) {
+    textureSet.sourceEmissive = sourceMaterial.emissiveMap;
+  }
   if (settings.assetIntegration.sourceAoStrength > 0 && sourceMaterial?.aoMap) {
     textureSet.sourceAo = sourceMaterial.aoMap;
   }
@@ -329,8 +459,34 @@ function createMaterialForSource({
     assetIntegration: {
       ...settings.assetIntegration,
       sourceAlbedoStrength,
+      sourceColor: sourceMaterial?.color?.toArray?.() ?? [1, 1, 1],
+      sourceEmissive: sourceMaterial?.emissive?.toArray?.() ?? [0, 0, 0],
+      sourceEmissiveIntensity: Number(sourceMaterial?.emissiveIntensity ?? 1),
+      sourceOpacity: Number(sourceMaterial?.opacity ?? 1),
+      sourceAlphaTest: Number(sourceMaterial?.alphaTest ?? 0),
+      sourceTransparent: Boolean(sourceMaterial?.transparent),
+      sourceDepthWrite: sourceMaterial?.depthWrite !== false,
+      sourceSide: Number.isInteger(sourceMaterial?.side) ? sourceMaterial.side : null,
+      sourceMetalnessFactor: Number(sourceMaterial?.metalness ?? 0),
+      sourceRoughnessFactor: Number(sourceMaterial?.roughness ?? 1),
+      sourceSpecularFactor: Number(sourceMaterial?.specularIntensity ?? 1),
+      primaryNormalStrength: Number(
+        semantic?.binding?.materialVariation?.normalGain ?? 1,
+      ),
+      primarySpecularStrength: Number(
+        semantic?.binding?.materialVariation?.specularGain ?? 1,
+      ),
+      semanticMaskAttributes: Boolean(semantic),
+      rockRegionAttributes: rockRegionEnabled,
+      regionTintStrength: settings.assetIntegration.regionTintStrength,
+      regionBaseTint: settings.assetIntegration.regionBaseTint,
+      regionShaftTint: settings.assetIntegration.regionShaftTint,
+      regionNeckTint: settings.assetIntegration.regionNeckTint,
+      regionCapTint: settings.assetIntegration.regionCapTint,
+      regionNeckOverlayStrength: settings.assetIntegration.regionNeckOverlayStrength,
+      vertexCavityStrength,
     },
-    profile,
+    profile: materialProfile,
     textures: textureSet,
     name,
   });
@@ -338,21 +494,78 @@ function createMaterialForSource({
   rockMaterial.userData.toonLabRockShaderPreset = settings.preset;
   rockMaterial.userData.toonLabRockTextureSource = textures?.rock
     ? 'provided'
-    : 'first-party-generated';
+    : semantic
+      ? 'shared-semantic-material-set'
+      : 'first-party-generated';
   rockMaterial.userData.toonlabSourceTextureIds = [...new Set([
+    ...Object.values(semantic?.textures ?? {}),
     textureSet.sourceRock,
     textureSet.sourceNormal,
     textureSet.sourceRoughness,
+    textureSet.sourceMetalness,
+    textureSet.sourceSpecular,
+    textureSet.sourceEmissive,
     textureSet.sourceAo,
   ].filter((texture) => texture?.isTexture && texture.uuid).map((texture) => texture.uuid))];
   rockMaterial.userData.toonLabRockTextureComposition = {
-    base: textures?.rock ? 'provided' : 'first-party-generated',
+    base: textures?.rock
+      ? 'provided'
+      : semantic
+        ? 'shared-semantic-material-set'
+        : 'first-party-generated',
     sourceAlbedoMode,
     sourceAlbedoStrength,
     sourceNormalStrength: settings.assetIntegration.sourceNormalStrength,
     sourceAoStrength: settings.assetIntegration.sourceAoStrength,
+    sourcePbrChannels: {
+      primaryAo: Boolean(textureSet.rockAo),
+      albedo: Boolean(textureSet.sourceRock),
+      alphaCutout: Boolean(textureSet.sourceRock && sourceMaterial?.alphaTest > 0),
+      emissive: Boolean(textureSet.sourceEmissive),
+      metallicRoughness: Boolean(textureSet.sourceMetalness || textureSet.sourceRoughness),
+      normal: Boolean(textureSet.sourceNormal),
+      occlusion: Boolean(textureSet.sourceAo),
+      specular: Boolean(textureSet.sourceSpecular),
+    },
     sourceTextureCount: rockMaterial.userData.toonlabSourceTextureIds.length,
   };
+  if (semantic) {
+    rockMaterial.userData.toonLabRockTextureComposition.materialSetId = semantic.materialSetId;
+    rockMaterial.userData.toonLabRockTextureComposition.surfaceState = surfaceState;
+    rockMaterial.userData.toonLabRockTextureComposition.sourcePbrChannels = {
+      albedo: Boolean(textureSet.rock),
+      normal: Boolean(textureSet.rockNormal),
+      smoothness: Boolean(textureSet.smoothness),
+      topMask: Boolean(textureSet.topMask),
+      grass: Boolean(textureSet.grass),
+      grassRoughness: Boolean(textureSet.grassRoughness),
+      sand: Boolean(textureSet.sand),
+      sandNormal: Boolean(textureSet.sandNormal),
+      snow: Boolean(textureSet.snow),
+      moss: Boolean(textureSet.moss),
+    };
+    const activeLayer = ['grass', 'snow', 'sand']
+      .filter((role) => materialProfile.layers?.[role]?.enabled)
+      .at(-1) ?? 'rock';
+    rockMaterial.userData.toonlabRockActiveSurfaceResponse = {
+      activeLayer,
+      color: activeLayer === 'rock' ? textureSet.rock?.uuid : textureSet[activeLayer]?.uuid,
+      normal: activeLayer === 'sand' && materialProfile.layers.sand.normalStrength > 0
+        ? textureSet.sandNormal?.uuid
+        : activeLayer === 'rock'
+          ? textureSet.rockNormal?.uuid
+          : null,
+      roughness: activeLayer === 'grass' && textureSet.grassRoughness
+        ? textureSet.grassRoughness.uuid
+        : materialProfile.layers?.[activeLayer]?.roughness ?? null,
+    };
+    rockMaterial.userData.toonlabRockProjectionContract = {
+      normalBlend: 'whiteout-world-to-tangent',
+      primary: 'world-space-triplanar',
+      scaleCompensation: 'absolute-world-position',
+      texelDensityInvariantUnderNonUniformScale: true,
+    };
+  }
   rockMaterial.userData.environmentShaderExclude = true;
   return markFactoryStyleMaterial(rockMaterial, 'RockSurface');
 }
@@ -362,6 +575,8 @@ export function createRockShaderMaterial({
   textures = {},
   sourceMaterial = null,
   name = 'Call Me Sensei Rock',
+  variation = 0,
+  surfaceState = 'source',
 } = {}) {
   const settings = createRockShaderSettings(input);
   return createMaterialForSource({
@@ -369,6 +584,8 @@ export function createRockShaderMaterial({
     settings,
     profile: rockShaderSettingsToProfile(settings),
     textures,
+    variation,
+    surfaceState,
     name,
   });
 }
@@ -384,19 +601,65 @@ export function applyRockShader(root, input = {}, {
   name = 'Call Me Sensei Rock',
   castShadow = true,
   receiveShadow = true,
+  variation = 0,
+  surfaceState = 'source',
+  detail = null,
 } = {}) {
   const settings = createRockShaderSettings(input);
+  const rockRegionEnabled = settings.assetIntegration.regionTintStrength > 0;
+  if (rockRegionEnabled && detail) {
+    throw new Error('Rock-region styling cannot run with geometry detail; rebuild semantic masks after geometry changes.');
+  }
+  const rockRegionInspection = rockRegionEnabled
+    ? inspectRockRegionBindings(root, { requireEveryMesh: true, sampleValues: true })
+    : null;
+  // Geometry detail runs before anything reads or writes vertex attributes:
+  // subdivision replaces every buffer, so a color/AO attribute built first
+  // would be sized to the old vertex count. Opt-in — most placements are not
+  // close enough to need it, and it multiplies triangles by 4^subdivisions.
+  const geometryDetail = detail
+    ? applyRockGeometryDetail(root, { variation, ...(detail === true ? {} : detail) })
+    : null;
+  // A present-but-zero tangent attribute is worse than no tangent attribute:
+  // TSL trusts it, builds an invalid TBN frame, and normal-mapped facets become
+  // literal black. Removing only invalid tangent attributes lets Three derive
+  // its guarded derivative frame while leaving geometry and UVs unchanged.
+  const tangentIntegrity = sanitizeRockTangents(root);
+  // Only bind the moss cavity channel when EVERY enriched mesh actually carries
+  // the attribute. A material sampling an attribute that some geometry lacks is
+  // a hard shader failure, so this stays off unless the write is complete.
+  const vertexCavityStrength = geometryDetail
+    && geometryDetail.meshes > 0
+    && geometryDetail.cavity === geometryDetail.meshes
+    ? ROCK_MOSS_CAVITY_STRENGTH
+    : 0;
   const profile = rockShaderSettingsToProfile(settings);
   const retainedSourceTextureIds = new Set();
+  const degenerateMaps = [];
   const report = {
     preset: settings.preset,
     matched: 0,
     applied: 0,
     skipped: 0,
     textureSource: textures?.rock ? 'provided' : 'first-party-generated',
-    usedGeneratedTextures: !textures?.rock,
+    usedGeneratedTextures: false,
     shadowDefaultsApplied: 0,
     retainedSourceTextures: 0,
+    variation,
+    // Slots dropped because the supplied map was too small to carry detail.
+    // Surfaced rather than silenced: a dropped map changes the render.
+    rejectedTextures: degenerateMaps,
+    // Tessellation/displacement actually applied, or null when not requested.
+    // Reported because it changes the triangle budget by up to 64x.
+    geometryDetail,
+    tangentIntegrity,
+    rockRegions: rockRegionInspection ? {
+      meshCount: rockRegionInspection.meshCount,
+      totalVertices: rockRegionInspection.totalVertices,
+      totalBytes: rockRegionInspection.totalBytes,
+      attribute: '_tl_rock_region',
+    } : null,
+    surfaceState,
   };
 
   root?.traverse?.((object) => {
@@ -428,13 +691,24 @@ export function applyRockShader(root, input = {}, {
     disposeOwnedMaterial(object.material);
     const sourceMaterials = Array.isArray(originalMaterial) ? originalMaterial : [originalMaterial];
     const nextMaterials = sourceMaterials.map((sourceMaterial, index) => createMaterialForSource({
+      degenerateMaps,
+      vertexCavityStrength,
+      rockRegionEnabled,
       sourceMaterial,
       settings,
       profile,
       textures,
+      variation,
+      surfaceState,
       name: sourceMaterials.length > 1 ? `${name} ${index + 1}` : name,
     }));
     for (const material of nextMaterials) {
+      const baseSource = material.userData.toonLabRockTextureComposition?.base;
+      if (baseSource === 'first-party-generated') {
+        report.usedGeneratedTextures = true;
+      } else if (baseSource === 'shared-semantic-material-set') {
+        report.textureSource = 'shared-semantic-material-set';
+      }
       for (const textureId of material.userData.toonlabSourceTextureIds ?? []) {
         retainedSourceTextureIds.add(textureId);
       }
@@ -472,7 +746,7 @@ export function restoreRockShader(root) {
 }
 
 /** Updates current scene inputs without changing the portable rock preset. */
-export function setRockShaderSceneState(root, { waterLevel } = {}) {
+export function setRockShaderSceneState(root, { skyColor, waterLevel } = {}) {
   let updated = 0;
   root?.traverse?.((object) => {
     if (!object?.isMesh) return;
@@ -480,15 +754,28 @@ export function setRockShaderSceneState(root, { waterLevel } = {}) {
     for (const material of materials) {
       const state = material?.userData?.toonLabRockSceneState;
       if (!state) continue;
+      if (skyColor !== undefined) state.setSkyColor(skyColor);
       if (Number.isFinite(Number(waterLevel))) state.setWaterLevel(Number(waterLevel));
       updated += 1;
     }
   });
-  return { updated, waterLevel: Number.isFinite(Number(waterLevel)) ? Number(waterLevel) : null };
+  const resolvedSkyColor = Array.isArray(skyColor) || ArrayBuffer.isView(skyColor)
+    ? Array.from(skyColor).slice(0, 3).map(Number)
+    : skyColor?.isColor
+      ? [skyColor.r, skyColor.g, skyColor.b]
+      : null;
+  return {
+    skyColor: resolvedSkyColor?.length === 3 && resolvedSkyColor.every(Number.isFinite)
+      ? resolvedSkyColor
+      : null,
+    updated,
+    waterLevel: Number.isFinite(Number(waterLevel)) ? Number(waterLevel) : null,
+  };
 }
 
 export function disposeDefaultRockShaderTextures() {
-  if (!defaultTextureSet) return;
-  for (const texture of Object.values(defaultTextureSet)) texture.dispose();
-  defaultTextureSet = null;
+  for (const set of textureSetsByVariation.values()) {
+    for (const texture of Object.values(set)) texture.dispose();
+  }
+  textureSetsByVariation.clear();
 }