@woosh/meep-engine 3.57.0 → 3.58.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 "__#476@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#467@#clear_field"(fluid: FluidComponent): void;
+    static "__#476@#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 "__#476@#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 "__#476@#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

@@ -166,23 +166,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 +219,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.
 
@@ -352,18 +372,44 @@ When the caller does not pass custom `bark_material` or `foliage_material`, the
 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, never past 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); 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.
 
 ---
 
@@ -401,6 +447,7 @@ src/generation/foliage/
     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 +459,10 @@ 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)
+    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 +470,17 @@ src/generation/foliage/
     foliage_leaf_silhouette.js
     FoliageAtlasCutout.js
     foliage_atlas_cutout.js (+ .spec.js)
+    tree_cluster_bake.js (+ .spec.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
+    tree_lod_plan.js (+ .spec.js)
     generate_tree.js (+ .spec.js)
     place_tree.js (+ .spec.js)
 ```