@call-me-sensei/toonlab 0.1.1

package/src/environment/environmentTextureResolver.js

@@ -0,0 +1,161 @@
+import * as THREE from 'three';
+
+import {
+  isFoliageMaterial,
+  isUtilityTextureLabel,
+  textureLabel,
+  textureSourceUrl,
+} from './environmentMaterialClassifier.js';
+
+export const fallbackEnvironmentWhiteTexture = new THREE.DataTexture(new Uint8Array([255, 255, 255, 255]), 1, 1);
+fallbackEnvironmentWhiteTexture.colorSpace = THREE.SRGBColorSpace;
+fallbackEnvironmentWhiteTexture.needsUpdate = true;
+
+export const fallbackEnvironmentBlackTexture = new THREE.DataTexture(new Uint8Array([0, 0, 0, 255]), 1, 1);
+fallbackEnvironmentBlackTexture.colorSpace = THREE.NoColorSpace;
+fallbackEnvironmentBlackTexture.needsUpdate = true;
+
+// Flat +Z normal for materials compiled without a real normal map bound.
+export const fallbackEnvironmentNormalTexture = new THREE.DataTexture(new Uint8Array([128, 128, 255, 255]), 1, 1);
+fallbackEnvironmentNormalTexture.colorSpace = THREE.NoColorSpace;
+fallbackEnvironmentNormalTexture.needsUpdate = true;
+
+const textureLoader = new THREE.TextureLoader();
+const textureExistenceCache = new Map();
+const textureLoadCache = new Map();
+
+export function textureKindCandidateUrl(sourceUrl, kind) {
+  if (!sourceUrl) return null;
+
+  const candidate = sourceUrl.replace(
+    /(^|[_\-/])(diffuse|lsab|smbe|normal|nrm|height|ao|mask|esa)(\.[a-z0-9]+)([?#].*)?$/i,
+    `$1${kind}$3$4`,
+  );
+  return candidate === sourceUrl ? null : candidate;
+}
+
+export async function textureUrlExists(url) {
+  if (!url) return false;
+  if (!textureExistenceCache.has(url)) {
+    textureExistenceCache.set(url, fetch(url, { method: 'HEAD' })
+      .then((response) => response.ok)
+      .catch(() => false));
+  }
+  return textureExistenceCache.get(url);
+}
+
+export function copyTextureTransform(target, source) {
+  if (!source) return target;
+  target.wrapS = source.wrapS;
+  target.wrapT = source.wrapT;
+  target.repeat.copy(source.repeat);
+  target.offset.copy(source.offset);
+  target.center.copy(source.center);
+  target.rotation = source.rotation;
+  target.flipY = source.flipY;
+  target.channel = source.channel;
+  return target;
+}
+
+export function loadEnvironmentTexture(url, referenceTexture, { colorSpace = THREE.SRGBColorSpace } = {}) {
+  const cacheKey = `${url}|${colorSpace}`;
+  if (!textureLoadCache.has(cacheKey)) {
+    textureLoadCache.set(cacheKey, new Promise((resolve, reject) => {
+      textureLoader.load(
+        url,
+        (texture) => {
+          texture.colorSpace = colorSpace;
+          copyTextureTransform(texture, referenceTexture);
+          texture.needsUpdate = true;
+          resolve(texture);
+        },
+        undefined,
+        reject,
+      );
+    }));
+  }
+
+  return textureLoadCache.get(cacheKey);
+}
+
+// Loads a sibling texture by filename-suffix convention when the asset pack
+// uses one (e.g. Liyue's *_Diffuse/_Normal/_SMBE files). Returns null when the
+// convention does not resolve, so standard-map sources always win.
+async function resolveConventionTexture(sourceUrl, referenceTexture, kind, options) {
+  const candidateUrl = textureKindCandidateUrl(sourceUrl, kind);
+  if (!candidateUrl || !await textureUrlExists(candidateUrl)) return null;
+  return loadEnvironmentTexture(candidateUrl, referenceTexture, options).catch(() => null);
+}
+
+// Resolves everything the environment shader can consume for one source
+// material. Standard Three.js/GLTF maps take priority; filename-convention
+// siblings (Liyue-style packs) fill the gaps; author hooks in
+// material.userData override both:
+//   userData.envNormalMap / envAoMap / envLightMap / envEmissiveMap
+export async function resolveEnvironmentTextureSet(mat) {
+  const sourceMap = mat?.map ?? null;
+  const sourceLabel = textureLabel(sourceMap);
+  const sourceUrl = textureSourceUrl(sourceMap);
+  const sourceMapIsUtility = isUtilityTextureLabel(sourceLabel || sourceUrl);
+  const candidateUrl = sourceMapIsUtility ? textureKindCandidateUrl(sourceUrl, 'Diffuse') : null;
+  const resolvedDiffuseMap = candidateUrl && await textureUrlExists(candidateUrl)
+    ? await loadEnvironmentTexture(candidateUrl, sourceMap).catch(() => null)
+    : null;
+  const packedCandidateUrls = sourceMapIsUtility
+    ? []
+    : [
+      ['SMBE', textureKindCandidateUrl(sourceUrl, 'SMBE')],
+      ['LSAB', textureKindCandidateUrl(sourceUrl, 'LSAB')],
+      ['ESA', textureKindCandidateUrl(sourceUrl, 'ESA')],
+    ].filter(([, url]) => Boolean(url));
+  let packedMap = null;
+  let packedMapKind = null;
+
+  for (const [kind, packedCandidateUrl] of packedCandidateUrls) {
+    if (!await textureUrlExists(packedCandidateUrl)) continue;
+    packedMap = await loadEnvironmentTexture(packedCandidateUrl, sourceMap).catch(() => null);
+    if (packedMap) {
+      packedMap.colorSpace = THREE.NoColorSpace;
+      packedMap.needsUpdate = true;
+      packedMapKind = kind;
+      break;
+    }
+  }
+  const foliageAlphaMap = isFoliageMaterial(mat) && ['LSAB', 'ESA'].includes(packedMapKind)
+    ? packedMap
+    : null;
+
+  const userData = mat?.userData ?? {};
+  const normalMap = userData.envNormalMap
+    ?? mat?.normalMap
+    ?? (sourceMapIsUtility ? null : await resolveConventionTexture(
+      sourceUrl, sourceMap, 'Normal', { colorSpace: THREE.NoColorSpace }));
+  const aoMap = userData.envAoMap ?? mat?.aoMap ?? null;
+  const lightMap = userData.envLightMap ?? mat?.lightMap ?? null;
+  const emissiveMap = userData.envEmissiveMap ?? mat?.emissiveMap ?? null;
+  const baseMap = resolvedDiffuseMap
+    ?? (sourceMapIsUtility ? fallbackEnvironmentWhiteTexture : sourceMap)
+    ?? fallbackEnvironmentWhiteTexture;
+
+  return {
+    alphaFromLuminance: Boolean(foliageAlphaMap || sourceMapIsUtility),
+    alphaMap: mat?.alphaMap ?? (sourceMapIsUtility ? sourceMap : foliageAlphaMap),
+    aoMap,
+    aoMapIntensity: Number.isFinite(mat?.aoMapIntensity) ? mat.aoMapIntensity : 1,
+    baseMap,
+    baseMapWasUtility: sourceMapIsUtility,
+    emissiveColor: mat?.emissive?.isColor && (mat.emissive.r || mat.emissive.g || mat.emissive.b)
+      ? mat.emissive.clone()
+      : new THREE.Color(1, 1, 1),
+    emissiveMap,
+    lightMap,
+    lightMapIntensity: Number.isFinite(mat?.lightMapIntensity) ? mat.lightMapIntensity : 1,
+    normalMap,
+    normalScale: mat?.normalScale?.isVector2 ? mat.normalScale.clone() : new THREE.Vector2(1, 1),
+    packedMap,
+    resolvedDiffuseMap: Boolean(resolvedDiffuseMap),
+    // True when the material arrived with no real color texture at all — the
+    // untextured/flat-color input class that gets the designed gradient look.
+    untextured: baseMap === fallbackEnvironmentWhiteTexture,
+  };
+}

package/src/environment/environmentTimeOfDay.js

@@ -0,0 +1,167 @@
+import * as THREE from 'three';
+
+import { environmentBackdropPeriodForHour, applyEnvironmentLampEmissive } from './environmentRigs.js';
+
+// One authority for time-of-day environment state. sampleEnvironmentTimeOfDay
+// interpolates keyframed lighting values for any hour; applyEnvironmentTimeOfDay
+// pushes the sampled state into the rigs and converted materials in one call.
+//
+// Keyframes describe the classic anime-interior day: cool night with lamps
+// carrying the room, warm low morning sun, neutral bright midday, amber
+// evening, back to night.
+
+const TIME_KEYFRAMES = [
+  {
+    hour: 0,
+    sunColor: 0x9bbcff,
+    sunIntensity: 0.1,
+    ambientScale: 0.55,
+    lampScale: 1.35,
+    skyGroundTint: [0.82, 0.86, 1.0],
+    skyTopTint: [0.62, 0.72, 1.02],
+    fogColor: [0.32, 0.38, 0.55],
+    accentScale: 0.2,
+  },
+  {
+    hour: 6,
+    sunColor: 0xffb56a,
+    sunIntensity: 0.45,
+    ambientScale: 0.8,
+    lampScale: 0.7,
+    skyGroundTint: [1.1, 0.94, 0.82],
+    skyTopTint: [0.95, 0.9, 1.0],
+    fogColor: [0.85, 0.7, 0.55],
+    accentScale: 0.85,
+  },
+  {
+    hour: 12,
+    sunColor: 0xfff1d8,
+    sunIntensity: 1.0,
+    ambientScale: 1.0,
+    lampScale: 0.0,
+    skyGroundTint: [1.05, 0.97, 0.9],
+    skyTopTint: [0.86, 0.96, 1.08],
+    fogColor: [0.78, 0.85, 0.95],
+    accentScale: 1.0,
+  },
+  {
+    hour: 18,
+    sunColor: 0xff884b,
+    sunIntensity: 0.5,
+    ambientScale: 0.78,
+    lampScale: 0.8,
+    skyGroundTint: [1.14, 0.9, 0.74],
+    skyTopTint: [0.92, 0.84, 0.96],
+    fogColor: [0.82, 0.6, 0.45],
+    accentScale: 0.9,
+  },
+  {
+    hour: 21,
+    sunColor: 0x9bbcff,
+    sunIntensity: 0.14,
+    ambientScale: 0.58,
+    lampScale: 1.3,
+    skyGroundTint: [0.84, 0.87, 1.0],
+    skyTopTint: [0.64, 0.74, 1.02],
+    fogColor: [0.34, 0.4, 0.58],
+    accentScale: 0.3,
+  },
+  // Wrap key (same as hour 0) so interpolation is seamless across midnight.
+  {
+    hour: 24,
+    sunColor: 0x9bbcff,
+    sunIntensity: 0.1,
+    ambientScale: 0.55,
+    lampScale: 1.35,
+    skyGroundTint: [0.82, 0.86, 1.0],
+    skyTopTint: [0.62, 0.72, 1.02],
+    fogColor: [0.32, 0.38, 0.55],
+    accentScale: 0.2,
+  },
+];
+
+function lerpColorHex(a, b, t) {
+  return new THREE.Color(a).lerp(new THREE.Color(b), t);
+}
+
+function lerpColorArray(a, b, t) {
+  return new THREE.Color(
+    THREE.MathUtils.lerp(a[0], b[0], t),
+    THREE.MathUtils.lerp(a[1], b[1], t),
+    THREE.MathUtils.lerp(a[2], b[2], t),
+  );
+}
+
+export function sampleEnvironmentTimeOfDay(hour) {
+  const normalized = ((Number(hour) % 24) + 24) % 24;
+  let previous = TIME_KEYFRAMES[0];
+  let next = TIME_KEYFRAMES[TIME_KEYFRAMES.length - 1];
+  for (let i = 0; i < TIME_KEYFRAMES.length - 1; i += 1) {
+    if (normalized >= TIME_KEYFRAMES[i].hour && normalized <= TIME_KEYFRAMES[i + 1].hour) {
+      previous = TIME_KEYFRAMES[i];
+      next = TIME_KEYFRAMES[i + 1];
+      break;
+    }
+  }
+  const span = Math.max(next.hour - previous.hour, 0.001);
+  const t = THREE.MathUtils.clamp((normalized - previous.hour) / span, 0, 1);
+
+  // Sun tracks east-to-west over the day; ratios feed the sun rig placement.
+  const dayT = normalized / 24;
+  const azimuth = (dayT - 0.5) * Math.PI * 1.6;
+  const elevation = Math.max(Math.sin((normalized - 6) / 12 * Math.PI), 0.06);
+
+  return {
+    accentScale: THREE.MathUtils.lerp(previous.accentScale, next.accentScale, t),
+    ambientScale: THREE.MathUtils.lerp(previous.ambientScale, next.ambientScale, t),
+    backdropPeriod: environmentBackdropPeriodForHour(normalized),
+    fogColor: lerpColorArray(previous.fogColor, next.fogColor, t),
+    hour: normalized,
+    lampScale: THREE.MathUtils.lerp(previous.lampScale, next.lampScale, t),
+    skyGroundTint: lerpColorArray(previous.skyGroundTint, next.skyGroundTint, t),
+    skyTopTint: lerpColorArray(previous.skyTopTint, next.skyTopTint, t),
+    sunColor: lerpColorHex(previous.sunColor, next.sunColor, t),
+    sunIntensity: THREE.MathUtils.lerp(previous.sunIntensity, next.sunIntensity, t),
+    sunSourceRatios: {
+      x: Math.sin(azimuth) * 0.85,
+      y: 0.4 + elevation * 0.6,
+      z: -Math.cos(azimuth) * 0.85,
+    },
+  };
+}
+
+// Pushes a sampled state into whatever pieces the caller wires up. Every
+// target is optional, so integrators adopt this incrementally.
+export function applyEnvironmentTimeOfDay(state, {
+  backdrop = null,
+  environmentRoot = null,
+  lampRig = null,
+  sunRig = null,
+  sunIntensityScale = 1,
+} = {}) {
+  if (!state) return;
+
+  sunRig?.setState({
+    color: state.sunColor,
+    intensity: state.sunIntensity * sunIntensityScale,
+    sourceRatios: state.sunSourceRatios,
+    diskOpacity: 0.62 * state.accentScale,
+    spillOpacity: 0.3 * state.accentScale,
+    beamOpacity: 0.28 * state.accentScale,
+    shaftOpacity: 0.1 * state.accentScale,
+  });
+  lampRig?.setIntensity(state.lampScale);
+  if (environmentRoot && lampRig) applyEnvironmentLampEmissive(environmentRoot, Math.max(state.lampScale, 0.15));
+  backdrop?.setPeriod(state.backdropPeriod);
+
+  environmentRoot?.traverse?.((obj) => {
+    if (!obj.isMesh || !obj.material) return;
+    const materials = Array.isArray(obj.material) ? obj.material : [obj.material];
+    for (const mat of materials) {
+      if (!mat?.userData?.environmentMaterial || !mat.uniforms) continue;
+      mat.uniforms.skyGroundTint?.value?.copy?.(state.skyGroundTint);
+      mat.uniforms.skyTopTint?.value?.copy?.(state.skyTopTint);
+      mat.uniforms.heightFogColor?.value?.copy?.(state.fogColor);
+    }
+  });
+}

package/src/environment/environmentVertexAo.js

@@ -0,0 +1,188 @@
+import * as THREE from 'three';
+
+// Conversion-time per-vertex ambient occlusion for environment meshes.
+//
+// This is the grounding lever for untextured/flat-color scenes: one bake at
+// conversion, zero per-frame cost, consumed by the environment shader through
+// the envVertexAo attribute (USE_ENV_VERTEX_AO). Deterministic by design —
+// fixed hemisphere directions, no randomness — so captures are repeatable.
+//
+// Uses three-mesh-bvh for the occluder queries; if the dependency cannot be
+// loaded the bake is skipped with a warning rather than falling back to a
+// pathologically slow linear raycast.
+
+const EPSILON_RATIO = 0.01;
+
+// Fixed cosine-weighted hemisphere directions (golden-spiral layout) in
+// tangent space (+Z = surface normal).
+function hemisphereDirections(count) {
+  const directions = [];
+  const golden = Math.PI * (3 - Math.sqrt(5));
+  for (let i = 0; i < count; i += 1) {
+    // Cosine-weighted: z = sqrt(1 - t) concentrates samples toward the pole.
+    const t = (i + 0.5) / count;
+    const z = Math.sqrt(1 - t);
+    const radius = Math.sqrt(t);
+    const angle = golden * i;
+    directions.push(new THREE.Vector3(
+      Math.cos(angle) * radius,
+      Math.sin(angle) * radius,
+      z,
+    ));
+  }
+  return directions;
+}
+
+function buildOccluderGeometry(occluderRoot) {
+  const positions = [];
+  const vertex = new THREE.Vector3();
+  occluderRoot.updateMatrixWorld(true);
+  occluderRoot.traverse((obj) => {
+    if (!obj.isMesh || !obj.geometry?.attributes?.position) return;
+    if (obj.userData?.environmentShaderExclude) return;
+    if (obj.userData?.environmentVertexAoOccluderExclude) return;
+    const geometry = obj.geometry;
+    const position = geometry.attributes.position;
+    const index = geometry.index;
+    const count = index ? index.count : position.count;
+    for (let i = 0; i < count; i += 1) {
+      const vertexIndex = index ? index.getX(i) : i;
+      vertex.fromBufferAttribute(position, vertexIndex).applyMatrix4(obj.matrixWorld);
+      positions.push(vertex.x, vertex.y, vertex.z);
+    }
+  });
+  if (positions.length === 0) return null;
+  const merged = new THREE.BufferGeometry();
+  merged.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  return merged;
+}
+
+export async function bakeEnvironmentVertexAo(meshes, {
+  occluderRoot = null,
+  environmentBox = null,
+  rayCount = 12,
+  maxDistance = null,
+  vertexBudget = 200000,
+  // Occlusion floor keeps fully-enclosed corners readable instead of black.
+  occlusionFloor = 0.22,
+  // Yield to the main thread between slices so big bakes do not jank a
+  // running frame loop; pass 0 to bake synchronously (deterministic scripts).
+  sliceSize = 6000,
+  onProgress = null,
+  shouldContinue = () => true,
+} = {}) {
+  const targets = (Array.isArray(meshes) ? meshes : [meshes]).filter((mesh) => mesh?.isMesh);
+  if (targets.length === 0 || !occluderRoot) return { bakedMeshCount: 0, skippedMeshCount: 0 };
+
+  let MeshBVH;
+  try {
+    ({ MeshBVH } = await import('three-mesh-bvh'));
+  } catch (error) {
+    console.warn('[environmentVertexAo] three-mesh-bvh unavailable; skipping vertex AO bake.', error);
+    return { bakedMeshCount: 0, skippedMeshCount: targets.length };
+  }
+
+  const occluderGeometry = buildOccluderGeometry(occluderRoot);
+  if (!occluderGeometry) return { bakedMeshCount: 0, skippedMeshCount: targets.length };
+  const bvh = new MeshBVH(occluderGeometry);
+
+  function abortedResult() {
+    occluderGeometry.dispose();
+    return {
+      aborted: true,
+      bakedMeshCount,
+      skippedMeshCount: targets.length - bakedMeshCount,
+    };
+  }
+
+  const size = environmentBox?.getSize(new THREE.Vector3()) ?? null;
+  const reach = Number.isFinite(maxDistance) && maxDistance > 0
+    ? maxDistance
+    : size
+      ? Math.max((size.x + size.y + size.z) / 3 * 0.35, 0.5)
+      : 4;
+  const epsilon = reach * EPSILON_RATIO;
+  const directions = hemisphereDirections(Math.max(4, Math.round(rayCount)));
+
+  const ray = new THREE.Ray();
+  const normalMatrix = new THREE.Matrix3();
+  const worldPosition = new THREE.Vector3();
+  const worldNormal = new THREE.Vector3();
+  const tangent = new THREE.Vector3();
+  const bitangent = new THREE.Vector3();
+  const sampleDir = new THREE.Vector3();
+
+  let bakedMeshCount = 0;
+  let skippedMeshCount = 0;
+  let usedVertexBudget = 0;
+  let processedSinceYield = 0;
+
+  for (const mesh of targets) {
+    if (!shouldContinue()) return abortedResult();
+    const geometry = mesh.geometry;
+    const position = geometry?.attributes?.position;
+    const normal = geometry?.attributes?.normal;
+    if (!position || !normal) {
+      skippedMeshCount += 1;
+      continue;
+    }
+    if (usedVertexBudget + position.count > vertexBudget) {
+      skippedMeshCount += 1;
+      console.warn(
+        `[environmentVertexAo] Skipping "${mesh.name || 'unnamed mesh'}" (${position.count} verts): `
+        + `vertex budget ${vertexBudget} exhausted. Raise vertexAoOptions.vertexBudget to include it.`,
+      );
+      continue;
+    }
+    usedVertexBudget += position.count;
+
+    mesh.updateMatrixWorld(true);
+    normalMatrix.getNormalMatrix(mesh.matrixWorld);
+    const ao = new Float32Array(position.count);
+
+    for (let i = 0; i < position.count; i += 1) {
+      worldPosition.fromBufferAttribute(position, i).applyMatrix4(mesh.matrixWorld);
+      worldNormal.fromBufferAttribute(normal, i).applyMatrix3(normalMatrix).normalize();
+
+      // Orthonormal basis around the world normal.
+      if (Math.abs(worldNormal.x) > 0.9) tangent.set(0, 1, 0);
+      else tangent.set(1, 0, 0);
+      bitangent.crossVectors(worldNormal, tangent).normalize();
+      tangent.crossVectors(bitangent, worldNormal).normalize();
+
+      let occlusion = 0;
+      let totalWeight = 0;
+      for (const dir of directions) {
+        sampleDir.copy(tangent).multiplyScalar(dir.x)
+          .addScaledVector(bitangent, dir.y)
+          .addScaledVector(worldNormal, dir.z)
+          .normalize();
+        ray.origin.copy(worldPosition).addScaledVector(worldNormal, epsilon);
+        ray.direction.copy(sampleDir);
+        const weight = dir.z;
+        totalWeight += weight;
+        const hit = bvh.raycastFirst(ray, THREE.DoubleSide);
+        if (hit && hit.distance < reach) {
+          occlusion += weight * (1 - hit.distance / reach);
+        }
+      }
+      const visibility = 1 - (totalWeight > 0 ? occlusion / totalWeight : 0);
+      ao[i] = THREE.MathUtils.clamp(
+        occlusionFloor + (1 - occlusionFloor) * visibility, 0, 1);
+
+      processedSinceYield += 1;
+      if (sliceSize > 0 && processedSinceYield >= sliceSize) {
+        processedSinceYield = 0;
+        onProgress?.(usedVertexBudget, vertexBudget);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        if (!shouldContinue()) return abortedResult();
+      }
+    }
+
+    geometry.setAttribute('envVertexAo', new THREE.BufferAttribute(ao, 1));
+    bakedMeshCount += 1;
+  }
+
+  occluderGeometry.dispose();
+  return { bakedMeshCount, skippedMeshCount };
+}

package/src/environment/index.js

@@ -0,0 +1,8 @@
+// Environment shading barrel. Import from '@call-me-sensei/toonlab/environment'.
+export * from './environmentMaterialAdapter.js';
+export * from './environmentSettings.js';
+export * from './environmentPresets.js';
+export * from './environmentRigs.js';
+export * from './environmentTimeOfDay.js';
+export * from './environmentAmbientProbe.js';
+export * from './environmentPlanarReflection.js';

package/src/environment/scanAssetStylize.js

@@ -0,0 +1,103 @@
+import * as THREE from 'three';
+
+import { copyTextureTransform } from './environmentTextureResolver.js';
+
+// Photoscan assets (Megascans/Fab exports) read as "posterized photos" under
+// the toon environment shader: their albedo carries photographic micro-detail
+// (grain, dirt, cracks, baked-in AO) that stylized stages never have, and
+// their detail maps (normal/AO) respond too literally to light. This module
+// is the opt-in stylization pass that pushes such assets toward an authored,
+// hand-painted read without touching the geometry:
+//
+//   1. Albedo simplify — redraw the base map at a capped size through a blur
+//      + saturation lift so photo grain collapses into painterly gradients.
+//   2. Detail compression — reduce normal-map strength, soften AO and warm
+//      its tint (roughness/metalness are already ignored by the toon path).
+//   3. Painterly color response — raise saturation, cool the shade tint, and
+//      add a subtle broad specular sheen so edges catch the sun.
+//
+// Applied per-material inside applyEnvironmentShader when scanStylize is
+// 'auto' (detected scan assets only) or true; never applied when false or
+// when material.userData.envScanStylize === false.
+
+// Fab/Megascans exports name meshes `<assetId>_LOD0_TIER2_...` and materials
+// `<Asset_Name>_<assetId>_<Quality>`; the LOD/TIER token is the reliable
+// tell. Explicit 'megascan'/'quixel' naming also qualifies.
+const SCAN_NAME_PATTERN = /(_lod\d+_tier\d+)|megascan|quixel/i;
+
+export function isScanAssetMaterial(obj, mat) {
+  if (mat?.userData?.envScanStylize === false) return false;
+  if (mat?.userData?.envScanStylize === true) return true;
+  return SCAN_NAME_PATTERN.test(`${obj?.name ?? ''} ${mat?.name ?? ''}`);
+}
+
+export const DEFAULT_SCAN_STYLIZE_PARAMS = {
+  // Albedo simplification. Blur is in pixels at the capped size, so it scales
+  // with however large the source texture was.
+  albedoMaxSize: 512,
+  albedoBlur: 1.6,
+  albedoSaturate: 1.18,
+  albedoBrightness: 1.04,
+  // Detail-map response compression.
+  normalMapStrength: 0.35,
+  aoMapStrength: 0.65,
+  aoWarmth: 0.7,
+  // Painterly color response: saturated color, cool shade, sun-catch sheen.
+  saturation: 1.2,
+  shadowTintColor: [0.7, 0.76, 0.94],
+  specularStrength: 0.1,
+  specularShininess: 24,
+  specularSoftness: 0.5,
+};
+
+const stylizedTextureCache = new WeakMap();
+
+// Returns a simplified copy of a scan albedo texture (cached per source).
+// The source draws twice: once sharp so canvas-edge blur transparency never
+// shows at UV seams, once through the blur/saturate filter on top.
+export function stylizeScanBaseMap(texture, params = DEFAULT_SCAN_STYLIZE_PARAMS) {
+  const image = texture?.image;
+  if (!image || !(image.width > 0) || !(image.height > 0)) return texture;
+  if (stylizedTextureCache.has(texture)) return stylizedTextureCache.get(texture);
+
+  const scale = Math.min(1, params.albedoMaxSize / Math.max(image.width, image.height));
+  const canvas = document.createElement('canvas');
+  canvas.width = Math.max(1, Math.round(image.width * scale));
+  canvas.height = Math.max(1, Math.round(image.height * scale));
+  const ctx = canvas.getContext('2d');
+  ctx.imageSmoothingEnabled = true;
+  ctx.imageSmoothingQuality = 'high';
+  ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
+  ctx.filter = `blur(${params.albedoBlur}px) saturate(${params.albedoSaturate}) brightness(${params.albedoBrightness})`;
+  ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
+
+  const stylized = new THREE.CanvasTexture(canvas);
+  copyTextureTransform(stylized, texture);
+  stylized.colorSpace = texture.colorSpace ?? THREE.SRGBColorSpace;
+  stylized.needsUpdate = true;
+  stylizedTextureCache.set(texture, stylized);
+  return stylized;
+}
+
+// Compresses the detail-map and color response of a converted environment
+// ShaderMaterial. No-op for the basic/standard debug material modes.
+export function applyScanStylizeToMaterial(material, params = DEFAULT_SCAN_STYLIZE_PARAMS) {
+  const uniforms = material?.uniforms;
+  if (!uniforms) return material;
+  if (uniforms.normalMapStrength) uniforms.normalMapStrength.value = params.normalMapStrength;
+  if (uniforms.aoMapStrength) {
+    uniforms.aoMapStrength.value = Math.min(uniforms.aoMapStrength.value, params.aoMapStrength);
+  }
+  if (uniforms.aoWarmth) uniforms.aoWarmth.value = params.aoWarmth;
+  if (uniforms.saturation) uniforms.saturation.value = params.saturation;
+  if (uniforms.shadowTintColor && params.shadowTintColor) {
+    uniforms.shadowTintColor.value.setRGB(...params.shadowTintColor);
+  }
+  if (uniforms.specularStrength && params.specularStrength > uniforms.specularStrength.value) {
+    uniforms.specularStrength.value = params.specularStrength;
+    uniforms.specularShininess.value = params.specularShininess;
+    uniforms.specularSoftness.value = params.specularSoftness;
+  }
+  material.userData.scanStylized = true;
+  return material;
+}

package/src/index.js

@@ -0,0 +1,21 @@
+export * from './toon/toonMaterialAdapter.js';
+export * from './toon/toonSettings.js';
+export * from './toon/characterRenderPasses.js';
+export * from './environment/environmentMaterialAdapter.js';
+export * from './environment/environmentSettings.js';
+export * from './environment/environmentAmbientProbe.js';
+export * from './environment/environmentPlanarReflection.js';
+export * from './environment/environmentPresets.js';
+export * from './environment/environmentRigs.js';
+export * from './environment/environmentTimeOfDay.js';
+export * from './post/postProcessing.js';
+export * from './water/water.js';
+export * from './sky/stylizedSky.js';
+export * from './vegetation/stylizedGrass.js';
+export * from './vegetation/stylizedTreeFoliage.js';
+export * from './vegetation/stylizedTree.js';
+export * from './vegetation/stylizedFlowers.js';
+export * from './character/characterRig.js';
+export * from './character/freestyleSwimClip.js';
+export * from './rockgen/index.js';
+export * from './debrisgen/index.js';

package/src/loaders/index.js

@@ -0,0 +1 @@
+export * from '../character/modelLoader.js';

package/src/post/index.js

@@ -0,0 +1,2 @@
+// Post-processing barrel. Import from '@call-me-sensei/toonlab/post'.
+export * from './postProcessing.js';