@woosh/meep-engine 3.56.0 → 3.57.0

package/src/generation/foliage/mesh/tree_mesh_build_foliage.js

@@ -1,454 +1,467 @@
-import { clamp } from "../../../core/math/clamp.js";
-import { lerp } from "../../../core/math/lerp.js";
-import { Geometry } from "../../../shade/renderer/geometry/Geometry.js";
-import {
-	geometry_obtain_attribute,
-	geometry_obtain_index
-} from "../../../shade/renderer/geometry/geometry_obtain_attribute.js";
-import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
-import { FoliageCardType } from "../config/FoliageCardType.js";
-import { TreeLODConfig } from "../config/TreeLODConfig.js";
-import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
-import { compute_foliage_variant_atlas_layout } from "../material/make_foliage_material.js";
-import { tree_mesh_apply_canopy_ao } from "./tree_mesh_apply_canopy_ao.js";
-import { geometry_obtain_joints_attribute } from "./tree_mesh_build_bark.js";
-
-/**
- * Synthesizes the foliage `Geometry` for a given LOD from a `FoliageAttachmentSet`,
- * applying golden-ratio low-discrepancy LOD decimation ($h_i < k_{\text{keep}}$),
- * optical area-compensation scaling ($s_{\text{comp}} = k_{\text{keep}}^{-\eta}$),
- * botanical 3D card geometry (`FoldedVCard`, `CrossCard`, `TriStarCluster`, `RibbedFrond`, `OctagonalCutoutHull`),
- * MaxRect-packed ontogenetic variant UV remapping, hemisphere-safe normal puffing,
- * volumetric canopy AO, and 4-joint skeletal wind skinning.
- *
- * Returns `null` if foliage is disabled or `lod_config.foliage_keep_ratio <= 0` or `attachments.count === 0`.
- *
- * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
- * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
- * @param {TreeSpeciesConfig} [config]
- * @param {TreeLODConfig} [lod_config]
- * @param {Geometry} [out]
- * @returns {Geometry|null}
- */
-export function tree_mesh_build_foliage(
-	skeleton,
-	attachments,
-	config = new TreeSpeciesConfig(),
-	lod_config = new TreeLODConfig(),
-	out = new Geometry()
-) {
-	const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
-	const lod_cfg = lod_config && lod_config.isTreeLODConfig ? lod_config : TreeLODConfig.from(lod_config);
-	const fol = species.foliage;
-	const keep_ratio = clamp(lod_cfg.foliage_keep_ratio ?? 1.0, 0.0, 1.0);
-	if (!fol.enabled || !attachments || attachments.count === 0 || keep_ratio <= 0.0) {
-		return null;
-	}
-
-	// Filter active attachment indices by golden-ratio rank
-	const active_indices = [];
-	for (let i = 0; i < attachments.count; i++) {
-		if (attachments.ranks[i] < keep_ratio) {
-			active_indices.push(i);
-		}
-	}
-	if (active_indices.length === 0 && attachments.count > 0) {
-		active_indices.push(0);
-	}
-	const card_count = active_indices.length;
-
-	// Area compensation scale: k_keep^(-eta)
-	const eta = clamp(lod_cfg.foliage_area_compensation_exponent ?? 0.42, 0.0, 0.6);
-	const area_comp = Math.pow(Math.max(0.08, keep_ratio), -eta);
-
-	// Determine effective card type for this LOD
-	let card_type = fol.card_type;
-	if (lod_cfg.simplify_cards) {
-		card_type = FoliageCardType.FoldedVCard;
-	}
-
-	const frond_segs = Math.max(2, fol.frond_segments | 0);
-	let verts_per_card = 6;
-	let tris_per_card = 4;
-
-	switch (card_type) {
-		case FoliageCardType.CrossCard:
-			verts_per_card = 8;
-			tris_per_card = 4;
-			break;
-		case FoliageCardType.TriStarCluster:
-			verts_per_card = 12;
-			tris_per_card = 6;
-			break;
-		case FoliageCardType.RibbedFrond:
-			verts_per_card = 3 * (frond_segs + 1);
-			tris_per_card = 4 * frond_segs;
-			break;
-		case FoliageCardType.OctagonalCutoutHull:
-			verts_per_card = 7;
-			tris_per_card = 6;
-			break;
-		case FoliageCardType.FoldedVCard:
-		default:
-			verts_per_card = 6;
-			tris_per_card = 4;
-			break;
-	}
-
-	const total_vertices = card_count * verts_per_card;
-	const total_indices = card_count * tris_per_card * 3;
-
-	const positions = geometry_obtain_attribute(out, StandardAttributes.Position, 3, total_vertices);
-	const normals = geometry_obtain_attribute(out, StandardAttributes.Normal, 3, total_vertices);
-	const uv0 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates0, 2, total_vertices);
-	const uv1 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates1, 2, total_vertices);
-	const colors = geometry_obtain_attribute(out, StandardAttributes.Color, 3, total_vertices);
-	const joints = geometry_obtain_joints_attribute(out, total_vertices);
-	const weights = geometry_obtain_attribute(out, StandardAttributes.SkinningWeights, 4, total_vertices);
-	const indices = geometry_obtain_index(out, total_indices);
-
-	const fol_mat = species.foliage_material;
-	const layout = compute_foliage_variant_atlas_layout(
-		fol_mat?.resolution ?? 128,
-		fol_mat?.variant_count ?? 4
-	);
-	const uv_rects = layout.uv_rects;
-	const variant_count = layout.variant_count;
-
-	const base_w = Math.max(0.05, fol.card_width) * area_comp;
-	const base_l = Math.max(0.05, fol.card_length) * area_comp;
-	const fold_angle = clamp(fol.fold_angle, 0.0, 0.65);
-	const sin_fold = Math.sin(fold_angle);
-	const cos_fold = Math.cos(fold_angle);
-	const arch_h = fol.arch_height;
-	const droop = fol.camber_droop;
-	const color_var_amp = clamp(fol.color_variation ?? 0.08, 0.0, 0.35);
-	const anchor_u = clamp(fol_mat?.stem_anchor_u ?? 0.5, 0.1, 0.9);
-	const anchor_v = clamp(fol_mat?.stem_anchor_v ?? 0.0, 0.0, 0.25);
-	const juv_shift = clamp(fol_mat?.juvenile_color_shift ?? 0.38, 0.0, 1.0);
-	const senescence = clamp(Math.max(fol_mat?.senescence ?? 0.0, fol_mat?.autumn_tint ?? 0.0), 0.0, 1.0);
-	const antho_pot = clamp(fol_mat?.anthocyanin_potential ?? 0.35, 0.0, 1.0);
-
-	let v_cursor = 0;
-	let i_cursor = 0;
-	let rect_u0 = 0.0;
-	let rect_v0 = 0.0;
-	let rect_u1 = 1.0;
-	let rect_v1 = 1.0;
-
-	/**
-	 * Helper to write a single foliage vertex in card-local coordinates `(x_w, y_u, z_f)`
-	 * and local normal `(nx_w, ny_u, nz_f)`, remapping local `[0, 1]^2` card UVs into the
-	 * card's assigned MaxRect-packed atlas tile `[rect_u0, rect_v0, rect_u1, rect_v1]`.
-	 */
-	const write_card_vertex = (
-		px0, py0, pz0,
-		wx, wy, wz,
-		ux, uy, uz,
-		fx, fy, fz,
-		x_w, y_u, z_f,
-		nx_w, ny_u, nz_f,
-		u_tex, v_tex,
-		flutter_w, phase_w,
-		r_col, g_col, b_col,
-		j0, j1, j2, j3,
-		w0, w1, w2, w3
-	) => {
-		const v3 = v_cursor * 3;
-		const v2 = v_cursor * 2;
-		const v4 = v_cursor * 4;
-
-		positions[v3] = px0 + wx * x_w + ux * y_u + fx * z_f;
-		positions[v3 + 1] = py0 + wy * x_w + uy * y_u + fy * z_f;
-		positions[v3 + 2] = pz0 + wz * x_w + uz * y_u + fz * z_f;
-
-		let gnx = wx * nx_w + ux * ny_u + fx * nz_f;
-		let gny = wy * nx_w + uy * ny_u + fy * nz_f;
-		let gnz = wz * nx_w + uz * ny_u + fz * nz_f;
-		const nl = Math.sqrt(gnx * gnx + gny * gny + gnz * gnz);
-		if (nl > 1e-8) {
-			gnx /= nl;
-			gny /= nl;
-			gnz /= nl;
-		}
-		normals[v3] = gnx;
-		normals[v3 + 1] = gny;
-		normals[v3 + 2] = gnz;
-
-		uv0[v2] = lerp(rect_u0, rect_u1, u_tex);
-		uv0[v2 + 1] = lerp(rect_v0, rect_v1, v_tex);
-
-		uv1[v2] = clamp(flutter_w, 0.0, 1.0);
-		uv1[v2 + 1] = clamp(phase_w, 0.0, 1.0);
-
-		colors[v3] = r_col;
-		colors[v3 + 1] = g_col;
-		colors[v3 + 2] = b_col;
-
-		joints[v4] = j0;
-		joints[v4 + 1] = j1;
-		joints[v4 + 2] = j2;
-		joints[v4 + 3] = j3;
-
-		weights[v4] = w0;
-		weights[v4 + 1] = w1;
-		weights[v4 + 2] = w2;
-		weights[v4 + 3] = w3;
-
-		return v_cursor++;
-	};
-
-	const has_j4 = Boolean(attachments.joints4 && attachments.weights4 && attachments.joints4.length >= attachments.count * 4);
-	const has_variants = Boolean(attachments.variant_indices && attachments.variant_indices.length >= attachments.count);
-	const has_maturities = Boolean(attachments.maturities && attachments.maturities.length >= attachments.count);
-	const has_sun = Boolean(attachments.sun_exposure && attachments.sun_exposure.length >= attachments.count);
-
-	for (let c = 0; c < card_count; c++) {
-		const att_idx = active_indices[c];
-		const a3 = att_idx * 3;
-		const a2 = att_idx * 2;
-		const a4 = att_idx * 4;
-
-		const px0 = attachments.positions[a3];
-		const py0 = attachments.positions[a3 + 1];
-		const pz0 = attachments.positions[a3 + 2];
-
-		const fx = attachments.forward[a3];
-		const fy = attachments.forward[a3 + 1];
-		const fz = attachments.forward[a3 + 2];
-
-		const ux = attachments.up[a3];
-		const uy = attachments.up[a3 + 1];
-		const uz = attachments.up[a3 + 2];
-
-		const wx = attachments.right[a3];
-		const wy = attachments.right[a3 + 1];
-		const wz = attachments.right[a3 + 2];
-
-		const maturity = has_maturities ? attachments.maturities[att_idx] : 0.5;
-		const sun_exp = has_sun ? attachments.sun_exposure[att_idx] : 0.65;
-		const v_idx = has_variants
-			? clamp(attachments.variant_indices[att_idx], 0, variant_count - 1)
-			: clamp(Math.floor(maturity * variant_count), 0, variant_count - 1);
-		const r4 = v_idx * 4;
-		rect_u0 = uv_rects[r4];
-		rect_v0 = uv_rects[r4 + 1];
-		rect_u1 = uv_rects[r4 + 2];
-		rect_v1 = uv_rects[r4 + 3];
-
-		const scale = attachments.scales[att_idx];
-		const card_w = base_w * scale;
-		const card_l = base_l * scale;
-		const half_w = card_w * 0.5;
-		const left_w = -card_w * anchor_u;
-		const right_w = card_w * (1.0 - anchor_u);
-
-		const phase = attachments.phases[att_idx];
-		const b_sway = attachments.branch_sway[att_idx];
-		const c_jit = attachments.color_jitter[att_idx] * color_var_amp;
-
-		// Continuous ontogenetic & crown-shell photoprotective modulation in vertex colors
-		const juv_lift = (0.5 - maturity) * juv_shift * 0.14;
-		let r_col = clamp(1.0 + c_jit * 1.1 + juv_lift * 0.9, 0.68, 1.0);
-		let g_col = clamp(1.0 + c_jit * 0.8 + juv_lift * 1.1, 0.68, 1.0);
-		let b_col = clamp(1.0 - c_jit * 0.6 - juv_lift * 0.5, 0.68, 1.0);
-
-		if (senescence > 1e-4) {
-			// Sun-exposed outer crown shell expresses stronger anthocyanin/carotenoid warmth than shaded interior
-			const shade_cool = (1.0 - sun_exp) * senescence * 0.22;
-			const sun_antho = sun_exp * senescence * antho_pot * 0.25;
-			r_col = clamp(r_col * (1.0 - shade_cool * 0.45 + sun_antho * 0.18), 0.65, 1.0);
-			g_col = clamp(g_col * (1.0 + shade_cool * 0.15 - sun_antho * 0.35), 0.55, 1.0);
-			b_col = clamp(b_col * (1.0 - sun_antho * 0.30), 0.55, 1.0);
-		}
-
-		const j0 = has_j4 ? attachments.joints4[a4] : attachments.joints[a2];
-		const j1 = has_j4 ? attachments.joints4[a4 + 1] : attachments.joints[a2 + 1];
-		const j2 = has_j4 ? attachments.joints4[a4 + 2] : 0;
-		const j3 = has_j4 ? attachments.joints4[a4 + 3] : 0;
-		const w0 = has_j4 ? attachments.weights4[a4] : attachments.weights[a2];
-		const w1 = has_j4 ? attachments.weights4[a4 + 1] : attachments.weights[a2 + 1];
-		const w2 = has_j4 ? attachments.weights4[a4 + 2] : 0.0;
-		const w3 = has_j4 ? attachments.weights4[a4 + 3] : 0.0;
-
-		const base_v = v_cursor;
-
-		if (card_type === FoliageCardType.CrossCard) {
-			// Plane 0: horizontal (W, F) with normal +U (since W x F = +U)
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, left_w, 0, 0, 0, 1, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, right_w, 0, 0, 0, 1, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, left_w, 0, card_l, 0, 1, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, right_w, 0, card_l, 0, 1, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-
-			indices[i_cursor++] = base_v + 0;
-			indices[i_cursor++] = base_v + 1;
-			indices[i_cursor++] = base_v + 3;
-			indices[i_cursor++] = base_v + 0;
-			indices[i_cursor++] = base_v + 3;
-			indices[i_cursor++] = base_v + 2;
-
-			// Plane 1: vertical (-U to +U, F) with normal +W (since (-U) x F = +W)
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -left_w, 0, 1, 0, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -right_w, 0, 1, 0, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -left_w, card_l, 1, 0, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -right_w, card_l, 1, 0, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-
-			indices[i_cursor++] = base_v + 4;
-			indices[i_cursor++] = base_v + 5;
-			indices[i_cursor++] = base_v + 7;
-			indices[i_cursor++] = base_v + 4;
-			indices[i_cursor++] = base_v + 7;
-			indices[i_cursor++] = base_v + 6;
-		} else if (card_type === FoliageCardType.TriStarCluster) {
-			for (let p = 0; p < 3; p++) {
-				const ang = (p * Math.PI) / 3.0;
-				const ca = Math.cos(ang);
-				const sa = Math.sin(ang);
-				const p_left_x = ca * left_w;
-				const p_left_y = sa * left_w;
-				const p_right_x = ca * right_w;
-				const p_right_y = sa * right_w;
-				const pn_x = -sa;
-				const pn_y = ca;
-				const p_base = base_v + p * 4;
-
-				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_left_x, p_left_y, 0, pn_x, pn_y, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_right_x, p_right_y, 0, pn_x, pn_y, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_left_x, p_left_y, card_l, pn_x, pn_y, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_right_x, p_right_y, card_l, pn_x, pn_y, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-
-				indices[i_cursor++] = p_base + 0;
-				indices[i_cursor++] = p_base + 1;
-				indices[i_cursor++] = p_base + 3;
-				indices[i_cursor++] = p_base + 0;
-				indices[i_cursor++] = p_base + 3;
-				indices[i_cursor++] = p_base + 2;
-			}
-		} else if (card_type === FoliageCardType.RibbedFrond) {
-			const lift_wing = half_w * sin_fold;
-			const span_w = half_w * cos_fold;
-
-			for (let s = 0; s <= frond_segs; s++) {
-				const t = s / frond_segs;
-				const v_tex = anchor_v + (1.0 - anchor_v) * t;
-				const z_s = t * card_l;
-				const y_spine = card_l * (arch_h * 4.0 * t * (1.0 - t) - droop * t * t);
-				const env_w = Math.sin(Math.PI * (0.12 + 0.82 * t));
-				const w_s = span_w * env_w;
-				const lift_s = lift_wing * env_w;
-				const flutter = clamp(b_sway * 0.3 + 0.7 * t, 0.0, 1.0);
-
-				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -w_s, y_spine + lift_s, z_s, -sin_fold * 0.35, cos_fold, 0, 0.0, v_tex, flutter, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, y_spine, z_s, 0.0, 1.0, 0, anchor_u, v_tex, flutter * 0.75, phase, r_col * 0.94, g_col * 0.94, b_col * 0.94, j0, j1, j2, j3, w0, w1, w2, w3);
-				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, w_s, y_spine + lift_s, z_s, sin_fold * 0.35, cos_fold, 0, 1.0, v_tex, flutter, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-
-				if (s > 0) {
-					const r0 = base_v + (s - 1) * 3;
-					const r1 = base_v + s * 3;
-					indices[i_cursor++] = r0 + 0;
-					indices[i_cursor++] = r0 + 1;
-					indices[i_cursor++] = r1 + 1;
-					indices[i_cursor++] = r0 + 0;
-					indices[i_cursor++] = r1 + 1;
-					indices[i_cursor++] = r1 + 0;
-
-					indices[i_cursor++] = r0 + 1;
-					indices[i_cursor++] = r0 + 2;
-					indices[i_cursor++] = r1 + 2;
-					indices[i_cursor++] = r0 + 1;
-					indices[i_cursor++] = r1 + 2;
-					indices[i_cursor++] = r1 + 1;
-				}
-			}
-		} else if (card_type === FoliageCardType.OctagonalCutoutHull) {
-			const lift = half_w * sin_fold * 0.7;
-			const span = half_w * cos_fold;
-			const camber = card_l * arch_h;
-
-			// v0: base petiole (0, 0, 0) at exact UV (anchor_u, anchor_v)
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, 0.0, 0.0, 0, 1, 0, anchor_u, anchor_v, b_sway * 0.25, phase, r_col * 0.9, g_col * 0.9, b_col * 0.9, j0, j1, j2, j3, w0, w1, w2, w3);
-			// v1: lower-left
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span * 0.85, lift * 0.7, card_l * 0.28, -sin_fold * 0.3, cos_fold, 0, 0.08, 0.28, b_sway * 0.55, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			// v2: lower-right
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span * 0.85, lift * 0.7, card_l * 0.28, sin_fold * 0.3, cos_fold, 0, 0.92, 0.28, b_sway * 0.55, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			// v3: center midrib
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, camber, card_l * 0.52, 0, 1, 0, anchor_u, 0.52, b_sway * 0.65, phase, r_col * 0.96, g_col * 0.96, b_col * 0.96, j0, j1, j2, j3, w0, w1, w2, w3);
-			// v4: upper-left
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift, card_l * 0.74, -sin_fold * 0.3, cos_fold, 0, 0.04, 0.74, 0.9, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			// v5: upper-right
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift, card_l * 0.74, sin_fold * 0.3, cos_fold, 0, 0.96, 0.74, 0.9, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			// v6: apex tip
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, -card_l * droop * 0.5, card_l, 0, 1, 0, anchor_u, 0.98, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-
-			// 6 outward (+U) triangles fanning around center midrib v3
-			indices[i_cursor++] = base_v + 0;
-			indices[i_cursor++] = base_v + 2;
-			indices[i_cursor++] = base_v + 3;
-
-			indices[i_cursor++] = base_v + 0;
-			indices[i_cursor++] = base_v + 3;
-			indices[i_cursor++] = base_v + 1;
-
-			indices[i_cursor++] = base_v + 3;
-			indices[i_cursor++] = base_v + 2;
-			indices[i_cursor++] = base_v + 5;
-
-			indices[i_cursor++] = base_v + 3;
-			indices[i_cursor++] = base_v + 5;
-			indices[i_cursor++] = base_v + 6;
-
-			indices[i_cursor++] = base_v + 3;
-			indices[i_cursor++] = base_v + 6;
-			indices[i_cursor++] = base_v + 4;
-
-			indices[i_cursor++] = base_v + 3;
-			indices[i_cursor++] = base_v + 4;
-			indices[i_cursor++] = base_v + 1;
-		} else {
-			// Default: FoldedVCard (6 vertices, 4 triangles)
-			const lift = half_w * sin_fold;
-			const span = half_w * cos_fold;
-			const tip_droop = -card_l * droop * 0.5;
-			const mid_arch = card_l * arch_h * 0.5;
-
-			// Row 0 (base, z = 0)
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift, 0.0, -sin_fold * 0.35, cos_fold, 0, 0.0, anchor_v, b_sway * 0.45, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, 0.0, 0.0, 0.0, 1.0, 0, anchor_u, anchor_v, b_sway * 0.25, phase, r_col * 0.92, g_col * 0.92, b_col * 0.92, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift, 0.0, sin_fold * 0.35, cos_fold, 0, 1.0, anchor_v, b_sway * 0.45, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-
-			// Row 1 (tip, z = card_l)
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift + tip_droop, card_l, -sin_fold * 0.35, cos_fold, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, mid_arch + tip_droop, card_l, 0.0, 1.0, 0, anchor_u, 1.0, 0.85, phase, r_col * 0.96, g_col * 0.96, b_col * 0.96, j0, j1, j2, j3, w0, w1, w2, w3);
-			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift + tip_droop, card_l, sin_fold * 0.35, cos_fold, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
-
-			// Left wing quad
-			indices[i_cursor++] = base_v + 0;
-			indices[i_cursor++] = base_v + 1;
-			indices[i_cursor++] = base_v + 4;
-			indices[i_cursor++] = base_v + 0;
-			indices[i_cursor++] = base_v + 4;
-			indices[i_cursor++] = base_v + 3;
-
-			// Right wing quad
-			indices[i_cursor++] = base_v + 1;
-			indices[i_cursor++] = base_v + 2;
-			indices[i_cursor++] = base_v + 5;
-			indices[i_cursor++] = base_v + 1;
-			indices[i_cursor++] = base_v + 5;
-			indices[i_cursor++] = base_v + 4;
-		}
-	}
-
-	// Apply volumetric canopy AO and hemisphere-safe normal puffing BEFORE ensureTangents()
-	tree_mesh_apply_canopy_ao(out, skeleton.crown_center, skeleton.crown_radii, {
-		ao_core_darkening: fol.ao_core_darkening ?? 0.35,
-		normal_puffiness: fol.normal_puffiness ?? 0.35,
-		preserve_existing_color: true
-	});
-
-	out.name = `${species.name || "tree"}_foliage_lod${lod_cfg.level}`;
-	out.ensureBounds();
-	out.ensureTangents();
-
-	return out;
-}
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { Geometry } from "../../../shade/renderer/geometry/Geometry.js";
+import {
+	geometry_obtain_attribute,
+	geometry_obtain_index
+} from "../../../shade/renderer/geometry/geometry_obtain_attribute.js";
+import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
+import { FoliageCardType } from "../config/FoliageCardType.js";
+import { TreeLODConfig } from "../config/TreeLODConfig.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { compute_foliage_variant_atlas_layout } from "../material/compute_foliage_variant_atlas_layout.js";
+import { foliage_tile_layout } from "../material/foliage_tile.js";
+import { CUTOUT_HULL_VERTEX_COUNT } from "../material/FoliageAtlasCutout.js";
+import { tree_mesh_apply_canopy_ao } from "./tree_mesh_apply_canopy_ao.js";
+import { geometry_obtain_joints_attribute } from "./tree_mesh_build_bark.js";
+
+/**
+ * `CutoutHull` outline when there is no fitted atlas: the whole tile, counter-clockwise.
+ * @type {Float32Array}
+ */
+const WHOLE_TILE_HULL = new Float32Array([0, 0, 1, 0, 1, 0.5, 1, 1, 0, 1, 0, 0.5]);
+
+/**
+ * Synthesizes the foliage `Geometry` for a given LOD from a `FoliageAttachmentSet`,
+ * applying golden-ratio low-discrepancy LOD decimation ($h_i < k_{\text{keep}}$),
+ * optical area-compensation scaling ($s_{\text{comp}} = k_{\text{keep}}^{-\eta}$),
+ * botanical 3D card geometry (`FoldedVCard`, `CrossCard`, `TriStarCluster`, `RibbedFrond`, `CutoutHull`),
+ * MaxRect-packed ontogenetic variant UV remapping, hemisphere-safe normal puffing,
+ * volumetric canopy AO, and 4-joint skeletal wind skinning.
+ *
+ * Returns `null` if foliage is disabled or `lod_config.foliage_keep_ratio <= 0` or `attachments.count === 0`.
+ *
+ * Vertex colours carry each card's tint divided by `attachments.tint_scale`, so a tint brighter than 1 survives the
+ * `unorm8` encoding: the material drawing these cards sets its `diffuse_color` to `tint_scale` (as `generate_tree`
+ * does for the synthesized material). Each card's `attachments.dryness` rolls it shut, flattens its arch and lets
+ * its tip hang, towards a leaf with no turgor.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {TreeSpeciesConfig} [config]
+ * @param {TreeLODConfig} [lod_config]
+ * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null} [cutout] shape of the atlas the
+ *        cards show, from `make_foliage_material`; `CutoutHull` cards cover whole tiles without it
+ * @param {Geometry} [out]
+ * @returns {Geometry|null}
+ */
+export function tree_mesh_build_foliage(
+	skeleton,
+	attachments,
+	config = new TreeSpeciesConfig(),
+	lod_config = new TreeLODConfig(),
+	cutout = null,
+	out = new Geometry()
+) {
+	const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
+	const lod_cfg = lod_config && lod_config.isTreeLODConfig ? lod_config : TreeLODConfig.from(lod_config);
+	const fol = species.foliage;
+	const keep_ratio = clamp(lod_cfg.foliage_keep_ratio ?? 1.0, 0.0, 1.0);
+	if (!attachments || attachments.count === 0 || keep_ratio <= 0.0) {
+		return null;
+	}
+
+	// Filter active attachment indices by golden-ratio rank
+	const active_indices = [];
+	for (let i = 0; i < attachments.count; i++) {
+		if (attachments.ranks[i] < keep_ratio) {
+			active_indices.push(i);
+		}
+	}
+	if (active_indices.length === 0 && attachments.count > 0) {
+		active_indices.push(0);
+	}
+	const card_count = active_indices.length;
+
+	// Area compensation scale: k_keep^(-eta)
+	const eta = clamp(lod_cfg.foliage_area_compensation_exponent ?? 0.42, 0.0, 0.6);
+	const area_comp = Math.pow(Math.max(0.08, keep_ratio), -eta);
+
+	// Determine effective card type for this LOD
+	let card_type = fol.card_type;
+	if (lod_cfg.simplify_cards) {
+		card_type = FoliageCardType.FoldedVCard;
+	}
+
+	const frond_segs = Math.max(2, fol.frond_segments | 0);
+	let verts_per_card = 6;
+	let tris_per_card = 4;
+
+	switch (card_type) {
+		case FoliageCardType.CrossCard:
+			verts_per_card = 8;
+			tris_per_card = 4;
+			break;
+		case FoliageCardType.TriStarCluster:
+			verts_per_card = 12;
+			tris_per_card = 6;
+			break;
+		case FoliageCardType.RibbedFrond:
+			verts_per_card = 3 * (frond_segs + 1);
+			tris_per_card = 4 * frond_segs;
+			break;
+		case FoliageCardType.CutoutHull:
+			verts_per_card = CUTOUT_HULL_VERTEX_COUNT + 1;
+			tris_per_card = CUTOUT_HULL_VERTEX_COUNT;
+			break;
+		case FoliageCardType.FoldedVCard:
+		default:
+			verts_per_card = 6;
+			tris_per_card = 4;
+			break;
+	}
+
+	const total_vertices = card_count * verts_per_card;
+	const total_indices = card_count * tris_per_card * 3;
+
+	const positions = geometry_obtain_attribute(out, StandardAttributes.Position, 3, total_vertices);
+	const normals = geometry_obtain_attribute(out, StandardAttributes.Normal, 3, total_vertices);
+	const uv0 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates0, 2, total_vertices);
+	const uv1 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates1, 2, total_vertices);
+	const colors = geometry_obtain_attribute(out, StandardAttributes.Color, 3, total_vertices);
+	const joints = geometry_obtain_joints_attribute(out, total_vertices);
+	const weights = geometry_obtain_attribute(out, StandardAttributes.SkinningWeights, 4, total_vertices);
+	const indices = geometry_obtain_index(out, total_indices);
+
+	// every card is the species' tile at its true size, attached where the tile's organ attaches
+	const tiles = foliage_tile_layout(species);
+	const layout = compute_foliage_variant_atlas_layout(tiles.resolution, tiles.variant_count);
+	const uv_rects = layout.uv_rects;
+	const variant_count = layout.variant_count;
+
+	// Hull cards trace the atlas the cards show; without one (a caller's own material) they cover whole tiles
+	const cutout_hulls = cutout !== null && cutout.variant_count === variant_count ? cutout.hulls : null;
+	const hull_source = cutout_hulls ?? WHOLE_TILE_HULL;
+	const hull_mid_v = new Float32Array(cutout_hulls !== null ? variant_count : 1);
+	for (let v = 0; v < hull_mid_v.length; v++) {
+		// the fan's centre on the midrib at the hull's mean height, where the stem keeps it inside the hull
+		let sum_v = 0.0;
+		for (let h = 0; h < CUTOUT_HULL_VERTEX_COUNT; h++) {
+			sum_v += hull_source[(v * CUTOUT_HULL_VERTEX_COUNT + h) * 2 + 1];
+		}
+		hull_mid_v[v] = clamp(sum_v / CUTOUT_HULL_VERTEX_COUNT, tiles.anchor_v + 0.02, tiles.anchor_v + 0.70);
+	}
+
+	// the card's width is the tile's; its length runs from the anchor to the tile's far edge
+	const base_w = tiles.card_size * area_comp;
+	const base_l = tiles.card_size * (1.0 - tiles.anchor_v) * area_comp;
+	const turgid_fold = clamp(fol.fold_angle, 0.0, 0.65);
+	const turgid_arch = fol.arch_height;
+	const turgid_droop = fol.camber_droop;
+	const anchor_u = tiles.anchor_u;
+	const anchor_v = tiles.anchor_v;
+
+	let v_cursor = 0;
+	let i_cursor = 0;
+	let rect_u0 = 0.0;
+	let rect_v0 = 0.0;
+	let rect_u1 = 1.0;
+	let rect_v1 = 1.0;
+
+	/**
+	 * Helper to write a single foliage vertex in card-local coordinates `(x_w, y_u, z_f)`
+	 * and local normal `(nx_w, ny_u, nz_f)`, remapping local `[0, 1]^2` card UVs into the
+	 * card's assigned MaxRect-packed atlas tile `[rect_u0, rect_v0, rect_u1, rect_v1]`.
+	 */
+	const write_card_vertex = (
+		px0, py0, pz0,
+		wx, wy, wz,
+		ux, uy, uz,
+		fx, fy, fz,
+		x_w, y_u, z_f,
+		nx_w, ny_u, nz_f,
+		u_tex, v_tex,
+		flutter_w, phase_w,
+		r_col, g_col, b_col,
+		j0, j1, j2, j3,
+		w0, w1, w2, w3
+	) => {
+		const v3 = v_cursor * 3;
+		const v2 = v_cursor * 2;
+		const v4 = v_cursor * 4;
+
+		positions[v3] = px0 + wx * x_w + ux * y_u + fx * z_f;
+		positions[v3 + 1] = py0 + wy * x_w + uy * y_u + fy * z_f;
+		positions[v3 + 2] = pz0 + wz * x_w + uz * y_u + fz * z_f;
+
+		let gnx = wx * nx_w + ux * ny_u + fx * nz_f;
+		let gny = wy * nx_w + uy * ny_u + fy * nz_f;
+		let gnz = wz * nx_w + uz * ny_u + fz * nz_f;
+		const nl = Math.sqrt(gnx * gnx + gny * gny + gnz * gnz);
+		if (nl > 1e-8) {
+			gnx /= nl;
+			gny /= nl;
+			gnz /= nl;
+		}
+		normals[v3] = gnx;
+		normals[v3 + 1] = gny;
+		normals[v3 + 2] = gnz;
+
+		uv0[v2] = lerp(rect_u0, rect_u1, u_tex);
+		uv0[v2 + 1] = lerp(rect_v0, rect_v1, v_tex);
+
+		uv1[v2] = clamp(flutter_w, 0.0, 1.0);
+		uv1[v2 + 1] = clamp(phase_w, 0.0, 1.0);
+
+		colors[v3] = r_col;
+		colors[v3 + 1] = g_col;
+		colors[v3 + 2] = b_col;
+
+		joints[v4] = j0;
+		joints[v4 + 1] = j1;
+		joints[v4 + 2] = j2;
+		joints[v4 + 3] = j3;
+
+		weights[v4] = w0;
+		weights[v4 + 1] = w1;
+		weights[v4 + 2] = w2;
+		weights[v4 + 3] = w3;
+
+		return v_cursor++;
+	};
+
+	const has_j4 = Boolean(attachments.joints4 && attachments.weights4 && attachments.joints4.length >= attachments.count * 4);
+	const has_variants = Boolean(attachments.variant_indices && attachments.variant_indices.length >= attachments.count);
+	const has_maturities = Boolean(attachments.maturities && attachments.maturities.length >= attachments.count);
+	const has_tints = Boolean(attachments.tints && attachments.tints.length >= attachments.count * 3);
+	const has_dryness = Boolean(attachments.dryness && attachments.dryness.length >= attachments.count);
+	// vertex colours are unorm8: tints over 1 are carried as tint / tint_scale, the material's diffuse_color holding tint_scale
+	const inv_tint_scale = has_tints ? 1.0 / Math.max(1.0, attachments.tint_scale ?? 1.0) : 1.0;
+
+	for (let c = 0; c < card_count; c++) {
+		const att_idx = active_indices[c];
+		const a3 = att_idx * 3;
+		const a2 = att_idx * 2;
+		const a4 = att_idx * 4;
+
+		const px0 = attachments.positions[a3];
+		const py0 = attachments.positions[a3 + 1];
+		const pz0 = attachments.positions[a3 + 2];
+
+		const fx = attachments.forward[a3];
+		const fy = attachments.forward[a3 + 1];
+		const fz = attachments.forward[a3 + 2];
+
+		const ux = attachments.up[a3];
+		const uy = attachments.up[a3 + 1];
+		const uz = attachments.up[a3 + 2];
+
+		const wx = attachments.right[a3];
+		const wy = attachments.right[a3 + 1];
+		const wz = attachments.right[a3 + 2];
+
+		const maturity = has_maturities ? attachments.maturities[att_idx] : 0.5;
+		const v_idx = has_variants
+			? clamp(attachments.variant_indices[att_idx], 0, variant_count - 1)
+			: clamp(Math.floor(maturity * variant_count), 0, variant_count - 1);
+		const r4 = v_idx * 4;
+		rect_u0 = uv_rects[r4];
+		rect_v0 = uv_rects[r4 + 1];
+		rect_u1 = uv_rects[r4 + 2];
+		rect_v1 = uv_rects[r4 + 3];
+
+		const scale = attachments.scales[att_idx];
+		const card_w = base_w * scale;
+		const card_l = base_l * scale;
+		const half_w = card_w * 0.5;
+		const left_w = -card_w * anchor_u;
+		const right_w = card_w * (1.0 - anchor_u);
+
+		const phase = attachments.phases[att_idx];
+		const b_sway = attachments.branch_sway[att_idx];
+
+		const r_col = has_tints ? attachments.tints[a3] * inv_tint_scale : 1.0;
+		const g_col = has_tints ? attachments.tints[a3 + 1] * inv_tint_scale : 1.0;
+		const b_col = has_tints ? attachments.tints[a3 + 2] * inv_tint_scale : 1.0;
+
+		// A drying leaf loses the turgor that holds it open and up: it rolls shut, its arch sags and its tip hangs.
+		// These are the limits a leaf without turgor goes to; the leaf falls before it reaches them.
+		const dry = has_dryness ? attachments.dryness[att_idx] : 0.0;
+		const fold_angle = turgid_fold + (Math.PI * 0.5 - turgid_fold) * dry;
+		const sin_fold = Math.sin(fold_angle);
+		const cos_fold = Math.cos(fold_angle);
+		const arch_h = turgid_arch * (1.0 - dry);
+		const droop = turgid_droop + (1.0 - turgid_droop) * dry;
+
+		const j0 = has_j4 ? attachments.joints4[a4] : attachments.joints[a2];
+		const j1 = has_j4 ? attachments.joints4[a4 + 1] : attachments.joints[a2 + 1];
+		const j2 = has_j4 ? attachments.joints4[a4 + 2] : 0;
+		const j3 = has_j4 ? attachments.joints4[a4 + 3] : 0;
+		const w0 = has_j4 ? attachments.weights4[a4] : attachments.weights[a2];
+		const w1 = has_j4 ? attachments.weights4[a4 + 1] : attachments.weights[a2 + 1];
+		const w2 = has_j4 ? attachments.weights4[a4 + 2] : 0.0;
+		const w3 = has_j4 ? attachments.weights4[a4 + 3] : 0.0;
+
+		const base_v = v_cursor;
+
+		if (card_type === FoliageCardType.CrossCard) {
+			// Plane 0: horizontal (W, F) with normal +U (since W x F = +U)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, left_w, 0, 0, 0, 1, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, right_w, 0, 0, 0, 1, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, left_w, 0, card_l, 0, 1, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, right_w, 0, card_l, 0, 1, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 2;
+
+			// Plane 1: vertical (-U to +U, F) with normal +W (since (-U) x F = +W)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -left_w, 0, 1, 0, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -right_w, 0, 1, 0, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -left_w, card_l, 1, 0, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -right_w, card_l, 1, 0, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 5;
+			indices[i_cursor++] = base_v + 7;
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 7;
+			indices[i_cursor++] = base_v + 6;
+		} else if (card_type === FoliageCardType.TriStarCluster) {
+			for (let p = 0; p < 3; p++) {
+				const ang = (p * Math.PI) / 3.0;
+				const ca = Math.cos(ang);
+				const sa = Math.sin(ang);
+				const p_left_x = ca * left_w;
+				const p_left_y = sa * left_w;
+				const p_right_x = ca * right_w;
+				const p_right_y = sa * right_w;
+				const pn_x = -sa;
+				const pn_y = ca;
+				const p_base = base_v + p * 4;
+
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_left_x, p_left_y, 0, pn_x, pn_y, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_right_x, p_right_y, 0, pn_x, pn_y, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_left_x, p_left_y, card_l, pn_x, pn_y, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_right_x, p_right_y, card_l, pn_x, pn_y, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+				indices[i_cursor++] = p_base + 0;
+				indices[i_cursor++] = p_base + 1;
+				indices[i_cursor++] = p_base + 3;
+				indices[i_cursor++] = p_base + 0;
+				indices[i_cursor++] = p_base + 3;
+				indices[i_cursor++] = p_base + 2;
+			}
+		} else if (card_type === FoliageCardType.RibbedFrond) {
+			const lift_wing = half_w * sin_fold;
+			const span_w = half_w * cos_fold;
+
+			for (let s = 0; s <= frond_segs; s++) {
+				const t = s / frond_segs;
+				const v_tex = anchor_v + (1.0 - anchor_v) * t;
+				const z_s = t * card_l;
+				const y_spine = card_l * (arch_h * 4.0 * t * (1.0 - t) - droop * t * t);
+				const env_w = Math.sin(Math.PI * (0.12 + 0.82 * t));
+				const w_s = span_w * env_w;
+				const lift_s = lift_wing * env_w;
+				const flutter = clamp(b_sway * 0.3 + 0.7 * t, 0.0, 1.0);
+
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -w_s, y_spine + lift_s, z_s, -sin_fold * 0.35, cos_fold, 0, 0.0, v_tex, flutter, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, y_spine, z_s, 0.0, 1.0, 0, anchor_u, v_tex, flutter * 0.75, phase, r_col * 0.94, g_col * 0.94, b_col * 0.94, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, w_s, y_spine + lift_s, z_s, sin_fold * 0.35, cos_fold, 0, 1.0, v_tex, flutter, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+				if (s > 0) {
+					const r0 = base_v + (s - 1) * 3;
+					const r1 = base_v + s * 3;
+					indices[i_cursor++] = r0 + 0;
+					indices[i_cursor++] = r0 + 1;
+					indices[i_cursor++] = r1 + 1;
+					indices[i_cursor++] = r0 + 0;
+					indices[i_cursor++] = r1 + 1;
+					indices[i_cursor++] = r1 + 0;
+
+					indices[i_cursor++] = r0 + 1;
+					indices[i_cursor++] = r0 + 2;
+					indices[i_cursor++] = r1 + 2;
+					indices[i_cursor++] = r0 + 1;
+					indices[i_cursor++] = r1 + 2;
+					indices[i_cursor++] = r1 + 1;
+				}
+			}
+		} else if (card_type === FoliageCardType.CutoutHull) {
+			// The tile's fitted hull, folded along the midrib u = anchor_u: each half turns about it by fold_angle,
+			// and the card arches and droops along its length like a frond's spine
+			const hull = hull_source;
+			const hull_base = hull_source === cutout_hulls ? v_idx * CUTOUT_HULL_VERTEX_COUNT * 2 : 0;
+			const len_per_v = card_l / (1.0 - anchor_v);
+			const mid_v = hull_mid_v[hull_source === cutout_hulls ? v_idx : 0];
+			const mid_t = clamp((mid_v - anchor_v) * len_per_v / card_l, 0.0, 1.0);
+
+			// midrib vertex, the fan's centre
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz,
+				0.0, card_l * (arch_h * 4.0 * mid_t * (1.0 - mid_t) - droop * mid_t * mid_t), (mid_v - anchor_v) * len_per_v,
+				0, 1, 0, anchor_u, mid_v, lerp(b_sway * 0.25, 1.0, mid_t), phase,
+				r_col * 0.96, g_col * 0.96, b_col * 0.96, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			for (let h = 0; h < CUTOUT_HULL_VERTEX_COUNT; h++) {
+				const u_h = hull[hull_base + h * 2];
+				const v_h = hull[hull_base + h * 2 + 1];
+				const across = (u_h - anchor_u) * card_w;
+				const side = across < 0.0 ? -1.0 : 1.0;
+				const along = (v_h - anchor_v) * len_per_v;
+				const t = clamp(along / card_l, 0.0, 1.0);
+
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz,
+					across * cos_fold,
+					Math.abs(across) * sin_fold + card_l * (arch_h * 4.0 * t * (1.0 - t) - droop * t * t),
+					along,
+					side * -sin_fold * 0.35, cos_fold, 0,
+					u_h, v_h, lerp(b_sway * 0.25, 1.0, t), phase,
+					r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+				// counter-clockwise in (u, v) is counter-clockwise in (W, F), which faces +U
+				indices[i_cursor++] = base_v;
+				indices[i_cursor++] = base_v + 1 + h;
+				indices[i_cursor++] = base_v + 1 + (h + 1) % CUTOUT_HULL_VERTEX_COUNT;
+			}
+		} else {
+			// Default: FoldedVCard (6 vertices, 4 triangles)
+			const lift = half_w * sin_fold;
+			const span = half_w * cos_fold;
+			const tip_droop = -card_l * droop * 0.5;
+			const mid_arch = card_l * arch_h * 0.5;
+
+			// Row 0 (base, z = 0)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift, 0.0, -sin_fold * 0.35, cos_fold, 0, 0.0, anchor_v, b_sway * 0.45, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, 0.0, 0.0, 0.0, 1.0, 0, anchor_u, anchor_v, b_sway * 0.25, phase, r_col * 0.92, g_col * 0.92, b_col * 0.92, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift, 0.0, sin_fold * 0.35, cos_fold, 0, 1.0, anchor_v, b_sway * 0.45, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			// Row 1 (tip, z = card_l)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift + tip_droop, card_l, -sin_fold * 0.35, cos_fold, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, mid_arch + tip_droop, card_l, 0.0, 1.0, 0, anchor_u, 1.0, 0.85, phase, r_col * 0.96, g_col * 0.96, b_col * 0.96, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift + tip_droop, card_l, sin_fold * 0.35, cos_fold, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			// Left wing quad
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 3;
+
+			// Right wing quad
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 2;
+			indices[i_cursor++] = base_v + 5;
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 5;
+			indices[i_cursor++] = base_v + 4;
+		}
+	}
+
+	// Apply volumetric canopy AO and hemisphere-safe normal puffing BEFORE ensureTangents()
+	tree_mesh_apply_canopy_ao(out, skeleton.crown_center, skeleton.crown_radii, {
+		ao_core_darkening: fol.ao_core_darkening ?? 0.35,
+		normal_puffiness: fol.normal_puffiness ?? 0.35,
+		preserve_existing_color: true
+	});
+
+	out.name = `${species.name || "tree"}_foliage_lod${lod_cfg.level}`;
+	out.ensureBounds();
+	out.ensureTangents();
+
+	return out;
+}