@woosh/meep-engine 3.57.0 → 3.59.0

package/src/generation/foliage/LOD_REWORK_BRIEF_2026_10_27.md

@@ -0,0 +1,521 @@
+# Tree LODs at a geometric error, with baked cluster cards (2026-10-27)
+
+Follows `REAL_TIME_TREES_BRIEF_2026_10_27.md`. The goal: every preset under `TREE_RENDER_COST_CEILING` at every LOD,
+with LODs that look like the tree, because each one is the tree drawn to an error rather than the finest mesh
+decimated.
+
+## What is wrong today
+
+- **LODs decimate the finest mesh.** `TreeLODConfig.createDefaultChain` is an authored chain: radial and longitudinal
+  scales, a branch-level cut, a radius cut, and a kept fraction of cards scaled up by `keep^-eta`.
+- **The foliage ignores the bark's cuts.** `tree_mesh_build_foliage` decimates cards by golden rank only. It never
+  reads `carriers`, `max_branch_level` or `min_branch_radius` (`tree_mesh_build_foliage.js:65-84`).
+- **So coarse LODs show floating leaves.** A coarse LOD keeps single-leaf cards, at their LOD0 positions and LOD0 skin
+  joints, around wood that is no longer drawn.
+- **Every LOD carries every joint.** `TreeLODAsset.scene_bundle` builds one `Skin` with the full joint set for every
+  LOD. The rig, `skin_info` and `wind_rig` are shared (`generate_tree.js:97-100`).
+- **Joints cost per instance.**
+  - Each wind joint is an ECS entity with a GPU transform row and a spring-damper step (`FoliageWindSystem`,
+    `shader_foliage_wind_apply.js`).
+  - Each skinned instance gets its own geometry clone, re-skinned every frame (`GPUMeshSkinningContext`).
+  - So the willow's 40,620 joints cost as much per tree as its triangles do.
+- **Nothing switches LODs at runtime.** `place_tree` takes a fixed `opts.lod` (`place_tree.js:56-66`), and nothing in
+  shade or engine selects mesh LODs by screen size.
+
+## Measured basis
+
+`H:/tmp/probe_error_lod_dp.mjs` on master (seed 1337). Each LOD at error `eps` is estimated as:
+- **Wood:** meshed only where its diameter is at least `eps`.
+- **Spines:** simplified to `eps` (Douglas-Peucker on position and radius).
+- **Rings:** as many sides as keep the chord's sagitta within `eps`.
+- **Cards:** everything below a cut is one 4-triangle card.
+
+Triangles per m² of side area; the LOD0 ceiling is 752.6:
+
+| preset | eps 1 cm | eps 2 cm | eps 4 cm | eps 8 cm | cuts at 2 cm (median leaves) |
+| :--- | ---: | ---: | ---: | ---: | ---: |
+| oak | 457 | 226 | 150 | 97 | 797 (21) |
+| pine | 2,053 | 661 | 51 | 10 | 4,691 (1) |
+| birch | 3,175 | 856 | 247 | 81 | 3,275 (6) |
+| willow | 3,984 | 1,181 | 340 | 133 | 6,823 (10) |
+| maple | 866 | 439 | 260 | 173 | 2,007 (4) |
+| spruce | 3,812 | 683 | 270 | 80 | 2,389 (16) |
+| shrub | 1,854 | 835 | 279 | 78 | 1,128 (8) |
+
+- **Wood stops being the cost once eps reaches 2 cm.** The twig layer, which is most of today's bark, falls under the
+  error.
+- **Cuts are the next cost, and they fall slowly.** Twigs grow straight off the boughs, so every twig base is its own
+  cut, holding a median of 1 to 21 leaves. On the willow at 2 cm, cards are 27k of its 43k triangles.
+
+## Design
+
+1. **Each LOD is the tree at an error `eps_k`, in metres.**
+   - Wood is meshed where its diameter is at least `eps_k`. Thinner wood is not visible as a tube at that error.
+   - A spine keeps the points it needs to stay within `eps_k` in position and radius.
+   - A ring has as many sides as keep its chord within `eps_k`. This replaces `radial_segments_min/max`,
+     `radial_scale`, `longitudinal_scale`, `max_branch_level` and `min_branch_radius`.
+   - Coarser LODs double the error, `eps_k = eps_0 * 2^k`. Each switch then happens at twice the distance, at the same
+     error on screen.
+2. **What the wood leaves out becomes cluster cards.**
+   - A cut gathers every twig and leaf the simulation grew below it.
+   - Each cluster is drawn orthographically from its card's facing, at a texel no coarser than `eps_k / 2`, into albedo,
+     alpha, normal and AO tiles.
+   - The leaves inside the tiles are the same leaf tiles drawn today (`foliage_tile_raster`); only the card count
+     changes, following the wood instead of the leaves.
+   - One card per leaf goes (F2).
+3. **A few baked clusters stand for all of them.**
+   - The simulation's clusters are siblings grown by the same rules, so each cut uses the nearest of a few baked
+     representatives, with the cut's transform and scale.
+   - Two clusters are interchangeable when they differ by less than the error.
+4. **The rig runs on each LOD's wood.**
+   - `tree_skeleton_assign_skin_joints` runs over the wood each LOD meshes.
+   - A cluster card takes its cut's joint and that joint's parent, two influences.
+   - No seat meets more than four joints, because twigs on twigs' first segments are no longer meshed.
+5. **The gate goes green.** A spec holds every preset's every LOD under `TREE_RENDER_COST_CEILING`, red before this
+   lands and green after.
+
+## Reuse map
+
+| job | existing code | how it is used |
+| :--- | :--- | :--- |
+| cost measure and ceiling | `analysis/tree_render_cost.js` | the gate, unchanged |
+| wood mesher | `mesh/tree_mesh_build_bark.js` (rings, RMF frames, collars, knots, UVs, skin rings) | kept; only its culling and sample counts move to `eps` |
+| ring skin weights | `mesh/interpolate_ring_skin_weights4.js` | unchanged |
+| leaf drawing | `material/foliage_tile.js` `foliage_tile_raster`, `polygon2_rasterize_coverage`, `material/make_foliage_material.js` (colour model, normal from height, ORM) | the leaves a cluster is drawn from |
+| orthographic CPU raster | `analysis/crown_opacity_measure.js` private `raster_geometry` (edge functions, top-left rule, barycentric UV, bilinear atlas alpha) | extracted to a shared rasterizer, extended to albedo, normal and depth; the crown measure uses the same one |
+| image filters | `engine/graphics/texture/sampler/` (`Sampler2D`, `sampler2d_copy_with_margins`, chamfer distance, `sampler2d_scale_down_*`), `engine/graphics/sh3/grid_dilate_average.js` | gutters, dilation, mips of the cluster tiles |
+| atlas packing | `core/geom/packing/max-rect/MaxRectanglesPacker.js`, `material/compute_foliage_variant_atlas_layout.js` | cluster tiles beside the leaf tiles |
+| card outlines | `material/foliage_atlas_cutout.js` (`foliage_atlas_cutout_fit_tile`: hull fitted to alpha, 6 vertices) and the `CutoutHull` card | cluster cards cut to their tile's alpha, so less overdraw |
+| card geometry and wind data | `mesh/tree_mesh_build_foliage.js` card writers (`CutoutHull`, `CrossCard`, `FoldedVCard`), UV1 flutter and phase, canopy AO | the cluster cards |
+| joint derivation | `skeleton/tree_skeleton_assign_skin_joints.js` (tolerance walk), `animation/build_tree_wind_rig.js` | run per LOD |
+| per-LOD assets | `asset/TreeLODAsset.js` (lazy builders, meshlets, `scene_bundle`, `prefab`) | one skin and one rig per LOD |
+| measures of the look | `analysis/tree_crown_opacity.js` (FIA density and transparency), `analysis/foliage_measure_leaf_area.js` | each LOD's crown is held to its LOD0 density and leaf area |
+
+**New code, none of which exists in the engine:**
+- **A polyline simplifier** (Douglas-Peucker over position and radius) in `core/geom/3d`.
+- **The cluster cut and its representatives:**
+  - a descriptor per cut;
+  - a greedy cover that picks representatives so every cut is within the error of one;
+  - the placement transform.
+  - `geometry_deduplicate` matches exact congruence and `graph_k_means_cluster` works on graph distances, so neither
+    fits.
+- **The cluster bake:** the shared rasterizer writing albedo, normal, depth and AO into tiles.
+
+## Forks
+
+- **F1. Where a cluster begins.**
+  - **(a) Every cut is a cluster.** Simple, but the cluster count falls slowly: the willow has 6,823 at 2 cm.
+  - **(b) Cuts along a meshed branch share a card per stretch of it.** The stretch is as long as the cards a cluster
+    tile can hold at the LOD's texel. The card count then follows the meshed wood's length over `eps_k`, the way
+    SpeedTree's 150-400 cards sit along the boughs.
+  - Recommended: (b). It is the only one that keeps falling as `eps` grows.
+- **F2. LOD0's error `eps_0`.**
+  - **(a) Each tree's smallest error that fits the ceiling,** found by the generator. The measured values are about
+    1-2 cm.
+  - **(b) One chosen error for every species.**
+  - Recommended: (a). Alex accepted a metric to tune against, and it sizes small and large trees alike.
+- **F3. The rig's tolerance at each LOD.**
+  - **(a) `deflection_tolerance` becomes `max(deflection_tolerance, eps_k)`.** A sway error smaller than the shape error
+    cannot be seen.
+  - **(b) It stays fixed.** Coarse LODs keep every joint their wood still holds.
+  - Recommended: (a).
+- **F4. Joints across LODs.**
+  - **(a) A coarser LOD's joints are a subset of the finer one's,** chosen by the same walk at the larger tolerance from
+    the finer LOD's joints. A switch then keeps the wind state of every joint both LODs share.
+  - **(b) Each LOD derives its own.**
+  - Recommended: (a). The cost is a constrained walk, about the same code.
+- **F5. Runtime LOD switching.** It is not in this design and no system does it. Without it, a scene uses whichever
+  LOD `place_tree` was given.
+  - Recommended: its own brief after this lands. Shade has screen-space-error selection only in virtual geometry, which
+    is static-only.
+
+## Stages, each measured against the cost gate and the look
+
+1. **L1: wood at an error.**
+   - The bark mesher takes `eps` in place of the authored chain.
+   - Reports triangles and joints per LOD, plus LOD0's crown density and leaf area against today's.
+2. **L2: cluster cards.**
+   - The cut (F1), the bake, the representatives, the cards.
+   - Each LOD's FIA crown density stays within the band at LOD0 (`tree_crown_opacity`), and its leaf area drawn stays
+     that of LOD0.
+3. **L3: the rig per LOD** (F3, F4). Joints per m² under the ceiling.
+4. **L4: the gate spec.** Every preset, every LOD, under `TREE_RENDER_COST_CEILING`, red then green.
+   `TreeLODConfig`'s authored fields are removed, a hard break.
+
+## Risks
+
+- **Distant cluster tiles thin out.** Alpha coverage is not preserved across mips anywhere in the engine. A cluster
+  card seen from far away loses leaves as plain box-filtered mips thin its alpha. This is measured in L2 with
+  `tree_crown_opacity` at coarser pixel sizes; if it shows, coverage-preserving mips are their own fix.
+- **A flat card shows edge-on.** Cluster cards seen along their plane vanish. Crossed or hull cards per cluster cost
+  triangles; L2 measures the side density over all views, which `tree_crown_opacity`'s hemi-octahedral frames already
+  give.
+- **Cluster wind.** A card moves rigidly with its cut's joints; the flutter attribute (UV1) still animates it. Twig-level
+  sway inside a cluster is gone below the LOD's error by design.
+
+## L1: wood at an error (built 2026-10-27)
+
+Decisions (Alex: the recommended forks): F1 (b) stretches, F2 (a) `eps_0` from the ceiling, F3 (a) the rig's tolerance
+follows `eps`, F4 (a) nested joints, F5 its own brief later.
+
+**Built.** `TreeLODConfig.error` replaces the authored chain's bark fields (hard break, with
+`BranchGeneratorConfig.radial_segments_min/max`). A branch is drawn while it is at least `eps` thick and its parent is
+drawn, to where it thins to `eps`. Rings and sides are planned against the surface the mesher draws, measured all round:
+half the error along the branch (`polyline_simplify_by_error`, new in `core/geom/polyline`), half around each ring,
+checked at every chord's middle too. Ring shape (lobes, flutes, ovalization, collars, knots) is one function the plan
+and the vertices share, bit-identical to before at the old sampling. `eps_0` is 1 cm, chosen, until L2 derives it.
+
+**Bark triangles, master against L1** (seed 1337):
+
+| preset | LOD0 master | LOD0 1 cm | LOD1 master | LOD1 2 cm | LOD2 master | LOD2 4 cm |
+| :--- | ---: | ---: | ---: | ---: | ---: | ---: |
+| oak | 69.7k | 29.1k | 3.6k | 12.8k | 0.8k | 6.0k |
+| pine | 556.7k | 119.5k | 14.8k | 20.3k | 0.2k | 0.6k |
+| birch | 295.9k | 49.5k | 5.0k | 10.5k | 0.5k | 2.9k |
+| willow | 422.5k | 132.4k | 5.8k | 30.4k | 0.6k | 7.6k |
+| maple | 58.9k | 26.9k | 3.0k | 10.7k | 0.7k | 4.7k |
+| spruce | 744.7k | 52.3k | 3.5k | 9.0k | 0.6k | 3.1k |
+| palm | 0.8k | 10.9k | 0.4k | 5.5k | 0.3k | 2.6k |
+| shrub | 46.9k | 8.7k | 1.2k | 2.4k | 0.1k | 0.6k |
+
+- LOD0 bark falls 2.2-14x on every woody preset. Coarse LODs carry more than master's, which kept only the boughs
+  whatever their thickness; at 4 cm a bough is still drawn. The palm's trunk was 3-4 sides authored; its leaf scars
+  and flare need 95 rings of 50 sides at 1 cm.
+- Leaf area at LOD0 is unchanged within 0.3%; side crown density drops by at most 0.02 (the thin wood no longer drawn).
+- Generation: the oak's LOD0 bark takes 137 ms against 82 ms, the pine's 793 ms against 288 ms, the palm's 467 ms
+  against 5 ms (measuring every candidate ring against every collar and knot).
+
+**Measured for L2.** The cost ceilings at LOD1 and LOD2 came from the authored chain's kept fractions (0.54 and 0.13
+of LOD0's). Doubling `eps` does not meet them: the oak's bark alone at 4 cm is 6.0k triangles against the LOD2
+ceiling's 3.0k for the whole tree. Either each LOD's error is derived from its own ceiling (F2 per level), or the
+ceilings follow the error; L2 decides with the cluster cards' cost in hand.
+
+**Mutation test.** 6 of 11 mutants killed. Survivors: drawing a child whose parent is not (no child is thicker than
+its parent, an equivalent mutant on real trees); four times the tolerance around a ring (round wood's chord middles
+still bound it; nothing tests shaped rings' accuracy); keeping every candidate ring, and not keeping the weld rings
+(cost and the weld's fade, which no spec measures); a card held 5% inside its ring pair (nothing exposes where a card
+attaches).
+
+## L2 measured before building (2026-10-27)
+
+`H:/tmp/probe_clusters.mjs` and `probe_clusters_bc.mjs`, master at 588207065, seed 1337. A cut is a subtree the wood at
+an error leaves undrawn, the leaves on drawn wood, or a drawn branch's undrawn tip. A card is estimated at 6 triangles.
+Density is triangles per m^2 of side area; LOD0's ceiling is 752.6.
+
+**F1 (b) as stretches within the error of one plane does not merge.** Douglas-Peucker along each drawn branch, with a
+run's error the distance of its leaves and undrawn twigs from their least-squares plane, keeps almost every cut apart:
+a single cut's twig system is already thicker than the error (the oak at 4 cm: 680 cuts, all of them thicker, 680
+cards). So the stretches come out as one card per cut.
+
+**Holding every leaf within the error of its card's plane costs too much.** Splitting each cut until every leaf is that
+close to one plane (a billboard cloud, Decoret et al. 2003) needs 12-16 cm of error to meet LOD0's ceiling:
+
+| preset | 4 cm | 8 cm | 16 cm |
+| :--- | ---: | ---: | ---: |
+| oak | 18,837 cards, 3,691/m^2 | 8,573, 1,669 | 1,069, 222 |
+| birch | 35,493, 10,265 | 7,988, 2,324 | 1,275, 372 |
+| spruce | 11,419, 3,630 | 2,745, 879 | 716, 231 |
+
+At 16 cm only the trunk and the main boughs are drawn as wood.
+
+**One card per cut, judged by what it shows** (its depth not held to the error, as SpeedTree's cluster cards are not):
+
+| preset | 1 cm | 2 cm | 3 cm | 4 cm | 6 cm | 8 cm | 16 cm |
+| :--- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| oak | 1,447 | 730 | | 308 | | 172 | 59 |
+| pine | 3,712 | 1,044 | 290 | 79 | 15 | 15 | 0 |
+| birch | 5,225 | 1,427 | | 408 | | 127 | 15 |
+| willow | 7,204 | 1,946 | 932 | 595 | 356 | 230 | 53 |
+| maple | 2,251 | 1,113 | 629 | 494 | 337 | 292 | 82 |
+| spruce | 7,891 | 1,405 | | 502 | | 146 | 59 |
+| shrub | 3,149 | 1,366 | 626 | 440 | 216 | 118 | 11 |
+
+LOD0's ceiling is met at 2-4 cm of error (oak 2, pine 3, maple 3, shrub 3, birch and spruce 3-4, willow 4).
+
+**The LOD1 and LOD2 ceilings.** Density falls about 2.3x each time the error doubles, not the 4x that one
+triangle per pixel at each LOD's switching distance would need, so ceilings derived per pixel (LOD1 188, LOD2 47 per
+m^2 with doubling) are not met by wood and cards at any error: far trees are an impostor's job (F5). The ceilings
+measured at 6aff5265e (407.6, 97.0) are met if each LOD's error comes from its own ceiling instead of doubling: about
+3-6 cm at LOD1 and 8-16 cm at LOD2.
+
+## L2: cluster cards (built 2026-10-27)
+
+Decision (Alex, after the measurements above): one card per cut, its depth not held to the error; each LOD's error
+derived from its own ceiling, the ceilings kept.
+
+**Built.**
+- `tree_clusters`: one cluster per cut. A leaf on drawn wood joins its branch's nearest cut; a branch with none
+  gathers its leaves into one at their mean place. A cluster hangs from its drawn bark point, skinned as that point.
+- `tree_cluster_cards`: a card in the plane its leaves, twigs and hanging point spread in, facing away from the crown.
+- `tree_cluster_bake`: an orthographic CPU bake at a texel equal to the error, 4x4 samples a texel, back to front in
+  linear light, through `tri2_rasterize_barycentric` (extracted from the crown opacity measure's raster, which now
+  uses it, bit-identical). Leaves are pressed onto the card; twigs are bark bands. The tiles pack into one atlas per
+  LOD, each cut to a 6-vertex hull fitted to its alpha.
+- `tree_lod_errors`: each LOD's error, a half-octave apart from 1 cm, the finest that fits its ceiling.
+- The per-leaf foliage (`tree_mesh_build_foliage`, no LOD) is the reference the bakes draw from; no LOD draws it.
+
+**The side area is what the tree grew.** `tree_grown_side_area` (wood nodes and every leaf's card) replaces the
+side area of an LOD's drawn mesh, which shrank as the error grew: the search and the gate disagreed on the palm and
+the fern. `TREE_RENDER_COST_CEILING` is re-derived under it at 6aff5265e: 761.2, 412.3, 96.2 triangles and 16.89
+joints per m^2.
+
+**How a card shows its leaves**, oak LOD0 FIA crown density from the side and from below (per-leaf .49/.53):
+
+| variant | side | below |
+| :--- | ---: | ---: |
+| one card, leaves projected | .42 | .44 |
+| three cards by leaf orientation | .40 | .51 |
+| three cards, leaves pressed | .42 | .53 |
+| **one card, leaves pressed** (built) | **.47** | **.46** |
+
+Pressing turns each leaf about where it attaches until it lies in the card's plane, so a card holds the leaf area
+the tree grew whichever way its leaves face (projected, a leaf turned 60 degrees away covers half). Baked normals
+turned the cards' grazing faces white and were flattened; the vertex canopy AO doubled the tiles' and was dropped.
+
+**Each preset, seed 1337**: error, triangles, triangles per m^2 (ceiling 761.2 / 412.3 / 96.2), atlas texels:
+
+| preset | LOD0 | LOD1 | LOD2 |
+| :--- | :--- | :--- | :--- |
+| oak | 2.0 cm, 16.6k, 565, 556^2 | 4.0 cm, 8.6k, 293, 316^2 | 11.3 cm, 2.1k, 70, 135^2 |
+| pine | 2.8 cm, 9.5k, 218, 787^2 | 2.8 cm, 9.5k, 218, 787^2 | 4.0 cm, 1.9k, 43, 500^2 |
+| birch | 2.8 cm, 8.6k, 444, 528^2 | 4.0 cm, 4.5k, 233, 335^2 | 8.0 cm, 1.4k, 73, 140^2 |
+| willow | 2.8 cm, 25.8k, 724, 1287^2 | 4.0 cm, 14.2k, 397, 842^2 | 11.3 cm, 2.1k, 60, 210^2 |
+| maple | 2.8 cm, 12.9k, 560, 371^2 | 4.0 cm, 9.1k, 396, 270^2 | 16.0 cm, 1.4k, 59, 82^2 |
+| spruce | 2.8 cm, 8.9k, 502, 459^2 | 4.0 cm, 5.6k, 313, 323^2 | 11.3 cm, 1.1k, 61, 117^2 |
+| palm | 1.0 cm, 11.6k, 525, 1572x1536 | 1.4 cm, 8.0k, 363, 1114x1090 | 5.7 cm, 1.7k, 75, 248x241 |
+| shrub | 2.0 cm, 4.4k, 661, 536^2 | 2.8 cm, 2.1k, 312, 364^2 | 5.7 cm, 0.5k, 77, 156^2 |
+| fern | 1.4 cm, 0.3k, 614, 122^2 | 2.0 cm, 0.1k, 292, 89^2 | 11.3 cm, 0.0k, 49, 11x20 |
+
+Every preset fits its ceiling's triangles at every LOD (the gate spec, `tree_render_cost.spec`). The willow was
+640k triangles; its LOD0 is 25.8k. The pine's LOD0 already fits LOD1's ceiling, so the two are one.
+
+**The look**, FIA crown density side/below at LOD0, LOD1, LOD2, against the per-leaf foliage:
+
+| preset | per-leaf | LOD0 | LOD1 | LOD2 |
+| :--- | :--- | :--- | :--- | :--- |
+| oak | .49/.53 | .47/.46 | .45/.46 | .41/.43 |
+| pine | .41/.39 | .30/.35 | .30/.35 | .27/.32 |
+| birch | .52/.77 | .54/.73 | .53/.70 | .49/.66 |
+| willow | .74/.76 | .71/.72 | .71/.70 | .66/.65 |
+| maple | .46/.47 | .44/.40 | .43/.39 | .38/.32 |
+| spruce | .29/.40 | .24/.39 | .23/.39 | .19/.38 |
+| shrub | .68/.71 | .68/.64 | .67/.62 | .60/.56 |
+| palm | | .68/.40 | .68/.40 | .65/.39 |
+| fern | | .59/.14 | .58/.13 | .45/.39 |
+
+Generation is 0.3-9.6 s a tree, its three LODs' bakes 0.1-9.1 s; the error search is 0.4-2.5 s of it.
+
+**Mutation test.** 13 of 13 killed, three after specs were added for them: the painter's order (where two twigs
+cross, the tile shows the nearer), a tile's empty edge (filtering never reaches the neighbour), and a leaf on drawn
+wood joining its branch's nearest cut.
+
+**Measured open items.**
+- **Texture memory has no gate.** At 10 bytes a texel uncompressed (albedo 4, normal 2, ORM 4), LOD0's atlas is
+  24.1 MB for the palm and 16.6 MB for the willow, 3.1 MB for the oak. Its 1 cm error is what the palm's ceiling
+  allows; the search floor stops it going finer.
+- **Density falls short on the conifers**: the pine's side density is .30 against .41 per-leaf, the spruce's .24
+  against .29. The broadleaves are within .03 from the side at LOD0; from below the oak, maple and shrub
+  lose .07.
+- **The fern's LOD2 is one card**, flat, so its density from below rises from .14 to .39.
+- **Joints are far over the ceiling** (willow 1,139, birch 779, oak 149 per m^2 against 16.89): L3.
+
+## L3: the rig per LOD (built 2026-10-27)
+
+Decisions (Alex): F3 (a) the rig's tolerance follows the error, F4 (a) nested joints.
+
+**Built.**
+- `tree_skeleton_assign_skin_joints` takes the wood an LOD draws (`options.rings`): its walk runs only over drawn
+  branches and places joints no further out than their bark; what the LOD leaves undrawn rides on the drawn wood it
+  hangs from, its drag still counted in the joint that carries it. The tolerance is `max(deflection_tolerance, eps)`.
+- `options.within`, the finer LOD's joints: the coarser walk places a joint only where the finer rig has one, the
+  first past where its error passes the tolerance. Walked within its own joints, a rig comes back whole.
+- `tree_lod_plan` (was `tree_lod_errors`) searches each LOD's error against the joint ceiling too, F2 (a) read
+  whole: the ceiling is triangles and joints. It returns each LOD's rig with its error; each LOD's builders bind it
+  (`tree_skeleton_bind_skin_joints`) before meshing, as the bark and the cluster cards read their skinning from the
+  nodes. `TreeAsset.skin_info` stays the rig of all the wood as grown, which the leaves as grown are bound to.
+- The gate spec holds every LOD's joints to the ceiling as well as its triangles.
+
+**Joints per m^2** (ceiling 16.89), seed 1337: every joint the wood as grown takes at 1 cm, against each LOD's rig.
+
+| preset | wood as grown | LOD0 | LOD1 | LOD2 |
+| :--- | ---: | ---: | ---: | ---: |
+| oak | 4,357, 148.6 | 301, 10.3 | 128, 4.4 | 13, 0.4 |
+| pine | 11,576, 266.8 | 175, 4.0 | 175, 4.0 | 24, 0.6 |
+| birch | 15,018, 778.8 | 207, 10.7 | 84, 4.4 | 25, 1.3 |
+| willow | 40,620, 1,138.6 | 293, 8.2 | 293, 8.2 | 26, 0.7 |
+| maple | 1,180, 51.3 | 127, 5.5 | 79, 3.4 | 1, 0.0 |
+| spruce | 8,130, 456.1 | 198, 11.1 | 103, 5.8 | 12, 0.7 |
+| palm | 65, 2.9 | 65, 2.9 | 64, 2.9 | 31, 1.4 |
+| shrub | 4,119, 620.4 | 72, 10.8 | 72, 10.8 | 15, 2.3 |
+| fern | 24, 56.4 | 4, 9.4 | 4, 9.4 | 1, 2.4 |
+
+Every preset fits the whole ceiling at every LOD. Rigging the drawn wood at the error is what cuts the joints, 10-60x
+on the woody presets; nesting costs little (nested in a 2.8 cm LOD0, the willow's 4 cm rig took 267 joints, free 293).
+
+**Three presets' LOD0 errors rose for their joints.** At the error their triangles allowed, the willow's rig was 20.3
+joints per m^2 (2.8 cm), the shrub's 29.5 (2 cm), the fern's 21.2 (1.4 cm). Their LOD0 errors are now 4 cm, 2.8 cm
+and 2 cm: the willow's LOD0 is 14.2k triangles against 25.8k, its FIA crown density .71/.70 against .71/.72; the
+shrub's .67/.62 against .68/.64; the fern's .58/.13 against .59/.14.
+
+**Mutation test.** 13 of 13 killed: the walk over undrawn wood, joints past the drawn bark, `within` ignored, a bind
+without pivots, the species' tolerance kept, joints left out of the search, LODs not nested, each LOD's wind rig taken
+from the wood as grown, the cost counting the wood as grown's joints, the bark or the cards built on whatever rig is
+bound (the cards' after the spec built every LOD's cards before any bark), and a search that never stops when nothing
+is drawn (it hangs: pinned by a tree that fits no ceiling at any error, which is drawn without wood).
+
+**Measured open items.**
+- **LOD0 and LOD1 are one** for the pine, the willow, the shrub and the fern: the finest error that fits LOD0's
+  ceiling already fits LOD1's, so the chain draws the same tree twice.
+- **Texture memory has no gate** (L2): the palm's LOD0 atlas is 24.1 MB uncompressed; the willow's fell to 7.1 MB
+  with its error.
+- Generation is 0.3-8.1 s a tree, its three LODs' builds 0.0-7.4 s.
+
+L4 (the gate green) is met: every preset, every LOD, triangles and joints. F5, runtime LOD switching, is its own brief.
+
+## Representative cluster tiles (built 2026-10-28)
+
+**What was wrong.** L2 baked one tile per cut at a texel equal to the LOD's error, to fit 600-1,100 tiles per LOD into
+memory. An oak leaf, 12.2 cm, was six texels long at LOD0: a blob (Alex's screenshot of the oak at LOD0). The design's
+point 3, a few baked clusters standing for all of them, had been dropped.
+
+Decisions (Alex): a few tiles per tree shared by all its LODs, the texel from the leaf, every cut matched to the
+nearest and placed at its own size and turn, the count from a texture-memory ceiling.
+
+**Built.**
+- **The leaf's texel** (`FoliageTileLayout.cluster_texel`): the outline's finest feature four texels across, its margin's
+  teeth aside (`LeafGeometry.outline`); a needle two across its width, as a stem is. The leaf tile's own texel, which
+  draws the teeth, was 10-100x too fine: one oak cut at it is 0.5 MB, one willow cut 56 MB.
+  Oak 1.41 mm, shrub 1.20, willow 3.91, maple 8.50, birch 9.38, pine 0.80, spruce 0.50, palm 49.6, fern 25.5.
+- **Coarser LODs** are seen no nearer than where the LOD before is drawn to a pixel, so a representative taken from a
+  coarser LOD's cut is baked at that LOD's error, or the leaf's texel if finer; a cut uses only representatives at its
+  LOD's texel or finer.
+- **The texture ceiling**, `TREE_RENDER_COST_CEILING.texture_density`: 240,667 bytes per m^2, the shrub's leaf atlas
+  at 6aff5265e (every preset's was 640 KiB, so per m^2 the densest is the smallest tree but the fern), derived as the
+  other ceilings are. The gate spec holds every preset to it.
+- **How many.** The ceiling alone gave 133 tiles to the birch and 349 to the maple, whose leaves' texels are coarse:
+  memory cannot stop variety the eye cannot tell. So the count is the fewest tiles that draw every cut at a size the
+  tree's own leaves grow to: a cut magnifies its representative's leaves by their size ratio, and the tree's leaves
+  span 0.84-1.16 of their median (10th to 90th percentile of `attachments.scales`), so within that a magnified leaf is
+  one the tree grows. Greedy set cover, within the ceiling; among the representatives that draw a cut so, it takes the
+  least unlike (leaf coverage, where it hangs). Holding coverage and hang to the leaf spread too left half the oak's
+  cuts unmatched at 48 tiles: cut shapes vary far more than leaves.
+- **Placement.** A cut draws its representative on its own plane, as large as it draws (its leaves' cards and its
+  twigs' bands: sized by its extent instead, the shrub's LOD0 crown density fell from .67/.62 to .55/.45), hanging
+  where it hangs, turned so each runs out from where it hangs the same way.
+- **Pressing per card.** A leaf on cuts of two LODs was pressed twice in place, onto the second card from the first:
+  the spruce's atlas came out 16% over its budget. Every card now presses its own copy.
+
+**Each preset, seed 1337:** tiles (from LOD0/1/2), the magnification at LOD0 (10th/50th/90th percentile), the atlas.
+
+| preset | tiles | LOD0 magnification | atlas | KiB/m^2 (ceiling 235) |
+| :--- | :--- | :--- | ---: | ---: |
+| oak | 11 (8/2/1) | 0.88/1.00/1.12 | 6.11 MiB | 213 |
+| willow | 16 (12/0/4) | 0.89/1.00/1.11 | 5.41 MiB | 155 |
+| birch | 17 (13/1/3) | 0.87/0.99/1.12 | 0.45 MiB | 24 |
+| maple | 15 (10/1/4) | 0.92/1.00/1.10 | 0.29 MiB | 13 |
+| pine | 19 (9/6/4) | 0.87/1.04/1.67 | 9.95 MiB | 235 |
+| spruce | 17 (1/15/1) | 0.44/1.00/2.36 | 4.09 MiB | 235 |
+| shrub | 11 (3/7/1) | 0.90/1.93/3.09 | 1.36 MiB | 210 |
+| palm | 1 (1/0/0) | 0.97/1.07/1.14 | 0.05 MiB | 2 |
+| fern | 3 (2/0/1) | 0.87/1.12/1.23 | 0.02 MiB | 56 |
+
+The oak's LOD0 leaves read as lobed oak leaves, the willow's as lanceolate ones, the maple's as palmate ones
+(screenshots at the playground's closest zoom). Triangles and joints are unchanged; the atlas and its LOD0 cards are
+built in 0.0-3.2 s.
+
+**The look**, FIA crown density side/below, against one tile per cut (L3):
+
+| preset | LOD0 | LOD1 | LOD2 | L3 LOD0 / LOD2 |
+| :--- | :--- | :--- | :--- | :--- |
+| oak | .46/.45 | .45/.45 | .42/.42 | .47/.46 / .41/.43 |
+| willow | .69/.67 | .69/.67 | .65/.63 | .71/.70 / .66/.65 |
+| birch | .52/.74 | .53/.66 | .53/.68 | .54/.73 / .49/.66 |
+| maple | .44/.41 | .43/.39 | .40/.39 | .44/.40 / .38/.32 |
+| pine | .27/.34 | .24/.30 | .28/.36 | .30/.35 / .27/.32 |
+| spruce | .25/.38 | .24/.39 | .23/.43 | .24/.39 / .19/.38 |
+| shrub | .68/.57 | .59/.57 | .49/.43 | .67/.62 / .60/.56 |
+| palm | .65/.37 | .65/.37 | .68/.55 | .68/.40 / .65/.39 |
+| fern | .61/.12 | .61/.12 | .54/.45 | .58/.13 / .45/.39 |
+
+**Measured open items.**
+- **The shrub's coarser LODs lose density**: LOD1 .59/.57 and LOD2 .49/.43 against .67/.62 and .60/.56. Its LOD1 is
+  drawn to LOD0's error, so its representatives are baked at that error (2.8 cm), coarse against its 9 cm leaves.
+- **The texture ceiling stops the cover first** on the shrub and the conifers, whose cuts at the leaf's texel cost
+  more than their budgets: one median shrub cut (54 cm at 1.2 mm) is 2 MB against its 1.4 MB. Their LOD0 cuts are
+  magnified past the leaf spread, the shrub's 1.93x at the median and 3.09x at the 90th percentile, the spruce's up
+  to 2.36x (one LOD0 tile), the pine's up to 1.67x. The pine's LOD1 loses .06 of density.
+- **Birch twigs are drawn in the bark's colour**, white (`bark_material.primary_color`), since L2.
+- **The palm's leaf `finest` skips its terminal leaflet** (`leaf_geometry`, compound leaves): its outline, which counts
+  it, is finer than its finest feature.
+
+## The palm's cluster cards (2026-10-28)
+
+**What was wrong** (Alex's screenshots of the palm at LOD0): blurred fronds with ragged holes, the cards standing
+upright.
+
+- **Upright cards.** A card's plane was fitted to where its leaves attach, its twigs' middles and where it hangs. A
+  palm's leaves (each a 1.7 m compound leaf, 9-14 to a frond) attach along a rachis that arches in a vertical plane, so
+  every frond's card stood in that plane: 43-90 degrees from horizontal. The crown seen from below was .37 dense
+  against .70 drawn leaf by leaf; the fern's .12 against .65. The plane is now fitted to what the card draws, its
+  leaves' cards and its twigs' bands each by its area: the palm's cards are 9-89 degrees from horizontal, and its crown
+  .59/.69 from the side and below against .62/.70 leaf by leaf (the fern .42/.63 against .47/.65).
+- **Blur.** The legible texel of a compound leaf is its leaflets' outline, the 20 cm leaflet four texels across: 49.6 mm,
+  a frond 77 x 65 texels, though the palm spent 0.05 of its 5.1 MiB budget. LOD0 is now drawn at the finest texel the
+  ceiling affords for its whole cover: the leaf material's own (`FoliageTileLayout.texel`, the palm's 13.2 mm),
+  coarsened by halves while the cover does not fit, never past the legible texel.
+- **Holes.** A frond's tile is its compound leaves pressed onto one plane; the notches between their leaflets show
+  through, and at 49.6 mm were ragged blotches. At 13.2 mm they are the notches.
+
+**LOD0 texels now:** maple 2.07 mm (was 8.50), birch 4.88 (9.38), palm 13.2 (49.6), fern 13.9 (25.5); the oak's
+1.41, the willow's 3.91, the shrub's 1.20 and the conifers' are where the ceiling held them.
+
+**The look**, FIA crown density side/below, against every leaf drawn as its own card:
+
+| preset | LOD0 | LOD1 | LOD2 | leaf by leaf |
+| :--- | :--- | :--- | :--- | :--- |
+| oak | .46/.46 | .45/.45 | .42/.42 | .48/.53 |
+| willow | .70/.68 | .70/.68 | .66/.64 | |
+| birch | .52/.72 | .53/.67 | .53/.67 | |
+| maple | .43/.43 | .42/.41 | .40/.40 | |
+| pine | .26/.32 | .25/.28 | .22/.27 | |
+| spruce | .24/.39 | .24/.40 | .22/.40 | |
+| shrub | .67/.60 | .59/.58 | .53/.51 | .67/.70 |
+| palm | .59/.69 | .59/.69 | .57/.67 | .62/.70 |
+| fern | .42/.63 | .42/.63 | .50/.61 | .47/.65 |
+
+The palm is drawn with one tile for its 12 fronds (its fronds magnified 0.91-1.06), 0.76 MiB.
+
+## Tiles drawn past the leaves' spread (2026-10-28)
+
+**What was wrong** (Alex's screenshot of the pine, seed 60557, LOD0 in the playground): thick logs among the
+branches, some thicker than the trunk beside them. They were tiles' twigs, magnified. Where the texture ceiling could
+not hold a cover within the leaves' spread at the legible texel, the choice stopped at legible and drew the cuts no
+tile covered with the least unlike of all, at any size. A pine's LOD0 cuts are whole boughs, 3.5 GB of their own tiles
+at 0.8 mm against a 9.9 MiB ceiling: 86% of its LOD0 cover (by area) was drawn past the spread, magnified up to 10.8x;
+the spruce's up to 15.6x; the shrub's tiles shrunk down to 0.02x. "Up to 1.67x" above was the 90th percentile.
+
+**The fix.** No cut is drawn at a size the tree's leaves do not grow to: LOD0's texel keeps halving past the legible
+texel until the cover fits. A blurred leaf is still the tree's leaf; a magnified tile is another tree. The loop ends: a
+cut's size is never under a texel, so at a texel as large as every cut one tile draws them all.
+
+**Each preset**, LOD0 texel and FIA crown density side/below per LOD, before / after (seed 1337; 60557 where it differs):
+
+| preset | LOD0 texel | LOD0 | LOD1 | LOD2 | atlas |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| oak | 1.41 / 2.83 mm | .46/.46 / same | .45/.45 / same | .42/.42 / same | 824x804 / 502x505 |
+| pine | 0.80 / 6.4 mm | .26/.32 / .26/.31 | .25/.28 / .26/.31 | .22/.27 / .25/.37 | 1038x1005 / 625x650 |
+| spruce | 0.50 / 4.0 mm | .24/.39 / .25/.40 | .24/.40 / .24/.40 | .22/.40 / .22/.38 | 1057x402 / 421x417 |
+| shrub | 1.20 / 4.8 mm (60557: 9.6) | .67/.60 / .64/.58 | .59/.58 / .64/.58 | .53/.51 / .59/.52 | 433x368 / 341x351 |
+
+The willow, birch, maple, palm and fern fitted at or before legible and are drawn byte for byte as before.
+The conifers' generation takes 1-2 s longer (single runs on a busy machine); the pine's choice ~5.0 s against
+~3.4 s (paired, 3 runs each).
+
+**Measured open items** (independent review):
+- **A cut's wood can be drawn thicker than it grew without magnification.** A cut is matched to a tile by the size of
+  its leaf and wood area together, so a few needle shoots on 44 mm of 4 mm twig (pine 60557, LOD0 cut 791) are drawn
+  with a tile of the same area that is mostly 1.2 m of bough up to 27.5 mm across. Pine 60557: 58 of 881 LOD0 cuts
+  draw more than 3x the wood area they grew (89 before); thickest drawn wood over thickest grown at most 5.3x (20.6x
+  before). Maple up to 4.8x, birch 4.2x, oak LOD2 9.6x.
+- **A tile's wood runs off its cut's own wood**: on pine 60557 the angle between them is 10 degrees at the median,
+  27 at the 90th percentile, 12-15 cuts over 45 degrees, unchanged by this fix.

package/src/generation/foliage/REAL_TIME_TREES_BRIEF_2026_10_27.md

@@ -0,0 +1,86 @@
+# Real-time trees: what went wrong and the way back (2026-10-27)
+
+## What the trees cost, commit by commit
+
+Seed 1337, triangles as bark + foliage, measured by generating each preset at each commit.
+
+| commit | date | change | oak LOD0 | willow LOD0 | spruce LOD0 | birch LOD0 | most joints |
+| :--- | :--- | :--- | ---: | ---: | ---: | ---: | ---: |
+| 309efebfa | 10-21 | posture and bark | 23k | 38k | 16k | 13k | 32 |
+| 00807d697 | 10-24 | generator graph | 11k | 16k | 11k | 6k | 32 |
+| 3976c5287 | 10-24 | derived wind joints | 11k | 35k | 10k | 6k | 517 |
+| ced837088 | 10-26 | oak twigs as meshed shoots | 83k | 35k | 10k | 6k | 5,703 |
+| 49845ff00 | 10-26 | every species' twigs; crown fills by light | 88k | 637k | 1,108k | 658k | 35,697 |
+| 7d610267e | 10-26 | a card is one leaf | 237k | 1,088k | 1,790k | 838k | 40,466 |
+| 4a3a41928 | 10-27 | S1: pine from the seed | 250k | 1,197k | 1,209k | 615k | 40,620 |
+
+Through 10-25 no tree was over 38k triangles at LOD0, and they were real-time. Two changes multiplied the cost:
+
+1. **Twigs became meshed branches** (ced837088 for the oak, 49845ff00 for all species). Every shoot is now a tube with its own rings and joints. The bark went from about 8k to 400k–860k triangles, and the joints from hundreds to tens of thousands.
+2. **A card became one leaf** (7d610267e). Foliage went up 3–12×, to 678k triangles on the willow.
+
+The LODs share the skeleton. LOD1 and LOD2 drop every branch below level 2 or under 1.5–3.5 cm, which takes away all the twig wood: bark falls to about 3k triangles. But they keep 55% and 28% of the per-leaf cards, scaled up to compensate. So a willow's LOD2 is still 145k triangles, made of single leaves floating where the twigs were. That is why they look bad at any triangle count anyone would ship.
+
+## How I got there
+
+- **The look was the goal, and I made botany the goal.** On 10-25 Alex said the appearance and flexibility of the generator matter more than real-world accuracy. Each request after that (the oak looks barren, these aren't oak leaves, the crowns look naked) was about the look. I answered each one by modelling more botany, at full resolution, straight into the render mesh.
+- **I had already written down the answer.** `SPEEDTREE_COMPARISON_2026_10_24.md` says individual leaves on thin 3D twigs blow out triangle counts and quad overdraw. It says SpeedTree bakes twig-and-leaf clusters into atlases and places 150–400 cluster cards to show 500k triangles of detail in 3k–8k. Two days later I built the opposite.
+- **The cost was a footnote three times.** "Birch now needs about 45,000 wind joints and 1.1 million triangles" (10-26). "Triangle counts went up ... willow about 1.1M" (10-26). "The pine went from 5k to 85k skeleton nodes and about 700k triangles" (10-27). Each time I listed it under open items and carried on.
+- **I removed the safety net and called it principled.** I raised `max_joints` to 65,536 because the derived count passed the cap. I used "derive counts, no round-number budgets" to justify unbounded counts, when that rule is about deriving the right count, not about never stopping.
+- **I reached for the engine.** When a twig seat on a twig needed six joints, I recommended eight skinning influences. A tree that needs that is the defect.
+
+## The way back
+
+**The simulation is a generator, not the mesh.** The shoot simulation earns its place: it decides where wood and leaves go, so crowns fill by light without knobs. What it produces should be represented at the detail the screen can show, never drawn shoot for shoot.
+
+1. **A cost gate next to the leaf gate.** Triangles per LOD and joints for every preset, per square metre the tree shows from the side, measured on every stage and reported as pass/fail. A regression stops the stage. Built: see the gate below.
+2. **Each LOD is the tree at a geometric error, one knob in world units.**
+   - Wood thinner than a LOD's error is not meshed.
+   - Rings and spine samples are as many as keep the surface within that error.
+   - That is the "physical tolerance" rule applied to geometry, instead of today's authored chain of scales and level cuts.
+3. **What a cut branch carries becomes a cluster card.**
+   - The simulated twigs and leaves below a cut are baked orthographically into an atlas tile, using the leaf rasterizer we already have.
+   - A handful of representative clusters per species are reused across the crown with each cut's transform, which is how SpeedTree gets 150–400 cards.
+   - Leaves stay botanically drawn inside the tiles; the card count follows the wood, not the leaf count.
+4. **The wind rig runs on each LOD's wood.**
+   - The tolerance knob is unchanged.
+   - Joints follow the meshed branches, so they drop with the twigs.
+   - A cluster card takes its cut branch's joint and its parent's, so no seat meets more than four joints.
+5. **Far LOD: an impostor.** `engine/graphics/impostors/octahedral` exists on the older renderer. Whether to port it to shade is its own decision, after 1–4.
+
+## Decisions (2026-10-27)
+
+- **F1 (Alex: per size, tuned against a metric is fine; mine to choose).** Cost is per square metre a tree shows from the
+  side: the mean side area of its drawn envelope (per-slice convex hulls, Cauchy's mean width). A tree twice the size
+  may spend four times the triangles. Volume was the other candidate. At the last real-time commits the shrub's density
+  per m^2 sits inside the trees' range (423 against 254-753 at 6aff5265e, 371 against 339-585 at 309efebfa), but per
+  m^3 it is 2-4 times above them: volume grows faster than what a tree costs to draw. Side area is also what the
+  screen pays for.
+- **F2 (Alex: yes).** One card per leaf goes; leaves are drawn inside baked cluster tiles.
+- **F3 (mine).** S2 is parked on `claude/s2-wood-from-leaf-parked` (0efafb11d), with its one failing assertion
+  recorded. S3-S6 wait. The plan resumes only for what the look needs, and only within the gate.
+
+## The gate (built)
+
+`analysis/tree_render_cost.js` measures every LOD's triangles and the joints per m^2 of side area.
+`TREE_RENDER_COST_CEILING` is the densest of the presets at 6aff5265e: 752.6 triangles per m^2 at LOD0 (willow), 407.6
+at LOD1 (willow), 97.0 at LOD2 (shrub), and 17.03 joints per m^2 (shrub).
+
+Every preset on master, seed 1337, against the ceiling:
+
+| preset | side area | LOD0 | LOD1 | LOD2 | joints |
+| :--- | ---: | ---: | ---: | ---: | ---: |
+| oak | 30.9 m^2 | 250k, 10.7x | 103k, 8.2x | 34k, 11.5x | 4,357, 8.3x |
+| pine | 43.6 m^2 | 641k, 19.5x | 61k, 3.4x | 16k, 3.8x | 11,576, 15.6x |
+| birch | 20.1 m^2 | 615k, 40.7x | 180k, 22.0x | 60k, 30.7x | 15,018, 43.9x |
+| willow | 36.8 m^2 | 1,197k, 43.3x | 432k, 28.8x | 145k, 40.8x | 40,620, 64.9x |
+| maple | 24.8 m^2 | 184k, 9.9x | 72k, 7.1x | 24k, 9.9x | 1,180, 2.8x |
+| spruce | 18.9 m^2 | 1,209k, 84.9x | 259k, 33.5x | 131k, 71.2x | 8,130, 25.2x |
+| palm | 24.8 m^2 | 4k, within | 2k, within | 0.5k, within | 65, within |
+| shrub | 6.6 m^2 | 124k, 24.9x | 44k, 16.2x | 14k, 22.5x | 4,119, 36.6x |
+| fern | 0.42 m^2 | 2k, 6.6x | 0.9k, 5.4x | 0.1k, 2.3x | 24, 3.4x |
+
+Every woody preset fails at every LOD, by 2.8x (maple's joints) to 85x (spruce at LOD0). The palm is within. The fern
+already failed at 6aff5265e (7,065 per m^2, a 0.4 m plant of 3.5k triangles). A spec holding every preset under the ceiling
+lands, red then green, with the change that brings them under it.
+