@woosh/meep-engine 3.56.0 → 3.58.0

package/src/generation/foliage/material/make_foliage_material.js

@@ -1,605 +1,302 @@
-import AABB2 from "../../../core/geom/2d/aabb/AABB2.js";
-import { pack_max_rectangles } from "../../../core/geom/packing/max-rect/pack_max_rectangles.js";
-import { clamp } from "../../../core/math/clamp.js";
-import { lerp } from "../../../core/math/lerp.js";
-import { sdnoise3_array } from "../../../core/math/noise/sdnoise.js";
-import { seededRandom } from "../../../core/math/random/seededRandom.js";
-import { smoothStep } from "../../../core/math/smoothStep.js";
-import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
-import { ShadeDrawSide } from "../../../shade/renderer/material/ShadeDrawSide.js";
-import { StandardShadeMaterial } from "../../../shade/renderer/material/StandardShadeMaterial.js";
-import { TransparencyMode } from "../../../shade/renderer/material/TransparencyMode.js";
-import { ColorSpace } from "../../../shade/renderer/texture/ColorSpace.js";
-import { ShadeTexture } from "../../../shade/renderer/texture/ShadeTexture.js";
-import { TextureFilterType } from "../../../shade/renderer/texture/TextureFilterType.js";
-import { TextureWrapType } from "../../../shade/renderer/texture/TextureWrapType.js";
-import { AlphaMode } from "../../../shade/renderer/texture/source/AlphaMode.js";
-import { ShadeImage } from "../../../shade/renderer/texture/source/ShadeImage.js";
-import { FoliageMaterialConfig } from "../config/FoliageMaterialConfig.js";
-
-const SCRATCH_NOISE = new Float32Array(4);
-
-/**
- * Packs `variant_count` square foliage card tiles of size `resolution x resolution` into a 2D atlas
- * using the engine's `MaxRectanglesPacker` (`pack_max_rectangles`), returning the atlas dimensions,
- * pixel-space `AABB2` boxes, and normalized `[u0, v0, u1, v1]` UV rectangles.
- *
- * @param {number} [resolution=128]
- * @param {number} [variant_count=4]
- * @returns {{
- *   resolution: number,
- *   variant_count: number,
- *   atlas_w: number,
- *   atlas_h: number,
- *   boxes: AABB2[],
- *   uv_rects: Float32Array
- * }}
- */
-export function compute_foliage_variant_atlas_layout(resolution = 128, variant_count = 4) {
-	const res = Math.max(16, resolution | 0);
-	const count = clamp(variant_count | 0, 1, 16);
-	const cols = Math.max(1, Math.ceil(Math.sqrt(count)));
-	const rows = Math.max(1, Math.ceil(count / cols));
-	const atlas_w = cols * res;
-	const atlas_h = rows * res;
-
-	/** @type {AABB2[]} */
-	const boxes = new Array(count);
-	for (let k = 0; k < count; k++) {
-		boxes[k] = new AABB2(0, 0, res, res);
-	}
-
-	const packed = pack_max_rectangles(atlas_w, atlas_h, boxes);
-	if (!packed) {
-		// Deterministic grid fallback if custom non-uniform boxes are ever used
-		for (let k = 0; k < count; k++) {
-			const c = k % cols;
-			const r = Math.floor(k / cols);
-			boxes[k].set(c * res, r * res, (c + 1) * res, (r + 1) * res);
-		}
-	}
-
-	const uv_rects = new Float32Array(count * 4);
-	for (let k = 0; k < count; k++) {
-		const b = boxes[k];
-		const k4 = k * 4;
-		uv_rects[k4] = b.x0 / atlas_w;
-		uv_rects[k4 + 1] = b.y0 / atlas_h;
-		uv_rects[k4 + 2] = b.x1 / atlas_w;
-		uv_rects[k4 + 3] = b.y1 / atlas_h;
-	}
-
-	return {
-		resolution: res,
-		variant_count: count,
-		atlas_w,
-		atlas_h,
-		boxes,
-		uv_rects
-	};
-}
-
-/**
- * Evaluates a single leaflet SDF, ontogenetic morphology, and venation relief in local leaflet
- * coordinates `(lx, ly)` where `ly` in `[0, 1]` runs from petiole base to leaflet tip and `lx`
- * in `[-0.5, 0.5]` runs across width.
- *
- * @param {number} lx
- * @param {number} ly
- * @param {string} shape `"ovate" | "lobed" | "serrated" | "palmate" | "needle" | "frond"`
- * @param {number} mu_k ontogenetic maturity in `[0, 1]` (`0` = juvenile, `1` = mature)
- * @param {number} shape_var ontogenetic morphology variation strength `[0, 1]`
- * @param {number} vein_contrast ontogenetic venation & bullation contrast `[0, 1]`
- * @returns {{ mask: number, vein: number, height: number, edge_norm: number }}
- */
-function evaluate_leaflet(lx, ly, shape, mu_k, shape_var, vein_contrast) {
-	if (ly < -0.05 || ly > 1.05) {
-		return { mask: 0.0, vein: 0.0, height: 0.0, edge_norm: 0.0 };
-	}
-
-	const t = clamp(ly, 0.0, 1.0);
-	const ax = Math.abs(lx);
-
-	// Juvenile leaves expand longitudinally before full lateral blade expansion (narrower, more acuminate)
-	const width_scale = lerp(1.0 - 0.26 * shape_var, 1.0 + 0.08 * shape_var, mu_k);
-	const lobe_scale = lerp(1.0 - 0.45 * shape_var, 1.0 + 0.15 * shape_var, mu_k);
-	const profile_exp = lerp(0.84, 0.68, mu_k);
-
-	let half_w = 0.34 * width_scale * Math.sin(Math.PI * Math.pow(t, profile_exp));
-
-	switch (shape) {
-		case "lobed": {
-			// Oak-like rounded lobes along margin deepen as lamina matures
-			const lobe = 1.0 + 0.28 * lobe_scale * Math.sin(t * Math.PI * 7.0 - 0.6) * Math.sin(Math.PI * t);
-			half_w *= lobe;
-			break;
-		}
-		case "serrated": {
-			// Birch/elm sawtooth serration
-			const tooth = (t * 14.0) % 1.0;
-			half_w *= (1.0 - 0.12 * lobe_scale + 0.16 * lobe_scale * (1.0 - tooth));
-			break;
-		}
-		case "palmate": {
-			// Maple-like broader lobed palmate blade
-			const lobe = 1.0 + 0.32 * lobe_scale * Math.cos(t * Math.PI * 5.0);
-			half_w = 0.40 * width_scale * Math.sin(Math.PI * Math.pow(t, lerp(0.76, 0.62, mu_k))) * lobe;
-			break;
-		}
-		case "needle": {
-			// Slender conifer needle
-			half_w = 0.065 * lerp(0.85, 1.05, mu_k) * (1.0 - 0.65 * t * t);
-			break;
-		}
-		case "frond": {
-			// Long tapering willow/palm/fern pinna
-			half_w = 0.19 * width_scale * Math.sin(Math.PI * Math.pow(t, lerp(0.70, 0.56, mu_k)));
-			break;
-		}
-		case "ovate":
-		default:
-			break;
-	}
-
-	if (ax > half_w + 0.04) {
-		return { mask: 0.0, vein: 0.0, height: 0.0, edge_norm: 0.0 };
-	}
-
-	const edge_dist = half_w - ax;
-	const mask = smoothStep(-0.015, 0.018, edge_dist);
-	if (mask <= 0.0) {
-		return { mask: 0.0, vein: 0.0, height: 0.0, edge_norm: 0.0 };
-	}
-
-	const inv_hw = 1.0 / Math.max(1e-3, half_w);
-	const edge_norm = clamp(edge_dist * inv_hw, 0.0, 1.0);
-
-	// Midrib + herringbone secondary veins (sharper and more lignified on mature leaves)
-	const midrib_sharp = lerp(700.0, 1050.0, mu_k);
-	const midrib = Math.exp(-ax * ax * midrib_sharp) * (1.0 - 0.58 * t);
-	const sec_coord = (t * 9.0 - ax * 6.5);
-	const sec_frac = sec_coord - Math.floor(sec_coord);
-	const sec_sharp = lerp(36.0, 80.0, mu_k * vein_contrast + 0.25);
-	const sec_amp = lerp(0.28, 0.54, mu_k);
-	const sec_vein = Math.exp(-Math.pow(sec_frac - 0.5, 2.0) * sec_sharp)
-		* smoothStep(0.0, half_w, half_w - ax * 0.85)
-		* sec_amp;
-
-	const vein_relief = lerp(1.0 - 0.62 * vein_contrast, 1.0 + 0.34 * vein_contrast, mu_k);
-	const vein = clamp((midrib + sec_vein) * vein_relief, 0.0, 1.0);
-
-	// Lamina pillow camber across width + mature interveinal mesophyll bullation + vein ridge
-	const camber = Math.sqrt(Math.max(0.0, 1.0 - Math.pow(ax * inv_hw, 2.0))) * lerp(0.45, 0.68, mu_k);
-	const bullation = Math.sin(sec_frac * Math.PI)
-		* smoothStep(0.0, 0.65, edge_norm)
-		* (1.0 - midrib)
-		* lerp(0.02, 0.26, mu_k)
-		* vein_contrast;
-	const height = (camber + bullation + vein * 0.40) * mask;
-
-	return { mask, vein, height, edge_norm };
-}
-
-/**
- * Synthesizes a turn-key procedural PBR cutout `StandardShadeMaterial` (`TransparencyMode.AlphaTested`,
- * `ShadeDrawSide.Double`) for botanical foliage cards, packing `config.variant_count` ontogenetic and
- * biochemically senescent leaf cluster variants into the texture atlas via `MaxRectanglesPacker`
- * (`pack_max_rectangles`), with dilated straight-alpha Albedo (`AlphaMode.Straight`, `ColorSpace.SRGB`),
- * 2-channel Normal map (`ColorSpace.LinearSRGB`), and ORM (`ColorSpace.LinearSRGB`).
- *
- * @param {FoliageMaterialConfig|Object} [config]
- * @param {number} [seed=1]
- * @returns {StandardShadeMaterial}
- */
-export function make_foliage_material(config = new FoliageMaterialConfig(), seed = 1) {
-	const cfg = config && config.isFoliageMaterialConfig ? config : FoliageMaterialConfig.from(config);
-	const layout = compute_foliage_variant_atlas_layout(cfg.resolution, cfg.variant_count);
-	const res = layout.resolution;
-	const variant_count = layout.variant_count;
-	const atlas_w = layout.atlas_w;
-	const atlas_h = layout.atlas_h;
-	const boxes = layout.boxes;
-
-	const rng = seededRandom((seed ^ 0x7F4A7C15) | 0);
-
-	const albedo_sampler = Sampler2D.uint8(4, atlas_w, atlas_h);
-	const normal_sampler = Sampler2D.uint8(2, atlas_w, atlas_h);
-	const orm_sampler = Sampler2D.uint8(4, atlas_w, atlas_h);
-
-	const albedo_data = albedo_sampler.data;
-	const normal_data = normal_sampler.data;
-	const orm_data = orm_sampler.data;
-
-	const height_field = new Float32Array(atlas_w * atlas_h);
-	const shape = cfg.leaf_shape || "lobed";
-	const leaflet_count = Math.max(1, cfg.leaflets_per_cluster | 0);
-	const base_rough = clamp(cfg.roughness, 0.1, 1.0);
-	const vein_str = clamp(cfg.vein_strength, 0.0, 1.0);
-
-	// Ontogeny & first-principles biochemical senescence parameters
-	const juv_shift = clamp(cfg.juvenile_color_shift ?? 0.38, 0.0, 1.0);
-	const juv_antho = clamp(cfg.juvenile_anthocyanin ?? 0.08, 0.0, 1.0);
-	const shape_var = clamp(cfg.ontogeny_shape_variation ?? 0.35, 0.0, 1.0);
-	const vein_contrast = clamp(cfg.ontogeny_vein_contrast ?? 0.55, 0.0, 1.0);
-
-	// Honour both first-principles `senescence` and legacy `autumn_tint`
-	const senescence = clamp(Math.max(cfg.senescence ?? 0.0, cfg.autumn_tint ?? 0.0), 0.0, 1.0);
-	const car_density = clamp(cfg.carotenoid_density ?? 0.75, 0.0, 1.0);
-	const antho_pot = clamp(cfg.anthocyanin_potential ?? 0.35, 0.0, 1.0);
-	const tannin_ox = clamp(cfg.tannin_oxidation ?? 0.25, 0.0, 1.0);
-
-	const p_r = cfg.primary_color.r;
-	const p_g = cfg.primary_color.g;
-	const p_b = cfg.primary_color.b;
-	const s_r = cfg.secondary_color.r;
-	const s_g = cfg.secondary_color.g;
-	const s_b = cfg.secondary_color.b;
-
-	// Pre-fill entire atlas with dilated base RGB (alpha = 0) and neutral normal/ORM so any
-	// unused rectangle cells (e.g., when variant_count = 3 or 5) still carry valid dilated RGB.
-	const fill_r = clamp(Math.round(Math.max(0.04, p_r) * 255), 1, 255);
-	const fill_g = clamp(Math.round(Math.max(0.04, p_g) * 255), 1, 255);
-	const fill_b = clamp(Math.round(Math.max(0.02, p_b) * 255), 1, 255);
-	const fill_rough = clamp(Math.round(base_rough * 255), 0, 255);
-	const total_texels = atlas_w * atlas_h;
-	for (let p = 0; p < total_texels; p++) {
-		const i4 = p * 4;
-		albedo_data[i4] = fill_r;
-		albedo_data[i4 + 1] = fill_g;
-		albedo_data[i4 + 2] = fill_b;
-		albedo_data[i4 + 3] = 0;
-
-		const i2 = p * 2;
-		normal_data[i2] = 128;
-		normal_data[i2 + 1] = 128;
-
-		orm_data[i4] = 255;
-		orm_data[i4 + 1] = fill_rough;
-		orm_data[i4 + 2] = 0;
-		orm_data[i4 + 3] = 255;
-	}
-
-	const anchor_u = clamp(cfg.stem_anchor_u ?? 0.5, 0.1, 0.9);
-	const anchor_v = clamp(cfg.stem_anchor_v ?? 0.0, 0.0, 0.25);
-	const min_stem_half_w = Math.max(0.022, 1.5 / res);
-
-	for (let v_idx = 0; v_idx < variant_count; v_idx++) {
-		const box = boxes[v_idx];
-		const tile_x0 = box.x0;
-		const tile_y0 = box.y0;
-
-		// Ontogenetic coordinate mu_k in [0, 1]: 0 = juvenile apical flush, 1 = mature basal foliage
-		const mu_k = variant_count > 1 ? v_idx / (variant_count - 1) : 0.65;
-		const ox = (rng() - 0.5) * 150.0 + v_idx * 37.3;
-		const oy = (rng() - 0.5) * 150.0 + v_idx * 53.7;
-
-		// Ontogenetic cluster geometry scaling: juvenile shoots are slightly more forward-cupped and compact
-		const angle_scale = lerp(1.0 - 0.22 * shape_var, 1.0 + 0.06 * shape_var, mu_k);
-		const len_scale = lerp(1.0 - 0.14 * shape_var, 1.0 + 0.04 * shape_var, mu_k);
-
-		const leaflets = [];
-		if (shape === "palmate") {
-			const count = Math.max(3, leaflet_count | 1);
-			for (let i = 0; i < count; i++) {
-				const frac = (i / (count - 1)) * 2.0 - 1.0; // [-1, 1]
-				const angle = frac * 1.05 * angle_scale;
-				const scale = (1.0 - 0.32 * Math.abs(frac)) * 0.76 * len_scale;
-				leaflets.push({
-					ox: anchor_u,
-					oy: anchor_v + 0.08,
-					dir_x: Math.sin(angle),
-					dir_y: Math.cos(angle),
-					length: scale,
-					width: scale * 0.9
-				});
-			}
-		} else if (shape === "needle") {
-			const pairs = Math.max(4, leaflet_count);
-			for (let i = 0; i < pairs; i++) {
-				const v_stem = anchor_v + 0.04 + (i / pairs) * 0.74;
-				for (const side of [-1, 1]) {
-					const angle = side * (0.45 + 0.25 * (1.0 - i / pairs)) * angle_scale;
-					const len = 0.36 * (1.0 - 0.35 * (i / pairs)) * len_scale;
-					leaflets.push({
-						ox: anchor_u,
-						oy: v_stem,
-						dir_x: Math.sin(angle),
-						dir_y: Math.cos(angle),
-						length: len,
-						width: len
-					});
-				}
-			}
-			leaflets.push({
-				ox: anchor_u,
-				oy: anchor_v + 0.72,
-				dir_x: 0.0,
-				dir_y: 1.0,
-				length: 0.26 * len_scale,
-				width: 0.26 * len_scale
-			});
-		} else {
-			const pairs = Math.max(1, Math.floor(leaflet_count / 2));
-			for (let p = 0; p < pairs; p++) {
-				const u_p = (p + 0.35) / (pairs + 0.35);
-				const v_stem = anchor_v + 0.04 + u_p * 0.56;
-				const angle_mag = lerp(0.95, 0.55, u_p) * angle_scale;
-				const len = lerp(0.40, 0.30, u_p) * len_scale;
-				for (const side of [-1, 1]) {
-					const angle = side * angle_mag;
-					leaflets.push({
-						ox: anchor_u,
-						oy: v_stem,
-						dir_x: Math.sin(angle),
-						dir_y: Math.cos(angle),
-						length: len,
-						width: len * 0.95
-					});
-				}
-			}
-			leaflets.push({
-				ox: anchor_u,
-				oy: anchor_v + 0.56,
-				dir_x: 0.0,
-				dir_y: 1.0,
-				length: 0.42 * len_scale,
-				width: 0.40 * len_scale
-			});
-		}
-
-		// Ontogenetic chlorophyll accumulation (juvenile protochlorophyllide lag -> lighter yellow-green)
-		const juv_factor = (1.0 - mu_k) * juv_shift;
-		// Staggered variant senescence progression across the atlas so autumn crowns exhibit natural leaf-to-leaf diversity
-		const sigma_k = senescence > 0.0
-			? clamp(senescence * (0.80 + 0.36 * Math.abs(mu_k - 0.35)) + senescence * senescence * 0.12, 0.0, 1.0)
-			: 0.0;
-		const sun_variant_factor = lerp(1.18, 0.74, mu_k);
-		const rough_ontogeny_offset = lerp(-0.10 * vein_contrast, 0.07 * vein_contrast, mu_k);
-
-		for (let ly_px = 0; ly_px < res; ly_px++) {
-			const v = (ly_px + 0.5) / res;
-			const atlas_y = tile_y0 + ly_px;
-			const row_offset = atlas_y * atlas_w;
-			// Prevent top-edge vertical bleeding into adjacent stacked tiles while keeping v=0 stem anchor solid
-			const top_border_fade = smoothStep(1.0, 0.975, v);
-
-			for (let lx_px = 0; lx_px < res; lx_px++) {
-				const u = (lx_px + 0.5) / res;
-				const atlas_x = tile_x0 + lx_px;
-				const p_idx = row_offset + atlas_x;
-
-				// Central woody twig / rachis along u = anchor_u, v in [anchor_v, anchor_v + 0.72]
-				let stem_mask = 0.0;
-				if (v >= anchor_v && v <= anchor_v + 0.72) {
-					const u_stem = clamp((v - anchor_v) / 0.72, 0.0, 1.0);
-					const stem_half_w = lerp(min_stem_half_w, 0.007, u_stem);
-					const d_stem = stem_half_w - Math.abs(u - anchor_u);
-					stem_mask = smoothStep(-0.008, 0.008, d_stem);
-				}
-
-				let best_mask = 0.0;
-				let best_vein = 0.0;
-				let best_h = 0.0;
-				let best_tip = 0.0;
-				let best_edge_norm = 0.5;
-
-				for (let l = 0; l < leaflets.length; l++) {
-					const lf = leaflets[l];
-					const dx = u - lf.ox;
-					const dy = v - lf.oy;
-					const ly = (dx * lf.dir_x + dy * lf.dir_y) / lf.length;
-					const lx = (dx * lf.dir_y - dy * lf.dir_x) / lf.width;
-
-					const eval_res = evaluate_leaflet(lx, ly, shape, mu_k, shape_var, vein_contrast);
-					if (eval_res.mask > best_mask) {
-						best_mask = eval_res.mask;
-						best_vein = eval_res.vein;
-						best_h = eval_res.height;
-						best_tip = clamp(ly, 0.0, 1.0);
-						best_edge_norm = eval_res.edge_norm;
-					}
-				}
-
-				best_mask *= top_border_fade;
-				const alpha = clamp(Math.max(best_mask, stem_mask), 0.0, 1.0);
-				height_field[p_idx] = Math.max(best_h * top_border_fade, stem_mask * 0.4);
-
-				sdnoise3_array(SCRATCH_NOISE, u * 6.0 + ox, v * 6.0 + oy, 0.0);
-				const n_var = SCRATCH_NOISE[0] * 0.5 + 0.5;
-
-				// 1. Base photosynthetic chlorophyll + carotenoid lamina reflectance (with juvenile chartreuse shift)
-				const vein_mix_w = lerp(0.38, 0.72, mu_k) * vein_str;
-				const mix_t = clamp(best_vein * vein_mix_w + best_tip * 0.24 + n_var * 0.18, 0.0, 1.0);
-				let cr = lerp(p_r, s_r, mix_t);
-				let cg = lerp(p_g, s_g, mix_t);
-				let cb = lerp(p_b, s_b, mix_t);
-
-				// Juvenile protochlorophyllide lag: higher mesophyll reflectance + yellow-green chartreuse shift
-				if (juv_factor > 1e-4) {
-					const tip_boost = 0.75 + 0.25 * best_tip;
-					const j_w = juv_factor * tip_boost;
-					cr = clamp(cr + j_w * 0.22, 0.0, 1.0);
-					cg = clamp(cg + j_w * 0.28, 0.0, 1.0);
-					cb = clamp(cb + j_w * 0.04, 0.0, 1.0);
-				}
-
-				// Transient juvenile epidermal anthocyanin flush along expanding young leaf margins/tips
-				const w_ant_juv = juv_antho * Math.pow(1.0 - mu_k, 1.8)
-					* (0.30 + 0.70 * (1.0 - best_edge_norm * 0.65) * (0.35 + 0.65 * best_tip))
-					* (1.0 - sigma_k);
-				if (w_ant_juv > 1e-4) {
-					cr = lerp(cr, 0.58, w_ant_juv * 0.75);
-					cg = lerp(cg, 0.24, w_ant_juv * 0.65);
-					cb = lerp(cb, 0.14, w_ant_juv * 0.65);
-				}
-
-				// 2. First-principles autumn senescence (Chlorophyll catabolism -> Carotenoid unmasking -> Anthocyanin -> Tannin)
-				if (sigma_k > 1e-4) {
-					// Vascular bundles (midrib & secondary veins) and basal petiole retain chlorophyll longest
-					const vascular_shield = clamp(
-						0.48 * best_vein + 0.34 * best_edge_norm * (1.0 - 0.55 * best_tip) + 0.18 * n_var,
-						0.0,
-						1.0
-					);
-					const r_chl_lin = clamp(1.0 - sigma_k * (1.36 - 0.68 * vascular_shield), 0.0, 1.0);
-					const r_chl = r_chl_lin * r_chl_lin;
-					const chl_loss = 1.0 - r_chl;
-
-					// (a) Unmask plastid carotenoids (xanthophyll / beta-carotene -> golden-yellow)
-					const car_r = lerp(0.76, 0.94, car_density);
-					const car_g = lerp(0.54, 0.74, car_density);
-					const car_b = lerp(0.14, 0.08, car_density);
-					const w_car = clamp(chl_loss * (0.38 + 0.62 * car_density), 0.0, 1.0);
-					cr = lerp(cr, car_r, w_car);
-					cg = lerp(cg, car_g, w_car);
-					cb = lerp(cb, car_b, w_car);
-
-					// (b) De novo vacuolar anthocyanin synthesis (high light + margin/tip sugar accumulation -> scarlet/crimson)
-					if (antho_pot > 1e-4) {
-						const margin_sugar = clamp(
-							0.52 * (1.0 - best_edge_norm) + 0.34 * best_tip + 0.22 * (1.0 - best_vein) + 0.15 * (1.0 - n_var),
-							0.0,
-							1.0
-						);
-						const w_ant = clamp(
-							antho_pot * chl_loss * Math.pow(sigma_k, 0.72) * sun_variant_factor * (0.42 + 0.78 * margin_sugar),
-							0.0,
-							1.0
-						);
-						// Vacuolar anthocyanin strongly absorbs green (~530nm) and blue while transmitting red (~650nm)
-						cr = lerp(cr, 0.82, w_ant * 0.85);
-						cg *= lerp(1.0, 0.18, w_ant);
-						cb *= lerp(1.0, 0.24, w_ant);
-					}
-
-					// (c) Late-senescence condensed tannin / polyphenol oxidation into russet/copper-brown
-					if (tannin_ox > 1e-4 && sigma_k > 0.22) {
-						const w_tan = clamp(
-							tannin_ox
-							* chl_loss * chl_loss
-							* smoothStep(0.22, 0.95, sigma_k)
-							* lerp(0.68, 1.22, mu_k)
-							* (0.42 + 0.72 * (1.0 - best_edge_norm * 0.7)),
-							0.0,
-							1.0
-						);
-						cr = lerp(cr, 0.44, w_tan);
-						cg = lerp(cg, 0.24, w_tan);
-						cb = lerp(cb, 0.10, w_tan);
-					}
-				}
-
-				// 3. Petiole / rachis coloration: herbaceous green on juvenile shoots -> suberized woody brown on mature shoots
-				if (stem_mask > best_mask) {
-					const stem_r = lerp(lerp(p_r, 0.32, 0.55), 0.32, mu_k);
-					const stem_g = lerp(lerp(p_g, 0.38, 0.55), 0.26, mu_k);
-					const stem_b = lerp(lerp(p_b, 0.16, 0.55), 0.16, mu_k);
-					cr = lerp(cr, stem_r, stem_mask * 0.75);
-					cg = lerp(cg, stem_g, stem_mask * 0.75);
-					cb = lerp(cb, stem_b, stem_mask * 0.75);
-				}
-
-				// Subtle basal petiole ambient darkening
-				const base_shade = 0.82 + 0.18 * v;
-				cr = Math.max(0.01, cr * base_shade);
-				cg = Math.max(0.01, cg * base_shade);
-				cb = Math.max(0.005, cb * base_shade);
-
-				const i4 = p_idx * 4;
-				albedo_data[i4] = clamp(Math.round(cr * 255), 1, 255);
-				albedo_data[i4 + 1] = clamp(Math.round(cg * 255), 1, 255);
-				albedo_data[i4 + 2] = clamp(Math.round(cb * 255), 1, 255);
-				albedo_data[i4 + 3] = clamp(Math.round(alpha * 255), 0, 255);
-
-				const ao = clamp(0.75 + 0.25 * best_h, 0.25, 1.0);
-				const rough = clamp(
-					base_rough + rough_ontogeny_offset + sigma_k * 0.08 - best_vein * 0.08 + (1.0 - n_var) * 0.06,
-					0.15,
-					0.95
-				);
-				orm_data[i4] = clamp(Math.round(ao * 255), 0, 255);
-				orm_data[i4 + 1] = clamp(Math.round(rough * 255), 0, 255);
-				orm_data[i4 + 2] = 0;
-				orm_data[i4 + 3] = 255;
-			}
-		}
-
-		// Pass 2 (per-tile): Central-difference tangent-space normal map clamped to tile bounds
-		const tile_vein_scale = lerp(1.0 - 0.58 * vein_contrast, 1.0 + 0.35 * vein_contrast, mu_k);
-		const norm_str = (1.6 * vein_str + 0.35) * tile_vein_scale;
-		for (let ly_px = 0; ly_px < res; ly_px++) {
-			const y0 = tile_y0 + Math.max(0, ly_px - 1);
-			const y1 = tile_y0 + Math.min(res - 1, ly_px + 1);
-			const yc = tile_y0 + ly_px;
-
-			for (let lx_px = 0; lx_px < res; lx_px++) {
-				const x0 = tile_x0 + Math.max(0, lx_px - 1);
-				const x1 = tile_x0 + Math.min(res - 1, lx_px + 1);
-				const xc = tile_x0 + lx_px;
-
-				const dh_du = (height_field[yc * atlas_w + x1] - height_field[yc * atlas_w + x0]) * 0.5 * norm_str;
-				const dh_dv = (height_field[y1 * atlas_w + xc] - height_field[y0 * atlas_w + xc]) * 0.5 * norm_str;
-
-				let nx = -dh_du;
-				let ny = -dh_dv;
-				const nz = 1.0;
-				const nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
-				nx /= nl;
-				ny /= nl;
-
-				const i2 = (yc * atlas_w + xc) * 2;
-				normal_data[i2] = clamp(Math.round((nx * 0.5 + 0.5) * 255), 0, 255);
-				normal_data[i2 + 1] = clamp(Math.round((ny * 0.5 + 0.5) * 255), 0, 255);
-			}
-		}
-	}
-
-	const albedo_image = ShadeImage.fromSampler2D(albedo_sampler);
-	albedo_image.color_space = ColorSpace.SRGB;
-	// CRITICAL: Keep AlphaMode.Straight so texture_write_to_gpu premultiplies once on upload
-	// and G-buffer albedo_unpremultiply recovers clean dilated leaf color at cutout boundaries.
-	albedo_image.alpha_mode = AlphaMode.Straight;
-	const texture_albedo = ShadeTexture.from(albedo_image);
-	texture_albedo.label = "foliage_leaf_albedo";
-	texture_albedo.color_space = ColorSpace.SRGB;
-	texture_albedo.mipmapGenerationFilter = TextureFilterType.MagicKernelSharp;
-	texture_albedo.wrapS = TextureWrapType.ClampToEdge;
-	texture_albedo.wrapT = TextureWrapType.ClampToEdge;
-
-	const normal_image = ShadeImage.fromSampler2D(normal_sampler);
-	normal_image.color_space = ColorSpace.None;
-	normal_image.alpha_mode = AlphaMode.Opaque;
-	const texture_normal = ShadeTexture.from(normal_image);
-	texture_normal.label = "foliage_leaf_normal";
-	texture_normal.color_space = ColorSpace.LinearSRGB;
-	texture_normal.mipmapGenerationFilter = TextureFilterType.LinearNormal;
-	texture_normal.wrapS = TextureWrapType.ClampToEdge;
-	texture_normal.wrapT = TextureWrapType.ClampToEdge;
-
-	const orm_image = ShadeImage.fromSampler2D(orm_sampler);
-	orm_image.color_space = ColorSpace.None;
-	orm_image.alpha_mode = AlphaMode.Opaque;
-	const texture_orm = ShadeTexture.from(orm_image);
-	texture_orm.label = "foliage_leaf_orm";
-	texture_orm.color_space = ColorSpace.LinearSRGB;
-	texture_orm.wrapS = TextureWrapType.ClampToEdge;
-	texture_orm.wrapT = TextureWrapType.ClampToEdge;
-
-	const material = new StandardShadeMaterial();
-	material.name = "foliage_leaf_material";
-	material.texture_albedo = texture_albedo;
-	material.texture_normal = texture_normal;
-	material.texture_orm = texture_orm;
-	material.roughness_factor = 1.0;
-	material.metallic_factor = 0.0;
-	// CRITICAL: Keep transmission_factor = 0 on AlphaTested cards so transparent card corners
-	// do not act as refractive glass in the path tracer!
-	material.transmission_factor = 0.0;
-	material.ambient_factors.a = 1.0;
-	material.ambient_factors.b = 0.0;
-	material.transparency_mode = TransparencyMode.AlphaTested;
-	material.transparency = TransparencyMode.AlphaTested;
-	material.draw_side = ShadeDrawSide.Double;
-
-	return material;
-}
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { sdnoise3_array } from "../../../core/math/noise/sdnoise.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { smoothStep } from "../../../core/math/smoothStep.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import {
+	FOLIAGE_CHLOROPHYLL_LOSS_RATE,
+	foliage_variant_senescence
+} from "../skeleton/foliage_senescence.js";
+import { compute_foliage_variant_atlas_layout } from "./compute_foliage_variant_atlas_layout.js";
+import { foliage_atlas_cutout_fit_alpha } from "./foliage_atlas_cutout.js";
+import { foliage_material_from_samplers } from "./foliage_material_from_samplers.js";
+import { foliage_tile_layout, foliage_tile_raster } from "./foliage_tile.js";
+
+const SCRATCH_NOISE = new Float32Array(4);
+
+/**
+ * Synthesizes a turn-key procedural PBR cutout `StandardShadeMaterial` (`TransparencyMode.AlphaTested`,
+ * `ShadeDrawSide.Double`) for a species' foliage cards, packing its `foliage_material.variant_count` ontogenetic and
+ * biochemically senescent variants into the texture atlas via `MaxRectanglesPacker` (`pack_max_rectangles`), with
+ * dilated straight-alpha Albedo (`AlphaMode.Straight`, `ColorSpace.SRGB`), 2-channel Normal map
+ * (`ColorSpace.LinearSRGB`), and ORM (`ColorSpace.LinearSRGB`).
+ *
+ * Every tile draws the species' leaf (or a stretch of its needle shoot) at its true size, from its architecture
+ * (`foliage_tile_layout`, `foliage_tile_raster`): the outline's exact coverage, its veins, its petiole.
+ *
+ * The atlas's shape comes out alongside it in `out_cutout`: per tile, the hull of everything drawn and the leaf
+ * coverage, which the card geometry and the card density are built on.
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("./FoliageAtlasCutout.js").FoliageAtlasCutout|null} [out_cutout]
+ * @returns {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+ */
+export function make_foliage_material(species, out_cutout = null) {
+	const cfg = species.foliage_material;
+	const tiles = foliage_tile_layout(species);
+	const layout = compute_foliage_variant_atlas_layout(tiles.resolution, tiles.variant_count);
+	const res = layout.resolution;
+	const tile_count = layout.variant_count;
+	const atlas_w = layout.atlas_w;
+	const atlas_h = layout.atlas_h;
+	const boxes = layout.boxes;
+
+	const rng = seededRandom((species.seed ^ 0x7F4A7C15) | 0);
+
+	const albedo_sampler = Sampler2D.uint8(4, atlas_w, atlas_h);
+	const normal_sampler = Sampler2D.uint8(2, atlas_w, atlas_h);
+	const orm_sampler = Sampler2D.uint8(4, atlas_w, atlas_h);
+
+	const albedo_data = albedo_sampler.data;
+	const normal_data = normal_sampler.data;
+	const orm_data = orm_sampler.data;
+
+	const height_field = new Float32Array(atlas_w * atlas_h);
+	const base_rough = clamp(cfg.roughness, 0.1, 1.0);
+	const vein_str = clamp(cfg.vein_strength, 0.0, 1.0);
+
+	// Ontogeny & first-principles biochemical senescence parameters
+	const juv_shift = clamp(cfg.juvenile_color_shift ?? 0.38, 0.0, 1.0);
+	const juv_antho = clamp(cfg.juvenile_anthocyanin ?? 0.08, 0.0, 1.0);
+	const vein_contrast = clamp(cfg.ontogeny_vein_contrast ?? 0.55, 0.0, 1.0);
+
+	// Honour both first-principles `senescence` and legacy `autumn_tint`
+	const senescence = clamp(Math.max(cfg.senescence ?? 0.0, cfg.autumn_tint ?? 0.0), 0.0, 1.0);
+	const car_density = clamp(cfg.carotenoid_density ?? 0.75, 0.0, 1.0);
+	const antho_pot = clamp(cfg.anthocyanin_potential ?? 0.35, 0.0, 1.0);
+	const tannin_ox = clamp(cfg.tannin_oxidation ?? 0.25, 0.0, 1.0);
+
+	const p_r = cfg.primary_color.r;
+	const p_g = cfg.primary_color.g;
+	const p_b = cfg.primary_color.b;
+	const s_r = cfg.secondary_color.r;
+	const s_g = cfg.secondary_color.g;
+	const s_b = cfg.secondary_color.b;
+
+	// Pre-fill entire atlas with dilated base RGB (alpha = 0) and neutral normal/ORM so any
+	// unused rectangle cells (e.g., when variant_count = 3 or 5) still carry valid dilated RGB.
+	const fill_r = clamp(Math.round(Math.max(0.04, p_r) * 255), 1, 255);
+	const fill_g = clamp(Math.round(Math.max(0.04, p_g) * 255), 1, 255);
+	const fill_b = clamp(Math.round(Math.max(0.02, p_b) * 255), 1, 255);
+	const fill_rough = clamp(Math.round(base_rough * 255), 0, 255);
+	const total_texels = atlas_w * atlas_h;
+	for (let p = 0; p < total_texels; p++) {
+		const i4 = p * 4;
+		albedo_data[i4] = fill_r;
+		albedo_data[i4 + 1] = fill_g;
+		albedo_data[i4 + 2] = fill_b;
+		albedo_data[i4 + 3] = 0;
+
+		const i2 = p * 2;
+		normal_data[i2] = 128;
+		normal_data[i2 + 1] = 128;
+
+		orm_data[i4] = 255;
+		orm_data[i4 + 1] = fill_rough;
+		orm_data[i4 + 2] = 0;
+		orm_data[i4 + 3] = 255;
+	}
+
+	if (out_cutout !== null) {
+		out_cutout.resize(tile_count);
+	}
+
+	for (let v_idx = 0; v_idx < tile_count; v_idx++) {
+		const box = boxes[v_idx];
+		const tile_x0 = box.x0;
+		const tile_y0 = box.y0;
+
+		// Ontogenetic coordinate mu_k in [0, 1]: 0 = juvenile apical flush, 1 = mature basal foliage
+		const raster = foliage_tile_raster(species, tiles, v_idx);
+		const mu_k = raster.maturity;
+		const ox = (rng() - 0.5) * 150.0 + v_idx * 37.3;
+		const oy = (rng() - 0.5) * 150.0 + v_idx * 53.7;
+
+		// Ontogenetic chlorophyll accumulation (juvenile protochlorophyllide lag -> lighter yellow-green)
+		const juv_factor = (1.0 - mu_k) * juv_shift;
+		// Staggered variant senescence progression across the atlas so autumn crowns exhibit natural leaf-to-leaf diversity
+		const sigma_k = foliage_variant_senescence(senescence, mu_k);
+		const sun_variant_factor = lerp(1.18, 0.74, mu_k);
+		const rough_ontogeny_offset = lerp(-0.10 * vein_contrast, 0.07 * vein_contrast, mu_k);
+
+		for (let ly_px = 0; ly_px < res; ly_px++) {
+			const v = (ly_px + 0.5) / res;
+			const atlas_y = tile_y0 + ly_px;
+			const row_offset = atlas_y * atlas_w;
+			for (let lx_px = 0; lx_px < res; lx_px++) {
+				const u = (lx_px + 0.5) / res;
+				const atlas_x = tile_x0 + lx_px;
+				const p_idx = row_offset + atlas_x;
+				const t_idx = ly_px * res + lx_px;
+
+				const alpha = raster.alpha[t_idx];
+				const best_mask = alpha;
+				const best_vein = raster.vein[t_idx];
+				const best_tip = raster.tip[t_idx];
+				const best_edge_norm = raster.edge_norm[t_idx];
+				const best_h = raster.height[t_idx];
+				const stem_mask = raster.stem[t_idx];
+				height_field[p_idx] = Math.max(best_h, stem_mask * 0.4);
+
+				const alpha_byte = clamp(Math.round(alpha * 255), 0, 255);
+				// a texel the leaf does not cover keeps the dilated fill: nothing is drawn there
+				if (alpha_byte === 0) continue;
+
+				sdnoise3_array(SCRATCH_NOISE, u * 6.0 + ox, v * 6.0 + oy, 0.0);
+				const n_var = SCRATCH_NOISE[0] * 0.5 + 0.5;
+
+				// 1. Base photosynthetic chlorophyll + carotenoid lamina reflectance (with juvenile chartreuse shift)
+				const vein_mix_w = lerp(0.38, 0.72, mu_k) * vein_str;
+				const mix_t = clamp(best_vein * vein_mix_w + best_tip * 0.24 + n_var * 0.18, 0.0, 1.0);
+				let cr = lerp(p_r, s_r, mix_t);
+				let cg = lerp(p_g, s_g, mix_t);
+				let cb = lerp(p_b, s_b, mix_t);
+
+				// Juvenile protochlorophyllide lag: higher mesophyll reflectance + yellow-green chartreuse shift
+				if (juv_factor > 1e-4) {
+					const tip_boost = 0.75 + 0.25 * best_tip;
+					const j_w = juv_factor * tip_boost;
+					cr = clamp(cr + j_w * 0.22, 0.0, 1.0);
+					cg = clamp(cg + j_w * 0.28, 0.0, 1.0);
+					cb = clamp(cb + j_w * 0.04, 0.0, 1.0);
+				}
+
+				// Transient juvenile epidermal anthocyanin flush along expanding young leaf margins/tips
+				const w_ant_juv = juv_antho * Math.pow(1.0 - mu_k, 1.8)
+					* (0.30 + 0.70 * (1.0 - best_edge_norm * 0.65) * (0.35 + 0.65 * best_tip))
+					* (1.0 - sigma_k);
+				if (w_ant_juv > 1e-4) {
+					cr = lerp(cr, 0.58, w_ant_juv * 0.75);
+					cg = lerp(cg, 0.24, w_ant_juv * 0.65);
+					cb = lerp(cb, 0.14, w_ant_juv * 0.65);
+				}
+
+				// 2. First-principles autumn senescence (Chlorophyll catabolism -> Carotenoid unmasking -> Anthocyanin -> Tannin)
+				if (sigma_k > 1e-4) {
+					// Vascular bundles (midrib & secondary veins) and basal petiole retain chlorophyll longest
+					const vascular_shield = clamp(
+						0.48 * best_vein + 0.34 * best_edge_norm * (1.0 - 0.55 * best_tip) + 0.18 * n_var,
+						0.0,
+						1.0
+					);
+					const r_chl_lin = clamp(1.0 - sigma_k * (FOLIAGE_CHLOROPHYLL_LOSS_RATE - 0.68 * vascular_shield), 0.0, 1.0);
+					const r_chl = r_chl_lin * r_chl_lin;
+					const chl_loss = 1.0 - r_chl;
+
+					// (a) Unmask plastid carotenoids (xanthophyll / beta-carotene -> golden-yellow)
+					const car_r = lerp(0.76, 0.94, car_density);
+					const car_g = lerp(0.54, 0.74, car_density);
+					const car_b = lerp(0.14, 0.08, car_density);
+					const w_car = clamp(chl_loss * (0.38 + 0.62 * car_density), 0.0, 1.0);
+					cr = lerp(cr, car_r, w_car);
+					cg = lerp(cg, car_g, w_car);
+					cb = lerp(cb, car_b, w_car);
+
+					// (b) De novo vacuolar anthocyanin synthesis (high light + margin/tip sugar accumulation -> scarlet/crimson)
+					if (antho_pot > 1e-4) {
+						const margin_sugar = clamp(
+							0.52 * (1.0 - best_edge_norm) + 0.34 * best_tip + 0.22 * (1.0 - best_vein) + 0.15 * (1.0 - n_var),
+							0.0,
+							1.0
+						);
+						const w_ant = clamp(
+							antho_pot * chl_loss * Math.pow(sigma_k, 0.72) * sun_variant_factor * (0.42 + 0.78 * margin_sugar),
+							0.0,
+							1.0
+						);
+						// Vacuolar anthocyanin strongly absorbs green (~530nm) and blue while transmitting red (~650nm)
+						cr = lerp(cr, 0.82, w_ant * 0.85);
+						cg *= lerp(1.0, 0.18, w_ant);
+						cb *= lerp(1.0, 0.24, w_ant);
+					}
+
+					// (c) Late-senescence condensed tannin / polyphenol oxidation into russet/copper-brown
+					if (tannin_ox > 1e-4 && sigma_k > 0.22) {
+						const w_tan = clamp(
+							tannin_ox
+							* chl_loss * chl_loss
+							* smoothStep(0.22, 0.95, sigma_k)
+							* lerp(0.68, 1.22, mu_k)
+							* (0.42 + 0.72 * (1.0 - best_edge_norm * 0.7)),
+							0.0,
+							1.0
+						);
+						cr = lerp(cr, 0.44, w_tan);
+						cg = lerp(cg, 0.24, w_tan);
+						cb = lerp(cb, 0.10, w_tan);
+					}
+				}
+
+				// 3. Petiole / rachis coloration: herbaceous green on juvenile shoots -> suberized woody brown on mature shoots
+				if (stem_mask > 0) {
+					const stem_r = lerp(lerp(p_r, 0.32, 0.55), 0.32, mu_k);
+					const stem_g = lerp(lerp(p_g, 0.38, 0.55), 0.26, mu_k);
+					const stem_b = lerp(lerp(p_b, 0.16, 0.55), 0.16, mu_k);
+					cr = lerp(cr, stem_r, stem_mask * 0.75);
+					cg = lerp(cg, stem_g, stem_mask * 0.75);
+					cb = lerp(cb, stem_b, stem_mask * 0.75);
+				}
+
+				// Subtle basal petiole ambient darkening
+				const base_shade = 0.82 + 0.18 * v;
+				cr = Math.max(0.01, cr * base_shade);
+				cg = Math.max(0.01, cg * base_shade);
+				cb = Math.max(0.005, cb * base_shade);
+
+				const i4 = p_idx * 4;
+				albedo_data[i4] = clamp(Math.round(cr * 255), 1, 255);
+				albedo_data[i4 + 1] = clamp(Math.round(cg * 255), 1, 255);
+				albedo_data[i4 + 2] = clamp(Math.round(cb * 255), 1, 255);
+				albedo_data[i4 + 3] = alpha_byte;
+
+				const ao = clamp(0.75 + 0.25 * best_h, 0.25, 1.0);
+				const rough = clamp(
+					base_rough + rough_ontogeny_offset + sigma_k * 0.08 - best_vein * 0.08 + (1.0 - n_var) * 0.06,
+					0.15,
+					0.95
+				);
+				orm_data[i4] = clamp(Math.round(ao * 255), 0, 255);
+				orm_data[i4 + 1] = clamp(Math.round(rough * 255), 0, 255);
+				orm_data[i4 + 2] = 0;
+				orm_data[i4 + 3] = 255;
+			}
+		}
+
+		if (out_cutout !== null) {
+			foliage_atlas_cutout_fit_alpha(out_cutout, v_idx, raster.alpha, res);
+		}
+
+		// Pass 2 (per-tile): Central-difference tangent-space normal map clamped to tile bounds
+		const tile_vein_scale = lerp(1.0 - 0.58 * vein_contrast, 1.0 + 0.35 * vein_contrast, mu_k);
+		const norm_str = (1.6 * vein_str + 0.35) * tile_vein_scale;
+		for (let ly_px = 0; ly_px < res; ly_px++) {
+			const y0 = tile_y0 + Math.max(0, ly_px - 1);
+			const y1 = tile_y0 + Math.min(res - 1, ly_px + 1);
+			const yc = tile_y0 + ly_px;
+
+			for (let lx_px = 0; lx_px < res; lx_px++) {
+				const x0 = tile_x0 + Math.max(0, lx_px - 1);
+				const x1 = tile_x0 + Math.min(res - 1, lx_px + 1);
+				const xc = tile_x0 + lx_px;
+
+				const dh_du = (height_field[yc * atlas_w + x1] - height_field[yc * atlas_w + x0]) * 0.5 * norm_str;
+				const dh_dv = (height_field[y1 * atlas_w + xc] - height_field[y0 * atlas_w + xc]) * 0.5 * norm_str;
+
+				let nx = -dh_du;
+				let ny = -dh_dv;
+				const nz = 1.0;
+				const nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
+				nx /= nl;
+				ny /= nl;
+
+				const i2 = (yc * atlas_w + xc) * 2;
+				normal_data[i2] = clamp(Math.round((nx * 0.5 + 0.5) * 255), 0, 255);
+				normal_data[i2 + 1] = clamp(Math.round((ny * 0.5 + 0.5) * 255), 0, 255);
+			}
+		}
+	}
+
+	const material = foliage_material_from_samplers(albedo_sampler, normal_sampler, orm_sampler, "foliage_leaf");
+	return material;
+}