@woosh/meep-engine 3.53.0 → 3.54.0

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

@@ -1,502 +1,569 @@
-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 { 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 {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),
-            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_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 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]);
-
-    // 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 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 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 * ry_f * 0 + 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;
-            }
-
-            // Initial card forward axis F along insertion angle from branch frustum tangent toward D_rad
-            const ins_angle = is_rosette ? fol.insertion_angle * 0.55 : fol.insertion_angle;
-            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) and gravitropism (downward droop along -Y)
-            fx += fol.phototropism * 0.45 * ncx + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35;
-            fy += fol.phototropism * 0.25 * Math.max(0.0, ncy) - fol.gravitropism * 0.85;
-            fz += fol.phototropism * 0.45 * ncz + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35;
-
-            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 scale_var = 1.0 + (rng() * 2.0 - 1.0) * fol.size_variance;
-            const card_scale = Math.max(0.25, scale_var * (is_rosette ? 0.92 : 1.0));
-            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);
-            color_jitter[cursor] = rng() * 2.0 - 1.0;
-
-            cursor++;
-        }
-    }
-
-    return {
-        count: cursor,
-        transforms,
-        positions,
-        forward,
-        up,
-        right,
-        scales,
-        ranks,
-        phases,
-        branch_sway,
-        color_jitter,
-        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_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 { 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")
+	};
+}