@call-me-sensei/toonlab 0.1.1

package/src/toon/settings/alphaSettings.js

@@ -0,0 +1,170 @@
+import {
+  hasAnyToken,
+  materialText,
+  roleIsFace,
+  roleIsHair,
+  roleIsSkin,
+  roleIsTransparentOverlay,
+} from '../../core/materialRoles.js';
+
+export const DEFAULT_ALPHA_SETTINGS = Object.freeze({
+  blendCutoff: 0.02,
+  costumeCutout: true,
+  cutoutCutoff: 0.35,
+  // Bayer-matrix screen-door fade (1 = fully visible). Unlike alpha blending
+  // it needs no sorting, keeps depth writes, and works with outlines — the
+  // standard way to fade a whole character in/out. Runtime helper:
+  // setToonDitherOpacity(root, value).
+  ditherOpacity: 1,
+  enabled: true,
+  expressionTokenCutout: true,
+  eyeHighlightOrder: 12,
+  eyeOrder: 11,
+  faceCutout: true,
+  hairCutout: true,
+  mapTransparentCutout: true,
+  overlayDepthWrite: false,
+  overlayOrder: 20,
+  preserveSourceAlphaTest: true,
+  scleraOrder: 10,
+  skinCutout: true,
+  sortOverlays: true,
+  sourceAlphaMapCutout: true,
+  sourceTransparentCutout: true,
+  transparentOverlayBlend: true,
+  transparentOpacityThreshold: 0.999,
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function enabledOption(value) {
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    return normalized !== 'off' && normalized !== 'none' && normalized !== 'false' && normalized !== '0';
+  }
+  return value !== false;
+}
+
+function normalizeAlphaOptions(options) {
+  if (options === false) return { enabled: false };
+  if (options === true) return { enabled: true };
+  if (typeof options === 'string') return { enabled: enabledOption(options) };
+  return options || {};
+}
+
+export function createAlphaSettings(options = null) {
+  const source = normalizeAlphaOptions(options);
+  const enabled = enabledOption(source.enabled);
+
+  return {
+    blendCutoff: enabled
+      ? numberOption(firstDefined(source, ['blendCutoff', 'blendAlphaTest', 'blendThreshold']), DEFAULT_ALPHA_SETTINGS.blendCutoff, { min: 0, max: 1 })
+      : -1,
+    costumeCutout: source.costumeCutout !== undefined ? enabledOption(source.costumeCutout) : DEFAULT_ALPHA_SETTINGS.costumeCutout,
+    cutoutCutoff: enabled
+      ? numberOption(firstDefined(source, ['cutoutCutoff', 'alphaCutoff', 'alphaTest', 'cutoutThreshold']), DEFAULT_ALPHA_SETTINGS.cutoutCutoff, { min: 0, max: 1 })
+      : -1,
+    ditherOpacity: numberOption(
+      firstDefined(source, ['ditherOpacity', 'ditherFadeout', 'fadeOpacity']),
+      DEFAULT_ALPHA_SETTINGS.ditherOpacity,
+      { min: 0, max: 1 },
+    ),
+    enabled,
+    expressionTokenCutout: source.expressionTokenCutout !== undefined ? enabledOption(source.expressionTokenCutout) : DEFAULT_ALPHA_SETTINGS.expressionTokenCutout,
+    eyeHighlightOrder: numberOption(firstDefined(source, ['eyeHighlightOrder', 'catchlightOrder']), DEFAULT_ALPHA_SETTINGS.eyeHighlightOrder, { min: -100, max: 100 }),
+    eyeOrder: numberOption(firstDefined(source, ['eyeOrder', 'irisOrder', 'pupilOrder']), DEFAULT_ALPHA_SETTINGS.eyeOrder, { min: -100, max: 100 }),
+    faceCutout: source.faceCutout !== undefined ? enabledOption(source.faceCutout) : DEFAULT_ALPHA_SETTINGS.faceCutout,
+    hairCutout: source.hairCutout !== undefined ? enabledOption(source.hairCutout) : DEFAULT_ALPHA_SETTINGS.hairCutout,
+    mapTransparentCutout: source.mapTransparentCutout !== undefined ? enabledOption(source.mapTransparentCutout) : DEFAULT_ALPHA_SETTINGS.mapTransparentCutout,
+    overlayDepthWrite: source.overlayDepthWrite !== undefined ? enabledOption(source.overlayDepthWrite) : DEFAULT_ALPHA_SETTINGS.overlayDepthWrite,
+    overlayOrder: numberOption(firstDefined(source, ['overlayOrder', 'transparentOverlayOrder']), DEFAULT_ALPHA_SETTINGS.overlayOrder, { min: -100, max: 100 }),
+    preserveSourceAlphaTest: source.preserveSourceAlphaTest !== undefined ? enabledOption(source.preserveSourceAlphaTest) : DEFAULT_ALPHA_SETTINGS.preserveSourceAlphaTest,
+    scleraOrder: numberOption(firstDefined(source, ['scleraOrder', 'eyeWhiteOrder']), DEFAULT_ALPHA_SETTINGS.scleraOrder, { min: -100, max: 100 }),
+    skinCutout: source.skinCutout !== undefined ? enabledOption(source.skinCutout) : DEFAULT_ALPHA_SETTINGS.skinCutout,
+    sortOverlays: source.sortOverlays !== undefined ? enabledOption(source.sortOverlays) : DEFAULT_ALPHA_SETTINGS.sortOverlays,
+    sourceAlphaMapCutout: source.sourceAlphaMapCutout !== undefined ? enabledOption(source.sourceAlphaMapCutout) : DEFAULT_ALPHA_SETTINGS.sourceAlphaMapCutout,
+    sourceTransparentCutout: source.sourceTransparentCutout !== undefined ? enabledOption(source.sourceTransparentCutout) : DEFAULT_ALPHA_SETTINGS.sourceTransparentCutout,
+    transparentOverlayBlend: source.transparentOverlayBlend !== undefined ? enabledOption(source.transparentOverlayBlend) : DEFAULT_ALPHA_SETTINGS.transparentOverlayBlend,
+    transparentOpacityThreshold: numberOption(
+      firstDefined(source, ['transparentOpacityThreshold', 'opaqueOpacityThreshold', 'opacityThreshold']),
+      DEFAULT_ALPHA_SETTINGS.transparentOpacityThreshold,
+      { min: 0, max: 1 },
+    ),
+  };
+}
+
+export function sourceOpacity(mat) {
+  return Number.isFinite(mat?.opacity) ? mat.opacity : 1;
+}
+
+export function usesAlphaCutout(mat, roleInfo, settings = createAlphaSettings()) {
+  if (!settings.enabled || !mat || roleIsTransparentOverlay(roleInfo)) return false;
+
+  const text = materialText(mat);
+  const tokenCutout = settings.expressionTokenCutout &&
+    hasAnyToken(text, ['skin', 'costume', 'cloth', 'clothes', 'hair', 'expression']);
+
+  return (
+    (settings.preserveSourceAlphaTest && Number.isFinite(mat.alphaTest) && mat.alphaTest > 0) ||
+    (settings.sourceAlphaMapCutout && Boolean(mat.alphaMap)) ||
+    (settings.mapTransparentCutout && mat.map?.transparent === true) ||
+    (settings.sourceTransparentCutout && mat.transparent === true && sourceOpacity(mat) >= settings.transparentOpacityThreshold) ||
+    (settings.skinCutout && roleIsSkin(roleInfo)) ||
+    (settings.faceCutout && roleIsFace(roleInfo)) ||
+    (settings.hairCutout && roleIsHair(roleInfo)) ||
+    (settings.costumeCutout && roleInfo?.role === 'costume') ||
+    tokenCutout
+  );
+}
+
+export function usesAlphaBlend(mat, roleInfo, settings = createAlphaSettings()) {
+  if (!settings.enabled || !mat) return false;
+  if (roleIsTransparentOverlay(roleInfo)) return settings.transparentOverlayBlend;
+  return mat.transparent === true && sourceOpacity(mat) < settings.transparentOpacityThreshold;
+}
+
+export function alphaTestForMaterial(mat, roleInfo, settings = createAlphaSettings()) {
+  if (usesAlphaBlend(mat, roleInfo, settings)) {
+    return Math.max(mat?.alphaTest ?? settings.blendCutoff, settings.blendCutoff);
+  }
+  if (usesAlphaCutout(mat, roleInfo, settings)) {
+    return Math.max(mat?.alphaTest ?? settings.cutoutCutoff, settings.cutoutCutoff);
+  }
+  return -1.0;
+}
+
+export function resolveAlphaForMaterial(settings, mat, roleInfo) {
+  const alphaBlend = usesAlphaBlend(mat, roleInfo, settings);
+  const alphaCutout = usesAlphaCutout(mat, roleInfo, settings);
+
+  return {
+    alphaBlend,
+    alphaCutout,
+    alphaTest: alphaTestForMaterial(mat, roleInfo, settings),
+    depthWrite: roleIsTransparentOverlay(roleInfo) ? settings.overlayDepthWrite : !alphaBlend,
+    opacity: sourceOpacity(mat),
+    transparent: mat?.transparent === true && !alphaCutout,
+  };
+}
+
+export function materialAlphaDrawOrder(settings, mat, roleInfo) {
+  if (!settings.sortOverlays) return 0;
+
+  const text = materialText(mat);
+  if (text.includes('白目') || roleInfo?.role === 'sclera') return settings.scleraOrder;
+  if (roleInfo?.role === 'eye' || roleInfo?.role === 'iris' || roleInfo?.role === 'pupil') return settings.eyeOrder;
+  if (roleInfo?.role === 'eyeHighlight' || roleInfo?.role === 'catchlight') return settings.eyeHighlightOrder;
+  if (roleIsTransparentOverlay(roleInfo)) return settings.overlayOrder;
+  return 0;
+}

package/src/toon/settings/averageShadowSettings.js

@@ -0,0 +1,181 @@
+export const DEFAULT_AVERAGE_SHADOW_SETTINGS = Object.freeze({
+  defaultMinLight: 0.28,
+  defaultStrength: 0.28,
+  enabled: false,
+  // Blends the per-pixel scene shadow toward a single measured per-character
+  // average (sampled around the character's bounding sphere by the runtime
+  // pass). Stops shadow boundaries from slicing a character in half when they
+  // stand at a shadow edge. Requires characterRenderPasses; inert otherwise.
+  measuredBlend: 0.65,
+  eyeMinLight: 1,
+  eyeStrength: 0,
+  faceMinLight: 1,
+  faceStrength: 0,
+  hairMinLight: 0.3,
+  hairStrength: 0.22,
+  skinMinLight: 0.4,
+  skinStrength: 0.18,
+  softness: 0.35,
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function normalizeAverageShadowOptions(options) {
+  if (options === true) return { enabled: true };
+  if (typeof options === 'string') {
+    const key = options.trim().toLowerCase();
+    return {
+      enabled: key !== 'off' && key !== 'none' && key !== 'false' && key !== '0',
+    };
+  }
+  return options || {};
+}
+
+function hasExplicitSettings(source) {
+  return Object.keys(source).some((key) => key !== 'enabled');
+}
+
+export function createAverageShadowSettings(options = null) {
+  const source = normalizeAverageShadowOptions(options);
+  const enabled = source.enabled === true ||
+    (source.enabled !== false && hasExplicitSettings(source));
+
+  return {
+    defaultMinLight: enabled
+      ? numberOption(
+        firstDefined(source, ['defaultMinLight', 'minLight', 'averageShadowMinLight']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.defaultMinLight,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    defaultStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['defaultStrength', 'strength', 'averageShadowStrength']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.defaultStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    enabled,
+    // measuredBlend is intentionally independent of `enabled`: the smoothing
+    // layer and the measured replacement solve different problems.
+    measuredBlend: numberOption(
+      firstDefined(source, ['measuredBlend', 'measuredShadowBlend', 'averageMeasuredBlend']),
+      DEFAULT_AVERAGE_SHADOW_SETTINGS.measuredBlend,
+      { min: 0, max: 1 },
+    ),
+    eyeMinLight: enabled
+      ? numberOption(
+        firstDefined(source, ['eyeMinLight', 'eyeAverageShadowMinLight']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.eyeMinLight,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    eyeStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['eyeStrength', 'eyeAverageShadowStrength']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.eyeStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    faceMinLight: enabled
+      ? numberOption(
+        firstDefined(source, ['faceMinLight', 'faceAverageShadowMinLight']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.faceMinLight,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    faceStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['faceStrength', 'faceAverageShadowStrength']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.faceStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    hairMinLight: enabled
+      ? numberOption(
+        firstDefined(source, ['hairMinLight', 'hairAverageShadowMinLight']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.hairMinLight,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    hairStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['hairStrength', 'hairAverageShadowStrength']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.hairStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    skinMinLight: enabled
+      ? numberOption(
+        firstDefined(source, ['skinMinLight', 'skinAverageShadowMinLight']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.skinMinLight,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    skinStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['skinStrength', 'skinAverageShadowStrength']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.skinStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    softness: enabled
+      ? numberOption(
+        firstDefined(source, ['softness', 'averageShadowSoftness', 'visibilitySoftness']),
+        DEFAULT_AVERAGE_SHADOW_SETTINGS.softness,
+        { min: 0, max: 1 },
+      )
+      : 0,
+  };
+}
+
+export function resolveAverageShadowForMaterial(settings, {
+  isEye = false,
+  isFace = false,
+  isHair = false,
+  isSkin = false,
+} = {}) {
+  if (isEye) {
+    return {
+      minLight: settings.eyeMinLight,
+      strength: settings.eyeStrength,
+    };
+  }
+
+  if (isFace) {
+    return {
+      minLight: settings.faceMinLight,
+      strength: settings.faceStrength,
+    };
+  }
+
+  if (isSkin) {
+    return {
+      minLight: settings.skinMinLight,
+      strength: settings.skinStrength,
+    };
+  }
+
+  if (isHair) {
+    return {
+      minLight: settings.hairMinLight,
+      strength: settings.hairStrength,
+    };
+  }
+
+  return {
+    minLight: settings.defaultMinLight,
+    strength: settings.defaultStrength,
+  };
+}

package/src/toon/settings/baseTextureSettings.js

@@ -0,0 +1,133 @@
+import * as THREE from 'three';
+
+export const BASE_TEXTURE_MATERIAL_COLOR_MODES = Object.freeze({
+  legacy: 'legacy',
+  source: 'source',
+  texture: 'texture',
+  white: 'white',
+});
+
+export const BASE_TEXTURE_SATURATION_MODES = Object.freeze({
+  legacy: 'legacy',
+  source: 'source',
+  custom: 'custom',
+});
+
+export const DEFAULT_BASE_TEXTURE_SETTINGS = Object.freeze({
+  customSaturation: 1,
+  materialColorMode: BASE_TEXTURE_MATERIAL_COLOR_MODES.legacy,
+  saturationMode: BASE_TEXTURE_SATURATION_MODES.legacy,
+});
+
+const MATERIAL_COLOR_MODE_ALIASES = Object.freeze({
+  '': BASE_TEXTURE_MATERIAL_COLOR_MODES.legacy,
+  auto: BASE_TEXTURE_MATERIAL_COLOR_MODES.legacy,
+  default: BASE_TEXTURE_MATERIAL_COLOR_MODES.legacy,
+  ignore: BASE_TEXTURE_MATERIAL_COLOR_MODES.texture,
+  legacy: BASE_TEXTURE_MATERIAL_COLOR_MODES.legacy,
+  none: BASE_TEXTURE_MATERIAL_COLOR_MODES.white,
+  preserve: BASE_TEXTURE_MATERIAL_COLOR_MODES.source,
+  raw: BASE_TEXTURE_MATERIAL_COLOR_MODES.source,
+  source: BASE_TEXTURE_MATERIAL_COLOR_MODES.source,
+  texture: BASE_TEXTURE_MATERIAL_COLOR_MODES.texture,
+  textureonly: BASE_TEXTURE_MATERIAL_COLOR_MODES.texture,
+  white: BASE_TEXTURE_MATERIAL_COLOR_MODES.white,
+});
+
+const SATURATION_MODE_ALIASES = Object.freeze({
+  '': BASE_TEXTURE_SATURATION_MODES.legacy,
+  auto: BASE_TEXTURE_SATURATION_MODES.legacy,
+  custom: BASE_TEXTURE_SATURATION_MODES.custom,
+  default: BASE_TEXTURE_SATURATION_MODES.legacy,
+  legacy: BASE_TEXTURE_SATURATION_MODES.legacy,
+  preserve: BASE_TEXTURE_SATURATION_MODES.source,
+  raw: BASE_TEXTURE_SATURATION_MODES.source,
+  source: BASE_TEXTURE_SATURATION_MODES.source,
+});
+
+function normalizeKey(value) {
+  return String(value ?? '')
+    .trim()
+    .replace(/[\s_-]+/g, '')
+    .toLowerCase();
+}
+
+function normalizeMaterialColorMode(value, fallback) {
+  return MATERIAL_COLOR_MODE_ALIASES[normalizeKey(value)] ?? fallback;
+}
+
+function normalizeSaturationMode(value, fallback) {
+  return SATURATION_MODE_ALIASES[normalizeKey(value)] ?? fallback;
+}
+
+export function createBaseTextureSettings(options = null) {
+  if (!options) return DEFAULT_BASE_TEXTURE_SETTINGS;
+
+  if (typeof options === 'string') {
+    return {
+      ...DEFAULT_BASE_TEXTURE_SETTINGS,
+      materialColorMode: normalizeMaterialColorMode(options, DEFAULT_BASE_TEXTURE_SETTINGS.materialColorMode),
+    };
+  }
+
+  const preserveSource = options.preserveSource === true || options.preserve === true;
+  const fallbackMode = preserveSource
+    ? BASE_TEXTURE_MATERIAL_COLOR_MODES.source
+    : DEFAULT_BASE_TEXTURE_SETTINGS.materialColorMode;
+  const fallbackSaturationMode = preserveSource
+    ? BASE_TEXTURE_SATURATION_MODES.source
+    : DEFAULT_BASE_TEXTURE_SETTINGS.saturationMode;
+  const customSaturation = Number.isFinite(options.customSaturation)
+    ? options.customSaturation
+    : Number.isFinite(options.saturation)
+      ? options.saturation
+      : DEFAULT_BASE_TEXTURE_SETTINGS.customSaturation;
+
+  return {
+    customSaturation,
+    materialColorMode: normalizeMaterialColorMode(
+      options.materialColorMode ?? options.materialColor ?? options.colorMode,
+      fallbackMode,
+    ),
+    saturationMode: normalizeSaturationMode(
+      options.saturationMode ?? options.saturationPolicy,
+      fallbackSaturationMode,
+    ),
+  };
+}
+
+export function getSourceMaterialColor(mat) {
+  return mat?.color?.isColor ? mat.color : new THREE.Color(1, 1, 1);
+}
+
+function isNeutralTextureMultiplier(color) {
+  const maxChannel = Math.max(color.r, color.g, color.b);
+  const minChannel = Math.min(color.r, color.g, color.b);
+  const luma = color.r * 0.2126 + color.g * 0.7152 + color.b * 0.0722;
+  return maxChannel - minChannel < 0.04 && luma < 0.98;
+}
+
+export function resolveBaseMaterialColor(mat, settings = DEFAULT_BASE_TEXTURE_SETTINGS) {
+  const sourceColor = getSourceMaterialColor(mat);
+  const hasTexture = mat?.map?.isTexture === true;
+  const mode = settings.materialColorMode ?? DEFAULT_BASE_TEXTURE_SETTINGS.materialColorMode;
+
+  if (mode === BASE_TEXTURE_MATERIAL_COLOR_MODES.white) return new THREE.Color(1, 1, 1);
+  if (mode === BASE_TEXTURE_MATERIAL_COLOR_MODES.texture && hasTexture) return new THREE.Color(1, 1, 1);
+  if (
+    mode === BASE_TEXTURE_MATERIAL_COLOR_MODES.legacy &&
+    hasTexture &&
+    isNeutralTextureMultiplier(sourceColor)
+  ) {
+    return new THREE.Color(1, 1, 1);
+  }
+
+  return sourceColor;
+}
+
+export function resolveBaseMapSaturation({ isFace = false, isSkin = false } = {}, settings = DEFAULT_BASE_TEXTURE_SETTINGS) {
+  const mode = settings.saturationMode ?? DEFAULT_BASE_TEXTURE_SETTINGS.saturationMode;
+  if (mode === BASE_TEXTURE_SATURATION_MODES.source) return 1;
+  if (mode === BASE_TEXTURE_SATURATION_MODES.custom) return settings.customSaturation;
+  return isSkin || isFace ? 0.98 : 1.04;
+}

package/src/toon/settings/celShadeSettings.js

@@ -0,0 +1,96 @@
+export const DEFAULT_CEL_SHADE_SETTINGS = Object.freeze({
+  bodyCelMidPoint: 0.06,
+  bodyCelSoftness: 0.045,
+  bodyMainLightIgnoreCelShade: 0.02,
+  edgeAntiAliasStrength: 1,
+  enabled: true,
+});
+
+export const REFERENCE_CEL_SHADE_SETTINGS = Object.freeze({
+  bodyCelMidPoint: 0,
+  bodyCelSoftness: 0.05,
+  bodyMainLightIgnoreCelShade: 0,
+  edgeAntiAliasStrength: 1,
+  enabled: true,
+});
+
+export const CEL_SHADE_PRESETS = Object.freeze({
+  baseline: DEFAULT_CEL_SHADE_SETTINGS,
+  reference: REFERENCE_CEL_SHADE_SETTINGS,
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function resolvePresetDefaults(source) {
+  const presetName = String(firstDefined(source, ['preset', 'profile']) || 'baseline').toLowerCase();
+  return CEL_SHADE_PRESETS[presetName] || DEFAULT_CEL_SHADE_SETTINGS;
+}
+
+export function createCelShadeSettings(options = null) {
+  const source = typeof options === 'string' ? { preset: options } : options || {};
+  const presetDefaults = resolvePresetDefaults(source);
+  const enabled = source.enabled !== false;
+
+  return {
+    bodyCelMidPoint: enabled
+      ? numberOption(
+        firstDefined(source, [
+          'bodyCelMidPoint',
+          'bodyCelThreshold',
+          'celMidPoint',
+          'mainCelMidPoint',
+          'mainLightCelMidPoint',
+        ]),
+        presetDefaults.bodyCelMidPoint,
+        { min: -1, max: 1 },
+      )
+      : presetDefaults.bodyCelMidPoint,
+    bodyCelSoftness: enabled
+      ? numberOption(
+        firstDefined(source, [
+          'bodyCelSoftness',
+          'bodyCelFeather',
+          'celSoftness',
+          'mainCelSoftness',
+          'mainLightCelSoftness',
+        ]),
+        presetDefaults.bodyCelSoftness,
+        { min: 0.001, max: 1 },
+      )
+      : presetDefaults.bodyCelSoftness,
+    bodyMainLightIgnoreCelShade: enabled
+      ? numberOption(
+        firstDefined(source, [
+          'bodyMainLightIgnoreCelShade',
+          'bodyLightIgnoreCelShade',
+          'mainLightIgnoreCelShade',
+          'lightIgnoreCelShade',
+        ]),
+        presetDefaults.bodyMainLightIgnoreCelShade,
+        { min: 0, max: 1 },
+      )
+      : presetDefaults.bodyMainLightIgnoreCelShade,
+    // Widens cel/rim/specular transitions by the per-pixel screen derivative so
+    // band edges stay ~1px feathered at any resolution or camera distance.
+    // 0 disables and reproduces the raw smoothstep edge.
+    edgeAntiAliasStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['edgeAntiAliasStrength', 'edgeAntiAlias', 'edgeAA']),
+        presetDefaults.edgeAntiAliasStrength ?? DEFAULT_CEL_SHADE_SETTINGS.edgeAntiAliasStrength,
+        { min: 0, max: 4 },
+      )
+      : 0,
+    enabled,
+  };
+}

package/src/toon/settings/contactShadowSettings.js

@@ -0,0 +1,114 @@
+// Screen-space depth-sampled contact shadow.
+//
+// Samples the scene depth prepass a short screen-space step toward the light;
+// when a closer surface sits just in front of the current pixel along that
+// direction, the pixel is treated as being in that surface's contact shadow.
+// The visible result is the thin anime "hair shadow" line where hair meets the
+// forehead, and grounding shadows where an arm crosses the torso.
+//
+// This only activates while a scene depth prepass is running (see
+// characterRenderPasses.js) and is automatically suppressed during dither
+// fadeout, because a fading character no longer writes reliable depth.
+
+export const DEFAULT_CONTACT_SHADOW_SETTINGS = Object.freeze({
+  enabled: true,
+  // How strongly the contact shadow darkens the cel band. 0 disables.
+  strength: 0.5,
+  // Face uses the head-up direction blend so hair shadows drape downward even
+  // when the light comes from the side. 0 = always use the light direction.
+  faceHeadUpBlend: 0,
+  // Face receives a separate (usually lower) strength; hair-on-forehead is the
+  // main use case, so it defaults on but softer than the body.
+  faceStrength: 0.4,
+  fadeRange: 1,
+  thresholdOffset: 0,
+  // Screen-space sample distance, relative to the shared depth-effect width.
+  width: 1,
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function normalizeContactShadowOptions(options) {
+  if (options === false) return { enabled: false };
+  if (options === true) return { enabled: true };
+  if (typeof options === 'string') {
+    const key = options.trim().toLowerCase();
+    return { enabled: key !== 'off' && key !== 'none' && key !== 'false' && key !== '0' };
+  }
+  return options || {};
+}
+
+export function createContactShadowSettings(options = null) {
+  const source = normalizeContactShadowOptions(options);
+  const enabled = source.enabled !== false;
+
+  return {
+    enabled,
+    faceHeadUpBlend: numberOption(
+      firstDefined(source, ['faceHeadUpBlend', 'faceFixedDirection']),
+      DEFAULT_CONTACT_SHADOW_SETTINGS.faceHeadUpBlend,
+      { min: 0, max: 1 },
+    ),
+    faceStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['faceStrength', 'faceContactShadowStrength']),
+        DEFAULT_CONTACT_SHADOW_SETTINGS.faceStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    fadeRange: numberOption(
+      firstDefined(source, ['fadeRange', 'softness']),
+      DEFAULT_CONTACT_SHADOW_SETTINGS.fadeRange,
+      { min: 0.01, max: 20 },
+    ),
+    strength: enabled
+      ? numberOption(
+        firstDefined(source, ['strength', 'intensity', 'usage']),
+        DEFAULT_CONTACT_SHADOW_SETTINGS.strength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    thresholdOffset: numberOption(
+      firstDefined(source, ['thresholdOffset', 'depthThresholdOffset']),
+      DEFAULT_CONTACT_SHADOW_SETTINGS.thresholdOffset,
+      { min: -0.05, max: 1 },
+    ),
+    width: numberOption(
+      firstDefined(source, ['width', 'contactShadowWidth']),
+      DEFAULT_CONTACT_SHADOW_SETTINGS.width,
+      { min: 0, max: 8 },
+    ),
+  };
+}
+
+export function resolveContactShadowForMaterial(settings, {
+  isEye = false,
+  isFace = false,
+  isOutline = false,
+} = {}) {
+  // Eyes are drawn slightly proud of the face surface, so contact shadow
+  // reads as dirt on them; keep them clean like the eye scene-shadow default.
+  let strength = settings.strength;
+  if (isFace) strength = settings.faceStrength;
+  if (isEye || isOutline) strength = 0;
+
+  return {
+    enabled: settings.enabled && strength > 0,
+    faceHeadUpBlend: settings.faceHeadUpBlend,
+    fadeRange: settings.fadeRange,
+    strength,
+    thresholdOffset: settings.thresholdOffset,
+    width: settings.width,
+  };
+}