@woosh/meep-engine 3.56.0 → 3.57.0

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

@@ -1,569 +1,637 @@
-import { GOLDEN_RATIO } from "../../../core/math/GOLDEN_RATIO.js";
-import { PI2 } from "../../../core/math/PI2.js";
-import { clamp } from "../../../core/math/clamp.js";
-import { lerp } from "../../../core/math/lerp.js";
-import { seededRandom } from "../../../core/math/random/seededRandom.js";
-import { t64_look_rotation } from "../../../engine/ecs/transform/t64_look_rotation.js";
-import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
-import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
-import { CrownEnvelopeType } from "../config/CrownEnvelopeType.js";
-import { PhyllotaxisMode } from "../config/PhyllotaxisMode.js";
-import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
-import { spine_frame_double_reflection } from "../skeleton/spine_frame_double_reflection.js";
-import { tree_mesh_compute_branch_rings } from "./tree_mesh_build_bark.js";
-
-const GOLDEN_CONJUGATE = 1.0 / GOLDEN_RATIO; // ~0.6180339887498949
-const GOLDEN_ANGLE = PI2 / (GOLDEN_RATIO * GOLDEN_RATIO);
-
-const SCRATCH_POS = new Float32Array(3);
-const SCRATCH_TAN = new Float32Array(3);
-const SCRATCH_P0 = new Float32Array(3);
-const SCRATCH_T0 = new Float32Array(3);
-const SCRATCH_R0 = new Float32Array(3);
-const SCRATCH_RMF = new Float64Array(6);
-
-/**
- * Flat typed-array structure holding all phyllotactic foliage attachment points and oriented card frames.
- *
- * @typedef {Object} FoliageAttachmentSet
- * @property {number} count number of foliage attachments
- * @property {Float32Array} positions `count * 3` attachment world/local positions
- * @property {Float32Array} forward `count * 3` unit card length axis F
- * @property {Float32Array} up `count * 3` unit card outward normal U
- * @property {Float32Array} right `count * 3` unit card width axis W = F x U (so W x F = +U)
- * @property {Float32Array} scales `count` per-card size multiplier
- * @property {Float32Array} ranks `count` golden-ratio low-discrepancy decimation rank in [0, 1)
- * @property {Float32Array} phases `count` per-card wind phase in [0, 1)
- * @property {Float32Array} branch_sway `count` parent branch sway weight in [0, 1]
- * @property {Float32Array} color_jitter `count` per-card luminance/tint jitter in [-1, 1]
- * @property {Float32Array} maturities `count` per-card ontogenetic leaf maturity in [0, 1] (0 = juvenile tip, 1 = mature base)
- * @property {Float32Array} sun_exposure `count` per-card canopy solar irradiance exposure in [0, 1]
- * @property {Uint8Array} variant_indices `count` assigned foliage atlas variant index in `[0, variant_count - 1]`
- * @property {Uint16Array} joints `count * 2` `[j_primary, j_parent]`
- * @property {Float32Array} weights `count * 2` `[w_primary, w_parent]`
- */
-
-/**
- * Generates phyllotactic foliage card attachment transforms along all eligible branches of a `TreeSkeleton`.
- *
- * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
- * @param {TreeSpeciesConfig} [config]
- * @returns {FoliageAttachmentSet}
- */
-export function foliage_collect_attachments(skeleton, config = new TreeSpeciesConfig()) {
-	const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
-	const fol = species.foliage;
-	if (!fol.enabled || skeleton.branch_count === 0) {
-		return {
-			count: 0,
-			transforms: [],
-			positions: new Float32Array(0),
-			forward: new Float32Array(0),
-			up: new Float32Array(0),
-			right: new Float32Array(0),
-			scales: new Float32Array(0),
-			ranks: new Float32Array(0),
-			phases: new Float32Array(0),
-			branch_sway: new Float32Array(0),
-			color_jitter: new Float32Array(0),
-			maturities: new Float32Array(0),
-			sun_exposure: new Float32Array(0),
-			variant_indices: new Uint8Array(0),
-			joints: new Uint16Array(0),
-			weights: new Float32Array(0),
-			joints4: new Uint16Array(0),
-			weights4: new Float32Array(0),
-			attr_ranks: Attribute.from(new Float32Array(0), 1, "foliage_ranks"),
-			attr_phases: Attribute.from(new Float32Array(0), 1, "foliage_phases"),
-			attr_branch_sway: Attribute.from(new Float32Array(0), 1, "foliage_branch_sway"),
-			attr_color_jitter: Attribute.from(new Float32Array(0), 1, "foliage_color_jitter"),
-			attr_maturities: Attribute.from(new Float32Array(0), 1, "foliage_maturities"),
-			attr_variant_indices: Attribute.from(new Uint8Array(0), 1, "foliage_variant_indices"),
-			attr_joints: Attribute.from(new Uint16Array(0), 2, "foliage_joints"),
-			attr_weights: Attribute.from(new Float32Array(0), 2, "foliage_weights")
-		};
-	}
-
-	const rng = seededRandom((species.seed ^ 0x5A3C9E17) | 0);
-	const max_existing_level = Math.max(0, species.levels.length - 1);
-	const min_level = Math.min(fol.attach_min_level, max_existing_level);
-	const branch_rings = tree_mesh_compute_branch_rings(skeleton, species, species.lods?.[0]);
-	const variant_count = clamp((species.foliage_material?.variant_count ?? 4) | 0, 1, 16);
-
-	const crown = species.crown;
-	const is_conical_crown = crown.envelope_type === CrownEnvelopeType.Conical;
-	const cx = skeleton.crown_center[0];
-	const cy = skeleton.crown_center[1];
-	const cz = skeleton.crown_center[2];
-	const rx_crown = Math.max(0.5, skeleton.crown_radii[0]);
-	const ry = Math.max(0.5, skeleton.crown_radii[1]);
-	const rz_crown = Math.max(0.5, skeleton.crown_radii[2]);
-	const ref_card_len = Math.max(0.25, fol.card_length);
-
-	// First collect eligible branch edge chains via `skeleton.graph`
-	const eligible_branches = [];
-	for (let b = 0; b < skeleton.branch_count; b++) {
-		const level = skeleton.branch_level[b];
-		if (level < min_level) continue;
-
-		const nodes = [];
-		const edges = [];
-		skeleton.collect_branch_chain(b, nodes, edges);
-		if (edges.length === 0) continue;
-
-		const t_norms = new Array(nodes.length);
-		for (let i = 0; i < nodes.length; i++) {
-			t_norms[i] = skeleton.node_t_norm(nodes[i]);
-		}
-
-		eligible_branches.push({ branch_id: b, level, nodes, edges, t_norms });
-	}
-
-	const lateral_count = Math.max(0, fol.cards_per_branch | 0);
-	const rosette_count = Math.max(0, fol.terminal_rosette_count | 0);
-	const per_branch = lateral_count + rosette_count;
-	const total_count = eligible_branches.length * per_branch;
-
-	/** @type {Transform64[]} */
-	const transforms = new Array(total_count);
-	const positions = new Float32Array(total_count * 3);
-	const forward = new Float32Array(total_count * 3);
-	const up = new Float32Array(total_count * 3);
-	const right = new Float32Array(total_count * 3);
-	const scales = new Float32Array(total_count);
-	const ranks = new Float32Array(total_count);
-	const phases = new Float32Array(total_count);
-	const branch_sway = new Float32Array(total_count);
-	const color_jitter = new Float32Array(total_count);
-	const maturities = new Float32Array(total_count);
-	const sun_exposure = new Float32Array(total_count);
-	const variant_indices = new Uint8Array(total_count);
-	const joints = new Uint16Array(total_count * 2);
-	const weights = new Float32Array(total_count * 2);
-	const joints4 = new Uint16Array(total_count * 4);
-	const weights4 = new Float32Array(total_count * 4);
-
-	let cursor = 0;
-	const bare = clamp(fol.bare_ratio, 0.0, 0.92);
-
-	for (let eb = 0; eb < eligible_branches.length; eb++) {
-		const item = eligible_branches[eb];
-		const level = item.level;
-		const nodes = item.nodes;
-		const edges = item.edges;
-		const t_norms = item.t_norms;
-		const b_rings = branch_rings.get(item.branch_id);
-		const b_len = Math.max(0.12, skeleton.branch_length[item.branch_id]);
-		const shoot_scale = clamp(b_len / (ref_card_len * 0.95), 0.22, 1.0);
-		const t_min = Math.max(bare, t_norms[0]);
-		const t_max = t_norms[t_norms.length - 1];
-		const base_phi = rng() * PI2;
-		const b_phase = skeleton.branch_phase_hash[item.branch_id];
-
-		for (let k = 0; k < per_branch; k++) {
-			const is_rosette = k >= lateral_count;
-			let t_attach = 1.0;
-
-			if (!is_rosette && lateral_count > 0) {
-				let u_k = (k + 0.5) / lateral_count;
-				if (fol.phyllotaxis_mode === PhyllotaxisMode.Opposite
-					|| fol.phyllotaxis_mode === PhyllotaxisMode.OppositeDecussate) {
-					const pair_idx = k >> 1;
-					const pair_total = Math.max(1, Math.ceil(lateral_count / 2));
-					u_k = (pair_idx + 0.5) / pair_total;
-				} else if (fol.phyllotaxis_mode === PhyllotaxisMode.Whorled) {
-					const w_size = Math.max(1, fol.whorl_count | 0);
-					const w_idx = Math.floor(k / w_size);
-					const w_total = Math.max(1, Math.ceil(lateral_count / w_size));
-					u_k = (w_idx + 0.5) / w_total;
-				}
-				t_attach = clamp(lerp(t_min, t_max * 0.92, u_k), t_min, t_max * 0.95);
-			} else {
-				const ros_idx = k - lateral_count;
-				const u_ros = (ros_idx + 0.5) / Math.max(1, rosette_count);
-				t_attach = clamp(lerp(Math.max(t_min, t_max * 0.88), t_max * 0.96, u_ros), t_min, t_max * 0.96);
-			}
-
-			// Locate segment containing t_attach
-			let seg_idx = edges.length - 1;
-			for (let s = 0; s < edges.length; s++) {
-				if (t_attach >= t_norms[s] && t_attach <= t_norms[s + 1]) {
-					seg_idx = s;
-					break;
-				}
-			}
-
-			const edge_id = edges[seg_idx];
-			const v0 = nodes[seg_idx];
-			const v1 = nodes[seg_idx + 1];
-			const t0 = t_norms[seg_idx];
-			const t1 = t_norms[seg_idx + 1];
-			const local_u = clamp((t_attach - t0) / Math.max(1e-5, t1 - t0), 0.05, 0.95);
-
-			skeleton.evaluate_segment_position(SCRATCH_POS, 0, edge_id, local_u);
-			skeleton.evaluate_segment_tangent(SCRATCH_TAN, 0, edge_id, local_u);
-			skeleton.node_read_position(SCRATCH_P0, 0, v0);
-			skeleton.node_read_tangent(SCRATCH_T0, 0, v0);
-			skeleton.node_read_frame_r(SCRATCH_R0, 0, v0);
-
-			spine_frame_double_reflection(
-				SCRATCH_RMF, 0,
-				SCRATCH_P0[0], SCRATCH_P0[1], SCRATCH_P0[2],
-				SCRATCH_T0[0], SCRATCH_T0[1], SCRATCH_T0[2],
-				SCRATCH_R0[0], SCRATCH_R0[1], SCRATCH_R0[2],
-				SCRATCH_POS[0], SCRATCH_POS[1], SCRATCH_POS[2],
-				SCRATCH_TAN[0], SCRATCH_TAN[1], SCRATCH_TAN[2]
-			);
-			const rx = SCRATCH_RMF[0], ry_f = SCRATCH_RMF[1], rz = SCRATCH_RMF[2];
-			const sx = SCRATCH_RMF[3], sy_f = SCRATCH_RMF[4], sz = SCRATCH_RMF[5];
-
-			// Phyllotactic angle phi
-			let phi = base_phi;
-			if (is_rosette) {
-				const r_idx = k - lateral_count;
-				phi += (r_idx * PI2) / Math.max(1, rosette_count);
-			} else {
-				switch (fol.phyllotaxis_mode) {
-					case PhyllotaxisMode.AlternateDistichous:
-						phi += k * Math.PI;
-						break;
-					case PhyllotaxisMode.Tristichous:
-						phi += k * (PI2 / 3.0);
-						break;
-					case PhyllotaxisMode.Opposite:
-						phi += (k & 1) * Math.PI;
-						break;
-					case PhyllotaxisMode.OppositeDecussate:
-						phi += (k & 1) * Math.PI + (k >> 1) * (Math.PI * 0.5);
-						break;
-					case PhyllotaxisMode.Whorled: {
-						const w_size = Math.max(1, fol.whorl_count | 0);
-						const w_idx = Math.floor(k / w_size);
-						const sub_idx = k % w_size;
-						phi += (sub_idx * PI2) / w_size + (w_idx * Math.PI) / w_size;
-						break;
-					}
-					case PhyllotaxisMode.SpiralGolden:
-					default:
-						phi += k * GOLDEN_ANGLE;
-						break;
-				}
-			}
-			phi += (rng() * 2.0 - 1.0) * fol.angular_jitter;
-
-			const cos_p = Math.cos(phi);
-			const sin_p = Math.sin(phi);
-			const drx = cos_p * rx + sin_p * sx;
-			const dry = cos_p * ry_f + sin_p * sy_f;
-			const drz = cos_p * rz + sin_p * sz;
-
-			// Anchor card stem origin on the actual meshed bark frustum chord [ra, rb]
-			// and interpolate the carrier frustum's exact 4-slot skinning weights
-			let px = SCRATCH_POS[0];
-			let py = SCRATCH_POS[1];
-			let pz = SCRATCH_POS[2];
-			let seg_tx = SCRATCH_TAN[0];
-			let seg_ty = SCRATCH_TAN[1];
-			let seg_tz = SCRATCH_TAN[2];
-
-			const c4 = cursor * 4;
-			const c2 = cursor * 2;
-
-			if (b_rings && b_rings.length >= 2) {
-				const ring_idx = Math.min(seg_idx, b_rings.length - 2);
-				const ra = b_rings[ring_idx];
-				const rb = b_rings[ring_idx + 1];
-				const xi = clamp((t_attach - ra.t_norm) / Math.max(1e-5, rb.t_norm - ra.t_norm), 0.05, 0.95);
-
-				px = lerp(ra.cx, rb.cx, xi);
-				py = lerp(ra.cy, rb.cy, xi);
-				pz = lerp(ra.cz, rb.cz, xi);
-
-				const dx_seg = rb.cx - ra.cx;
-				const dy_seg = rb.cy - ra.cy;
-				const dz_seg = rb.cz - ra.cz;
-				const seg_len = Math.hypot(dx_seg, dy_seg, dz_seg);
-				if (seg_len > 1e-6) {
-					seg_tx = dx_seg / seg_len;
-					seg_ty = dy_seg / seg_len;
-					seg_tz = dz_seg / seg_len;
-				}
-
-				// Merge 4-slot skinning weights from ra (weight 1 - xi) and rb (weight xi)
-				const merged_j = [-1, -1, -1, -1, -1, -1, -1, -1];
-				const merged_w = [0, 0, 0, 0, 0, 0, 0, 0];
-				let m_count = 0;
-
-				const accumulate_joint = (j_id, w_val) => {
-					if (w_val <= 1e-7) return;
-					for (let m = 0; m < m_count; m++) {
-						if (merged_j[m] === j_id) {
-							merged_w[m] += w_val;
-							return;
-						}
-					}
-					merged_j[m_count] = j_id;
-					merged_w[m_count] = w_val;
-					m_count++;
-				};
-
-				const w_a = 1.0 - xi;
-				const w_b = xi;
-				accumulate_joint(ra.j0, ra.w0 * w_a);
-				accumulate_joint(ra.j1, ra.w1 * w_a);
-				accumulate_joint(ra.j2, ra.w2 * w_a);
-				accumulate_joint(ra.j3, ra.w3 * w_a);
-				accumulate_joint(rb.j0, rb.w0 * w_b);
-				accumulate_joint(rb.j1, rb.w1 * w_b);
-				accumulate_joint(rb.j2, rb.w2 * w_b);
-				accumulate_joint(rb.j3, rb.w3 * w_b);
-
-				// Sort descending by weight and normalize top 4
-				for (let a = 0; a < m_count - 1; a++) {
-					for (let b_sort = a + 1; b_sort < m_count; b_sort++) {
-						if (merged_w[b_sort] > merged_w[a]) {
-							const tw = merged_w[a];
-							merged_w[a] = merged_w[b_sort];
-							merged_w[b_sort] = tw;
-							const tj = merged_j[a];
-							merged_j[a] = merged_j[b_sort];
-							merged_j[b_sort] = tj;
-						}
-					}
-				}
-
-				const top_k = Math.min(4, m_count);
-				let w4_sum = 0.0;
-				for (let s = 0; s < top_k; s++) w4_sum += merged_w[s];
-				const inv_w4 = w4_sum > 1e-7 ? 1.0 / w4_sum : 1.0;
-
-				for (let s = 0; s < 4; s++) {
-					if (s < top_k) {
-						joints4[c4 + s] = merged_j[s];
-						weights4[c4 + s] = merged_w[s] * inv_w4;
-					} else {
-						joints4[c4 + s] = 0;
-						weights4[c4 + s] = 0.0;
-					}
-				}
-
-				// Populate 2-slot legacy joints/weights normalized to sum to 1.0
-				const j_prim = top_k > 0 ? merged_j[0] : 0;
-				const j_par = top_k > 1 ? merged_j[1] : j_prim;
-				const w0_raw = top_k > 0 ? merged_w[0] : 1.0;
-				const w1_raw = top_k > 1 ? merged_w[1] : 0.0;
-				const w2_sum = w0_raw + w1_raw;
-				joints[c2] = j_prim;
-				joints[c2 + 1] = j_par;
-				weights[c2] = w2_sum > 1e-7 ? w0_raw / w2_sum : 1.0;
-				weights[c2 + 1] = w2_sum > 1e-7 ? w1_raw / w2_sum : 0.0;
-			} else {
-				const j_prim = skeleton.node_read_joint(v1, 0);
-				const j_par = skeleton.node_read_joint(v1, 1);
-				const w_prim = j_prim === j_par ? 1.0 : clamp(0.35 + 0.65 * t_attach, 0.0, 1.0);
-				joints[c2] = j_prim;
-				joints[c2 + 1] = j_par;
-				weights[c2] = w_prim;
-				weights[c2 + 1] = 1.0 - w_prim;
-				joints4[c4] = j_prim;
-				joints4[c4 + 1] = j_par;
-				weights4[c4] = w_prim;
-				weights4[c4 + 1] = 1.0 - w_prim;
-			}
-
-			// Outward canopy normal n_canopy from crown center
-			let ncx = px - cx;
-			let ncy = (py - cy) + 0.35 * ry;
-			let ncz = pz - cz;
-			const nc_len = Math.sqrt(ncx * ncx + ncy * ncy + ncz * ncz);
-			if (nc_len > 1e-6) {
-				ncx /= nc_len;
-				ncy /= nc_len;
-				ncz /= nc_len;
-			} else {
-				ncx = 0.0;
-				ncy = 1.0;
-				ncz = 0.0;
-			}
-
-			const h_norm_card = clamp((py - crown.base_height) / Math.max(0.1, crown.height), 0.0, 1.0);
-			const w_apex_spire = is_conical_crown && h_norm_card > 0.72
-				? Math.pow(clamp((h_norm_card - 0.72) / 0.25, 0.0, 1.0), 1.35)
-				: 0.0;
-
-			// Initial card forward axis F along insertion angle from branch frustum tangent toward D_rad
-			const base_ins = is_rosette ? fol.insertion_angle * 0.55 : fol.insertion_angle;
-			const ins_angle = base_ins * (1.0 - 0.65 * w_apex_spire);
-			const cos_a = Math.cos(ins_angle);
-			const sin_a = Math.sin(ins_angle);
-			let fx = cos_a * seg_tx + sin_a * drx;
-			let fy = cos_a * seg_ty + sin_a * dry;
-			let fz = cos_a * seg_tz + sin_a * drz;
-
-			// Blend phototropism (outward/sky), gravitropism (downward droop along -Y), and orthotropic apical candle spire
-			const grav_atten = 1.0 - 0.90 * w_apex_spire;
-			const out_atten = 1.0 - 0.75 * w_apex_spire;
-			fx += fol.phototropism * 0.45 * out_atten * ncx + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35 * out_atten;
-			fy += fol.phototropism * 0.25 * Math.max(0.0, ncy) - fol.gravitropism * 0.85 * grav_atten;
-			fz += fol.phototropism * 0.45 * out_atten * ncz + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35 * out_atten;
-
-			if (w_apex_spire > 1e-4) {
-				const w_spire = clamp(w_apex_spire * (is_rosette ? 0.92 : 0.78), 0.0, 0.94);
-				fx = lerp(fx, -0.15 * ncx, w_spire);
-				fy = lerp(fy, 1.0, w_spire);
-				fz = lerp(fz, -0.15 * ncz, w_spire);
-			}
-
-			const f_len = Math.sqrt(fx * fx + fy * fy + fz * fz);
-			if (f_len > 1e-8) {
-				fx /= f_len;
-				fy /= f_len;
-				fz /= f_len;
-			} else {
-				fx = drx;
-				fy = dry;
-				fz = drz;
-			}
-
-			// Desired card upward normal U: blend of world +Y and outward canopy normal n_canopy
-			let ux = ncx * 0.45;
-			let uy = 0.65 + ncy * 0.35;
-			let uz = ncz * 0.45;
-			// Gram-Schmidt orthogonalize U against F
-			const dot_uf = ux * fx + uy * fy + uz * fz;
-			ux -= dot_uf * fx;
-			uy -= dot_uf * fy;
-			uz -= dot_uf * fz;
-			const u_len = Math.sqrt(ux * ux + uy * uy + uz * uz);
-			if (u_len > 1e-6) {
-				ux /= u_len;
-				uy /= u_len;
-				uz /= u_len;
-			} else {
-				// Fallback perpendicular to F
-				if (Math.abs(fy) < 0.9) {
-					ux = -fz;
-					uy = 0.0;
-					uz = fx;
-				} else {
-					ux = 1.0;
-					uy = 0.0;
-					uz = 0.0;
-				}
-				const d2 = ux * fx + uy * fy + uz * fz;
-				ux -= d2 * fx;
-				uy -= d2 * fy;
-				uz -= d2 * fz;
-				const l2 = Math.sqrt(ux * ux + uy * uy + uz * uz);
-				ux /= l2;
-				uy /= l2;
-				uz /= l2;
-			}
-
-			// Enforce outward/sky hemisphere alignment: dot(U, n_canopy + (0, 0.5, 0)) >= 0
-			if (ux * ncx + uy * (ncy + 0.5) + uz * ncz < 0.0) {
-				ux = -ux;
-				uy = -uy;
-				uz = -uz;
-			}
-
-			// W = F x U so that (W, F) card triangles have face normal W x F = +U!
-			const wx = fy * uz - fz * uy;
-			const wy = fz * ux - fx * uz;
-			const wz = fx * uy - fy * ux;
-
-			const c3 = cursor * 3;
-
-			positions[c3] = px;
-			positions[c3 + 1] = py;
-			positions[c3 + 2] = pz;
-
-			forward[c3] = fx;
-			forward[c3 + 1] = fy;
-			forward[c3 + 2] = fz;
-
-			up[c3] = ux;
-			up[c3 + 1] = uy;
-			up[c3 + 2] = uz;
-
-			right[c3] = wx;
-			right[c3 + 1] = wy;
-			right[c3 + 2] = wz;
-
-			const apex_env_scale = is_conical_crown && h_norm_card > 0.70
-				? lerp(1.0, 0.24, Math.pow(clamp((h_norm_card - 0.70) / 0.28, 0.0, 1.0), 1.15))
-				: 1.0;
-			const scale_var = 1.0 + (rng() * 2.0 - 1.0) * fol.size_variance;
-			const card_scale = Math.max(
-				0.18,
-				scale_var * (is_rosette ? 0.92 : 1.0) * Math.min(shoot_scale, apex_env_scale)
-			);
-			scales[cursor] = card_scale;
-
-			const t64 = new Transform64();
-			t64.setTranslation(px, py, pz);
-			t64_look_rotation(t64, fx, fy, fz, ux, uy, uz);
-			t64.setScaleScalar(card_scale);
-			t64.updateMatrix();
-			transforms[cursor] = t64;
-
-			// Golden-ratio low-discrepancy rank in [0, 1)
-			ranks[cursor] = ((cursor * GOLDEN_CONJUGATE) + b_phase * 0.13) % 1.0;
-			phases[cursor] = (b_phase + k * 0.17) % 1.0;
-			branch_sway[cursor] = clamp((level + t_attach) * 0.28, 0.1, 1.0);
-			const c_jit = rng() * 2.0 - 1.0;
-			color_jitter[cursor] = c_jit;
-
-			// Ontogenetic leaf maturity mu_i in [0, 1]:
-			// Acropetal shoot progression (terminal rosette / distal tip -> 0 juvenile, basal nodes -> 1 mature)
-			// combined with crown shell periphery (outer shell -> younger shoots, inner core -> older shade leaves)
-			const u_shoot = is_rosette
-				? clamp(0.88 + 0.12 * ((k - lateral_count + 0.5) / Math.max(1, rosette_count)), 0.88, 1.0)
-				: clamp((t_attach - t_min) / Math.max(1e-4, t_max * 0.92 - t_min), 0.0, 1.0);
-			const ndx_c = (px - cx) / rx_crown;
-			const ndy_c = (py - cy) / ry;
-			const ndz_c = (pz - cz) / rz_crown;
-			const rho_shell = clamp(Math.sqrt(ndx_c * ndx_c + ndy_c * ndy_c + ndz_c * ndz_c), 0.0, 1.0);
-			const maturity = clamp(
-				0.66 * (1.0 - u_shoot) + 0.24 * (1.0 - rho_shell) + 0.05 + 0.07 * c_jit,
-				0.0,
-				1.0
-			);
-			const sun_exp = clamp(0.62 * rho_shell + 0.38 * h_norm_card, 0.0, 1.0);
-			maturities[cursor] = maturity;
-			sun_exposure[cursor] = sun_exp;
-			variant_indices[cursor] = clamp(Math.floor(maturity * variant_count), 0, variant_count - 1);
-
-			cursor++;
-		}
-	}
-
-	return {
-		count: cursor,
-		transforms,
-		positions,
-		forward,
-		up,
-		right,
-		scales,
-		ranks,
-		phases,
-		branch_sway,
-		color_jitter,
-		maturities,
-		sun_exposure,
-		variant_indices,
-		joints,
-		weights,
-		joints4,
-		weights4,
-		attr_ranks: Attribute.from(ranks, 1, "foliage_ranks"),
-		attr_phases: Attribute.from(phases, 1, "foliage_phases"),
-		attr_branch_sway: Attribute.from(branch_sway, 1, "foliage_branch_sway"),
-		attr_color_jitter: Attribute.from(color_jitter, 1, "foliage_color_jitter"),
-		attr_maturities: Attribute.from(maturities, 1, "foliage_maturities"),
-		attr_variant_indices: Attribute.from(variant_indices, 1, "foliage_variant_indices"),
-		attr_joints: Attribute.from(joints, 2, "foliage_joints"),
-		attr_weights: Attribute.from(weights, 2, "foliage_weights")
-	};
-}
+import { GOLDEN_RATIO } from "../../../core/math/GOLDEN_RATIO.js";
+import { PI2 } from "../../../core/math/PI2.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { t64_look_rotation } from "../../../engine/ecs/transform/t64_look_rotation.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
+import { CrownEnvelopeType } from "../config/CrownEnvelopeType.js";
+import { FoliageTileContent } from "../config/FoliageTileContent.js";
+import { PhyllotaxisMode, phyllotaxis_sample_angle } from "../config/PhyllotaxisMode.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { foliage_atlas_cutout } from "../material/foliage_atlas_cutout.js";
+import { spine_frame_double_reflection } from "../skeleton/spine_frame_double_reflection.js";
+import {
+	foliage_cards_per_metre,
+	foliage_leafy_span_start,
+	foliage_shoot_card_scale
+} from "../skeleton/foliage_card_density.js";
+import { foliage_unit_card_spans } from "../skeleton/foliage_unit_cards.js";
+import { foliage_tile_layout } from "../material/foliage_tile.js";
+import {
+	foliage_abscission_threshold,
+	foliage_crown_height_norm,
+	foliage_crown_rho,
+	foliage_leaf_dryness,
+	foliage_leaf_maturity,
+	foliage_leaf_variant,
+	foliage_sun_exposure,
+	foliage_variant_abscission_onset,
+	foliage_variant_maturity
+} from "../skeleton/foliage_senescence.js";
+import { interpolate_ring_skin_weights4 } from "./interpolate_ring_skin_weights4.js";
+import { tree_skeleton_read_joint_motion } from "../skeleton/tree_skeleton_read_joint_motion.js";
+import { tree_mesh_compute_branch_rings } from "./tree_mesh_build_bark.js";
+
+const GOLDEN_CONJUGATE = 1.0 / GOLDEN_RATIO; // ~0.6180339887498949
+const GOLDEN_ANGLE = PI2 / (GOLDEN_RATIO * GOLDEN_RATIO);
+
+const SCRATCH_POS = new Float32Array(3);
+const SCRATCH_TAN = new Float32Array(3);
+const SCRATCH_P0 = new Float32Array(3);
+const SCRATCH_T0 = new Float32Array(3);
+const SCRATCH_R0 = new Float32Array(3);
+const SCRATCH_RMF = new Float64Array(6);
+/** @type {import("../skeleton/foliage_unit_cards.js").FoliageUnitCardSpan[]} */
+const SCRATCH_SPANS = [];
+
+/**
+ * Flat typed-array structure holding all phyllotactic foliage attachment points and oriented card frames.
+ *
+ * @typedef {Object} FoliageAttachmentSet
+ * @property {number} count number of foliage attachments
+ * @property {Uint32Array} carriers `count` skeleton branch carrying each card
+ * @property {Float32Array} positions `count * 3` attachment world/local positions
+ * @property {Float32Array} forward `count * 3` unit card length axis F
+ * @property {Float32Array} up `count * 3` unit card outward normal U
+ * @property {Float32Array} right `count * 3` unit card width axis W = F x U (so W x F = +U)
+ * @property {Float32Array} scales `count` per-card size multiplier
+ * @property {Float32Array} ranks `count` golden-ratio low-discrepancy decimation rank in [0, 1)
+ * @property {Float32Array} phases `count` per-card wind phase in [0, 1)
+ * @property {Float32Array} branch_sway `count` parent branch sway weight in [0, 1]
+ * @property {Float32Array} color_jitter `count` per-card luminance/tint jitter in [-1, 1]
+ * @property {Float32Array} maturities `count` per-card ontogenetic leaf maturity in [0, 1] (0 = juvenile tip, 1 = mature base)
+ * @property {Float32Array} sun_exposure `count` per-card canopy solar irradiance exposure in [0, 1]
+ * @property {Uint8Array} variant_indices `count` assigned foliage atlas tile: its maturity variant in `[0, variant_count - 1]`
+ * @property {Float32Array} dryness `count` how far each still-attached leaf has dried with senescence, `[0, 1)`
+ * @property {Float32Array} tints `count * 3` linear RGB multiplier of each card's albedo; may exceed 1
+ * @property {number} tint_scale the largest tint channel, at least 1: vertex colours carry `tint / tint_scale` so
+ *           they fit `unorm8`, and the foliage material's `diffuse_color` carries `tint_scale` back
+ * @property {Uint16Array} joints `count * 2` `[j_primary, j_parent]`
+ * @property {Float32Array} weights `count * 2` `[w_primary, w_parent]`
+ */
+
+/**
+ * Generates phyllotactic foliage card attachment transforms along every branch whose generator is the
+ * `source` of a `species.foliage_rules` entry, one set of cards per (branch, rule) pair.
+ *
+ * On a branch grown by annual units every leaf is a card, at its own node along its unit, leaving the shoot at the
+ * rule's insertion angle and turned by its phyllotaxis (`foliage_unit_card_spans`); a needle-shoot card lies along
+ * the stretch of shoot it draws. Elsewhere how many cards a carrier gets follows from its leafy length and the card
+ * it carries (`foliage_cards_per_metre`): enough leaf that a line of sight through the shoot's foliage sleeve meets
+ * one leaf on average, rounded with a per-branch dither, so short shoots carry their share on average rather than a
+ * card each.
+ *
+ * With `foliage_material.senescence`, leaves are shed outer and apical first (`foliage_abscission_threshold`); the
+ * cards still attached carry how far they have dried.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {TreeSpeciesConfig} [config]
+ * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout} [cutout] shape of the foliage atlas the
+ *        cards will show; fitted from `config.foliage_material` when omitted
+ * @returns {FoliageAttachmentSet}
+ */
+export function foliage_collect_attachments(skeleton, config = new TreeSpeciesConfig(), cutout) {
+	const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
+	const fol = species.foliage;
+	if (species.foliage_rules.length === 0 || skeleton.branch_count === 0) {
+		return {
+			count: 0,
+			carriers: new Uint32Array(0),
+			transforms: [],
+			positions: new Float32Array(0),
+			forward: new Float32Array(0),
+			up: new Float32Array(0),
+			right: new Float32Array(0),
+			scales: new Float32Array(0),
+			ranks: new Float32Array(0),
+			phases: new Float32Array(0),
+			branch_sway: new Float32Array(0),
+			color_jitter: new Float32Array(0),
+			maturities: new Float32Array(0),
+			sun_exposure: new Float32Array(0),
+			variant_indices: new Uint8Array(0),
+			dryness: new Float32Array(0),
+			tints: new Float32Array(0),
+			tint_scale: 1.0,
+			joints: new Uint16Array(0),
+			weights: new Float32Array(0),
+			joints4: new Uint16Array(0),
+			weights4: new Float32Array(0),
+			attr_ranks: Attribute.from(new Float32Array(0), 1, "foliage_ranks"),
+			attr_phases: Attribute.from(new Float32Array(0), 1, "foliage_phases"),
+			attr_branch_sway: Attribute.from(new Float32Array(0), 1, "foliage_branch_sway"),
+			attr_color_jitter: Attribute.from(new Float32Array(0), 1, "foliage_color_jitter"),
+			attr_maturities: Attribute.from(new Float32Array(0), 1, "foliage_maturities"),
+			attr_variant_indices: Attribute.from(new Uint8Array(0), 1, "foliage_variant_indices"),
+			attr_joints: Attribute.from(new Uint16Array(0), 2, "foliage_joints"),
+			attr_weights: Attribute.from(new Float32Array(0), 2, "foliage_weights")
+		};
+	}
+
+	const rng = seededRandom((species.seed ^ 0x5A3C9E17) | 0);
+	const branch_rings = tree_mesh_compute_branch_rings(skeleton, species, species.lods?.[0]);
+	const layout = foliage_tile_layout(species);
+	const variant_count = layout.variant_count;
+	const needle_shoot = species.foliage_material.tile_content === FoliageTileContent.NeedleShoot;
+
+	const crown = species.crown;
+	const is_conical_crown = crown.envelope_type === CrownEnvelopeType.Conical;
+	const cx = skeleton.crown_center[0];
+	const cy = skeleton.crown_center[1];
+	const cz = skeleton.crown_center[2];
+	const ry = Math.max(0.5, skeleton.crown_radii[1]);
+	const atlas = cutout ?? foliage_atlas_cutout(species);
+	const coverage = atlas.mean_coverage();
+
+	const fol_mat = species.foliage_material;
+	const senescence = clamp(Math.max(fol_mat?.senescence ?? 0.0, fol_mat?.autumn_tint ?? 0.0), 0.0, 1.0);
+	const color_var_amp = clamp(fol.color_variation ?? 0.08, 0.0, 0.35);
+	const juv_shift = clamp(fol_mat?.juvenile_color_shift ?? 0.38, 0.0, 1.0);
+	const antho_pot = clamp(fol_mat?.anthocyanin_potential ?? 0.35, 0.0, 1.0);
+
+	// First collect (carrier branch, foliage rule) pairs with the branch edge chains via `skeleton.graph`
+	const foliage_rules = species.foliage_rules;
+	const eligible_branches = [];
+	let total_count = 0;
+	for (let b = 0; b < skeleton.branch_count; b++) {
+		// dead branches carry no leaves
+		if (skeleton.branch_dead[b]) continue;
+		const generator = skeleton.branch_generator[b];
+		let chain = null;
+
+		for (let r = 0; r < foliage_rules.length; r++) {
+			const rule = foliage_rules[r];
+			if (rule.source !== generator) continue;
+
+			if (chain === null) {
+				const nodes = [];
+				const edges = [];
+				skeleton.collect_branch_chain(b, nodes, edges);
+				const t_norms = new Array(nodes.length);
+				for (let i = 0; i < nodes.length; i++) {
+					t_norms[i] = skeleton.node_t_norm(nodes[i]);
+				}
+				chain = { nodes, edges, t_norms };
+			}
+			if (chain.edges.length === 0) break;
+
+			const t_norms = chain.t_norms;
+			const t_first = t_norms[0];
+			const t_max = t_norms[t_norms.length - 1];
+
+			if (skeleton.branch_unit_count[b] > 0) {
+				// a branch grown by annual units bears leaves on its units young enough to keep them: a leaf at each of
+				// its nodes, spaced along the unit; a needle-shoot card covers a stretch of it from its start and lies
+				// along it
+				foliage_unit_card_spans(skeleton, species, b, rule, layout.leaves_per_card, SCRATCH_SPANS);
+				for (let i = 0; i < SCRATCH_SPANS.length; i++) {
+					const span = SCRATCH_SPANS[i];
+					eligible_branches.push({
+						branch_id: b,
+						level: skeleton.branch_level[b],
+						nodes: chain.nodes,
+						edges: chain.edges,
+						t_norms,
+						t_min: span.t_min,
+						t_max: span.t_max,
+						slot_offset: needle_shoot ? 0.0 : 0.5,
+						shoot_scale: span.scale,
+						insertion_angle: needle_shoot ? 0.0 : rule.insertion_angle,
+						u_from: span.u_min,
+						u_to: span.u_max,
+						count: span.count,
+						rule
+					});
+					total_count += span.count;
+				}
+				break;
+			}
+
+			const t_min = Math.max(foliage_leafy_span_start(rule.attach_min), t_first);
+			const b_len = Math.max(0.12, skeleton.branch_length[b]);
+			const leafy_len = b_len * Math.max(0.0, t_max - t_min) / Math.max(1e-6, t_max - t_first);
+			const shoot_scale = foliage_shoot_card_scale(layout.card_size, b_len);
+			const expected = leafy_len * foliage_cards_per_metre(layout, fol.card_type, coverage, rule.insertion_angle, shoot_scale);
+			// golden-ratio dither per (branch, rule): exact on average, deterministic per branch
+			const dither = (skeleton.branch_phase_hash[b] + r * GOLDEN_CONJUGATE) % 1.0;
+			const count = Math.floor(expected + dither);
+			if (count === 0) continue;
+
+			eligible_branches.push({
+				branch_id: b,
+				level: skeleton.branch_level[b],
+				nodes: chain.nodes,
+				edges: chain.edges,
+				t_norms,
+				t_min,
+				t_max,
+				slot_offset: 0.5,
+				shoot_scale,
+				insertion_angle: rule.insertion_angle,
+				u_from: -1.0,
+				u_to: -1.0,
+				count,
+				rule
+			});
+			total_count += count;
+		}
+	}
+
+	/** @type {Transform64[]} */
+	const transforms = new Array(total_count);
+	const carriers = new Uint32Array(total_count);
+	const positions = new Float32Array(total_count * 3);
+	const forward = new Float32Array(total_count * 3);
+	const up = new Float32Array(total_count * 3);
+	const right = new Float32Array(total_count * 3);
+	const scales = new Float32Array(total_count);
+	const ranks = new Float32Array(total_count);
+	const phases = new Float32Array(total_count);
+	const branch_sway = new Float32Array(total_count);
+	const color_jitter = new Float32Array(total_count);
+	const maturities = new Float32Array(total_count);
+	const sun_exposure = new Float32Array(total_count);
+	const variant_indices = new Uint8Array(total_count);
+	const dryness = new Float32Array(total_count);
+	const tints = new Float32Array(total_count * 3);
+	let tint_scale = 1.0;
+	const joints = new Uint16Array(total_count * 2);
+	const weights = new Float32Array(total_count * 2);
+	const joints4 = new Uint16Array(total_count * 4);
+	const joint_motion = tree_skeleton_read_joint_motion(skeleton);
+	const weights4 = new Float32Array(total_count * 4);
+
+	let cursor = 0;
+
+	for (let eb = 0; eb < eligible_branches.length; eb++) {
+		const item = eligible_branches[eb];
+		const rule = item.rule;
+		const level = item.level;
+		const card_count = item.count;
+		const nodes = item.nodes;
+		const edges = item.edges;
+		const t_norms = item.t_norms;
+		const b_rings = branch_rings.get(item.branch_id);
+		const shoot_scale = item.shoot_scale;
+		const t_min = item.t_min;
+		const t_max = item.t_max;
+		const base_phi = rng() * PI2;
+		const b_phase = skeleton.branch_phase_hash[item.branch_id];
+
+		for (let k = 0; k < card_count; k++) {
+			// nodes evenly spaced over the leafy span, as many leaves at each as the phyllotaxis puts there; a card that
+			// covers a stretch of shoot hangs from that stretch's start
+			const slot_offset = item.slot_offset;
+			let u_k = (k + slot_offset) / card_count;
+			if (rule.phyllotaxis_mode === PhyllotaxisMode.Opposite
+				|| rule.phyllotaxis_mode === PhyllotaxisMode.OppositeDecussate) {
+				const pair_idx = k >> 1;
+				const pair_total = Math.max(1, Math.ceil(card_count / 2));
+				u_k = (pair_idx + slot_offset) / pair_total;
+			} else if (rule.phyllotaxis_mode === PhyllotaxisMode.Whorled) {
+				const w_size = Math.max(1, rule.whorl_count | 0);
+				const w_idx = Math.floor(k / w_size);
+				const w_total = Math.max(1, Math.ceil(card_count / w_size));
+				u_k = (w_idx + slot_offset) / w_total;
+			}
+			const t_attach = lerp(t_min, t_max, u_k);
+
+			// Locate segment containing t_attach
+			let seg_idx = edges.length - 1;
+			for (let s = 0; s < edges.length; s++) {
+				if (t_attach >= t_norms[s] && t_attach <= t_norms[s + 1]) {
+					seg_idx = s;
+					break;
+				}
+			}
+
+			const edge_id = edges[seg_idx];
+			const v0 = nodes[seg_idx];
+			const v1 = nodes[seg_idx + 1];
+			const t0 = t_norms[seg_idx];
+			const t1 = t_norms[seg_idx + 1];
+			const local_u = clamp((t_attach - t0) / Math.max(1e-5, t1 - t0), 0.05, 0.95);
+
+			skeleton.evaluate_segment_position(SCRATCH_POS, 0, edge_id, local_u);
+			skeleton.evaluate_segment_tangent(SCRATCH_TAN, 0, edge_id, local_u);
+			skeleton.node_read_position(SCRATCH_P0, 0, v0);
+			skeleton.node_read_tangent(SCRATCH_T0, 0, v0);
+			skeleton.node_read_frame_r(SCRATCH_R0, 0, v0);
+
+			spine_frame_double_reflection(
+				SCRATCH_RMF, 0,
+				SCRATCH_P0[0], SCRATCH_P0[1], SCRATCH_P0[2],
+				SCRATCH_T0[0], SCRATCH_T0[1], SCRATCH_T0[2],
+				SCRATCH_R0[0], SCRATCH_R0[1], SCRATCH_R0[2],
+				SCRATCH_POS[0], SCRATCH_POS[1], SCRATCH_POS[2],
+				SCRATCH_TAN[0], SCRATCH_TAN[1], SCRATCH_TAN[2]
+			);
+			const rx = SCRATCH_RMF[0], ry_f = SCRATCH_RMF[1], rz = SCRATCH_RMF[2];
+			const sx = SCRATCH_RMF[3], sy_f = SCRATCH_RMF[4], sz = SCRATCH_RMF[5];
+
+			// Phyllotactic angle phi
+			let phi = phyllotaxis_sample_angle(rule.phyllotaxis_mode, k, rule.whorl_count, base_phi);
+			phi += (rng() * 2.0 - 1.0) * fol.angular_jitter;
+
+			const cos_p = Math.cos(phi);
+			const sin_p = Math.sin(phi);
+			const drx = cos_p * rx + sin_p * sx;
+			const dry = cos_p * ry_f + sin_p * sy_f;
+			const drz = cos_p * rz + sin_p * sz;
+
+			// Anchor card stem origin on the actual meshed bark frustum chord [ra, rb]
+			// and interpolate the carrier frustum's exact 4-slot skinning weights
+			let px = SCRATCH_POS[0];
+			let py = SCRATCH_POS[1];
+			let pz = SCRATCH_POS[2];
+			let seg_tx = SCRATCH_TAN[0];
+			let seg_ty = SCRATCH_TAN[1];
+			let seg_tz = SCRATCH_TAN[2];
+
+			const c4 = cursor * 4;
+			const c2 = cursor * 2;
+
+			if (b_rings && b_rings.length >= 2) {
+				const ring_idx = Math.min(seg_idx, b_rings.length - 2);
+				const ra = b_rings[ring_idx];
+				const rb = b_rings[ring_idx + 1];
+				const xi = clamp((t_attach - ra.t_norm) / Math.max(1e-5, rb.t_norm - ra.t_norm), 0.05, 0.95);
+
+				px = lerp(ra.cx, rb.cx, xi);
+				py = lerp(ra.cy, rb.cy, xi);
+				pz = lerp(ra.cz, rb.cz, xi);
+
+				const dx_seg = rb.cx - ra.cx;
+				const dy_seg = rb.cy - ra.cy;
+				const dz_seg = rb.cz - ra.cz;
+				const seg_len = Math.hypot(dx_seg, dy_seg, dz_seg);
+				if (seg_len > 1e-6) {
+					seg_tx = dx_seg / seg_len;
+					seg_ty = dy_seg / seg_len;
+					seg_tz = dz_seg / seg_len;
+				}
+
+				// Merge 4-slot skinning weights from ra (weight 1 - xi) and rb (weight xi)
+				const top_k = interpolate_ring_skin_weights4(joints4, c4, weights4, c4, ra, rb, xi, joint_motion, px, py, pz);
+
+				// Populate 2-slot legacy joints/weights normalized to sum to 1.0
+				const j_prim = joints4[c4];
+				const j_par = top_k > 1 ? joints4[c4 + 1] : j_prim;
+				const w0_raw = weights4[c4];
+				const w1_raw = top_k > 1 ? weights4[c4 + 1] : 0.0;
+				const w2_sum = w0_raw + w1_raw;
+				joints[c2] = j_prim;
+				joints[c2 + 1] = j_par;
+				weights[c2] = w2_sum > 1e-7 ? w0_raw / w2_sum : 1.0;
+				weights[c2 + 1] = w2_sum > 1e-7 ? w1_raw / w2_sum : 0.0;
+			} else {
+				const j_prim = skeleton.node_read_joint(v1, 0);
+				const j_par = skeleton.node_read_joint(v1, 1);
+				const w_prim = j_prim === j_par ? 1.0 : clamp(0.35 + 0.65 * t_attach, 0.0, 1.0);
+				joints[c2] = j_prim;
+				joints[c2 + 1] = j_par;
+				weights[c2] = w_prim;
+				weights[c2 + 1] = 1.0 - w_prim;
+				joints4[c4] = j_prim;
+				joints4[c4 + 1] = j_par;
+				weights4[c4] = w_prim;
+				weights4[c4 + 1] = 1.0 - w_prim;
+			}
+
+			// Outward canopy normal n_canopy from crown center
+			let ncx = px - cx;
+			let ncy = (py - cy) + 0.35 * ry;
+			let ncz = pz - cz;
+			const nc_len = Math.sqrt(ncx * ncx + ncy * ncy + ncz * ncz);
+			if (nc_len > 1e-6) {
+				ncx /= nc_len;
+				ncy /= nc_len;
+				ncz /= nc_len;
+			} else {
+				ncx = 0.0;
+				ncy = 1.0;
+				ncz = 0.0;
+			}
+
+			const h_norm_card = foliage_crown_height_norm(crown, py);
+			const w_apex_spire = is_conical_crown && h_norm_card > 0.72
+				? Math.pow(clamp((h_norm_card - 0.72) / 0.25, 0.0, 1.0), 1.35)
+				: 0.0;
+
+			// Initial card forward axis F along insertion angle from branch frustum tangent toward D_rad
+			const ins_angle = item.insertion_angle * (1.0 - 0.65 * w_apex_spire);
+			const cos_a = Math.cos(ins_angle);
+			const sin_a = Math.sin(ins_angle);
+			let fx = cos_a * seg_tx + sin_a * drx;
+			let fy = cos_a * seg_ty + sin_a * dry;
+			let fz = cos_a * seg_tz + sin_a * drz;
+
+			// Blend phototropism (outward/sky), gravitropism (downward droop along -Y), and orthotropic apical candle spire
+			const grav_atten = 1.0 - 0.90 * w_apex_spire;
+			const out_atten = 1.0 - 0.75 * w_apex_spire;
+			fx += fol.phototropism * 0.45 * out_atten * ncx + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35 * out_atten;
+			fy += fol.phototropism * 0.25 * Math.max(0.0, ncy) - fol.gravitropism * 0.85 * grav_atten;
+			fz += fol.phototropism * 0.45 * out_atten * ncz + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35 * out_atten;
+
+			if (w_apex_spire > 1e-4) {
+				const w_spire = clamp(w_apex_spire * 0.78, 0.0, 0.94);
+				fx = lerp(fx, -0.15 * ncx, w_spire);
+				fy = lerp(fy, 1.0, w_spire);
+				fz = lerp(fz, -0.15 * ncz, w_spire);
+			}
+
+			const f_len = Math.sqrt(fx * fx + fy * fy + fz * fz);
+			if (f_len > 1e-8) {
+				fx /= f_len;
+				fy /= f_len;
+				fz /= f_len;
+			} else {
+				fx = drx;
+				fy = dry;
+				fz = drz;
+			}
+
+			// Desired card upward normal U: blend of world +Y and outward canopy normal n_canopy
+			let ux = ncx * 0.45;
+			let uy = 0.65 + ncy * 0.35;
+			let uz = ncz * 0.45;
+			// Gram-Schmidt orthogonalize U against F
+			const dot_uf = ux * fx + uy * fy + uz * fz;
+			ux -= dot_uf * fx;
+			uy -= dot_uf * fy;
+			uz -= dot_uf * fz;
+			const u_len = Math.sqrt(ux * ux + uy * uy + uz * uz);
+			if (u_len > 1e-6) {
+				ux /= u_len;
+				uy /= u_len;
+				uz /= u_len;
+			} else {
+				// Fallback perpendicular to F
+				if (Math.abs(fy) < 0.9) {
+					ux = -fz;
+					uy = 0.0;
+					uz = fx;
+				} else {
+					ux = 1.0;
+					uy = 0.0;
+					uz = 0.0;
+				}
+				const d2 = ux * fx + uy * fy + uz * fz;
+				ux -= d2 * fx;
+				uy -= d2 * fy;
+				uz -= d2 * fz;
+				const l2 = Math.sqrt(ux * ux + uy * uy + uz * uz);
+				ux /= l2;
+				uy /= l2;
+				uz /= l2;
+			}
+
+			// Enforce outward/sky hemisphere alignment: dot(U, n_canopy + (0, 0.5, 0)) >= 0
+			if (ux * ncx + uy * (ncy + 0.5) + uz * ncz < 0.0) {
+				ux = -ux;
+				uy = -uy;
+				uz = -uz;
+			}
+
+			// W = F x U so that (W, F) card triangles have face normal W x F = +U!
+			const wx = fy * uz - fz * uy;
+			const wy = fz * ux - fx * uz;
+			const wz = fx * uy - fy * ux;
+
+			const c3 = cursor * 3;
+
+			carriers[cursor] = item.branch_id;
+
+			positions[c3] = px;
+			positions[c3 + 1] = py;
+			positions[c3 + 2] = pz;
+
+			forward[c3] = fx;
+			forward[c3 + 1] = fy;
+			forward[c3 + 2] = fz;
+
+			up[c3] = ux;
+			up[c3 + 1] = uy;
+			up[c3 + 2] = uz;
+
+			right[c3] = wx;
+			right[c3 + 1] = wy;
+			right[c3 + 2] = wz;
+
+			const apex_env_scale = is_conical_crown && h_norm_card > 0.70
+				? lerp(1.0, 0.24, Math.pow(clamp((h_norm_card - 0.70) / 0.28, 0.0, 1.0), 1.15))
+				: 1.0;
+			const scale_var = 1.0 + (rng() * 2.0 - 1.0) * fol.size_variance;
+			const card_scale = Math.max(
+				0.18,
+				scale_var * Math.min(shoot_scale, apex_env_scale)
+			);
+			scales[cursor] = card_scale;
+
+			const t64 = new Transform64();
+			t64.setTranslation(px, py, pz);
+			t64_look_rotation(t64, fx, fy, fz, ux, uy, uz);
+			t64.setScaleScalar(card_scale);
+			t64.updateMatrix();
+			transforms[cursor] = t64;
+
+			// Golden-ratio low-discrepancy rank in [0, 1)
+			ranks[cursor] = ((cursor * GOLDEN_CONJUGATE) + b_phase * 0.13) % 1.0;
+			phases[cursor] = (b_phase + k * 0.17) % 1.0;
+			branch_sway[cursor] = clamp((level + t_attach) * 0.28, 0.1, 1.0);
+			const c_jit = rng() * 2.0 - 1.0;
+			color_jitter[cursor] = c_jit;
+
+			// Ontogenetic leaf maturity mu_i in [0, 1]:
+			// Acropetal shoot progression (distal tip -> 0 juvenile, basal nodes -> 1 mature)
+			// combined with crown shell periphery (outer shell -> younger shoots, inner core -> older shade leaves)
+			const u_shoot = item.u_from >= 0.0
+				? lerp(item.u_from, item.u_to, (k + 0.5) / card_count)
+				: clamp((t_attach - t_min) / Math.max(1e-4, t_max - t_min), 0.0, 1.0);
+			const rho_shell = foliage_crown_rho(skeleton, px, py, pz);
+			const maturity = foliage_leaf_maturity(u_shoot, rho_shell, c_jit);
+			const variant = foliage_leaf_variant(maturity, variant_count);
+			const sun_exp = foliage_sun_exposure(rho_shell, h_norm_card);
+
+			// abscission: on its tile's schedule, past its threshold the leaf has fallen
+			const onset = foliage_variant_abscission_onset(foliage_variant_maturity(variant, variant_count));
+			const threshold = foliage_abscission_threshold(onset, sun_exp, u_shoot);
+			if (senescence >= threshold) {
+				continue;
+			}
+			dryness[cursor] = foliage_leaf_dryness(senescence, onset, threshold);
+
+			// Continuous ontogenetic & crown-shell photoprotective tint, free to brighten as well as darken
+			const c_tint = c_jit * color_var_amp;
+			const juv_lift = (0.5 - maturity) * juv_shift * 0.14;
+			let r_col = Math.max(0.68, 1.0 + c_tint * 1.1 + juv_lift * 0.9);
+			let g_col = Math.max(0.68, 1.0 + c_tint * 0.8 + juv_lift * 1.1);
+			let b_col = Math.max(0.68, 1.0 - c_tint * 0.6 - juv_lift * 0.5);
+			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 = Math.max(0.65, r_col * (1.0 - shade_cool * 0.45 + sun_antho * 0.18));
+				g_col = Math.max(0.55, g_col * (1.0 + shade_cool * 0.15 - sun_antho * 0.35));
+				b_col = Math.max(0.55, b_col * (1.0 - sun_antho * 0.30));
+			}
+			tints[c3] = r_col;
+			tints[c3 + 1] = g_col;
+			tints[c3 + 2] = b_col;
+			tint_scale = Math.max(tint_scale, r_col, g_col, b_col);
+
+			maturities[cursor] = maturity;
+			sun_exposure[cursor] = sun_exp;
+			variant_indices[cursor] = variant;
+
+			cursor++;
+		}
+	}
+
+	// shed leaves leave the arrays longer than the cards that remain: views of what remains
+	const n = cursor;
+	transforms.length = n;
+	const out_ranks = ranks.subarray(0, n);
+	const out_phases = phases.subarray(0, n);
+	const out_branch_sway = branch_sway.subarray(0, n);
+	const out_color_jitter = color_jitter.subarray(0, n);
+	const out_maturities = maturities.subarray(0, n);
+	const out_variant_indices = variant_indices.subarray(0, n);
+	const out_joints = joints.subarray(0, n * 2);
+	const out_weights = weights.subarray(0, n * 2);
+
+	return {
+		count: n,
+		carriers: carriers.subarray(0, n),
+		transforms,
+		positions: positions.subarray(0, n * 3),
+		forward: forward.subarray(0, n * 3),
+		up: up.subarray(0, n * 3),
+		right: right.subarray(0, n * 3),
+		scales: scales.subarray(0, n),
+		ranks: out_ranks,
+		phases: out_phases,
+		branch_sway: out_branch_sway,
+		color_jitter: out_color_jitter,
+		maturities: out_maturities,
+		sun_exposure: sun_exposure.subarray(0, n),
+		variant_indices: out_variant_indices,
+		dryness: dryness.subarray(0, n),
+		tints: tints.subarray(0, n * 3),
+		tint_scale,
+		joints: out_joints,
+		weights: out_weights,
+		joints4: joints4.subarray(0, n * 4),
+		weights4: weights4.subarray(0, n * 4),
+		attr_ranks: Attribute.from(out_ranks, 1, "foliage_ranks"),
+		attr_phases: Attribute.from(out_phases, 1, "foliage_phases"),
+		attr_branch_sway: Attribute.from(out_branch_sway, 1, "foliage_branch_sway"),
+		attr_color_jitter: Attribute.from(out_color_jitter, 1, "foliage_color_jitter"),
+		attr_maturities: Attribute.from(out_maturities, 1, "foliage_maturities"),
+		attr_variant_indices: Attribute.from(out_variant_indices, 1, "foliage_variant_indices"),
+		attr_joints: Attribute.from(out_joints, 2, "foliage_joints"),
+		attr_weights: Attribute.from(out_weights, 2, "foliage_weights")
+	};
+}