@woosh/meep-engine 3.60.3 → 3.60.5

package/src/generation/foliage/FOLIAGE_DESIGN.md

@@ -1,547 +0,0 @@
-# Meep Procedural Foliage & Tree Generation System — Architecture & Design Document
-
-## 1. Executive Summary & Architectural Philosophy
-
-This document specifies a production-grade, State-of-the-Art (SotA) procedural tree and foliage generation system for **Meep Engine** (`src/generation/foliage/`), comparable in capability to SpeedTree while engineered from the ground up around Meep's data-oriented, zero-allocation primitives and visibility-buffer (`MeshletGeometry` / `StandardShadeMaterial` / `Prefab`) rendering architecture.
-
-### Core Design Tenets
-1. **Turn-Key Top Layer, Layered Override API Underneath**:
-   - **Top Layer (1-line turn-key)**: `generate_tree({ preset: TreePreset.Oak, seed: 42 })` or `place_tree(scene_context, dataset, { preset: "pine", position: [10, 0, -5] })` produces a complete, multi-LOD, wind-rigged, PBR-materialized tree asset (`TreeAsset` / `SceneBundle` / `Prefab`) with zero external asset files required.
-   - **Mid Layer (Species & Generator Descriptors)**: Declarative `TreeSpeciesConfig`, a branch generator graph (`BranchGeneratorConfig` nodes joined by `BranchSpawnRule` edges, foliage placed by `FoliageSpawnRule`s), `CrownConfig`, `FoliageConfig`, `BarkMaterialConfig`, `FoliageMaterialConfig`, and `TreeWindConfig` with `AnimationCurve` profiles and full JSON serialization.
-   - **Low Layer (Pure Pipeline Passes)**: Composable, allocation-conscious pure functions operating on `Graph` skeletons, `Transform64` node frames, Hermite spine buffers, `PointHashGrid3` crown fields, and `Geometry` / `Attribute` buffers.
-2. **Zero Duplicate Adjacent Infrastructure**:
-   - **Coordinate System**: Strictly Meep's right-handed **Y-up** convention (`Vector3.up = (0, 1, 0)`, ground plane `X-Z`).
-   - **Splines & Profiles**: 3D branch spines are piecewise **Cubic Hermite** segments evaluated via `spline3_hermite` and `spline3_hermite_derivative`. 1D distribution profiles (radius taper modifier, child length scaling, insertion angle, internode density) use Meep's `AnimationCurve` and `Keyframe` (`src/engine/animation/curve/AnimationCurve.js`).
-   - **Topological Skeleton (`Graph` + `Transform64` + `Attribute`)**: The hierarchical branch graph is stored directly in Meep's directed **`Graph`** (`src/core/graph/v2/Graph.js`, using `EdgeDirectionType.Forward` edges from `src/core/graph/Edge.js`), while each node's 3D position, Rotation-Minimizing Frame (`[R, S, T]`), and cross-sectional radius are stored in **`Transform64`** (`src/engine/ecs/transform/Transform64.js`), and per-node / per-segment attributes are packed into **`Attribute`** buffers (`src/shade/renderer/geometry/Attribute.js`). (`BinaryTopology` is a polygonal surface mesh structure with unordered edge vertices and is not contorted into a directed graph.)
-   - **Spatial Acceleration**: Crown competition and space colonization use **`PointHashGrid3`** (`src/core/geom/3d/hash-grid/PointHashGrid3.js`) for zero-allocation $O(N)$ neighborhood queries.
-   - **Math, Noise, & Determinism**: Uses `v3_*`, `quat3_*`, `m4_*`, `aabb3_*`, `tube_frame_transport`, `sdnoise3_array`, `curl_noise_3d`, `seededRandom`, `hash_mix2`, and `hash_mix3`.
-   - **Real-Time Rendering Native to Shade**: Emits `Geometry` and `MeshletGeometry` (`meshlet_geometry_build_from_geometry`), `StandardShadeMaterial` (with procedural `Sampler2D` $\to$ `ShadeImage` $\to$ `ShadeTexture` albedo/normal/ORM synthesis when custom textures are omitted), skeletal `Skin` bindings (`StandardAttributes.SkinningJoints` + `StandardAttributes.SkinningWeights`), GPU fluid-driven `FoliageWindRig`s (`shader_foliage_wind_apply` sampling `GPUSceneWind`), `SceneBundle`s, and compiled `Prefab`s (`prefab_compile`).
-
----
-
-## 2. System Architecture & Pipeline Overview
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                        TOP-LEVEL TURN-KEY API                               │
-│   generate_tree(options) / build_tree_prefab(options) / place_tree(...)     │
-│   Presets: Oak, Pine, Birch, Willow, Maple, Spruce, Palm, Shrub, Fern       │
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-                                       ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ STAGE 1: SKELETON TOPOLOGY & HYBRID GROWTH (Graph + Transform64 + Attribute)│
-│  • Parametric Allometric Growth (Weber & Penn levels 0..L_max)              │
-│  • Crown Envelope SDFs + Space Colonization (PointHashGrid3)                │
-│  • Tropisms (Gravitropism, Phototropism/Heliotropism, Curl/Simplex Gnarl)   │
-│  • Dichotomous/Sympodial Trunk Splitting & Apical Dominance                 │
-│  • Da Vinci / Murray Pipe-Model Cross-Section Accumulation (r_p^α = Σ r_i^α)│
-│  • Rotation-Minimizing Frames (RMF: Double-Reflection + tube_frame_transport)│
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-                     ┌─────────────────┴─────────────────┐
-                     ▼                                   ▼
-┌─────────────────────────────────────────┐ ┌─────────────────────────────────┐
-│ STAGE 2A: BARK & BRANCH MESH SYNTHESIS  │ │ STAGE 2B: PHYLLOTAXIS & FOLIAGE │
-│  • Hermite Spine Sampling (spline3_*)   │ │  • Phyllotactic Node Placement  │
-│  • Root Buttressing & Multi-Lobe Flare  │ │    (Golden Angle 137.5°,        │
-│  • Bark Flutes & Knot Swelling          │ │     Decussate, Opposite, Whorl) │
-│  • Seamless Branch Welding / Collars    │ │  • Heliotropic & Gravitropic    │
-│    (Ray-Cylinder Snap + Normal Slerp)   │ │    Petiole Orientation          │
-│  • Adaptive Ring Collapse (Watertight)  │ │  • Folded V-Cards, Cross-Cards, │
-│  • Quantized Seamless Bark UVs          │ │    Alpha-Tight Hulls, & Fronds  │
-└────────────────────┬────────────────────┘ └────────────────┬────────────────┘
-                     └─────────────────┬─────────────────────┘
-                                       ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ STAGE 3: REAL-TIME SHADING, FLUID WIND SKINNING, & MULTI-LOD COMPILATION    │
-│  • Analytic Canopy AO + Spherized/Puffed Foliage Normals                    │
-│  • Skeletal Joint Extraction (Skin) & Per-Vertex Joint/Weight Binding       │
-│  • GPU Fluid-Driven Foliage Bone Rig (FoliageWindRig + GPUSceneWind)        │
-│  • Multi-LOD Chain (LOD0..LOD3) with Area-Compensated Card Decimation       │
-│  • Procedural PBR Texture & StandardShadeMaterial Synthesis                 │
-│  • MeshletGeometry, SceneBundle, & Prefab Compilation                       │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 3. Core Engine Primitives Leveraged (`Graph`, `Transform64`, `Attribute`)
-
-Rather than contorting `BinaryTopology` (which is a Blender BMesh-style polygonal surface mesh structure with unordered edge endpoints) into a directed graph, the foliage system builds directly on Meep's dedicated graph, transform, and attribute classes:
-
-1. **`Graph` & `Edge` (`src/core/graph/v2/Graph.js`, `src/core/graph/Edge.js`)**:
-   - Represents the directed skeletal topology of the tree (`EdgeDirectionType.Forward` edges `parent_v -> child_v`), connecting both intra-branch Cubic Hermite spine segments and inter-branch lateral attachments into a single rooted arborescence.
-2. **`Transform64` & `t64_look_rotation` (`src/engine/ecs/transform/Transform64.js`, `t64_look_rotation.js`)**:
-   - Stores each skeleton node's and each foliage attachment's 3D position (`translation` at offset `12`), orthonormal Rotation-Minimizing Frame (`rotation` quaternion at offset `16` mapping local $+X \to \mathbf{R}_v$, $+Y \to \mathbf{S}_v$, $+Z \to \mathbf{T}_v$), and cross-sectional radius (`scale` at offset `20`) in a single contiguous 23-float64 buffer.
-3. **`Attribute` (`src/shade/renderer/geometry/Attribute.js`)**:
-   - Stores typed-array per-node, per-segment, and per-attachment channels (`Attribute.from(typedArray, itemSize, name)`) with `AttributeSpec` metadata, versioning, hashing, and deep cloning.
-
----
-
-## 4. Stage 1: Skeleton Topology & Hybrid Growth Engine
-
-### 4.1 `TreeSkeleton` Layout on `Graph`, `Transform64`, and `Attribute`
-A `TreeSkeleton` combines a `Graph<number>` (`skeleton.graph`), an array of `Transform64` node frames (`skeleton.node_transforms`), and typed `Attribute` buffers:
-
-#### Node Transforms & Node `Attribute`s (Skeleton Nodes)
-- **`node_transforms[v]: Transform64`**:
-  - `translation` (`f64[3]` at offset 12): Node 3D position $\mathbf{p}_v = (x, y, z)$ with $+Y$ up.
-  - `rotation` (`f64[4]` at offset 16): Unit quaternion orienting local $+X$ (`right`) along RMF radial vector $\mathbf{R}_v$, local $+Y$ (`up`) along binormal $\mathbf{S}_v = \mathbf{T}_v \times \mathbf{R}_v$, and local $+Z$ (`forward`) along unit spine tangent $\mathbf{T}_v$.
-  - `scale` (`f64[3]` at offset 20): Uniform cross-sectional radius $R_v$ at node $v$.
-- **Per-Node `Attribute`s**:
-  - `attr_node_branch_info` (`Int32Array`, `itemSize = 4`): `[branch_id, level, parent_branch_id, in_segment_id]`.
-  - `attr_node_spine_param` (`Float32Array`, `itemSize = 3`): `[t_normalized, arc_length_s, phase_hash]` where $t \in [0, 1]$ is position along the current branch spine, $s$ is cumulative arc length from branch base, and `phase_hash` $\in [0, 1]$ is the deterministic wind phase.
-  - `attr_node_joint` (`Uint16Array`, `itemSize = 2`): `[skin_joint_index, parent_skin_joint_index]` for skeletal wind skinning.
-
-#### Segment `Attribute`s (Cubic Hermite Spine Segments)
-Each Cubic Hermite spine segment $e = (v_0 \to v_1)$ adds a directed `EdgeDirectionType.Forward` edge in `skeleton.graph` and stores:
-- `attr_segment_endpoints` (`Int32Array`, `itemSize = 2`): `[v0, v1]`.
-- `attr_segment_hermite_m0` (`Float32Array`, `itemSize = 3`): Exit tangent vector $\mathbf{m}_0$ at $v_0$ (scaled by chord length $\|\mathbf{p}_{v_1} - \mathbf{p}_{v_0}\|$).
-- `attr_segment_hermite_m1` (`Float32Array`, `itemSize = 3`): Entry tangent vector $\mathbf{m}_1$ at $v_1$ (scaled by chord length).
-- `attr_segment_metrics` (`Float32Array`, `itemSize = 2`): `[segment_length, parent_attach_t]`.
-
-Evaluating any point or derivative at local parameter $u \in [0, 1]$ along edge $e$ directly invokes:
-- `spline3_hermite(u, p0x, p1x, m0x, m1x)` (for $x, y, z$)
-- `spline3_hermite_derivative(u, p0x, p1x, m0x, m1x)` (for $x, y, z$)
-
-### 4.2 Hybrid Parametric + Space-Colonization Growth Algorithm
-A tree grows by one of two front ends (`TreeGrowth`, `generate_tree`'s `growth`; TWO_FRONT_ENDS_BRIEF_2026_10_28.md):
-`TreeGrowth.Graph`, the default, grows the framework below alone (`tree_skeleton_grow_framework`) and draws its species'
-shoot prototypes on its carriers (`tree_shoot_prototypes`, `tree_shoot_instances`): the wood any LOD draws grafted
-onto each carrier, every leaf and twig the prototype's cuts at the tree's error, for most trees;
-`TreeGrowth.Botanical` grows that framework and then every shoot system of `species.shoot_rules` on it
-(`tree_skeleton_grow`, `tree_skeleton_grow_shoots`). The botanical tree's framework is the graph tree, node for node,
-thickened by the shoots it carries. Everything after the skeleton draws both alike. A species is the same for both but
-where the botanical front end grows its framework from shoots: the pine, grown from its seed, has its own graph framework
-(`make_tree_species_preset`'s `growth`).
-
-Branches are grown breadth-first from the trunk (`species.branches[0]`). Every `species.branch_rules` edge
-`source -> target` (always `source < target`, so the graph is acyclic) spawns branches of generator `target` along
-each branch of generator `source`; one generator may spawn several kinds of children (boughs, roots, stubs, sprouts,
-inter-whorl branches) and several generators may spawn the same kind (fan-in). Branching depth $l$ counts lateral
-hops from the trunk; split forks keep their parent's depth and generator.
-1. **Crown Envelope & Space Colonization Field**:
-   - The crown volume is defined by a configurable `CrownEnvelopeType` (`Conical`, `Spherical`, `Hemispherical`, `Cylindrical`, `TaperedCylindrical`, `Flame`, `InverseConical`, `TendFlame`, `Weeping`, or custom `AnimationCurve` profile) centered at $(0, H_{\text{crown}}, 0)$.
-   - When `space_colonization_weight > 0`, $N_{\text{attract}}$ attraction points are sampled deterministically inside the crown envelope using `seededRandom` and indexed in a `PointHashGrid3` with cell size equal to the attraction radius $d_i$.
-2. **Branch Spawn & Phyllotactic Budding**:
-   - Along each parent branch, each outgoing rule spawns its children inside `[attach_min, attach_max]` according to the rule's `PhyllotaxisMode` (`SpiralGolden` $137.507764^\circ$, `AlternateDistichous` $180^\circ$, `OppositeDecussate` $180^\circ + 90^\circ$ flip, `Opposite` $180^\circ$, `Whorled` $360^\circ / M$, `FlareLobes` on the crests of the parent's basal buttress lobes).
-   - Child branch length $L_l(t_p)$ is modulated by the rule's `length_profile: AnimationCurve` and, for rules with `crown_envelope`, the crown envelope $S_{\text{env}}(h_{\text{norm}})$. Children of a rule without `crown_envelope` (roots, trunk sprouts) are neither shrunk by the envelope nor kept inside it.
-   - Self-pruning: below a crown rule's `attach_min` the rule once grew children too, at the same nodes continued down the stem; they died in the crown's shade. Each keeps `(1 - self_pruning) - age` of its length as a dead stub (age 0 just below the living children, 1 at the stem base; size at death `(1 - age)` of today's), and once that no longer clears the bark it is grown over and becomes a bark scar (knot).
-   - Generators with `root` grow structural surface roots: they descend onto the ground plane $y = 0$ and creep along it, add no pipe-model area to their stem, and never receive a wind joint.
-   - Initial child heading $\mathbf{T}_c(0)$ diverges from parent tangent $\mathbf{T}_p(t_p)$ by insertion angle $\alpha_{\text{insert}}(t_p)$ around the azimuth $\phi_k$ in the parent's RMF plane $(\mathbf{R}_p, \mathbf{S}_p)$.
-   - The child's initial RMF normal $\mathbf{R}_c(0)$ is aligned with the adaxial (upper crotch) projection of $\mathbf{T}_p$:
-     $$\mathbf{R}_c(0) = \text{normalize}\big(\mathbf{T}_p - (\mathbf{T}_p \cdot \mathbf{T}_c(0))\mathbf{T}_c(0)\big)$$
-     guaranteeing that $\theta = 0$ on the child's cross-section always lies at the top of the branch collar.
-   - **Dorsiventral parents** (`BranchGeneratorConfig.plagiotropism` $p > 0$, lateral generators only):
-     - **The plane.** A plagiotropic parent bears its buds in the plane of its tangent $\mathbf{T}_p$ and the horizontal
-       $\mathbf{H} = \mathbf{T}_p \times \mathbf{e}_y$ across it. The plane's normal is
-       $\mathbf{N} = \mathbf{H} \times \mathbf{T}_p$, which points up.
-     - **Ventral knockout.** No bud is emitted into the downward cone of half-angle $p\,\pi/2$.
-       - A bud whose own heading points into the cone does not break. That test is about where the bud sits on the
-         bough.
-       - Nor may fanning, or a turn for clearance, carry a bud's emitted heading into the cone. Each such candidate is
-         rejected, and a bud with none left does not break.
-       - Contact projection of a child's first segment can still deflect it in afterwards.
-     - **Fanning.** The surviving buds' radial direction loses $p\,|\mathbf{H}|$ of its component along $\mathbf{N}$,
-       fanning them into the plane. A vertical parent has no such plane, and its children are not fanned.
-     - **Which species.** Plagiotropism follows the species' architectural model (Hallé, Oldeman & Tomlinson's architectural models, as listed by Pfisterer (2000, *Mitt. Biol. Bundesanst.* 370) and Millet, Bouchard & Édelin (1999, *Écoscience* 6: 187–203)):
-       - **Massart's model** (*Picea*, *Abies*): tiers of plagiotropic branches. The spruce preset sets it.
-       - **Rauh's model** (*Pinus*, *Acer*, *Quercus*, *Betula*): branches orthotropic and built like the trunk. Those
-         presets set none.
-       - **Troll's model** (*Fagus*, *Tilia*, *Ulmus*): every axis plagiotropic. Not among the presets.
-       - The knockout is the least sourced part: laterals of a plagiotropic branch lie in its horizontal plane, but no
-         *Picea*-specific source was found for the fate of its ventral buds. On spruce it barely acts, since the buds are
-         already distichous.
-     - **Replaces.** This replaces an undocumented emission rule keyed on the *child's* gravitropism, which biased every
-       lateral's buds upward and off its underside.
-       - **Pads:** its effect was small (oak 0.750 with it, 0.789 without).
-       - **Headings:** its effect was not. Without it, oak has 3.8% of twigs more than 30° below the horizontal against
-         1.4% (mean heading y 0.327 against 0.398), and birch 1.2% against 0.6%.
-       - **No basis:** Rauh-model branches are orthotropic and branch radially, and the positional bias reported for
-         some of them is slight hypotony (lower-side laterals favoured; Millet et al. 1999), not an upward one.
-3. **Stepped Spine Integration with Tropisms, Gnarl, & Splits**:
-   - As segment $k \to k+1$ advances by $\Delta s = L_l / N_{\text{seg}}$:
-     - **Intrinsic curvature**: Pitch rotation around $\mathbf{S}_k$ by $\Delta \theta_{\text{curve}}(t_k)$ and helical twist around $\mathbf{T}_k$.
-     - **Gravitropism (Y-up)**: Bending toward $-\mathbf{e}_y = (0, -1, 0)$ (or $+\mathbf{e}_y$ for negative gravitropism), weighted by mechanical tip compliance $\text{lerp}(0.2, 1.0, t^\gamma)$.
-     - **Phototropism**: Steering toward $\text{normalize}(\alpha_{\text{sky}}\mathbf{e}_y + (1-\alpha_{\text{sky}})\mathbf{d}_{\text{radial}})$ to seek sky light and escape interior crown self-shading.
-     - **Curl / Simplex Gnarl**: 3D divergence-free `curl_noise_3d` (or `sdnoise3_array`) projected perpendicular to $\mathbf{T}_k$.
-     - **Plagiotropism**: a lateral shoot with `plagiotropism` $p$ is steered by $-p\,T_{k,y}\,\mathbf{e}_y$ towards the horizontal. The apical `tip_upcurl` still turns its tip up, so conifer boughs keep their upturned ends.
-     - **Straightness**: `straightness` $\lambda$ adds $\lambda(\mathbf{T}_0 - \mathbf{T}_k)$, a pull back towards the heading the branch was given, so strong gnarl does not carry a branch out of its sector. $\mathbf{T}_0$ is the bud's heading. For the fork that continues a split it becomes the heading the split deflected it to, as the other forks aim along their own. It resists every deviation from that heading, droop included.
-     - **Space Colonization Pull**: Queries `PointHashGrid3.forEachNear` around $\mathbf{p}_k$, pulling $\mathbf{T}_{k+1}$ toward unclaimed attraction points within radius $d_i$ and marking attraction points within kill radius $d_k$ as consumed.
-     - **Sympodial / Dichotomous Forking (`split_probability`, `split_angle`, `split_Spread`)**: At segment $k$, a stem can bifurcate or trifurcate into $M \in \{2, 3\}$ daughter branches that diverge symmetrically in azimuth and pitch.
-     - **RMF Transport**: Advances $(\mathbf{R}_k, \mathbf{S}_k) \to (\mathbf{R}_{k+1}, \mathbf{S}_{k+1})$ via Wang et al. (2008) **Double Reflection** with fallback to `tube_frame_transport`.
-4. **Bottom-Up Pipe-Model Cross-Section Accumulation**:
-   - After all branch levels are generated in `skeleton.graph`, a bottom-up post-order pass accumulates cross-sectional area using the Da Vinci / Murray Pipe Model law:
-     $$R_{\text{pipe}}(v) = \left( R_{\text{tip}}^\alpha + \sum_{e=(v \to u)} R_{\text{pipe}}(u)^\alpha \right)^{1/\alpha}, \quad \alpha \in [2.0, 2.8]$$
-   - The final radius at node $v$ blends the artist-controlled parametric taper curve (`radius_profile: AnimationCurve`) with the physical pipe model via `pipe_model_weight` $\in [0, 1]$.
-5. **Annual Shoot Layer** (`skeleton/tree_skeleton_grow_shoots.js`, `skeleton/shoot_systems_simulate.js`; see
-   `CROWN_FILLING_BRIEF_2026_10_26.md` and `SELF_ORGANIZING_FRAMEWORK_BRIEF_2026_10_26.md`):
-   - **Input.** Each `species.shoot_rules` entry (`ShootSystemRule`, its bud zones `ShootBudZone`) grows the
-     shoot system on every living branch of its `source` generator, after the pipe-model pass. A lateral is a branch
-     of the rule's `target` for its mother's order (short shoots `short_target`), one level below its carrier.
-   - **Time.** The framework is as old as it took to grow at `shoot_growth.leader_growth`; each carrier carries its
-     annual units over its length. The tree grows `max` of that and `shoot_growth.age` seasons. A carrier that
-     stopped growing before then grows on from its tip as an axis of its own order and generator, written onto it, so a
-     tree grown from a seed leader (the pine) is one stem from the ground up. The stem's units are
-     `shoot_growth.leader_unit(height)` (Kellomäki & Kurttio 1991, Eq. 6), not its unit before.
-   - **Each season, tree-wide**, under a voxel light field (`ShootLightField`: leaf area, Beer-Lambert from a standard
-     overcast sky) rebuilt round the crown as it grows:
-     - **Vigour.** The light each axis's tip receives flows down to its carrier and back up, shared at each node with
-       apical control `shoot_growth.apical_control` (Borchert-Honda, as Palubicki et al. 2009); a new unit's mean
-       length is scaled by its axis's vigour relative to the most vigorous. At 0.5 every vigour is 1.
-     - **Extension.** Every living axis grows a terminal unit. Its course turns by phototropism (towards where the
-       light field grows brighter), gravitropism, and a lateral's plagiotropism and straightness; zigzag kinks the unit
-       off the course, not the course. Short shoots survive as their light allows.
-     - **Buds.** Last season's units burst their zones' buds (and this season's, sylleptically). A bud breaks where
-       there is room, else turns by the golden angle round its node.
-     - **Shedding.** A new shoot survives at `net_yield(Q, gross) / gross`, `gross` the yield of the unit it grew on:
-       in full light every shoot is kept, and only shade sheds. A shed axis takes everything on it.
-     - **Wood.** The wood thickens with what it carries (`ShootGirth`): Table 7 (`d = 0.27 + 0.13 age + 0.02 l` cm)
-       for a unit of its age, the pipe model at the species' exponent, and 1 / 0.82 of a lateral where it joins.
-   - **Avoidance** (`ShootFrameworkHash`, `ShootWoodHash`). No unit grows into the ground, through framework wood, or
-     through older shoot wood it does not join: a mother either side of where it grew and over its crotch, a
-     grandmother at its mother's base, a carrier's extension and the carrier's laterals by its tip, and siblings'
-     first units within the collar they share (out of the mother's wood, at least half way). A shoot whose line
-     thicker (or as thick and older) wood has grown into dies; so does a lateral whose tip the wood its mother grew
-     since has closed over, and a carrier its parent has grown over, with its twigs. Graph branches buried by the
-     thickening are dead.
-   - **Leaves pay.** A lateral of a generator that bears no leaves (no foliage rule) does not grow.
-   - **The record.** Every carrier and twig records where each of its annual units starts
-     (`TreeSkeleton.branch_unit_start_t`), for the foliage pass (§6.1).
-
----
-
-## 5. Stage 2A: Bark & Branch Mesh Synthesis
-
-### 5.1 Root Flare, Buttressing, & Fluted Cross-Sections
-At longitudinal spline parameter $t \in [0, 1]$ (arc-length $s$) and cross-sectional azimuth $\theta \in [0, 2\pi)$:
-$$R(t, \theta) = R_{\text{node}}(t) \cdot \Big[ 1 + A_{\text{flare}}(1 - \text{smoothstep}(0, t_{\text{flare}}, t))^{p_{\text{flare}}} \Psi_{\text{lobes}}(\theta, t) + A_{\text{flute}} \sin(k_{\text{flute}}\theta + \omega_{\text{twist}} s) \Big]$$
-where $\Psi_{\text{lobes}}(\theta, t) = \sum_{m=1}^{N_{\text{lobes}}} w_m \max(0, \cos(\theta - \phi_m - \omega_{\text{twist}} t))^{s_{\text{lobe}}}$ creates realistic root buttresses at the base of the trunk ($l = 0$).
-
-### 5.2 Seamless Branch Welding (Collar Blending)
-For any lateral branch ($l \ge 1$) attached to a parent branch of radius $R_p$ at point $\mathbf{x}_p$ with parent axis $\mathbf{T}_p$:
-1. **Collar Ring Projection onto Parent Cylinder**:
-   - For the first $K_{\text{weld}}$ rings ($u = k / K_{\text{weld}} \in [0, 1]$), the base collar radius is flared by `collar_spread_upper` (crotch side $\theta \approx 0$) and `collar_spread_lower` (underside $\theta \approx \pi$).
-   - Each base vertex ($u = 0$) is projected backward along $-\mathbf{T}_{c,0}$ onto the parent branch cylinder surface of radius $R_p$ around axis $\mathbf{T}_p$ (clamped cleanly to $\le 0.92 R_p$ radial offset so wide child branches never miss the parent cylinder).
-   - Intermediate collar rings ($0 < u < 1$) blend via Hermite weight $(1 - u)^2$ between the parent-conforming collar curve and the cylindrical child branch tube.
-2. **Normal Blending ($C^1$ Shading Continuity)**:
-   - At $u = 0$, the vertex normal is set to the parent cylinder's outward radial normal $\mathbf{n}_{\text{parent}}$ at the contact point.
-   - Across $u \in [0, 1]$, the vertex normal is interpolated via spherical/normalized linear blend between $\mathbf{n}_{\text{parent}}$ and the child's analytic tapered tube normal $\mathbf{n}_{\text{child}}$.
-
-### 5.3 Watertight Tessellation at a Geometric Error
-- Each LOD draws the bark to its error $\epsilon$ (`TreeLODConfig.error`, m): a branch is drawn while its wood is at
-  least $\epsilon$ thick and its parent is drawn, and its spine ends where it thins to $\epsilon$.
-- Rings stand where the surface needs them: candidates at every node, every segment's middle and every collar and knot
-  centre are measured all round (spine, radius, lobes, flutes, ovalization, collar bosses, knots, the weld's flare; bark
-  relief is the normal map's), and Douglas-Peucker (`polyline_simplify_by_error`) keeps those the rings either side
-  would miss by more than $\epsilon / 2$.
-- Each kept ring has the fewest sides $M_i$ whose polygon misses none of its measured points, nor its shape at any
-  chord's middle, by more than $\epsilon / 2$; for round wood of radius $R$ that is $R (1 - \cos(\pi / M_i)) \le \epsilon / 2$.
-- Whenever $M_{i+1} < M_i$ between consecutive rings $i$ and $i+1$, a **manifold zippering strip** advances around $\theta \in [0, 2\pi]$ on whichever ring has the smaller next normalized angle $j / M$, emitting $M_i + M_{i+1}$ triangles with **zero T-junctions** and preserving UV seam duplication at $\theta = 0$ and $\theta = 2\pi$.
-- Branch tips are closed with either a tapered apex fan (when $R_{\text{tip}} \le \epsilon$) or a rounded cap.
-
-### 5.4 Quantized Seamless Bark UVs
-- At each branch base, circumferential tile count is quantized to an integer:
-  $$K_{\text{wrap}} = \max\!\left(1, \, \text{round}(2\pi R_0 \cdot \rho_{\text{tex}})\right)$$
-- Vertex $j \in \{0, \dots, M_i\}$ receives $U_{i,j} = K_{\text{wrap}} \cdot (j / M_i) + \tau_{\text{twist}} s_i$, ensuring $U_{i,M_i} - U_{i,0} = K_{\text{wrap}} \in \mathbb{Z}$ (zero vertical texture seam) and $V_i = s_i \cdot \rho_{\text{tex}}$.
-
----
-
-## 6. Stage 2B: Botanical Phyllotaxis & Foliage Synthesis
-
-### 6.1 Phyllotactic Attachment Generator
-Generates `FoliageAttachment` transforms along carrier branches of levels $l \in [l_{\text{min}}, L_{\max}]$:
-- Supports `SpiralGolden` ($137.507764^\circ$), `AlternateDistichous` ($180^\circ$), `Tristichous` ($120^\circ$), `Opposite` ($2\times 180^\circ$), `OppositeDecussate` ($2\times 180^\circ$ with $90^\circ$ alternation), and `Whorled` ($M$ organs per node), with nodes spaced evenly over the carrier's leafy span.
-- **Card density is derived, not authored** (`skeleton/foliage_card_density.js`):
-  - **The sleeve.** A card leaves the shoot at insertion angle $\alpha$ and reaches $L$, so the shoot wears a foliage
-    sleeve of radius $R = L \sin\alpha$.
-  - **One leaf per line of sight.** The carrier holds just enough leaf that a line of sight through that sleeve meets
-    one leaf on average. By Cauchy's formula the sleeve's mean projected area is a quarter of its surface ($2\pi R$ per
-    metre), and a flat leaf's is half its area. So the leaf area is $\pi R$ per metre, and
-    $$n = \frac{\pi \sin\alpha \,(1 - v_a)}{S \, s \, \phi \, P}\ \text{cards per metre}.$$
-    The terms:
-    - $S$ is the side of the species' square card, the size its tile draws its leaf at (`foliage_tile_layout`, §6.3),
-      and $s$ the card scale on that shoot.
-    - $\phi$ is the atlas's measured leaf coverage (`FoliageAtlasCutout.coverage`).
-    - $P$ is the number of planes a card stands up (2 for `CrossCard`, 3 for `TriStarCluster`).
-    - $v_a$ is where the tile's leaf attaches (`FoliageTileLayout.anchor_v`): the card's length spans the tile from
-      there.
-  - **Leafy span.** It starts at the rule's `attach_min`, honoured up to 0.92 (`foliage_leafy_span_start`), for the
-    cards and the sail alike.
-  - **Rounding.** The expected count is rounded with a golden-ratio dither per (branch, rule), so it is exact on
-    average.
-  - **Annual units replace the rule.** A branch that records its annual units (`TreeSkeleton.branch_unit_start_t`,
-    written by the annual shoot layer, §4.2) carries, on each unit, its leaves (`leaves_per_unit + leaves_per_metre L`,
-    times `leaf_survival` at the unit's age; a short shoot `leaves_per_short_shoot` at its tip), in place of the
-    density rule (`foliage_unit_card_spans`).
-    - **A card a leaf.** Each leaf is a card at its own node along the unit, leaving the shoot at the rule's insertion
-      angle and turned by its phyllotaxis. A needle-shoot card draws a stretch of shoot with its needles instead, as
-      many as the shoot bears there, and lies along it.
-    - **Maturity.** Each card draws its own maturity from its branch.
-    - **Wind.** The joint mechanics load the same card on that unit.
-  - **Wind.** The joint mechanics take the same $\pi R$ per metre as the foliage's sail. The wind rig and the cards
-    agree within 0–3.5% on every preset (size variance and length floors).
-- **Abscission and wilt** (`skeleton/foliage_senescence.js`):
-  - **Each tile's onset.** The pigment model ages each atlas tile at its own pace: a tile of maturity $\mu$ is at stage
-    $\sigma_k = \sigma(0.80 + 0.36|\mu - 0.35|) + 0.12\sigma^2$ (`foliage_variant_senescence`), and retains
-    $1 - \sigma_k(1.36 - \text{shielding})$ of its chlorophyll. Its exposed lamina is bare once $\sigma_k = 1/1.36$.
-    `foliage_variant_abscission_onset` solves that for the tree's senescence, $\sigma_0(\mu)$: 0.66 for mature tiles,
-    0.73 for juvenile ones and 0.82 at $\mu = 0.35$. No leaf falls or dries before its own tile's onset.
-  - **Each card's threshold.** After that, exposure orders the fall. A card's threshold
-    $\theta \in [\sigma_0(\mu), 1]$ comes from the mean of its sun exposure ($0.62\,\rho_{\text{shell}} + 0.38\,h_{\text{norm}}$)
-    and its position along its shoot. Outer and apical leaves fall first, and the crown is bare at $\sigma = 1$.
-  - **Dryness.** Between its onset and its fall the card dries: $d = (\sigma - \sigma_0)/(\theta - \sigma_0)$.
-    - The mesh builder takes a folding card (`FoldedVCard`, `RibbedFrond`, `CutoutHull`) towards a leaf with no turgor:
-      the fold closes towards $\pi/2$, the arch goes to 0, and the droop goes to 1. `CrossCard` and `TriStarCluster`
-      have no fold and do not wilt.
-    - A card just before its fall is nearly shut, a valid sliver.
-  - **Wind.** The joint mechanics shed the same leaves from their sail. They judge the expected leaf (no jitter) at each
-    segment's middle.
-- **Heliotropic & Gravitropic Orientation**:
-  - Reorients each leaf/frond basis $(\mathbf{F}, \mathbf{U}, \mathbf{W})$ so its adaxial normal $\mathbf{U}$ tilts toward the sky + canopy-outward light vector (`phototropism` $\in [0, 1]$) while its forward tip $\mathbf{F}$ droops under `gravitropism` $\in [-1, 1]$, with seeded angular jitter to prevent specular aliasing.
-
-### 6.2 Foliage Topologies
-Supports 5 production real-time foliage card/mesh archetypes:
-1. **`FoldedVCard`**: $2 \times 2$ or $2 \times 3$ grid with transverse V-fold angle $\beta_{\text{fold}}$, longitudinal midrib arch $h_{\text{arch}} \sin(\pi v)$, and tip camber $-h_{\text{camber}} v^2$. Never appears razor-flat at grazing view angles.
-2. **`CrossCard` (needle shoot)**: Two orthogonal intersecting V-cards rotated by $90^\circ$ around the shoot axis $\mathbf{F}$; each plane draws the needles in its sector round the shoot (§6.3).
-3. **`TriStarCluster` (needle shoot)**: Three cards arranged at $60^\circ$ star angles, each drawing its sector's needles.
-4. **`RibbedFrond` (Palms, Ferns, Cycads, Weeping Boughs)**: Multi-segment curved Cubic Hermite frond spine with RMF transport, longitudinal V-fold variation, and width profile $W(t) = W_{\max} \sin(\pi t^{p_w})$.
-5. **`CutoutHull` (Fitted Alpha-Bound Card, the broadleaves' leaf)**: the convex hull of everything its atlas tile
-   draws, reduced to 6 vertices and fanned around a midrib vertex.
-   - **Shape.** Each half turns about the midrib by `fold_angle`, and the card arches and droops along its length like
-     a frond spine.
-   - **Fitting.** `make_foliage_material` fits the hulls while it synthesizes the atlas (`FoliageAtlasCutout`):
-     - Each covered texel row contributes the outer corners of its first and last texel that has any alpha.
-     - `convex_hull_monotone_2d` hulls those points.
-     - `convex_hull_fixed_count_2d_relaxation` reduces the hull to 6 vertices inside the tile, inset by half a texel
-       (its `bounds`), so no corner reaches the atlas neighbour.
-     - When no edge can be removed without leaving the tile, the unbounded fit is clipped to the tile
-       (`polygon2_clip_axis_halfplane`) and relaxed again.
-     - If that stalls too, the hull is the silhouette's bounding box as a hexagon. It is looser, but it holds every drawn
-       texel. Clamping the unbounded fit's corners instead would cut the leaf.
-   - **Result.** A willow's lanceolate leaf is cut far tighter than a hazel's broad one (`foliage_atlas_cutout.spec`).
-   - **Custom material.** With a caller's own material, the cards cover whole tiles.
-
-### 6.3 Leaf Architecture and the Atlas Tile
-Every tile draws the species' own leaf at its true size (`material/leaf_geometry.js`, `material/foliage_tile.js`;
-`LEAF_ARCHITECTURE_BRIEF_2026_10_26.md`):
-- **The leaf, as floras describe it** (`LeafArchitecture`, in the terms of Ellis et al. 2009, *Manual of Leaf
-  Architecture*): blade length and length/width ratio, where it is widest, apex and base angles and shapes, pinnate or
-  palmate lobes with their sinus depth, teeth a centimetre and their depth and order, secondary veins and their
-  angle, petiole length; a compound leaf's leaflets and rachis. Each preset cites its flora.
-- **The outline** is a monotone cubic Hermite envelope through the base, the base angle's point a quarter of the way up,
-  the widest point, the apex angle's point and the apex; rounded ends are arcs, acuminate ones concave. A pinnately
-  lobed blade is a body out to the sinus floors plus a rounded lobe along each secondary vein; a palmate one is a lobe
-  per primary vein over a body; teeth are offset along the outline's normal. All contours wind the same way, so
-  `polygon2_rasterize_coverage` fills their union by the nonzero rule with exact coverage across each row.
-- **The tile** draws the mature leaf filling it within a 2% margin, attached at the bottom middle; younger leaves are
-  smaller. The card is that tile at that scale: its size is the leaf's. The resolution draws the leaf's finest feature
-  (a tooth, a sinus) four texels across and its stems two, so they survive the alpha test.
-- **Needle shoots** draw a stretch of shoot as long as a needle, its needles shared among the card's planes, each
-  plane showing those in its sector round the shoot, foreshortened by their azimuth.
-
----
-
-## 7. Stage 3: Shading, Wind Rigging, Materials, & Multi-LODs
-
-### 7.1 Canopy Ambient Occlusion & Spherized Foliage Normals
-- **Per-Vertex Canopy AO (`StandardAttributes.Color`)**:
-  - Combines macro crown ellipsoid depth $AO_{\text{crown}}(\mathbf{v}) \in [AO_{\text{core}}, 1.0]$ with local hierarchy depth $AO_{\text{local}}(v) \in [0.7, 1.0]$ (darkening inner branch crotches and petiole bases while brightening outer sun-exposed tips).
-  - Multiplied with optional per-cluster hue/value jitter in `StandardAttributes.Color` (`vec3<f32>`), which `StandardShadeMaterial` automatically multiplies with `texture_albedo` in the G-buffer pass.
-  - **Tint headroom.** Vertex colours are encoded as `unorm8`, so on their own they can only darken. Each card's tint
-    (`FoliageAttachmentSet.tints`) is free to exceed 1. The builder writes `tint / tint_scale`, where `tint_scale` is
-    the largest tint channel, and the foliage material's `diffuse_color` (the shader's `albedo_color`) carries
-    `tint_scale` back. The product is exactly `albedo · tint · AO`. Across the presets `tint_scale` is about 1.1, and
-    about half of all tint channels exceed 1.
-- **Spherized / Puffed Foliage Normals (`StandardAttributes.Normal`)**:
-  - Blends the geometric card normal $\mathbf{n}_{\text{card}}$ with the canopy-outward normal $\text{normalize}(\mathbf{v} - \mathbf{C}_{\text{crown}})$ by `normal_puffiness` $\in [0, 0.85]$ before running `geometry.ensureTangents()`, giving leaf clusters soft volumetric canopy lighting.
-
-### 7.2 Real-Time Wind Encoding & GPU Fluid-Driven Foliage Bone Animation
-Meep's visibility-buffer renderer (`Shade`) deforms `MeshletGeometry` on the GPU via Remedy / *Alan Wake 2*-style dual-quaternion compute skinning (`GPUAnimationManager` + `GPUMeshSkinningContext`) and publishes a unified 3D fluid dynamics wind field (`GPUSceneWind`, combining `GlobalFluidEffector` far-field wind + gusts and the 3D MAC `GPUFluidCascadeStack` local wakes, vortices, and explosions) samplable on the GPU via `chunk_wind_field_sample` (`wind_field_sample(pos_ws)`). Rather than shipping baked keyframe animation clips, foliage bones are driven directly on the GPU by the fluid dynamics wind field:
-1. **`uv1` Wind Weight Packing (`StandardAttributes.TextureCoordinates1`)**:
-   - Every bark and foliage vertex writes normalized `uv1 = [wind_hierarchy_weight, wind_edge_flutter_weight]` in $[0, 1]^2$ (encoded losslessly to `u16x2` in `MeshletBatch`).
-2. **Skeletal Joint Hierarchy & `Skin` Generation**:
-   - The tree generator maps structural nodes (trunk sections + primary boughs up to a configurable joint budget $J_{\max} \le 64$) to `SceneNode` joints in pre-order.
-   - Every bark and foliage vertex binds up to 4 joints (`StandardAttributes.SkinningJoints`: `Uint16Array(4 * V)`, `StandardAttributes.SkinningWeights`: `Float32Array(4 * V)` summing to $1.0$). A bark ring moves with the joint whose span it is in, alone: a joint turns its whole span about its pivot, as the rig placed it, so the bark is continuous across every pivot (which the joint turning it does not move) and a child's joint pivots where the bark it grows from carries it; between rings the mesh eases a pivot's crease over the ring segment around it. A child's first ring is seated in its parent's bark, carried as that bark carries it, and so is the child's wood before its own first joint. Blending a span with the joints above it, as the weights once did by `t_norm` along the branch, tore the bark at the pivot ending the span (the palm's trunk opened 7.6 cm in the reference wind). Leaves and cluster cards take the weights of the bark where they hang.
-3. **GPU Fluid-Driven Foliage Bone System (`FoliageWindRig` + `shader_foliage_wind_apply` + `GPUSceneWind`)**:
-   - **Data Tables (`ANIMATION_DATABASE_SPEC`)**:
-     - `animation_foliage_rigs` (`ANIMATION_FOLIAGE_RIG_STRUCT`): stores `joints_first`, `joint_count`, `root_node` (`transforms` row of the tree root), and `weight`.
-     - `animation_foliage_joints` (`ANIMATION_FOLIAGE_JOINT_STRUCT`, 64 B / 16 words per bone): stores static physical aeroelastic parameters (`rest_rotation`, unit `branch_axis` $\hat{\mathbf{d}}_j$, Euler-Bernoulli cantilever `compliance` $c_j$, `natural_frequency` $\omega_j$, `damping_ratio` $\zeta_j$, `max_angle` $\theta_{\max,j}$, `turbulence` $\tau_j$, `node`, `rig`) alongside persistent GPU-integrated dynamic state (`angular_displacement` $\boldsymbol{\theta}_j$, `angular_velocity` $\dot{\boldsymbol{\theta}}_j$, `flutter_phase` $\phi_j$).
-   - **GPU Compute Pass (`shader_foliage_wind_apply.js`)**:
-     - Dispatched inside `GPUAnimationManager.tick()` alongside `shader_animation_apply`, binding `scene_context.wind` via `wind_field_add_resources` and `chunk_wind_field_sample` (`WIND_FIELD_UNIFORM` switch).
-     - Reads each bone's world position $\mathbf{p}_{\text{ws}} = \text{joint\_node.global}[3].xyz$, samples the 3D fluid velocity $\mathbf{w}_{\text{ws}} = \text{wind\_field\_sample}(\mathbf{p}_{\text{ws}})$, and transforms $\mathbf{w}_{\text{ws}}$ into the tree root's model space $\mathbf{w}_{\text{model}}$.
-     - Computes cross-flow aerodynamic drag torque $\boldsymbol{\tau}_{\text{drag}} \propto (\hat{\mathbf{d}}_j \times \mathbf{w}_{\text{model}}) \cdot c_j(0.5 + 0.5\|\mathbf{w}_{\text{model}}\|)$ plus Strouhal vortex-shedding oscillation along the orthogonal basis $(\mathbf{e}_1, \mathbf{e}_2) \perp \hat{\mathbf{d}}_j$, with asymptotic soft saturation $\theta_{\max,j} \cdot x / (1 + x)$ so extreme fluid impulses never snap branches past $\theta_{\max,j}$.
-     - Integrates an unconditionally stable implicit 2nd-order damped harmonic spring-damper oscillator ($\ddot{\boldsymbol{\theta}} + 2\zeta\omega\dot{\boldsymbol{\theta}} + \omega^2(\boldsymbol{\theta} - \boldsymbol{\theta}_{\text{target}}) = \mathbf{0}$), writes $(\boldsymbol{\theta}_j, \dot{\boldsymbol{\theta}}_j, \phi_j)$ back to `animation_foliage_joints`, and accumulates the resulting local quaternion into `pose_accumulator` via `pose_accumulator_add_rotation`.
-     - Downstream `shader_animation_pose_resolve` $\to$ `graph_scene_update_transform_hierarchy` $\to$ `shader_skin_matrix_prep` $\to$ `GPUMeshSkinningContext` (dual-quaternion meshlet deformation + BLAS/TLAS BVH refit) executes unchanged with zero scale conflicts.
-
-### 7.3 Procedural PBR `StandardShadeMaterial` Synthesis
-When the caller does not pass `custom_bark_material` or `custom_foliage_material`, the system synthesizes studio-quality procedural PBR textures using `Sampler2D` $\to$ `ShadeImage.fromSampler2D` $\to$ `ShadeTexture.from`. Both are the species', whatever the tree's seed or growth: a `TreeSpeciesCache` passed to `generate_tree` makes a bark material once per `bark_material` and a leaf atlas once per `foliage` and `foliage_material`, and shares them between the trees made alike, each tree tinting a leaf material of its own over the shared atlas.
-1. **`make_bark_material(config)`**:
-   - Generates tileable (`TextureWrapType.Repeat`) bark **Albedo** (fissured ridges, lenticels/stripes for birch, warm heartwood/moss undertones), **Tangent-Space Normal Map** (derived analytically from height gradients), and **ORM Map** (`R`: fissure occlusion, `G`: micro-roughness, `B`: 0 metalness) on a `StandardShadeMaterial` (`TransparencyMode.Opaque`, `ShadeDrawSide.Front`).
-2. **`make_foliage_material(species)`**:
-   - Generates the species' leaf (or needle shoot) **Albedo + Alpha Cutout** texture from its `LeafArchitecture` (§6.3: outline coverage, midvein and secondary veins, petiole, premultiplied RGBA compatible with Shade's `albedo_unpremultiply` and hashed alpha test), **Tangent-Space Normal Map** (camber, vein relief, bullation), and **ORM Map** on a `StandardShadeMaterial` (`TransparencyMode.AlphaTested`, `ShadeDrawSide.Double`, `transmission_factor: 0`).
-
-### 7.4 Multi-LOD Chain
-Each LOD (default 3) is the tree drawn to a geometric error $\epsilon_k$, in metres (`LOD_REWORK_BRIEF_2026_10_27.md`):
-- **Bark** (§5.3): wood at least $\epsilon_k$ thick, its rings and sides as few as keep the surface within it.
-- **Cluster cards for what the wood leaves out.** Each cut is one card (`tree_clusters`, `tree_cluster_cards`): an
-  undrawn branch on drawn wood with everything it carries, or a drawn branch's undrawn tip; a leaf on drawn wood joins
-  its branch's nearest cut. The card lies in the plane what it draws spreads in: its leaves' cards and its twigs' bands,
-  each by its area (the least-spread axis is its normal), facing away from the crown's centre. Where its leaves attach
-  is not enough: a palm's attach along a rachis arching in a vertical plane while they spread to either side. Its depth is not held to the error, as
-  SpeedTree's cluster cards' is not; holding every leaf within the error of a plane needs 12-16 cm before LOD0 fits.
-- **A few tiles for every cut** (`tree_cluster_representatives`): the fewest cuts whose tiles draw every cut of every
-  LOD with its leaves magnified no further than the tree's own leaves vary (the 10th to 90th percentile of their
-  sizes), within the tree's texture ceiling. A cut draws its representative on its own plane, as large as it draws
-  (its leaves' and twigs' area: sized by its extent instead, the shrub's crown lost .12 of its density), hanging where it
-  hangs, turned to run out its way. All of a tree's LODs share the one atlas.
-- **The texel is the leaf's**: the leaf material's own (`FoliageTileLayout.texel`), coarsened by halves only while the
-  cover does not fit the texture ceiling, to what still tells the leaf from another
-  (`FoliageTileLayout.legible_texel`: its outline's finest feature, teeth aside, four texels across, a needle two
-  across its width), and past it only where even that does not fit: a blurred leaf is still the tree's, a tile drawn
-  past the leaves' spread is not (its twigs as thick as boughs); a coarser LOD's representative at the error of the
-  LOD before it, where that one is drawn to a pixel. Tied to the LOD's error, LOD0's leaves were six texels long.
-- **The bake** (`tree_cluster_bake`): each representative's tile is drawn orthographically from the leaves and twigs
-  the tree grew, at its texel, 4x4 samples a texel, back to front in linear light. Every leaf is first pressed
-  onto its card, turned about where it attaches until it lies in the card's plane, so a card shows the leaf area the
-  tree grew whichever way the leaves face; projecting them instead loses half a leaf turned 60 degrees away. Twigs
-  are bands their length by their diameter. Albedo, normal (in the card's frame) and ORM tiles pack into one atlas per
-  LOD (`MaxRectanglesPacker`), each card a 6-vertex hull fitted to its tile's alpha
-  (`foliage_atlas_cutout_fit_alpha`), fanned, 6 triangles. Canopy AO is in the tiles, not the vertices.
-- **The rig per LOD** (`tree_lod_plan`): the joint walk (`tree_skeleton_assign_skin_joints`, §7.2) runs over the
-  wood the LOD draws, no further out than its bark, at a tolerance of `max(deflection_tolerance, eps_k)`: a sway
-  smaller than the shape's error cannot be seen. A coarser LOD places joints only where the finer has one, so a switch
-  keeps the joints both share. A card is skinned as the bark point it hangs from
-  (`interpolate_ring_skin_weights4`); its flutter grows with distance from that point. Each LOD's builders bind its
-  rig (`tree_skeleton_bind_skin_joints`) before meshing.
-- **Each LOD's error from its ceiling** (`tree_lod_plan`): the finest, a half-octave apart from
-  `TREE_LOD_ERROR_FINEST` (1 cm), at which the tree's triangles and its rig's joints per m^2 of what it grew
-  (`tree_grown_side_area`) fit `TREE_RENDER_COST_CEILING` at that LOD, and never finer than the LOD before. The atlas is
-  held to the ceiling's texture bytes per m^2.
-- **The leaves as grown** (`tree_mesh_build_foliage`, every leaf a card) are the reference the bakes draw from and the
-  measures hold the LODs to; no LOD draws them.
-
----
-
-## 8. Module File Organization (`src/generation/foliage/`)
-
-Following Meep's strict one-export-per-file (`PascalCase.js` for classes/enums, `snake_case.js` for pure functions) convention:
-
-```
-src/generation/foliage/
-  config/
-    CrownEnvelopeType.js
-    PhyllotaxisMode.js
-    FoliageCardType.js
-    FoliageBarkType.js
-    TreePreset.js
-    BranchGeneratorConfig.js
-    BranchSpawnRule.js
-    FoliageSpawnRule.js
-    ShootSystemRule.js
-    CrownConfig.js
-    FoliageConfig.js
-    BarkMaterialConfig.js
-    FoliageMaterialConfig.js
-    TreeWindConfig.js
-    TreeLODConfig.js
-    TreeSpeciesConfig.js (+ .spec.js)
-  presets/
-    make_tree_species_preset.js (+ .spec.js)
-  skeleton/
-    TreeSkeleton.js (+ .spec.js)
-    crown_envelope_evaluate.js (+ .spec.js)
-    spine_frame_double_reflection.js (+ .spec.js)
-    tree_skeleton_grow.js (+ .spec.js)
-    tree_skeleton_grow_framework.js
-    tree_skeleton_fit_crown_frame.js
-    tree_skeleton_copy_branches.js (+ .spec.js)
-    tree_skeleton_extend_branch.js
-    tree_skeleton_floor_girth.js
-    tree_skeleton_compute_pipe_radii.js (+ .spec.js)
-    shoot_demography.js (+ .spec.js)
-    tree_skeleton_grow_shoots.js (+ .spec.js)
-    tree_skeleton_assign_skin_joints.js (+ .spec.js)
-    tree_skeleton_bind_skin_joints.js
-    tree_skeleton_grow_growth_modifiers.spec.js
-    foliage_card_density.js
-    foliage_senescence.js
-  mesh/
-    branch_collar_project.js (+ .spec.js)
-    branch_ring_triangulate.js (+ .spec.js)
-    tree_mesh_build_bark.js (+ .spec.js)
-    foliage_collect_attachments.js (+ .spec.js, _density.spec.js)
-    foliage_seasons.spec.js
-    tree_mesh_build_foliage.js (+ .spec.js, _cutout.spec.js)
-    tree_mesh_apply_canopy_ao.js (+ .spec.js)
-    foliage_scale_spread.js
-    tree_clusters.js (+ .spec.js)
-    tree_cluster_cards.js (+ .spec.js)
-    tree_mesh_build_clusters.js
-    tree_cluster_representatives.js (+ .spec.js)
-  material/
-    make_bark_material.js (+ .spec.js)
-    make_foliage_material.js (+ .spec.js)
-    compute_foliage_variant_atlas_layout.js
-    foliage_leaf_silhouette.js
-    FoliageAtlasCutout.js
-    foliage_atlas_cutout.js (+ .spec.js)
-    tree_cluster_bake.js (+ .spec.js)
-    tree_cluster_atlas.js
-    tree_cluster_press.js
-    tree_cluster_tiles.js
-    tree_cluster_atlas_pack.js
-    foliage_material_from_samplers.js
-  animation/
-    build_tree_wind_rig.js (+ .spec.js)
-  asset/
-    TreeLODAsset.js
-    TreeAsset.js
-    TreeSpeciesCache.js (+ .spec.js)
-    tree_shoot_prototypes.js (+ .spec.js)
-    tree_shoot_instances.js (+ .spec.js)
-    tree_lod_plan.js (+ .spec.js)
-    generate_tree.js (+ .spec.js)
-    place_tree.js (+ .spec.js)
-```
-
----
-
-## 9. Adversarial Design Review & Required Revisions
-
-An adversarial audit of §§1–8 against the `packages/meep-engine/src` implementation identified 10 critical invariants and edge cases, all resolved in the final design below:
-
-1. **`Graph`, `Transform64`, and `Attribute` Integration (No `BinaryTopology` Contortion)**:
-   - *Finding*: `BinaryTopology` is a polygonal surface mesh structure with unordered edge endpoints (`v1`, `v2`), not a general-purpose directed graph.
-   - *Resolution*: `TreeSkeleton` uses Meep's directed `Graph` (`src/core/graph/v2/Graph.js`, `EdgeDirectionType.Forward`) for topology, `Transform64` (`src/engine/ecs/transform/Transform64.js`, `t64_look_rotation`) for node 3D positions, RMF bases (`[R, S, T]`), and cross-sectional radii, and `Attribute` (`src/shade/renderer/geometry/Attribute.js`) for per-node and per-segment buffers.
-2. **Deep-Copy Isolation on `TreeSkeleton.copy()` and `clone()`**:
-   - *Finding*: Cloning a `TreeSkeleton` must not alias `Transform64` instances or `Attribute` typed arrays.
-   - *Resolution*: `TreeSkeleton.prototype.copy()` deep-copies `this.graph`, each `Transform64` in `this.node_transforms`, and all node/segment `Attribute` instances via `Attribute.prototype.copy()`.
-3. **`PointHashGrid3` Non-Incremental Rebuild, Static `VISITED` Scratch, & XOR Hash Collisions**:
-   - *Finding*: `PointHashGrid3` uses a module-static `VISITED` array in `forEachNear` (forbidding nested calls) and Teschner XOR hashing (requiring exact distance filtering).
-   - *Resolution*: `tree_skeleton_grow` builds `PointHashGrid3` once with `cell_size = max_attraction_radius`, tracks consumed attraction points in a separate `Uint8Array(N_attract)` `alive` buffer, never nests `forEachNear`, and filters candidates by `alive[idx] === 1` and exact squared distance $d^2 \le r_{\text{attract}}^2$.
-4. **Seeded Noise Offset & Mulberry32 Hash Avalanche**:
-   - *Finding*: `sdnoise3_array` and `curl_noise_3d` are unseeded, and `hash_mix2` / `hash_mix3` (`(a * 31 + b) | 0`) lack bit avalanche if divided directly by $2^{32}$.
-   - *Resolution*: All per-branch/per-node seeds mixed with `hash_mix3` are passed through `seededRandom` (Mulberry32 avalanche) before sampling floats, and all 3D noise evaluations add a seed-derived spatial offset $\mathbf{o}_{\text{seed}} \in [-500, 500]^3$.
-5. **Lazy `MeshletGeometry` / `Prefab` Evaluation & Zero Degenerate Triangles**:
-   - *Finding*: `geometry_to_meshlets_meshoptimizer` asserts `MeshoptClusterizer.ready` (async WASM), and `meshlet_batch_to_bvh` asserts `root === 0`, which fails if `MeshoptClusterizer` strips any index-degenerate triangle (`i0 === i1 || i1 === i2 || i2 === i0`) or if a 0-triangle geometry is clusterized.
-   - *Resolution*:
-     - `TreeLODAsset.bark_meshlet_geometry`, `foliage_meshlet_geometry`, `scene_bundle`, and `prefab` are lazy memoized getters.
-     - `M_min >= 3` is enforced on all branch rings, tapered zero-radius branch tips use an $M$-triangle apex fan (zero degenerate triangles), and empty foliage sets `foliage_meshlet_geometry = null`.
-6. **Branch Collar Projection & Dichotomous Fork Guards**:
-   - *Finding*: Steep insertion angles ($\alpha \to 0^\circ, 180^\circ$) cause `0/0` in $\mathbf{R}_{c,0}$ and unbounded axial ray pullback $\tau \to \infty$; large child radii ($R_c \approx R_p$) bunch vertices if clamped post-flare; terminal dichotomous splits should not project onto the lateral cylinder wall.
-   - *Resolution*: Fall back to `tube_frame_transport` when $\|\mathbf{T}_p - (\mathbf{T}_p \cdot \mathbf{T}_{c,0})\mathbf{T}_{c,0}\|^2 \le 10^{-8}$, clamp axial pullback $|\tau| \le 1.25 R_p$, scale collar flare radius prior to ring emission so $R_{\text{lateral}} \le 0.88 R_p$, and use direct terminal ring blending for terminal splits (`parent_attach_t >= 0.95`).
-7. **Double-Reflection RMF Degeneracy Guards**:
-   - *Finding*: Coincident points ($c_1 \le 10^{-12}$) or pure lateral steps with unchanged tangent ($c_2 \le 10^{-12}$) divide by zero in Wang et al.'s double reflection.
-   - *Resolution*: Guard $c_1 \le 10^{-12}$ via `tube_frame_transport`, and when $c_2 \le 10^{-12}$ treat the second reflection as identity followed by Gram-Schmidt orthonormalization.
-8. **Double-Sided Foliage Backface Normal Negation in `fragment_gbuffer.js`**:
-   - *Finding*: `fragment_gbuffer.js` negates `world_vertex_normal` when `dot(world_face_normal, view_direction) < 0`. Replacing card normals with pure radial crown normals causes back-facing sunlit cards to flip their normal into the dark trunk interior and can trigger Gram-Schmidt tangent singularities when $\mathbf{n} \parallel \mathbf{t}_{\text{uv}}$.
-   - *Resolution*: Orient card front faces outward ($\mathbf{U} \cdot \mathbf{n}_{\text{canopy}} \ge 0$), constrain `normal_puffiness` so $\mathbf{n}_{\text{vertex}} \cdot \mathbf{n}_{\text{face}} \ge 0.55$ (smooth V-fold dome + bounded skyward tilt), and encode macro volumetric crown shading in `StandardAttributes.Color` (`AO_crown * AO_local`).
-9. **`StandardShadeMaterial` & `ShadeTexture` Pipeline Invariants**:
-   - *Finding*: Default `ambient_factors = LinearModifier(1, 1)` saturates `out.ambient` to `>= 1.0`; `transmission_factor > 0` makes cutout card corners cast refractive shadows in the path tracer; `ShadeImage` defaults to `AlphaMode.Straight` (which premultiplies on GPU upload) and `ColorSpace.SRGB`.
-   - *Resolution*: Set `ambient_factors.set(1, 0)` on both materials, keep `transmission_factor = 0` on cutout foliage, write dilated straight RGBA with `AlphaMode.Straight` on foliage albedo, and set `image.color_space = ColorSpace.None`, `image.alpha_mode = AlphaMode.Opaque`, `texture.color_space = ColorSpace.LinearSRGB` on normal and ORM textures.
-10. **Zero-Defect `Skin`, `SceneBundle`, & GPU Fluid-Driven `FoliageWindRig` Playback**:
-    - *Finding*: `prefab_normalize_skin_frames` requires rigid bind frames (`frame_defect === 0`, `residual === 0`) and leaf mesh nodes (`obstructed.length === 0`); shipping baked keyframe wind clips would ignore Meep's 3D fluid dynamics simulation (`GPUSceneWind`); `prefab_place` does not register `FoliageWindRig`s automatically.
-    - *Resolution*: Author `tree_root` (`node 0`), joint nodes (`1..J`) with identity rest rotations `[0, 0, 0, 1]` and exact translation inverse-bind matrices $T(-\mathbf{p}_j)$, and leaf mesh nodes (`parent: 0`, identity local transform) sharing one `Skin`. `build_tree_wind_rig` authors a `FoliageWindRig` whose bones sample `GPUSceneWind` (`chunk_wind_field_sample`) in `shader_foliage_wind_apply`. `place_tree` registers the `FoliageWindRig` on `scene_context.animation_manager` with a position-desynchronized `flutter_phase`, and `unplace_tree` unregisters `foliage_rig_ids` before `prefab_unplace`.
-