@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/texgen/textureSettings.js

@@ -0,0 +1,342 @@
+// Canonical settings, field metadata, and validation for the procedural
+// texture generator. The field schema below is the single source of truth:
+// defaults, the lab UI, recipe validation, and the AI parameter mapping all
+// derive from it (same pattern as rockgen/debrisgen *_SETTING_FIELD_SCHEMA).
+
+import { TEXTURE_GENERATORS, TEXTURE_GENERATOR_IDS } from './textureGenerators.js';
+
+export const TEXTURE_DETAIL_BLENDS = Object.freeze(['overlay', 'add', 'multiply', 'screen', 'min', 'max', 'mix']);
+export const TEXTURE_ACCENT_BLENDS = Object.freeze(['normal', 'multiply', 'overlay', 'screen']);
+export const TEXTURE_EMISSIVE_SOURCES = Object.freeze(['crevices', 'peaks', 'band', 'accentA', 'accentB', 'everywhere']);
+
+const GENERATOR_LABELS = Object.freeze(Object.fromEntries(
+  TEXTURE_GENERATOR_IDS.map((id) => [id, TEXTURE_GENERATORS[id].label]),
+));
+
+const num = (key, label, min, max, step, defaultValue, description, extra = {}) => Object.freeze({
+  defaultValue, description, key, label, range: Object.freeze({ max, min, step }), type: 'number', ...extra,
+});
+const bool = (key, label, defaultValue, description, extra = {}) => Object.freeze({
+  defaultValue, description, key, label, type: 'boolean', ...extra,
+});
+const sel = (key, label, options, optionLabels, defaultValue, description, extra = {}) => Object.freeze({
+  defaultValue, description, key, label, optionLabels, options, type: 'select', ...extra,
+});
+const col = (key, label, defaultValue, description, extra = {}) => Object.freeze({
+  defaultValue: Object.freeze(defaultValue), description, key, label, type: 'color', ...extra,
+});
+
+const generatorField = (defaultValue, description) => sel(
+  'generator', 'Pattern', TEXTURE_GENERATOR_IDS, GENERATOR_LABELS, defaultValue, description,
+);
+
+// Layer parameters shared by base/detail/accent layers. Which ones a given
+// generator reads is declared in TEXTURE_GENERATORS[id].uses — UIs filter
+// on that so only meaningful sliders show.
+const layerParamFields = ({ advancedShape = false } = {}) => [
+  num('scale', 'Scale', 1, 64, 1, 6, 'Feature cells across the tile. Higher = finer features.'),
+  bool('rotate90', 'Rotate 90°', false, 'Turns the pattern a quarter turn (planks run vertical, strata run horizontal). Tiling stays exact.', { advanced: true }),
+  num('detail', 'Detail octaves', 1, 8, 1, 4, 'Fractal octaves layered into the noise.'),
+  num('detailGain', 'Detail strength', 0.15, 0.85, 0.01, 0.5, 'How much each finer octave contributes.', { advanced: true }),
+  num('stretchX', 'Stretch X', 0.25, 8, 0.05, 1, 'Horizontal anisotropy (brushed metal, wood planks).', { advanced: true }),
+  num('stretchY', 'Stretch Y', 0.25, 8, 0.05, 1, 'Vertical anisotropy (drips, strata, fibers).', { advanced: true }),
+  num('warp', 'Warp', 0, 1, 0.01, 0, 'Domain warp: melts straight features into organic meanders.'),
+  num('warpScale', 'Warp scale', 1, 32, 1, 3, 'Frequency of the warp field.', { advanced: true }),
+  num('columns', 'Columns', 1, 64, 1, 4, 'Pattern cells across the tile.', { advanced: advancedShape }),
+  num('rows', 'Rows', 1, 64, 1, 8, 'Pattern cells down the tile.', { advanced: advancedShape }),
+  num('gap', 'Gap width', 0, 0.4, 0.005, 0.06, 'Mortar/groove width between pattern cells.', { advanced: advancedShape }),
+  num('bevel', 'Bevel', 0, 0.5, 0.005, 0.12, 'Edge ramp from groove up to the cell face.', { advanced: advancedShape }),
+  num('cellJitter', 'Cell jitter', 0, 1, 0.01, 1, 'Randomizes cell centers: 0 = perfect grid, 1 = organic.', { advanced: true }),
+  num('cellVariation', 'Cell variation', 0, 1, 0.01, 0.35, 'Per-cell brightness variance (brick tint shifts).'),
+  num('edgeWidth', 'Edge width', 0.01, 0.6, 0.005, 0.12, 'Width of cracks / caustic filaments / speckle chips.', { advanced: advancedShape }),
+  num('rings', 'Rings / veins', 1, 32, 1, 6, 'Ring or vein count across the tile (wood, marble).', { advanced: advancedShape }),
+  num('grain', 'Grain', 0, 1, 0.01, 0.5, 'Streak amount (wood) or vein sharpness (marble).', { advanced: advancedShape }),
+];
+
+const detailLayerFields = (defaults) => [
+  bool('enabled', 'Enabled', defaults.enabled, 'Toggles this detail layer.'),
+  generatorField(defaults.generator, 'Pattern blended over the base height.'),
+  sel('blend', 'Blend', TEXTURE_DETAIL_BLENDS, {
+    add: 'Add', max: 'Lighten', min: 'Darken', mix: 'Mix', multiply: 'Multiply', overlay: 'Overlay', screen: 'Screen',
+  }, defaults.blend, 'How this layer combines with the height underneath.'),
+  num('amount', 'Amount', 0, 1, 0.01, defaults.amount, 'Blend strength of this layer.'),
+  bool('invert', 'Invert', false, 'Flips the layer before blending.', { advanced: true }),
+  num('contrast', 'Contrast', -1, 1, 0.01, 0, 'Sharpens (+) or flattens (-) the layer.', { advanced: true }),
+  ...layerParamFields({ advancedShape: true }).map((field) => (
+    field.key === 'scale' ? { ...field, defaultValue: defaults.scale } : field
+  )),
+];
+
+const accentLayerFields = (defaults) => [
+  bool('enabled', 'Enabled', defaults.enabled, 'Toggles this overlay.'),
+  generatorField(defaults.generator, 'Mask pattern deciding where the overlay lands.'),
+  col('color', 'Color', defaults.color, 'Overlay color where the mask is strongest.'),
+  col('colorB', 'Color B', defaults.colorB, 'Secondary overlay color for variation within the mask.'),
+  num('coverage', 'Coverage', 0, 1, 0.01, defaults.coverage, 'How much of the surface the overlay claims.'),
+  num('softness', 'Softness', 0.01, 0.6, 0.01, defaults.softness, 'Feather width of the overlay border.'),
+  num('creviceBias', 'Crevice bias', -1, 1, 0.01, defaults.creviceBias, '+1 pools into crevices (moss, grime); -1 caps ridges and peaks (snow, wear).'),
+  sel('blend', 'Blend', TEXTURE_ACCENT_BLENDS, {
+    multiply: 'Multiply', normal: 'Paint', overlay: 'Overlay', screen: 'Screen',
+  }, defaults.blend, 'How the overlay color mixes into the albedo.'),
+  num('roughnessShift', 'Roughness shift', -1, 1, 0.01, defaults.roughnessShift, 'Overlay area gets rougher (+) or glossier (-).'),
+  num('heightShift', 'Height shift', -0.5, 0.5, 0.01, defaults.heightShift, 'Overlay area rises (+) or sinks (-) in the height map.'),
+  num('metalShift', 'Metal shift', -1, 1, 0.01, defaults.metalShift, 'Overlay area gains (+) or loses (-) metalness — rust strips metal.', { advanced: true }),
+  num('contrast', 'Mask contrast', -1, 1, 0.01, 0, 'Sharpens (+) or flattens (-) the mask pattern.', { advanced: true }),
+  bool('invert', 'Invert mask', false, 'Flips the mask before thresholding.', { advanced: true }),
+  ...layerParamFields({ advancedShape: true }).map((field) => (
+    field.key === 'scale' ? { ...field, defaultValue: defaults.scale }
+      : field.key === 'warp' ? { ...field, defaultValue: defaults.warp }
+        : field
+  )),
+];
+
+const RAW_FIELD_SCHEMA = {
+  global: [
+    num('seed', 'Seed', 0, 99999, 1, 1337, 'Deterministic seed — every value is a different texture with the same recipe.'),
+  ],
+  base: [
+    generatorField('fbm', 'Primary structure of the material: this drives height, color banding, and pattern cells.'),
+    num('contrast', 'Contrast', -1, 1, 0.01, 0, 'Sharpens (+) or flattens (-) the base pattern.'),
+    num('bias', 'Brightness bias', -0.5, 0.5, 0.01, 0, 'Shifts the whole pattern up or down the ramp.', { advanced: true }),
+    bool('invert', 'Invert', false, 'Flips the base pattern (crevices become ridges).'),
+    ...layerParamFields(),
+  ],
+  detailA: detailLayerFields({ amount: 0.35, blend: 'overlay', enabled: true, generator: 'fbm', scale: 18 }),
+  detailB: detailLayerFields({ amount: 0.2, blend: 'add', enabled: false, generator: 'speckle', scale: 24 }),
+  color: [
+    col('color0', 'Deepest', [0.16, 0.14, 0.13], 'Ramp stop at the darkest crevices.'),
+    col('color1', 'Low', [0.35, 0.31, 0.28], 'Ramp stop between crevices and the mid tone.'),
+    col('color2', 'Mid', [0.55, 0.5, 0.45], 'Ramp stop for the average surface.'),
+    col('color3', 'High', [0.72, 0.68, 0.62], 'Ramp stop approaching the ridges.'),
+    col('color4', 'Peak', [0.88, 0.85, 0.79], 'Ramp stop at the highest ridges.'),
+    num('pos1', 'Low position', 0.02, 0.98, 0.01, 0.25, 'Where the Low stop sits on the height ramp.', { advanced: true }),
+    num('pos2', 'Mid position', 0.02, 0.98, 0.01, 0.5, 'Where the Mid stop sits on the height ramp.', { advanced: true }),
+    num('pos3', 'High position', 0.02, 0.98, 0.01, 0.75, 'Where the High stop sits on the height ramp.', { advanced: true }),
+    num('rampSmooth', 'Band smoothness', 0, 1, 0.01, 1, '1 = smooth gradient, 0 = hard cel bands between the five stops.'),
+    num('jitterHue', 'Hue jitter', 0, 0.5, 0.005, 0.04, 'Painterly hue drift across the surface.'),
+    num('jitterValue', 'Value jitter', 0, 0.5, 0.005, 0.08, 'Painterly brightness drift across the surface.'),
+    num('jitterScale', 'Jitter scale', 2, 64, 1, 24, 'Frequency of the painterly drift.', { advanced: true }),
+    bool('jitterCells', 'Jitter per cell', false, 'Applies drift per pattern cell (per brick / plank / scale) instead of smoothly.'),
+    num('cavity', 'Cavity shading', 0, 1, 0.01, 0.35, 'Darkens crevices toward the cavity tint — the hand-painted occlusion read.'),
+    col('cavityTint', 'Cavity tint', [0.13, 0.09, 0.08], 'Color the crevices sink toward.', { advanced: true }),
+    num('sheen', 'Ridge sheen', 0, 1, 0.01, 0.18, 'Screens the sheen tint over ridges and edges — worn highlight.'),
+    col('sheenTint', 'Sheen tint', [1, 0.97, 0.88], 'Color of the ridge highlight.', { advanced: true }),
+    num('hueShift', 'Hue shift', -0.5, 0.5, 0.005, 0, 'Rotates the final palette hue.'),
+    num('saturation', 'Saturation', 0, 2, 0.01, 1, 'Final color saturation.'),
+    num('brightness', 'Brightness', 0.25, 1.75, 0.01, 1, 'Final brightness multiplier.'),
+    num('contrast', 'Color contrast', -1, 1, 0.01, 0, 'Final color contrast.'),
+    num('gamma', 'Gamma', 0.4, 2.5, 0.01, 1, 'Final gamma on the albedo.', { advanced: true }),
+  ],
+  wear: [
+    num('damage', 'Damage', 0, 1, 0.01, 0, 'Universal wear macro: carves seeded scratches and chips into the surface and roughens them. One knob, many parameters.'),
+    num('dirt', 'Dirt', 0, 1, 0.01, 0, 'Grime macro: darkens crevices with pooled dirt and raises their roughness, independent of the overlay slots.'),
+  ],
+  accentA: accentLayerFields({
+    blend: 'normal', color: [0.35, 0.48, 0.22], colorB: [0.52, 0.62, 0.28], coverage: 0.35,
+    creviceBias: 0.5, enabled: false, generator: 'fbm', heightShift: 0.05, metalShift: 0,
+    roughnessShift: 0.25, scale: 5, softness: 0.18, warp: 0.3,
+  }),
+  accentB: accentLayerFields({
+    blend: 'multiply', color: [0.16, 0.12, 0.09], colorB: [0.3, 0.24, 0.18], coverage: 0.3,
+    creviceBias: 0.6, enabled: false, generator: 'turbulence', heightShift: -0.03, metalShift: 0,
+    roughnessShift: 0.2, scale: 4, softness: 0.22, warp: 0.25,
+  }),
+  surface: [
+    num('heightScale', 'Height depth', 0, 1, 0.01, 0.5, 'Overall relief strength — feeds the normal map, AO, and displacement.'),
+    num('normalStrength', 'Normal strength', 0, 3, 0.01, 1, 'Extra multiplier on the derived normal map.'),
+    bool('invertHeight', 'Invert height', false, 'Flips the height map (grooves become ridges).'),
+    num('aoStrength', 'Occlusion', 0, 1, 0.01, 0.55, 'Baked ambient occlusion depth in the crevices.'),
+    num('roughness', 'Roughness', 0, 1, 0.01, 0.75, 'Base roughness: 0 = mirror gloss, 1 = fully matte.'),
+    num('roughnessContrast', 'Roughness contrast', -1, 1, 0.01, 0.35, '+1 = crevices rough & ridges polished; -1 = the reverse.'),
+    num('metalness', 'Metalness', 0, 1, 0.01, 0, 'Base metalness of the material.'),
+  ],
+  emissive: [
+    bool('enabled', 'Enabled', false, 'Adds a glow map (lava cracks, sci-fi circuits, embers).'),
+    col('color', 'Glow color', [1, 0.45, 0.12], 'Emissive color.'),
+    num('intensity', 'Intensity', 0, 8, 0.05, 2, 'Emissive brightness (preview material intensity).'),
+    sel('source', 'Glow from', TEXTURE_EMISSIVE_SOURCES, {
+      accentA: 'Overlay A', accentB: 'Overlay B', band: 'Height band', crevices: 'Crevices', everywhere: 'Everywhere', peaks: 'Peaks',
+    }, 'crevices', 'Which part of the surface glows.'),
+    num('threshold', 'Level', 0, 1, 0.01, 0.5, 'Height level the glow hugs (band / crevices / peaks).'),
+    num('width', 'Width', 0.02, 0.8, 0.01, 0.25, 'Thickness of the glowing region.'),
+    num('softness', 'Softness', 0.01, 0.6, 0.01, 0.2, 'Feather on the glow border.'),
+  ],
+};
+
+export const TEXTURE_SETTING_GROUPS = Object.freeze([
+  Object.freeze({ description: 'Deterministic seed shared by every layer.', id: 'global', label: 'Seed' }),
+  Object.freeze({ description: 'The primary structure: pattern, frequency, warp.', id: 'base', label: 'Base pattern' }),
+  Object.freeze({ description: 'Mid-frequency relief blended over the base.', id: 'detailA', label: 'Detail layer A' }),
+  Object.freeze({ description: 'Fine grain, pores, chips.', id: 'detailB', label: 'Detail layer B' }),
+  Object.freeze({ description: 'Five-stop height ramp, painterly jitter, cavity & sheen, final grade.', id: 'color', label: 'Color' }),
+  Object.freeze({ description: 'One-knob damage and dirt macros layered over everything.', id: 'wear', label: 'Wear & tear' }),
+  Object.freeze({ description: 'Masked colored overlay: moss, rust, dirt, snow, lichen…', id: 'accentA', label: 'Overlay A' }),
+  Object.freeze({ description: 'Second masked overlay: grime, stains, scorch, drips…', id: 'accentB', label: 'Overlay B' }),
+  Object.freeze({ description: 'PBR response: relief, occlusion, roughness, metalness.', id: 'surface', label: 'Surface' }),
+  Object.freeze({ description: 'Optional emissive map.', id: 'emissive', label: 'Glow' }),
+]);
+
+/** group id -> { fieldKey -> field descriptor } (UI SchemaGroup shape). */
+export const TEXTURE_SETTING_FIELD_SCHEMA = Object.freeze(Object.fromEntries(
+  Object.entries(RAW_FIELD_SCHEMA).map(([group, fields]) => [
+    group,
+    Object.freeze(Object.fromEntries(fields.map((field) => [
+      field.key,
+      Object.freeze({ ...field, group, id: `${group}-${field.key}` }),
+    ]))),
+  ]),
+));
+
+export const DEFAULT_TEXTURE_SETTINGS = Object.freeze(Object.fromEntries(
+  Object.entries(TEXTURE_SETTING_FIELD_SCHEMA).map(([group, fields]) => [
+    group,
+    Object.freeze(Object.fromEntries(Object.values(fields).map((field) => [
+      field.key,
+      Array.isArray(field.defaultValue) ? Object.freeze([...field.defaultValue]) : field.defaultValue,
+    ]))),
+  ]),
+));
+
+/** '#rrggbb' or '#rgb' -> [r, g, b] in 0..1, or null when not parseable. */
+export function hexToRgb01(hex) {
+  if (typeof hex !== 'string') return null;
+  const m = hex.trim().match(/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!m) return null;
+  let s = m[1];
+  if (s.length === 3) s = s.split('').map((c) => c + c).join('');
+  return [0, 1, 2].map((i) => parseInt(s.slice(i * 2, i * 2 + 2), 16) / 255);
+}
+
+export function rgb01ToHex(rgb) {
+  const channel = (v) => Math.round(Math.min(1, Math.max(0, Number(v) || 0)) * 255).toString(16).padStart(2, '0');
+  return `#${channel(rgb?.[0])}${channel(rgb?.[1])}${channel(rgb?.[2])}`;
+}
+
+function clampFieldValue(field, value, fallback) {
+  if (field.type === 'number') {
+    const v = Number(value);
+    if (!Number.isFinite(v)) return fallback;
+    const { min, max, step } = field.range;
+    const clamped = Math.min(max, Math.max(min, v));
+    return step >= 1 ? Math.round(clamped) : clamped;
+  }
+  if (field.type === 'boolean') {
+    if (typeof value === 'boolean') return value;
+    if (value === 'true' || value === 1) return true;
+    if (value === 'false' || value === 0) return false;
+    return fallback;
+  }
+  if (field.type === 'select') {
+    return field.options.includes(value) ? value : fallback;
+  }
+  if (field.type === 'color') {
+    const fromHex = hexToRgb01(value);
+    const rgb = fromHex ?? value;
+    if (Array.isArray(rgb) && rgb.length >= 3 && rgb.every((c) => Number.isFinite(Number(c)))) {
+      return rgb.slice(0, 3).map((c) => Math.min(1, Math.max(0, Number(c))));
+    }
+    return [...fallback];
+  }
+  return value === undefined ? fallback : value;
+}
+
+/**
+ * Builds a complete, clamped settings object. Unknown groups/keys in the
+ * overrides are ignored; colors accept hex strings or [r,g,b] triplets.
+ */
+export function createTextureSettings(overrides = {}) {
+  const result = {};
+  for (const [group, fields] of Object.entries(TEXTURE_SETTING_FIELD_SCHEMA)) {
+    const groupOverrides = overrides?.[group] ?? {};
+    const groupResult = {};
+    for (const field of Object.values(fields)) {
+      const fallback = Array.isArray(field.defaultValue) ? [...field.defaultValue] : field.defaultValue;
+      groupResult[field.key] = field.key in groupOverrides
+        ? clampFieldValue(field, groupOverrides[field.key], fallback)
+        : fallback;
+    }
+    result[group] = groupResult;
+  }
+  result.global.seed = Math.max(0, Math.round(Number(result.global.seed) || 0)) % 100000;
+
+  // Optional image base layer — not schema-driven (no slider maps to a
+  // bitmap). Same shape/discipline as debrisgen's surface.customTexture:
+  // a data URL plus clamped derivation params, preserved through clones.
+  const image = overrides?.image;
+  const clampNum = (value, min, max, fallback) => {
+    const v = Number(value);
+    return Number.isFinite(v) ? Math.min(max, Math.max(min, v)) : fallback;
+  };
+  result.image = image && typeof image.dataUrl === 'string' && image.dataUrl
+    ? {
+      bands: Math.round(clampNum(image.bands, 0, 10, 0)),
+      dataUrl: image.dataUrl,
+      heightBase: clampNum(image.heightBase, 0, 1, 0.35),
+      heightDetail: clampNum(image.heightDetail, 0, 1, 0.65),
+      name: String(image.name ?? 'Image'),
+      seamless: image.seamless !== false,
+    }
+    : null;
+  return result;
+}
+
+export function cloneTextureSettings(settings) {
+  return createTextureSettings(settings);
+}
+
+/** Flattens settings to { 'group.key': value } — the AI patch space. */
+export function flattenTextureSettings(settings) {
+  const flat = {};
+  for (const [group, fields] of Object.entries(TEXTURE_SETTING_FIELD_SCHEMA)) {
+    for (const field of Object.values(fields)) {
+      const value = settings?.[group]?.[field.key];
+      flat[`${group}.${field.key}`] = Array.isArray(value) ? rgb01ToHex(value) : value;
+    }
+  }
+  return flat;
+}
+
+/**
+ * Applies { 'group.key': value } patches onto settings with schema
+ * clamping. Returns { settings, applied, ignored } — ignored lists the
+ * patch keys that named no known field.
+ */
+export function applyTextureSettingsPatch(settings, patch = {}) {
+  const next = createTextureSettings(settings);
+  const applied = [];
+  const ignored = [];
+  for (const [path, value] of Object.entries(patch)) {
+    const [group, key] = String(path).split('.');
+    const field = TEXTURE_SETTING_FIELD_SCHEMA[group]?.[key];
+    if (!field) {
+      ignored.push(path);
+      continue;
+    }
+    const fallback = next[group][key];
+    next[group][key] = clampFieldValue(field, value, fallback);
+    applied.push(path);
+  }
+  return { applied, ignored, settings: next };
+}
+
+export const TEXTURE_RECIPE_KIND = 'toonlab.textureRecipe';
+
+export function createTextureRecipeDocument(settings, { name = 'Untitled texture' } = {}) {
+  return {
+    kind: TEXTURE_RECIPE_KIND,
+    name,
+    settings: createTextureSettings(settings),
+    version: 1,
+  };
+}
+
+export function validateTextureRecipeDocument(document) {
+  const errors = [];
+  if (!document || typeof document !== 'object') errors.push('Recipe must be an object.');
+  else {
+    if (document.kind !== TEXTURE_RECIPE_KIND) errors.push('Unknown recipe kind.');
+    if (document.version !== 1) errors.push('Unsupported recipe version.');
+    if (!document.settings || typeof document.settings !== 'object') errors.push('Recipe settings are missing.');
+  }
+  return { errors, ok: errors.length === 0 };
+}

package/src/texgen/textureThree.js

@@ -0,0 +1,59 @@
+// THREE adapters for baked texture maps. Follows the repo texture
+// conventions (src/debrisgen/debrisTextures.js): color-carrying maps are
+// tagged SRGBColorSpace, data maps NoColorSpace, everything repeats and
+// mipmaps. DataTexture needs an explicit needsUpdate on every write.
+
+import * as THREE from 'three';
+
+const MAP_COLOR_SPACES = Object.freeze({
+  albedo: 'srgb',
+  ao: 'data',
+  emissive: 'srgb',
+  heightBytes: 'data',
+  metalness: 'data',
+  normal: 'data',
+  orm: 'data',
+  roughness: 'data',
+});
+
+export const TEXTURE_THREE_MAP_IDS = Object.freeze(Object.keys(MAP_COLOR_SPACES));
+
+function configure(texture, kind) {
+  texture.colorSpace = kind === 'srgb' ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+  texture.wrapS = THREE.RepeatWrapping;
+  texture.wrapT = THREE.RepeatWrapping;
+  texture.generateMipmaps = true;
+  texture.minFilter = THREE.LinearMipmapLinearFilter;
+  texture.magFilter = THREE.LinearFilter;
+  texture.needsUpdate = true;
+  return texture;
+}
+
+/**
+ * Wraps every byte buffer of an evaluateTextureMaps() result in a
+ * DataTexture. Pass a previous `textures` object to update in place —
+ * buffers of an unchanged size are re-tagged with needsUpdate; a size
+ * change disposes and recreates. Returns { textures, recreated }.
+ */
+export function syncTextureMapTextures(maps, textures = null) {
+  const sizeChanged = !textures || textures.size !== maps.size;
+  if (sizeChanged && textures) {
+    for (const id of TEXTURE_THREE_MAP_IDS) textures[id]?.dispose();
+  }
+  const next = sizeChanged ? { size: maps.size } : textures;
+  for (const [id, kind] of Object.entries(MAP_COLOR_SPACES)) {
+    if (sizeChanged) {
+      next[id] = configure(new THREE.DataTexture(maps[id], maps.size, maps.size, THREE.RGBAFormat), kind);
+    } else {
+      next[id].image.data = maps[id];
+      next[id].needsUpdate = true;
+    }
+  }
+  return { recreated: sizeChanged, textures: next };
+}
+
+/** Disposes every texture created by syncTextureMapTextures. */
+export function disposeTextureMapTextures(textures) {
+  if (!textures) return;
+  for (const id of TEXTURE_THREE_MAP_IDS) textures[id]?.dispose();
+}

package/src/vegetation/flowerSpecies.js

@@ -138,15 +138,21 @@ function rgbHex(rgb, shade = 1) {
   return `#${rgb.map((channel) => channelHex(channel * shade)).join('')}`;
 }
 
-function paintGeometry(geometry, [r, g, b]) {
+function paintGeometry(geometry, [r, g, b], role = 0) {
   const count = geometry.getAttribute('position').count;
   const colors = new Float32Array(count * 3);
+  const roles = new Float32Array(count);
   for (let i = 0; i < count; i += 1) {
     colors[i * 3] = r;
     colors[i * 3 + 1] = g;
     colors[i * 3 + 2] = b;
+    roles[i] = role;
   }
   geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+  // 0 = petal, 1 = center. The shared flower shader uses this semantic
+  // attribute instead of guessing from color, so recoloring never changes
+  // the center/petal lighting relationship.
+  geometry.setAttribute('flowerRole', new THREE.BufferAttribute(roles, 1));
   return geometry;
 }
 
@@ -199,7 +205,7 @@ export function createFlowerHeadGeometry({ species, color } = {}) {
         .makeRotationZ(azimuth)
         .multiply(new THREE.Matrix4().makeTranslation(0, petalBase, 0))
         .multiply(new THREE.Matrix4().makeRotationX(lift)));
-      pieces.push(paintGeometry(petal, petalColor));
+      pieces.push(paintGeometry(petal, petalColor, 0));
     }
   }
 
@@ -207,7 +213,7 @@ export function createFlowerHeadGeometry({ species, color } = {}) {
     const dome = new THREE.SphereGeometry(centerRadius, 10, 5, 0, Math.PI * 2, 0, Math.PI / 2);
     dome.rotateX(Math.PI / 2);
     dome.scale(1, 1, 0.45);
-    pieces.push(paintGeometry(dome, toRgb(spec.center.color)));
+    pieces.push(paintGeometry(dome, toRgb(spec.center.color), 1));
   }
 
   const merged = mergeGeometries(pieces);
@@ -256,5 +262,11 @@ export function createFlowerHeadTexture({ color, petal }) {
   }
   const texture = new THREE.CanvasTexture(canvas);
   texture.colorSpace = THREE.SRGBColorSpace;
+  // Semantic asset metadata for composite flower-head materials. The shader
+  // uses this mask radius to shade center and petal roles independently; it
+  // must not infer the role from color because every palette is valid.
+  texture.userData.toonlabFlower = {
+    centerRadius: center ? center.radius / canvas.width : 0,
+  };
   return texture;
 }

package/src/vegetation/grassPalettes.js

@@ -0,0 +1,153 @@
+// Curated grass material palettes. These are intentionally smaller than a
+// grass preset: they repaint only the blade root, tip, and material shadow
+// tone. Geometry, motion, shadow strength, scene light, and the IP-wide
+// VegetationShaderProfile remain owned by their respective scopes.
+
+const COLOR_KEYS = Object.freeze(['baseColor', 'tipColor', 'shadowTint']);
+
+function color(value) {
+  if (Array.isArray(value) && value.length >= 3) {
+    return Object.freeze(value.slice(0, 3).map(Number));
+  }
+  const hex = String(value ?? '').replace(/^#/, '');
+  if (!/^[0-9a-f]{6}$/i.test(hex)) throw new Error(`Invalid grass palette color "${value}".`);
+  return Object.freeze([
+    parseInt(hex.slice(0, 2), 16) / 255,
+    parseInt(hex.slice(2, 4), 16) / 255,
+    parseInt(hex.slice(4, 6), 16) / 255,
+  ]);
+}
+
+function definePalette({ id, label, description, baseColor, tipColor, shadowTint }) {
+  return Object.freeze({
+    baseColor: color(baseColor),
+    description,
+    id,
+    label,
+    shadowTint: color(shadowTint),
+    tipColor: color(tipColor),
+  });
+}
+
+/**
+ * Built-in grass paint palettes. Values are sRGB triplets because
+ * StylizedGrassField uploads grass colors with THREE.SRGBColorSpace.
+ */
+export const GRASS_COLOR_PALETTES = Object.freeze([
+  definePalette({
+    id: 'sensei_meadow',
+    label: 'Sensei Meadow',
+    description: 'The balanced green meadow used by the studio grass preset.',
+    baseColor: [0.42, 0.68, 0.24],
+    tipColor: [0.74, 0.9, 0.42],
+    shadowTint: [0.42, 0.47, 0.62],
+  }),
+  definePalette({
+    id: 'spring_lime',
+    label: 'Spring Lime',
+    description: 'Young yellow-green blades with a cool spring shadow.',
+    baseColor: '#5fa13e',
+    tipColor: '#b9e45f',
+    shadowTint: '#66718a',
+  }),
+  definePalette({
+    id: 'deep_forest',
+    label: 'Deep Forest',
+    description: 'Dense woodland green with a muted blue-green shadow.',
+    baseColor: '#245c35',
+    tipColor: '#61a857',
+    shadowTint: '#455969',
+  }),
+  definePalette({
+    id: 'sage_field',
+    label: 'Sage Field',
+    description: 'Soft desaturated greens for uplands and windswept fields.',
+    baseColor: '#6e8657',
+    tipColor: '#b9c98a',
+    shadowTint: '#687181',
+  }),
+  definePalette({
+    id: 'dry_prairie',
+    label: 'Dry Prairie',
+    description: 'Sun-dried ochre grass with a violet-brown shadow.',
+    baseColor: '#98713e',
+    tipColor: '#d9c476',
+    shadowTint: '#6f6274',
+  }),
+  definePalette({
+    id: 'autumn_amber',
+    label: 'Autumn Amber',
+    description: 'Warm russet and amber blades grounded by a plum shadow.',
+    baseColor: '#a4522c',
+    tipColor: '#e0a548',
+    shadowTint: '#745268',
+  }),
+  definePalette({
+    id: 'wisteria',
+    label: 'Wisteria',
+    description: 'Fantasy violet grass with lavender tips and a deep lilac shadow.',
+    baseColor: '#7254a5',
+    tipColor: '#b9a3ed',
+    shadowTint: '#62587e',
+  }),
+  definePalette({
+    id: 'moonlit_blue',
+    label: 'Moonlit Blue',
+    description: 'Cool blue grass for nocturnal, alpine, or magical biomes.',
+    baseColor: '#345f85',
+    tipColor: '#73b6c5',
+    shadowTint: '#4f5d7a',
+  }),
+  definePalette({
+    id: 'sakura_field',
+    label: 'Sakura Field',
+    description: 'Rose-pink blades with pale blossom tips and a mauve shadow.',
+    baseColor: '#a9567d',
+    tipColor: '#ed9fbf',
+    shadowTint: '#755775',
+  }),
+  definePalette({
+    id: 'crimson_field',
+    label: 'Crimson Field',
+    description: 'Deep red fantasy grass with coral tips and a cool wine shadow.',
+    baseColor: '#7d3041',
+    tipColor: '#d66963',
+    shadowTint: '#594e69',
+  }),
+]);
+
+/** Resolves a built-in palette by id, or accepts one of the catalog entries. */
+export function resolveGrassColorPalette(paletteOrId) {
+  if (typeof paletteOrId === 'string') {
+    return GRASS_COLOR_PALETTES.find((entry) => entry.id === paletteOrId) ?? null;
+  }
+  if (paletteOrId && COLOR_KEYS.every((key) => Array.isArray(paletteOrId[key]))) {
+    return paletteOrId;
+  }
+  return null;
+}
+
+/** Returns a new settings object with only the coordinated paint trio replaced. */
+export function applyGrassColorPalette(settings = {}, paletteOrId) {
+  const palette = resolveGrassColorPalette(paletteOrId);
+  if (!palette) throw new Error(`Unknown grass color palette "${String(paletteOrId)}".`);
+  return {
+    ...settings,
+    baseColor: [...palette.baseColor],
+    shadowTint: [...palette.shadowTint],
+    tipColor: [...palette.tipColor],
+  };
+}
+
+function sameColor(left, right, epsilon) {
+  return Array.isArray(left) && Array.isArray(right) && left.length >= 3 && right.length >= 3
+    && left.slice(0, 3).every((channel, index) =>
+      Math.abs(Number(channel) - Number(right[index])) <= epsilon);
+}
+
+/** Infers the active palette from all three colors; no palette id is persisted. */
+export function matchGrassColorPalette(settings, epsilon = 1e-5) {
+  return GRASS_COLOR_PALETTES.find((palette) =>
+    COLOR_KEYS.every((key) => sameColor(settings?.[key], palette[key], epsilon))) ?? null;
+}
+

package/src/vegetation/index.js

@@ -10,3 +10,9 @@ export * from './treeRecipe.js';
 export * from './treeExport.js';
 export * from './scatter.js';
 export * from './stylizedForest.js';
+export * from './vegetationShaders.js';
+export * from './grassPalettes.js';
+export * from '../shaders-tsl/grass.js';
+export * from '../shaders-tsl/tree-leaf.js';
+export * from '../shaders-tsl/flower.js';
+export * from '../shaders-tsl/woody-surface.js';

package/src/vegetation/stylizedBush.js

@@ -45,6 +45,7 @@ export class StylizedBush extends THREE.Group {
       canopy = {},
       canopyLayout = {},
       foliage = {},
+      vegetationShader = null,
     } = options;
     this.name = 'StylizedBush';
     // Kept for toJSON(); not cloned (see StylizedTree.config).
@@ -76,6 +77,7 @@ export class StylizedBush extends THREE.Group {
       color: canopyColor,
       palette: canopyPalette,
       seed,
+      vegetationShader,
       ...foliage,
     });