@woosh/meep-engine 3.51.0 → 3.53.0

package/src/engine/sound/simulation/probe/probe_sdf_grid.js

@@ -3,12 +3,12 @@ import { lerp } from "../../../../core/math/lerp.js";
 import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
 
 // Voxel grid is finer than the spacing hint so it resolves sub-`minSpacing` features (thin corridors).
-export const OVERSAMPLE = 2;
+const DEFAULT_OVERSAMPLE = 2;
 // Per-axis voxel resolution is capped so the SDF grid stays bounded (256³ f32 ≈ 64 MB).
-export const RESOLUTION_LIMIT = 256;
+const DEFAULT_RESOLUTION_LIMIT = 256;
 // Open halls get probes at most this multiple of `minSpacing` apart (the sparseness ceiling + the SDF query
 // cutoff — beyond it "very open" is good enough).
-export const DEFAULT_SPARSENESS_RATIO = 4;
+const DEFAULT_SPARSENESS_RATIO = 4;
 
 const ASCENT_ITERATIONS = 5;
 const ASCENT_RATE = 0.2;
@@ -31,16 +31,28 @@ const ASCENT_RATE = 0.2;
 
 /**
  * Build a signed distance field on a voxel grid over `bounds` by sampling
- * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by {@link OVERSAMPLE})
- * so it resolves sub-spacing features, and capped at {@link RESOLUTION_LIMIT}³.
+ * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by `oversample`,
+ * default {@link DEFAULT_OVERSAMPLE}) so it resolves sub-spacing features, and capped at `resolutionLimit`³
+ * (default {@link DEFAULT_RESOLUTION_LIMIT}³).
  *
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {number[]} bounds `[x0,y0,z0,x1,y1,z1]`
- * @param {number} minSpacing the probe spacing hint
- * @param {number} [sparsenessRatio]
+ * @param {Object} options
+ * @param {AcousticOccluderIndex} options.index the acoustic scene
+ * @param {number[]} options.bounds `[x0,y0,z0,x1,y1,z1]`
+ * @param {number} options.minSpacing the probe spacing hint
+ * @param {number} [options.sparsenessRatio]
+ * @param {number} [options.oversample]
+ * @param {number} [options.resolutionLimit]
  * @returns {SdfGrid}
  */
-export function build_sdf_grid(index, bounds, minSpacing, sparsenessRatio = DEFAULT_SPARSENESS_RATIO) {
+export function build_sdf_grid({
+    index,
+    bounds,
+    minSpacing,
+    sparsenessRatio = DEFAULT_SPARSENESS_RATIO,
+    oversample = DEFAULT_OVERSAMPLE,
+    resolutionLimit = DEFAULT_RESOLUTION_LIMIT,
+}) {
+
     const maxSpacing = minSpacing * sparsenessRatio;
 
     const x0 = bounds[0], y0 = bounds[1], z0 = bounds[2];
@@ -48,10 +60,10 @@ export function build_sdf_grid(index, bounds, minSpacing, sparsenessRatio = DEFA
 
     const extX = x1 - x0, extY = y1 - y0, extZ = z1 - z0;
 
-    const voxel = minSpacing / OVERSAMPLE;
-    const rx = clamp(Math.ceil(extX / voxel) + 1, 2, RESOLUTION_LIMIT);
-    const ry = clamp(Math.ceil(extY / voxel) + 1, 2, RESOLUTION_LIMIT);
-    const rz = clamp(Math.ceil(extZ / voxel) + 1, 2, RESOLUTION_LIMIT);
+    const voxel = minSpacing / oversample;
+    const rx = clamp(Math.ceil(extX / voxel) + 1, 2, resolutionLimit);
+    const ry = clamp(Math.ceil(extY / voxel) + 1, 2, resolutionLimit);
+    const rz = clamp(Math.ceil(extZ / voxel) + 1, 2, resolutionLimit);
 
     // actual per-axis voxel size (probe positions lerp over [0, res-1])
     const vsX = extX / (rx - 1);
@@ -76,7 +88,7 @@ export function build_sdf_grid(index, bounds, minSpacing, sparsenessRatio = DEFA
     // "open air" = off any surface by ~½ a NOMINAL voxel. Based on the spacing hint, NOT the actual per-axis
     // voxel size: a degenerate (zero-extent) axis can't zero it, and the resolution cap can't inflate it past
     // maxSpacing (which would reject every voxel).
-    const clearanceFloor = (minSpacing / OVERSAMPLE) * 0.5;
+    const clearanceFloor = (minSpacing / oversample) * 0.5;
 
     return {
         sdf, rx, ry, rz, strideZ, total,
@@ -86,14 +98,31 @@ export function build_sdf_grid(index, bounds, minSpacing, sparsenessRatio = DEFA
     };
 }
 
-/** World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`. */
+/**
+ * World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`.
+ *
+ * @param {SdfGrid} grid
+ * @param {number[]|Float32Array} out `[x,y,z]` written here
+ * @param {number} fx
+ * @param {number} fy
+ * @param {number} fz
+ * @returns {void}
+ */
 export function grid_voxel_to_world(grid, out, fx, fy, fz) {
     out[0] = grid.x0 + fx * grid.vsX;
     out[1] = grid.y0 + fy * grid.vsY;
     out[2] = grid.z0 + fz * grid.vsZ;
 }
 
-/** SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped). */
+/**
+ * SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped).
+ *
+ * @param {SdfGrid} grid
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
+ */
 export function grid_sample_world(grid, x, y, z) {
     const fx = grid.vsX > 0 ? (x - grid.x0) / grid.vsX : 0;
     const fy = grid.vsY > 0 ? (y - grid.y0) / grid.vsY : 0;
@@ -108,6 +137,12 @@ export function grid_sample_world(grid, x, y, z) {
  * {@link scs3d_sample_linear} samples — so the interpolation is delegated rather than re-derived here.
  * (Same clamp semantics: clamping the COORDINATE into `[0, res-1]` and clamping the two sample INDICES
  * agree on every input, including out-of-range coordinates, where both collapse to the edge voxel.)
+ *
+ * @param {SdfGrid} grid
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
  */
 export function grid_sample_trilinear(grid, x, y, z) {
     return scs3d_sample_linear(grid.sdf, grid.rx, grid.ry, grid.rz, x, y, z);
@@ -117,6 +152,13 @@ export function grid_sample_trilinear(grid, x, y, z) {
  * Gradient-ascend a voxel to the local SDF maximum (the most-open sub-voxel point), written into `out` as a
  * fractional voxel coordinate clamped to within ½ voxel of the start. Central-difference gradient on the
  * trilinearly-sampled SDF; the gradient is not normalised, so steps shrink near the maximum.
+ *
+ * @param {number[]|Float32Array} out `[fx,fy,fz]` written here
+ * @param {SdfGrid} grid
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ * @returns {void}
  */
 export function grid_local_maximum(out, grid, vx, vy, vz) {
     const minX = vx - 0.4999, maxX = vx + 0.4999;
@@ -144,6 +186,14 @@ export function grid_local_maximum(out, grid, vx, vy, vz) {
 /**
  * Mark every voxel whose centre is within `radius` of the world point `(px,py,pz)` as claimed. O((radius/voxel)³)
  * per call. A degenerate axis (`vs===0`, a zero-extent bake region) claims all its coincident layers.
+ *
+ * @param {Uint8Array} claimed per-voxel claimed flags (`total` elements)
+ * @param {SdfGrid} grid
+ * @param {number} px
+ * @param {number} py
+ * @param {number} pz
+ * @param {number} radius
+ * @returns {void}
  */
 export function grid_claim_sphere(claimed, grid, px, py, pz, radius) {
     const { rx, ry, rz, strideZ, x0, y0, z0, vsX, vsY, vsZ } = grid;

package/src/generation/foliage/FOLIAGE_DESIGN.md

@@ -0,0 +1,318 @@
+# 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`, `BranchLevelConfig`, `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
+For each recursion level $l \in \{0, \dots, L_{\max}\}$:
+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 of level $l - 1$, child branches are spawned above `bare_length_ratio` $t_{\text{bare}} \in [0, 1)$ according to the level's `PhyllotaxisMode` (`SpiralGolden` $137.507764^\circ$, `AlternateDistichous` $180^\circ$, `OppositeDecussate` $180^\circ + 90^\circ$ flip, `Opposite` $180^\circ$, `Whorled` $360^\circ / M$).
+   - Child branch length $L_l(t_p)$ is modulated by the parent's `length_profile: AnimationCurve` and the crown envelope $S_{\text{env}}(h_{\text{norm}})$.
+   - 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.
+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$.
+     - **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. 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 Adaptive Radial & Longitudinal Tessellation
+- Ring radial vertex count $M_i$ adapts to local radius $R(t_i)$ and target LOD scale:
+  $$M_i = \text{clamp}\!\left( \lceil 2\pi R(t_i) / \epsilon_{\text{radial}} \rceil, \, M_{\min}, \, M_{\max} \right)$$
+- 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), plus terminal rosette clustering at branch tips ($t \to 1$).
+- **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` (Default Broadleaf Cluster)**: $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` (Conifer Needle Tuft / Dense Shrub Cluster)**: Two orthogonal intersecting V-cards rotated by $90^\circ$ around the petiole axis $\mathbf{F}$.
+3. **`TriStarCluster` (Volumetric Bush / Pine Shoot)**: Three cards arranged at $60^\circ$ star angles with radial offset.
+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. **`OctagonalCutoutHull` (Tight Alpha-Bound Card)**: 6-vertex diamond/hexagonal hull trimming empty corner texels to cut alpha-test quad overdraw by ~35%.
+
+---
+
+## 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.
+- **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 ancestor joints (`StandardAttributes.SkinningJoints`: `Uint16Array(4 * V)`, `StandardAttributes.SkinningWeights`: `Float32Array(4 * V)` summing to $1.0$) with smooth cubic Hermite weight falloff along each branch segment.
+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 `foliage_material`, the system synthesizes studio-quality procedural PBR textures using `Sampler2D` $\to$ `ShadeImage.fromSampler2D` $\to$ `ShadeTexture.from`:
+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(config)`**:
+   - Generates a botanical twig/leaf or conifer-needle cluster **Albedo + Alpha Cutout** texture (serrated/lobed/ovate/palmate/needle silhouettes, midrib & lateral venation, premultiplied RGBA compatible with Shade's `albedo_unpremultiply` and hashed alpha test), **Tangent-Space Normal Map** (vein relief), and **ORM Map** on a `StandardShadeMaterial` (`TransparencyMode.AlphaTested`, `ShadeDrawSide.Double`, `transmission_factor: 0.25`).
+
+### 7.4 Multi-LOD Chain with Area-Compensated Foliage Decimation
+Generates a configurable $N$-level LOD chain (default 4 levels: `LOD0`, `LOD1`, `LOD2`, `LOD3`):
+- **Branch Hierarchy & Ring Reduction**:
+  - `LOD0`: All branch levels, full radial segments ($M_0 = 16 \to 4$), $100\%$ foliage cards ($2 \times 3$ folded V-cards).
+  - `LOD1`: Prunes finest sub-twigs below radius threshold, reduces radial segments by $0.65\times$, retains $55\%$ foliage cards ($2 \times 2$ V-cards).
+  - `LOD2`: Retains trunk + primary/secondary boughs, reduces radial segments by $0.4\times$, retains $28\%$ foliage cards (single-fold cards).
+  - `LOD3`: Coarse structural trunk/boughs + $12\%$ large cross-cluster canopy cards.
+- **Golden-Ratio Stratified Decimation & Area Compensation**:
+  - Foliage attachments are filtered deterministically via Golden Ratio low-discrepancy rank $h_i = (i \cdot \varphi^{-1}) \bmod 1 < k_{\text{keep}}$, ensuring uniform thinning across every branch.
+  - Surviving cards are scaled around their petiole pivot by:
+    $$s_{\text{comp}}(k_{\text{keep}}) = k_{\text{keep}}^{-\eta}, \quad \eta = 0.42$$
+    preserving apparent optical density and crown silhouette across all LOD transitions.
+
+---
+
+## 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
+    TreePreset.js
+    BranchLevelConfig.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_compute_pipe_radii.js (+ .spec.js)
+    tree_skeleton_assign_skin_joints.js (+ .spec.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)
+    tree_mesh_build_foliage.js (+ .spec.js)
+    tree_mesh_apply_canopy_ao.js (+ .spec.js)
+  material/
+    make_bark_material.js (+ .spec.js)
+    make_foliage_material.js (+ .spec.js)
+  animation/
+    build_tree_wind_rig.js (+ .spec.js)
+  asset/
+    TreeLODAsset.js
+    TreeAsset.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`.
+