@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/src/rock-shader/rockShaderSettings.js

@@ -138,7 +138,7 @@ const GROUP_DEFINITIONS = Object.freeze({
     fields: Object.freeze({
       exposure: field({
         defaultValue: 1,
-        description: 'HDR albedo exposure before scene lighting and tone mapping.',
+        description: 'Rock-specific direct-sun calibration. Base Color and indirect sky light remain unchanged.',
         label: 'Exposure',
         range: { max: 4, min: 0, step: 0.01 },
       }),
@@ -148,6 +148,12 @@ const GROUP_DEFINITIONS = Object.freeze({
         label: 'Ambient Floor',
         range: { max: 0.4, min: 0, step: 0.005 },
       }),
+      skyColorInfluence: field({
+        defaultValue: 0.35,
+        description: 'Fraction of active sky chroma admitted into the albedo-relative readability floor.',
+        label: 'Sky Color Influence',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
       skyFillStrength: field({
         defaultValue: 1,
         description: 'Rock-specific strength of the scene sky probe; direct sunlight is unchanged.',
@@ -160,6 +166,18 @@ const GROUP_DEFINITIONS = Object.freeze({
         label: 'Sky Fill Tint',
         type: 'color',
       }),
+      shadowFill: field({
+        defaultValue: 0,
+        description: 'Fraction of direct sun retained where the shared low-angle shadow mask occludes the rock. Normal-facing response is preserved.',
+        label: 'Direct Shadow Fill',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      shadowFillTint: field({
+        defaultValue: [1, 1, 1],
+        description: 'RGB weighting for retained direct light inside shared sun-shadow coverage.',
+        label: 'Direct Shadow Fill Tint',
+        type: 'color',
+      }),
     }),
   }),
   shoreline: Object.freeze({
@@ -315,7 +333,11 @@ const GROUP_DEFINITIONS = Object.freeze({
         defaultValue: 1.6,
         description: 'Strength of the projected moss coverage pattern.',
         label: 'Coverage Gain',
-        range: { max: 6, min: 0, step: 0.01 },
+        // Ceiling raised from 6. The shader squares this term against a moss
+        // albedo whose linear luminance is near 0.13 (D19-032), so 6 is not
+        // enough to reach full coverage on a surface where moss is the
+        // subject rather than incidental weathering. The default is unchanged.
+        range: { max: 24, min: 0, step: 0.01 },
       }),
       colorPower: field({
         defaultValue: 1.25,
@@ -335,6 +357,152 @@ const GROUP_DEFINITIONS = Object.freeze({
         label: 'High Color',
         type: 'color',
       }),
+      // --- moss as a material, not a tint --------------------------------
+      // New capability. Every default is the previous behaviour, so a style
+      // that does not set them renders exactly as before.
+      roughness: field({
+        defaultValue: -1,
+        description: 'Surface roughness under full moss; -1 keeps the stone value.',
+        label: 'Moss Roughness',
+        range: { max: 1, min: -1, step: 0.01 },
+      }),
+      relief: field({
+        defaultValue: 0,
+        description: 'Flattens the rock detail normal under moss, as a cushion would.',
+        label: 'Moss Relief Fill',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      fringe: field({
+        defaultValue: 0,
+        description: 'Ragged break-up of the moss coverage boundary.',
+        label: 'Edge Fringe',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      fringeScale: field({
+        defaultValue: 0.35,
+        // Now a fraction of PATCH scale, not of the moss projection size. The
+        // fringe field is world-space fBm rather than a resample of the moss
+        // albedo (D19-211), and what it has to break up is the patch boundary,
+        // so the patch period is the only period it can be meaningfully
+        // relative to. `fringe` defaults to 0, so nothing shipped observes the
+        // change.
+        description: 'Fringe noise period as a fraction of the colonisation patch scale.',
+        label: 'Fringe Scale',
+        range: { max: 1, min: 0.02, step: 0.01 },
+      }),
+      formDriven: field({
+        defaultValue: 0,
+        description: 'Blends coverage from the moss albedo toward the geometric moisture field.',
+        label: 'Form-Driven Coverage',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      // --- coverage mask -------------------------------------------------
+      // `coverage` is the switch: -1 keeps the shipped squared-clamp curve,
+      // whose transition band is so narrow that moss resolves as a horizontal
+      // waterline. 0..1 selects the patch-mask path, where this value IS the
+      // fraction of supported surface moss takes.
+      coverage: field({
+        defaultValue: -1,
+        description: 'Target moss coverage of supported surface; -1 keeps the legacy coverage curve.',
+        label: 'Coverage',
+        range: { max: 1, min: -1, step: 0.01 },
+      }),
+      band: field({
+        defaultValue: 0.18,
+        description: 'Width of the coverage transition. Narrow bands read as a dyed waterline.',
+        label: 'Transition Band',
+        range: { max: 0.5, min: 0.001, step: 0.001 },
+      }),
+      patchScale: field({
+        defaultValue: 0.6,
+        description: 'World-space period of the colonisation noise, metres.',
+        label: 'Patch Scale',
+        range: { max: 20, min: 0.01, step: 0.01 },
+      }),
+      patchStrength: field({
+        defaultValue: 0.8,
+        description: 'How strongly colonisation noise gates coverage. 0 gives an unbroken cap.',
+        label: 'Patch Strength',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      patchOctaves: field({
+        defaultValue: 3,
+        description: 'Octaves of colonisation noise.',
+        label: 'Patch Octaves',
+        range: { max: 6, min: 1, step: 1 },
+      }),
+      patchContrast: field({
+        defaultValue: 1.6,
+        description: 'Separates the noise into distinct cushions rather than a smooth cloud.',
+        label: 'Patch Contrast',
+        range: { max: 6, min: 0.1, step: 0.01 },
+      }),
+      // --- value, form and depth -----------------------------------------
+      // The four defects that made a working patch mask still read as
+      // camouflage rather than as moss (D19-210 … D19-213). Every default is
+      // inert: -1 and 0 reproduce the shipped render exactly.
+      //
+      // `patternFloor` / `patternCeiling` remap the moss map's own luminance
+      // range onto the colour ramp. The shipped path feeds the RAW rgb sample
+      // into `mix(lowColor, highColor)`, and the shipped moss albedo occupies a
+      // linear luminance of 0.092-0.279 with 99.3% of its texels inside a
+      // single decile. The ramp coordinate therefore never exceeds ~0.09: moss
+      // renders as `lowColor` everywhere, `highColor` is dead, and the five
+      // authored palette stops collapse to one very dark green. Setting a floor
+      // switches the ramp to a scalar remap of that measured range, which both
+      // reaches the light end of the palette and stops the per-channel sample
+      // from skewing hue. See D19-210.
+      patternFloor: field({
+        defaultValue: -1,
+        description: 'Moss-map luminance that maps to Low Color; -1 keeps the shipped per-channel ramp.',
+        label: 'Pattern Floor',
+        range: { max: 1, min: -1, step: 0.001 },
+      }),
+      patternCeiling: field({
+        defaultValue: 1,
+        description: 'Moss-map luminance that maps to High Color. Ignored when Pattern Floor is -1.',
+        label: 'Pattern Ceiling',
+        range: { max: 1, min: 0, step: 0.001 },
+      }),
+      // Moss and stone read at a close value in life because moss grows where
+      // the stone stays WET, and wet stone is darker than dry stone. Without
+      // this the only way to close the value gap is to lift the moss or drop
+      // the stone globally — the first fights the shared palette, the second is
+      // the scene's grade to make. This closes it from the physically correct
+      // side and leaves a damp halo just beyond each cushion. See D19-210.
+      damp: field({
+        defaultValue: 0,
+        description: 'Darkens the stone where the moss support field is wet, including just beyond the moss.',
+        label: 'Damp Stone',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      // Crowns, ridges and shoulders shed water and dry first, so they stay
+      // bare. The support term could express "hollow" via `rockCavity` but had
+      // no term for "exposed", and its slope half saturates across the whole
+      // upper hemisphere — leaving the colonisation noise as the only thing
+      // distinguishing one upper face from another. See D19-212.
+      exposure: field({
+        defaultValue: 0,
+        description: 'How strongly convex, weather-exposed form (crowns and ridges) suppresses moss.',
+        label: 'Exposure Penalty',
+        range: { max: 2, min: 0, step: 0.01 },
+      }),
+      // A moss cushion is a raised soft mass, not a decal. `relief` flattens the
+      // stone's own detail under the moss but nothing ever raised the moss
+      // itself, so the patch stayed geometrically identical to the rock it sat
+      // on. See D19-213.
+      cushion: field({
+        defaultValue: 0,
+        description: 'Raises the moss into a soft cushion by tilting the shading normal along the patch field.',
+        label: 'Cushion Depth',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      contact: field({
+        defaultValue: 0,
+        description: 'Contact shading where a cushion meets bare stone — the occlusion a raised mass casts.',
+        label: 'Contact Shade',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
     }),
   }),
   layerMask: Object.freeze({
@@ -540,6 +708,42 @@ const GROUP_DEFINITIONS = Object.freeze({
         label: 'Vertex AO Strength',
         range: { max: 2, min: 0, step: 0.01 },
       }),
+      regionTintStrength: field({
+        defaultValue: 0,
+        description: 'Influence of the fail-closed _TL_ROCK_REGION base, shaft, neck, and cap palette. Zero does not require the attribute.',
+        label: 'Geology Region Tint',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
+      regionBaseTint: field({
+        defaultValue: [1, 1, 1],
+        description: 'Multiplier applied to the geological support/base region.',
+        label: 'Base Region Tint',
+        type: 'color',
+      }),
+      regionShaftTint: field({
+        defaultValue: [1, 1, 1],
+        description: 'Multiplier applied to the main hoodoo shaft region.',
+        label: 'Shaft Region Tint',
+        type: 'color',
+      }),
+      regionNeckTint: field({
+        defaultValue: [1, 1, 1],
+        description: 'Independent overlay multiplier around the constricted neck.',
+        label: 'Neck Region Tint',
+        type: 'color',
+      }),
+      regionCapTint: field({
+        defaultValue: [1, 1, 1],
+        description: 'Multiplier applied to the resistant caprock region.',
+        label: 'Cap Region Tint',
+        type: 'color',
+      }),
+      regionNeckOverlayStrength: field({
+        defaultValue: 0,
+        description: 'How strongly the overlapping neck mask modifies the primary base/shaft/cap partition.',
+        label: 'Neck Overlay Strength',
+        range: { max: 1, min: 0, step: 0.01 },
+      }),
     }),
   }),
 });
@@ -589,9 +793,12 @@ export const DEFAULT_ROCK_SHADER_SETTINGS = Object.freeze(Object.fromEntries(
 export const CALL_ME_SENSEI_ROCK_SHADER_SETTINGS = Object.freeze({
   projection: Object.freeze({
     scale: 48,
-    saturation: 0.72,
-    contrast: 0.72,
-    brightness: 0.04,
+    // Geological maps already own lithology color and value structure. The
+    // previous 0.72 saturation/contrast pair washed every family toward the
+    // same pale grey before lighting, most visibly red sandstone.
+    saturation: 1,
+    contrast: 1,
+    brightness: 0,
     projectionContrast: 2,
     sideOnly: false,
     nearDetailScale: 1.2,
@@ -599,10 +806,11 @@ export const CALL_ME_SENSEI_ROCK_SHADER_SETTINGS = Object.freeze({
     nearDetailDistance: 70,
   }),
   material: Object.freeze({
-    // Daylight stone is blue-white rather than neutral grey. Keep this bias
-    // subtle: the shared sky probe still owns the stronger blue response in
-    // recesses and on back faces.
-    tint: Object.freeze([0.97, 0.99, 1]),
+    // Geological Base Color stays neutral at the material boundary. Daylight,
+    // golden hour, weather, and night color belong to the shared scene sun and
+    // sky probe; baking a blue-white cast here washed warm rocks such as
+    // sandstone out even before they saw the active environment.
+    tint: Object.freeze([1, 1, 1]),
     metallic: 0,
     smoothness: 0.07,
     useSmoothnessTexture: false,
@@ -610,14 +818,23 @@ export const CALL_ME_SENSEI_ROCK_SHADER_SETTINGS = Object.freeze({
     emissiveStrength: 0,
   }),
   lighting: Object.freeze({
-    // Match the accepted high-key response under the package's white
-    // intensity-8 daylight sun. This is material exposure, not a scene-local
-    // light override: sun faces retain chalk-white headroom while the probe
-    // owns the blue shaded face.
-    exposure: 0.9,
-    ambientFloor: 0.01,
+    // Preserve Base Color headroom under the package's intensity-8 daylight
+    // sun. This is material exposure, not a scene-local light override.
+    exposure: 0.95,
+    // Keep the readability floor small: the main shadow-side value and colour
+    // must come from the scene's live sky, not a neutral emissive wash.
+    ambientFloor: 0.04,
+    skyColorInfluence: 1,
+    // Restore the strong open-sky fill that gave the accepted rocks their blue
+    // daylight backs. Its colour is now dynamic rather than baked blue, so the
+    // same channel becomes pink/orange at sunset and deep blue at night.
     skyFillStrength: 0.72,
-    skyFillTint: Object.freeze([0.72, 0.86, 1]),
+    skyFillTint: Object.freeze([1, 1, 1]),
+    // Shadowed faces belong to the sky probe. Retaining any fraction of the
+    // sunset sun here paints orange into the cool side and destroys the
+    // warm-key/cool-fill separation.
+    shadowFill: 0,
+    shadowFillTint: Object.freeze([1, 1, 1]),
   }),
   shoreline: Object.freeze({
     wetBandWidth: 1,
@@ -652,6 +869,19 @@ export const CALL_ME_SENSEI_ROCK_SHADER_SETTINGS = Object.freeze({
     colorPower: 1.3,
     lowColor: Object.freeze([0.24, 0.42, 0.12]),
     highColor: Object.freeze([0.46, 0.68, 0.24]),
+    // New capability, neutral defaults. No authored value above is changed.
+    roughness: -1,
+    relief: 0,
+    fringe: 0,
+    fringeScale: 0.35,
+    formDriven: 0,
+    // Inert: `coverage: -1` keeps the shipped coverage curve.
+    coverage: -1,
+    band: 0.18,
+    patchScale: 0.6,
+    patchStrength: 0.8,
+    patchOctaves: 3,
+    patchContrast: 1.6,
   }),
   layerMask: Object.freeze({
     useAssetMask: true,

package/src/rock-shader/rockTangentIntegrity.js

@@ -0,0 +1,136 @@
+const DEFAULT_EPSILON = 1e-6;
+const DEFAULT_ORTHOGONALITY_TOLERANCE = 0.1;
+
+function finite(value) {
+  return Number.isFinite(Number(value));
+}
+
+/**
+ * Audits a geometry tangent attribute before a normal-mapped material can
+ * consume it. A missing tangent attribute is valid: Three.js derives a
+ * derivative TBN frame. A present but zero/invalid attribute is not valid and
+ * produces literal black facets in WebGPU/TSL normal mapping.
+ */
+export function inspectRockGeometryTangents(geometry, {
+  epsilon = DEFAULT_EPSILON,
+  orthogonalityTolerance = DEFAULT_ORTHOGONALITY_TOLERANCE,
+} = {}) {
+  const position = geometry?.getAttribute?.('position');
+  const normal = geometry?.getAttribute?.('normal');
+  const tangent = geometry?.getAttribute?.('tangent');
+  const vertices = position?.count ?? 0;
+  const report = {
+    vertices,
+    hasTangents: Boolean(tangent),
+    tangentVertices: tangent?.count ?? 0,
+    invalidVertices: 0,
+    zeroLength: 0,
+    nonFinite: 0,
+    invalidHandedness: 0,
+    nonOrthogonal: 0,
+    countMismatch: Boolean(tangent && tangent.count !== vertices),
+    itemSizeInvalid: Boolean(tangent && tangent.itemSize < 4),
+    valid: true,
+  };
+  if (!tangent) return report;
+
+  const epsilonSquared = Math.max(Number(epsilon) || DEFAULT_EPSILON, 1e-12) ** 2;
+  const orthogonality = Math.max(
+    Number(orthogonalityTolerance) || DEFAULT_ORTHOGONALITY_TOLERANCE,
+    1e-6,
+  );
+  const count = Math.min(tangent.count, vertices || tangent.count);
+  for (let index = 0; index < count; index += 1) {
+    const x = tangent.getX(index);
+    const y = tangent.getY(index);
+    const z = tangent.getZ(index);
+    const w = tangent.itemSize > 3 ? tangent.getW(index) : 0;
+    const lengthSquared = (x * x) + (y * y) + (z * z);
+    let invalid = false;
+    if (![x, y, z, w].every(finite)) {
+      report.nonFinite += 1;
+      invalid = true;
+    }
+    if (!finite(lengthSquared) || lengthSquared <= epsilonSquared) {
+      report.zeroLength += 1;
+      invalid = true;
+    }
+    if (!finite(w) || Math.abs(w) < 0.5) {
+      report.invalidHandedness += 1;
+      invalid = true;
+    }
+    if (normal && normal.count > index && finite(lengthSquared) && lengthSquared > epsilonSquared) {
+      const nx = normal.getX(index);
+      const ny = normal.getY(index);
+      const nz = normal.getZ(index);
+      const normalLengthSquared = (nx * nx) + (ny * ny) + (nz * nz);
+      if (normalLengthSquared > epsilonSquared) {
+        const cosine = Math.abs((x * nx) + (y * ny) + (z * nz))
+          / Math.sqrt(lengthSquared * normalLengthSquared);
+        if (!finite(cosine) || cosine > orthogonality) {
+          report.nonOrthogonal += 1;
+          invalid = true;
+        }
+      }
+    }
+    if (invalid) report.invalidVertices += 1;
+  }
+  if (report.countMismatch || report.itemSizeInvalid) {
+    report.invalidVertices = Math.max(report.invalidVertices, tangent.count);
+  }
+  report.valid = report.invalidVertices === 0
+    && !report.countMismatch
+    && !report.itemSizeInvalid;
+  return report;
+}
+
+/**
+ * Removes only invalid tangent attributes. Three.js then uses its derivative
+ * tangent frame, which is the safe fallback for degenerate UV islands. Vertex
+ * positions, normals, UVs, indices, materials, and texture files are untouched.
+ */
+export function sanitizeRockGeometryTangents(geometry, options = {}) {
+  const inspection = inspectRockGeometryTangents(geometry, options);
+  const removed = inspection.hasTangents && !inspection.valid;
+  if (removed) {
+    geometry.deleteAttribute('tangent');
+    geometry.userData ??= {};
+    geometry.userData.toonLabRemovedInvalidTangents = {
+      invalidVertices: inspection.invalidVertices,
+      tangentVertices: inspection.tangentVertices,
+    };
+  }
+  return { ...inspection, removed };
+}
+
+/** Audits and repairs every mesh below a rock root. */
+export function sanitizeRockTangents(root, options = {}) {
+  const issues = [];
+  const report = {
+    meshes: 0,
+    meshesWithTangents: 0,
+    repairedMeshes: 0,
+    vertices: 0,
+    tangentVertices: 0,
+    invalidVertices: 0,
+    issues,
+  };
+  root?.traverse?.((object) => {
+    if (!object?.isMesh || !object.geometry) return;
+    report.meshes += 1;
+    const result = sanitizeRockGeometryTangents(object.geometry, options);
+    report.vertices += result.vertices;
+    report.tangentVertices += result.tangentVertices;
+    report.invalidVertices += result.invalidVertices;
+    if (result.hasTangents) report.meshesWithTangents += 1;
+    if (result.removed) {
+      report.repairedMeshes += 1;
+      issues.push({
+        mesh: object.name || `mesh-${report.meshes}`,
+        invalidVertices: result.invalidVertices,
+        tangentVertices: result.tangentVertices,
+      });
+    }
+  });
+  return report;
+}

package/src/rock-shader/rockTextureIntegrity.js

@@ -0,0 +1,115 @@
+// Integrity checks for textures handed to the rock shader.
+//
+// A detail map only earns its slot if it can actually carry detail. Published
+// catalog artifacts sometimes ship a placeholder in a real texture slot — a
+// 4x4 normal map, for instance — which is materially worse than shipping
+// nothing: the shader's own deterministic fallback is a usable surface, and a
+// placeholder silently displaces it. Every consumer that harvests maps off an
+// imported material needs the same predicate, so it lives here rather than in
+// any one call site.
+//
+// This is deliberately a *resolution* test, not a content test. Reading pixels
+// back is not possible for GPU-compressed formats (KTX2/Basis) without a
+// decode, and resolution alone is sufficient to catch the placeholder class.
+
+/**
+ * Minimum edge length, in texels, for a map to be treated as carrying detail.
+ *
+ * A triplanar detail map is projected at metre scale, so its texel density is
+ * what produces fracture and erosion relief. Below 16x16 there is no spatial
+ * frequency left to project and the map is indistinguishable from a constant.
+ */
+export const MIN_DETAIL_MAP_EDGE_TEXELS = 16;
+
+/** Texture slots treated as detail maps for integrity purposes. */
+export const ROCK_DETAIL_MAP_SLOTS = Object.freeze([
+  'rockNormal',
+  'sandNormal',
+  'sourceNormal',
+  'stylizedNormal',
+  'smoothness',
+  'topMask',
+]);
+
+/**
+ * Reads a texture's pixel dimensions across the shapes three.js uses:
+ * `DataTexture`/`Texture` carry `image`, compressed KTX2 textures carry
+ * `mipmaps[0]`, and loaders that went through `Source` carry `source.data`.
+ *
+ * @returns {{width: number, height: number} | null} null when undeterminable.
+ */
+export function resolveTextureSize(texture) {
+  if (!texture?.isTexture) return null;
+  const candidates = [
+    texture.image,
+    texture.source?.data,
+    Array.isArray(texture.mipmaps) ? texture.mipmaps[0] : null,
+  ];
+  for (const candidate of candidates) {
+    const width = Number(candidate?.width);
+    const height = Number(candidate?.height);
+    if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0) {
+      return { width, height };
+    }
+  }
+  return null;
+}
+
+/**
+ * True when a texture is too small to carry the detail its slot implies.
+ *
+ * Undeterminable sizes return `false` — this guard removes maps only when it
+ * can prove they are degenerate, so an unusual-but-valid texture is never
+ * silently dropped.
+ */
+export function isDegenerateDetailMap(texture, {
+  minEdgeTexels = MIN_DETAIL_MAP_EDGE_TEXELS,
+} = {}) {
+  const size = resolveTextureSize(texture);
+  if (!size) return false;
+  return size.width < minEdgeTexels || size.height < minEdgeTexels;
+}
+
+/**
+ * Describes a texture for diagnostics without assuming it is loaded.
+ */
+export function describeTexture(texture) {
+  const size = resolveTextureSize(texture);
+  return {
+    name: texture?.name || null,
+    resolution: size ? `${size.width}x${size.height}` : 'unknown',
+    uuid: texture?.uuid ?? null,
+  };
+}
+
+/**
+ * Removes degenerate detail maps from a texture set.
+ *
+ * Returns a new object plus the list of rejected slots so callers can report
+ * the substitution rather than hiding it — a dropped map changes the rendered
+ * result and should be visible in an asset report.
+ *
+ * @param {Record<string, unknown>} textures
+ * @param {{minEdgeTexels?: number, slots?: readonly string[]}} [options]
+ * @returns {{textures: Record<string, unknown>, rejected: Array<{slot: string, reason: string, texture: object}>}}
+ */
+export function withoutDegenerateDetailMaps(textures, {
+  minEdgeTexels = MIN_DETAIL_MAP_EDGE_TEXELS,
+  slots = ROCK_DETAIL_MAP_SLOTS,
+} = {}) {
+  const result = { ...(textures ?? {}) };
+  const rejected = [];
+  for (const slot of slots) {
+    const texture = result[slot];
+    if (!texture?.isTexture) continue;
+    if (!isDegenerateDetailMap(texture, { minEdgeTexels })) continue;
+    const described = describeTexture(texture);
+    rejected.push({
+      reason: `below the ${minEdgeTexels}x${minEdgeTexels} minimum for a detail map`,
+      slot,
+      texture: described,
+    });
+    delete result[slot];
+  }
+  return { rejected, textures: result };
+}

package/src/rockgen/index.js

@@ -13,3 +13,4 @@ export * from './sdf/sculptEdits.js';
 export * from './mesh/meshDocument.js';
 export * from './lod/index.js';
 export * from './export/glbExport.js';
+export * from './surface/c7GeologySurface.js';

package/src/rockgen/rockDocument.js

@@ -24,7 +24,7 @@ import { compileDocument } from './sdf/fieldCompiler.js';
 export const ROCKGEN_PROJECT_DOCUMENT_TYPE = 'toonlab/rockgen-project';
 
 /** Current schema version for rockgen project documents. */
-export const ROCKGEN_PROJECT_SCHEMA_VERSION = 5;
+export const ROCKGEN_PROJECT_SCHEMA_VERSION = 6;
 
 /** Sparse source-mesh edits are packed into the portable document so normal
  * sculpting remains below the hosted creation-document limit. Runtime state
@@ -70,6 +70,21 @@ function lodTrianglesOption(value, targetTriangles, lodRatios) {
     : [];
 }
 
+function surfacePackageOption(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.schema !== 'toonlab/c7-geology-surface' || Number(value.version) !== 1) return null;
+  const geology = String(value.geology ?? '').trim();
+  if (!geology) return null;
+  const mapResolution = Math.max(32, Math.min(2048, Math.round(Number(value.mapResolution) || 512)));
+  return {
+    geology,
+    mapResolution,
+    schema: 'toonlab/c7-geology-surface',
+    seed: Math.round(Number(value.seed) || 0) >>> 0,
+    version: 1,
+  };
+}
+
 function bytesToBase64(bytes) {
   let binary = '';
   const chunkSize = 0x8000;
@@ -219,6 +234,7 @@ export function createRockReferenceIdentity(options = null) {
     role: String(options.role ?? '').trim(),
     series: String(options.series ?? '').trim(),
     sourceMode: 'mesh-template',
+    surfacePackage: surfacePackageOption(options.surfacePackage),
     surfaceMode: options.surfaceMode === 'generated' ? 'generated' : 'source',
     targetTriangles: positiveInteger(options.targetTriangles, lodTriangles[0] ?? 0),
     topFinish,
@@ -508,8 +524,9 @@ export function serializeRockDocument(document, { pretty = false } = {}) {
 // v3 adds optional descriptor-only reference identity and its LOD contract.
 // v4 adds sparse vertex deltas for editable source-mesh projects. v5 packs
 // those deltas as float32 binary in portable JSON so normal sculpt sessions
-// fit the hosted creation limit. Existing preset/custom projects remain
-// reference-free.
+// fit the hosted creation limit. v6 adds the optional deterministic C7 surface
+// package identity used by the 480 source-mesh catalog. Existing
+// preset/custom projects remain reference-free.
 const MIGRATIONS = Object.freeze([
   (document) => ({
     ...document,
@@ -547,6 +564,13 @@ const MIGRATIONS = Object.freeze([
       schemaVersion: 5,
     };
   },
+  (document) => ({
+    ...document,
+    reference: document.reference && typeof document.reference === 'object'
+      ? { ...document.reference, surfacePackage: document.reference.surfacePackage ?? null }
+      : null,
+    schemaVersion: 6,
+  }),
 ]);
 
 /**