@woosh/meep-engine 3.57.0 → 3.59.0

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#467@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#478@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#467@#clear_field"(fluid: FluidComponent): void;
+    static "__#478@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#467@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#478@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#467@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#478@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidObstacle> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof FluidComponent>)[];

package/src/engine/physics/inertia/world_inverse_inertia.js

@@ -255,7 +255,7 @@ export function world_inverse_inertia_apply_array(
 
     // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
     // quaternion (-qx, -qy, -qz, qw). Inlined for V8 inliner — see
-    // PosedShape3D.support and core/geom/vec3/v3_quat3_apply_inverse.js
+    // PosedShape3D.support and core/geom/vec3/v3_quaternion_apply_inverse.js
     // for the canonical form.
     const tx = qw * vx - qy * vz + qz * vy;
     const ty = qw * vy - qz * vx + qx * vz;

package/src/engine/physics/narrowphase/narrowphase_step.js

@@ -1733,7 +1733,7 @@ function sphere_box_voronoi_fid_array(sphere, sphere_offset, box, box_offset) {
     // Inverse-rotate (sx - bx, sy - by, sz - bz) by the box's quaternion
     // to get the sphere centre in box-local frame. Inlined for the same
     // V8-inliner reason described in PosedShape3D.support — see
-    // core/geom/vec3/v3_quat3_apply_inverse.js for the canonical form.
+    // core/geom/vec3/v3_quaternion_apply_inverse.js for the canonical form.
     const dx = sx - bx;
     const dy = sy - by;
     const dz = sz - bz;

package/src/engine/sound/simulation/render/reverbImpulseResponse.d.ts

@@ -15,5 +15,4 @@
  * @returns {AudioBuffer}
  */
 export function reverbImpulseResponse(ctx: BaseAudioContext, decayBands: Float32Array | number[], decayPower: number, random: () => number): AudioBuffer;
-export { LOW_MID_HZ, MID_HIGH_HZ } from "./reverb_band_tails.js";
 //# sourceMappingURL=reverbImpulseResponse.d.ts.map

package/src/engine/sound/simulation/render/reverbImpulseResponse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reverbImpulseResponse.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/reverbImpulseResponse.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;GAeG;AACH,2CANW,gBAAgB,cAChB,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,gBACK,MAAM,GACf,WAAW,CAoDvB"}
+{"version":3,"file":"reverbImpulseResponse.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/reverbImpulseResponse.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,2CANW,gBAAgB,cAChB,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,gBACK,MAAM,GACf,WAAW,CAoDvB"}

package/src/engine/sound/simulation/render/reverbImpulseResponse.js

@@ -1,11 +1,5 @@
 import { reverb_band_length, reverb_band_tails } from "./reverb_band_tails.js";
 
-/**
- * The band split frequencies now live with the kernel that applies them ({@link reverb_band_tails}); they
- * stay re-exported here because this module is where consumers have always imported them from.
- */
-export { LOW_MID_HZ, MID_HIGH_HZ } from "./reverb_band_tails.js";
-
 /**
  * Generate a stereo reverb impulse response from a PER-BAND decay time `[low, mid, high]` (the probe-baked
  * RT60s). White noise is split into three bands (one-pole filters), each given its OWN exponential decay

package/src/engine/sound/simulation/render/reverb_band_tails.d.ts

@@ -46,7 +46,7 @@ export function reverb_band_tails(out_low: Float64Array, out_mid: Float64Array,
  * Band split frequencies (Hz): low | mid below this, mid | high below the second. Crude one-pole splits —
  * enough to give the reverb tail per-band timbre (a bright vs. dead room), it is decaying noise, not a
  * precise crossover. They live beside the kernel that applies them; both impulse-response producers and
- * {@link EventInstance}'s direct-path crossover re-export/consume them so every band split in the engine
+ * {@link EventInstance}'s direct-path crossover consume them so every band split in the engine
  * lands on the same two edges.
  * @type {number}
  */

package/src/engine/sound/simulation/render/reverb_band_tails.js

@@ -2,7 +2,7 @@
  * Band split frequencies (Hz): low | mid below this, mid | high below the second. Crude one-pole splits —
  * enough to give the reverb tail per-band timbre (a bright vs. dead room), it is decaying noise, not a
  * precise crossover. They live beside the kernel that applies them; both impulse-response producers and
- * {@link EventInstance}'s direct-path crossover re-export/consume them so every band split in the engine
+ * {@link EventInstance}'s direct-path crossover consume them so every band split in the engine
  * lands on the same two edges.
  * @type {number}
  */

package/src/engine/sound/sopra/runtime/EventInstance.js

@@ -4,7 +4,7 @@ import { FADE_EPSILON, rampGain } from "../util/fadeOutAndStop.js";
 import { SOPRA_PANNING_MODEL_TO_WEBAUDIO, SopraPanningModel } from "../definition/SopraPanningModel.js";
 import { EffectChain } from "./EffectChain.js";
 import { VOICE_POOL } from "./VoicePool.js";
-import { LOW_MID_HZ, MID_HIGH_HZ } from "../../simulation/render/reverbImpulseResponse.js";
+import { LOW_MID_HZ, MID_HIGH_HZ } from "../../simulation/render/reverb_band_tails.js";
 import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
 
 /**

package/src/generation/foliage/CROWN_FULLNESS_BRIEF_2026_10_26.md

@@ -0,0 +1,86 @@
+# Crown Fullness: what keeps the crowns bare
+
+Alex, 2026-10-26: oak, pine, maple and spruce "look largely naked" as a whole, though their leaves look right.
+
+## Measured (seed 1337, master 7d610267e)
+
+**What sheds the shoots.** The light of every shoot candidate, as the simulation judged it:
+
+| preset | DBH | height | crown width | leaf | framework | twigs | candidates kept | below compensation | saturated |
+| :--- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| oak | 87 cm | 8.6 m | 6.1 m | 89 m² | 151 m | 1,811 | 47% | 15% | 71% |
+| pine | 73 cm | 10.6 m | 5.0 m | 16 m² | 71 m | 838 | 67% | 0% | 100% |
+| maple | 88 cm | 8.6 m | 6.3 m | 49 m² | 114 m | 2,600 | 83% | 14% | 60% |
+| spruce | 69 cm | 10.7 m | 6.3 m | 80 m² | 78 m | 40,061 | 93% | 6% | 82% |
+
+Light does not bind these crowns: most candidates sit in saturating light.
+
+**Vigour does not fill them** (`ShootGrowthConfig.vigour` raised 2× and 4×):
+
+| preset | leaf ×1 / ×2 / ×4 | side density ×1 / ×2 / ×4 |
+| :--- | :--- | :--- |
+| oak | 89 / 101 / 82 m² | 0.50 / 0.46 / 0.45 |
+| pine | 16 / 35 / 35 m² | 0.34 / 0.42 / 0.42 |
+| maple | 51 / 48 / 47 m² | 0.41 / 0.40 / 0.40 |
+| spruce | 78 / 74 / 72 m² | 0.33 / 0.33 / 0.33 |
+
+Above its gross yield every burst shoot is kept. The twig systems then stop growing outward for want of buds and
+room, not of light.
+
+**The framework does** (every non-root `BranchSpawnRule.count` doubled):
+
+| preset | leaf ×1 → ×2 | crown LAI | side density | side transparency | below density |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| oak | 89 → 188 m² | 3.1 → 5.3 | 0.50 → 0.66 | 0.42 → 0.33 | 0.58 → 0.71 |
+| pine | 16 → 38 m² | 0.7 → 1.4 | 0.34 → 0.48 | 0.64 → 0.56 | 0.35 → 0.46 |
+| maple | 51 → 116 m² | 2.0 → 4.3 | 0.41 → 0.62 | 0.42 → 0.37 | 0.42 → 0.63 |
+| spruce | 78 → 199 m² | 3.0 → 6.0 | 0.33 → 0.51 | 0.31 → 0.24 | 0.42 → 0.59 |
+
+FIA rates healthy crowns at 45-51% density and about 15% transparency [Randolph 2006].
+
+## Diagnosis
+
+The crowns are bare because their framework is sparse, and the framework's density is authored:
+- `count: 5` boughs, `count: 2` branches each, and so on, chosen per preset, not sourced;
+- each carrier wears a twig sleeve of limited reach;
+- between sleeves the crown is empty, and no twig system can reach across, at any vigour.
+
+The crown-filling principle ("fullness is set by light, not by when the simulation stops") holds for the twigs but
+not for the framework they hang on.
+
+The trunks are also far too thick for their height (an 87 cm DBH oak 8.6 m tall), the pipe model's known
+over-thickening. That is a separate defect; it makes trunk-based leaf targets meaningless here.
+
+## Targets
+
+**Expected whole-tree leaf area.** These are trees of the size the presets mean to be, not of their over-thick trunks;
+all sources are forest-grown trees.
+
+| preset | measured | expected | basis |
+| :--- | ---: | ---: | :--- |
+| oak (DBH 40 cm, h 14 m) | 89 m² | 280-430 m² one-sided | Forrester et al. 2017 (*Q. robur*, Table A.5); Gómez-García & Pérez-Rodríguez 2015 leaf mass × SLA 12.9-16.2 m²/kg |
+| maple (DBH 30 cm, h 13 m) | 49 m² | ~130 m² one-sided | Martin et al. 1998, *Can. J. For. Res.* 28: 1648-1659, *A. rubrum*, Table 4 (n = 11, DBH 6-52 cm) |
+| pine (DBH 25 cm, h 11 m) | 16 m² | 35-64 m² projected | Forrester et al. 2017; Repola 2009, *Silva Fennica* 43: 184 needle mass × projected SLA 3.9-5.7 m²/kg |
+| spruce (DBH 25 cm, h 11 m) | 78 m² | 100-150 m² projected | Forrester et al. 2017; Repola 2009 × SLA 3.3-5.0 m²/kg |
+
+- Every preset carries a third to two-thirds of the leaf a real tree of its size does.
+- Doubling the framework brings oak, maple and spruce into their ranges, and pine near its lower end. That fits the
+  diagnosis.
+- European oak allometries run about twice the American oaks' (Martin et al. 1998) at the same DBH.
+- No open-grown allometry, crown-level LAI or leaf area density was found for these species.
+- The research subagent's working files are in the session scratchpad.
+
+## The fork
+
+1. **Grow the framework from shoots too** (self-organizing, as Palubicki et al. 2009 do):
+   - The same bud demography and light that fill the periphery grow the whole crown. The boughs are the shoots that
+     survived and thickened, and branch spacing is an outcome of self-shading.
+   - The generator graph keeps what shoots cannot give: the trunk, whorl and architectural model, roots, stubs.
+   - This is the principled end state and a large refactor of `tree_skeleton_grow`.
+2. **Derive the framework's density from the twigs' reach:**
+   - A carrier's twig system wears a sleeve of measurable reach. Carriers are spaced so the sleeves tile the crown,
+     as card density was derived from the leaf sleeve.
+   - The generator graph stays and its counts become outcomes.
+   - Smaller, but the framework's other shape choices stay authored.
+3. **Source the counts per species:** branches per whorl and per metre of stem are measured for pine and spruce;
+   oak and maple are thinner.

package/src/generation/foliage/FOLIAGE_DESIGN.md

@@ -106,6 +106,16 @@ Evaluating any point or derivative at local parameter $u \in [0, 1]$ along edge
 - `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,
@@ -166,23 +176,37 @@ hops from the trunk; split forks keep their parent's depth and generator.
      $$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`):
+   `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
-     peripheral twig system on every living branch of its `source` generator, after the pipe-model pass. The twigs are
-     branches of generator `target` (short shoots `short_target`), one level below their carrier.
-   - **The carrier's growth.** A framework branch is born when its parent's tip passed its seat, at the species'
-     `shoot_growth.leader_growth`; it carries `round(age)` annual units over its whole length.
+     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):
-     - Every living axis grows a terminal unit; short shoots survive as their light allows.
-     - Last season's units burst their zones' buds (and this season's, sylleptically). Unit lengths are drawn per
-       order.
-     - New shoots are kept to their light's net yield, `shoot_growth.net_yield(Q)` over the rule's gross yield. A shed
-       axis takes everything on it.
-     - 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, on twigs,
-       carriers and the framework above them.
-   - **Avoidance.** A unit grows only where it clears today's wood; a shoot the wood has grown into dies.
+     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).
 
@@ -205,9 +229,15 @@ For any lateral branch ($l \ge 1$) attached to a parent branch of radius $R_p$ a
    - 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)$$
+### 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.
 
@@ -333,7 +363,7 @@ Meep's visibility-buffer renderer (`Shade`) deforms `MeshletGeometry` on the GPU
    - 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.
+   - 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`.
@@ -346,24 +376,51 @@ Meep's visibility-buffer renderer (`Shade`) deforms `MeshletGeometry` on the GPU
      - 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`:
+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 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.
+### 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.
 
 ---
 
@@ -397,10 +454,16 @@ src/generation/foliage/
     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
@@ -412,6 +475,11 @@ src/generation/foliage/
     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)
@@ -419,11 +487,21 @@ src/generation/foliage/
     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)
 ```