@woosh/meep-engine 3.53.0 → 3.54.0

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

@@ -1,415 +1,454 @@
-import { clamp } from "../../../core/math/clamp.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 { 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`),
- * 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 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(species.foliage_material?.stem_anchor_u ?? 0.5, 0.1, 0.9);
-    const anchor_v = clamp(species.foliage_material?.stem_anchor_v ?? 0.0, 0.0, 0.25);
-
-    let v_cursor = 0;
-    let i_cursor = 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)`.
-     */
-    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] = u_tex;
-        uv0[v2 + 1] = 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);
-
-    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 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;
-
-        const r_col = clamp(1.0 + c_jit * 1.1, 0.7, 1.0);
-        const g_col = clamp(1.0 + c_jit * 0.8, 0.7, 1.0);
-        const b_col = clamp(1.0 - c_jit * 0.6, 0.7, 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);
-                // Width vector W_p = ca * W + sa * U; Normal vector N_p = W_p x F = -sa * W + ca * U
-                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);
-
-                // Left wing, center midrib, right wing
-                // Notice: for left wing (x from -w_s to 0, y from y_spine + lift_s to y_spine),
-                // edge (+w_s, -lift_s, 0) x (0, 0, 1) has normal (+lift_s, +w_s, 0) -> (+sin_fold * 0.4, cos_fold, 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;
-                    // Left strip
-                    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;
-                    // Right strip
-                    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/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;
+}