@woosh/meep-engine 3.58.0 → 3.59.0

package/src/generation/foliage/TWO_FRONT_ENDS_BRIEF_2026_10_28.md

@@ -0,0 +1,552 @@
+# Two growth front ends on one pipeline (2026-10-28)
+
+Alex, 2026-10-28: the botanical generator is very slow. Can we keep it for beautiful, highly detailed trees, and add a
+graph generator for real-time ones? Only if the two share most of their code.
+
+They can. Both front ends grow a `TreeSkeleton` and its leaves, and everything after that point is shared. This brief
+covers three things: the contract both front ends fill, how the graph's presets get their density, and how the graph
+tree's cards come from a botanical prototype grown once per species.
+
+## Measured (master b8c61d89e, seed 1337)
+
+### Where the code sits
+
+Source lines, specs excluded:
+
+| part | lines | what |
+| :--- | ---: | :--- |
+| shared | ~14k | `TreeSkeleton`, pipe radii, joint mechanics, rig, bark mesh, attachments, clusters, cards, representatives, atlas, LOD plan, cost gate, wind, materials, analysis |
+| botany only | ~2.9k | `shoot_systems_simulate`, `ShootLightField`, `ShootWoodHash`, `ShootFrameworkHash`, `ShootGirth`, `shoot_demography`, `shoot_geometry`, `tree_skeleton_grow_shoots`; `ShootSystemRule`, `ShootGrowthConfig`, `ShootBudZone` |
+| graph only | ~2.7k | the rule part of `tree_skeleton_grow`; `BranchSpawnRule`, `BranchGeneratorConfig`, `FoliageSpawnRule`, `crown_envelope_evaluate` |
+
+The graph front end exists already. Each tree grows its framework with it, then `tree_skeleton_grow_shoots` grows
+the twigs on top. The palm and the fern use the graph alone, and so does any preset whose `shoot_rules` is empty.
+
+### What each front end costs
+
+Times are for the whole asset, every LOD built.
+
+| preset | nodes, botany → graph | leaves, botany → graph | whole asset, botany → graph |
+| :--- | :--- | :--- | :--- |
+| oak | 9,856 → 766 | 30,017 → 6,714 | 4.3 → 2.0 s |
+| pine | 78,275 → 18 | 14,082 → 10 | 9.4 → 0.9 s |
+| birch | 48,695 → 401 | 53,174 → 4,510 | 6.4 → 0.9 s |
+| willow | 64,234 → 723 | 129,056 → 23,634 | 12.5 → 1.5 s |
+| maple | 10,854 → 604 | 20,862 → 5,838 | 4.6 → 1.3 s |
+| spruce | 109,725 → 690 | 116,185 → 18,377 | 7.9 → 1.5 s |
+| shrub | 7,131 → 84 | 12,863 → 471 | 1.2 → 0.6 s |
+
+The graph-only trees are bare. The presets' framework rules were thinned for the shoots to fill. The pine has no graph
+framework at all: since S1 (4a3a41928) it grows from its seed.
+
+### Where a graph-only tree spends its time
+
+| preset | atlas and LOD0 cards | bark and leaf materials | everything else |
+| :--- | ---: | ---: | ---: |
+| oak | 1.09 s | 0.28 s | ~0.3 s |
+| willow | 0.92 s | 0.33 s | ~0.4 s |
+| spruce | 1.49 s | 0.38 s | ~0.3 s |
+| maple | 0.71 s | 0.64 s | ~0.3 s |
+| birch | 0.38 s | 0.52 s | ~0.1 s |
+
+The atlas and the materials depend on the species, not the tree, yet every tree computes them again.
+
+### Which wood the LODs draw
+
+The botanical trees, with framework branches (grown by the graph) counted apart from shoot branches (grown by
+`tree_skeleton_grow_shoots`):
+
+| preset | LOD0 error | framework drawn at LOD0 | shoots drawn at LOD0 | shoot orders drawn | shoots drawn at LOD1 |
+| :--- | ---: | ---: | ---: | ---: | ---: |
+| oak | 2.0 cm | 115 / 117 | 33 / 2,515 (1.3%) | 2 | 0 |
+| pine | 2.8 cm | 1 / 5 | 252 / 9,225 (2.7%) | 3 | 252 |
+| birch | 2.8 cm | 44 / 54 | 131 / 16,851 (0.8%) | 3 | 50 |
+| willow | 4.0 cm | 76 / 83 | 121 / 21,464 (0.6%) | 2 | 121 |
+| maple | 2.8 cm | 79 / 86 | 1 / 4,331 (0.02%) | 1 | 0 |
+| spruce | 2.8 cm | 116 / 151 | 35 / 31,720 (0.1%) | 2 | 3 |
+| shrub | 2.8 cm | 12 / 17 | 31 / 2,416 (1.3%) | 3 | 31 |
+
+- At least 97% of the simulated shoots are never drawn as wood at any LOD; they end up inside cluster cards.
+- The graph's framework is nearly all of LOD0's wood.
+- The exceptions are the pine and shrub, whose framework is shoots, and the birch and willow, which draw 121–131
+  shoots up to three orders deep.
+
+## The design
+
+**One pipeline, two front ends.**
+- The botanical front end is today's generator, unchanged, per-tree bake included. It serves hero trees.
+- The graph front end grows only the framework. On each terminal carrier it hangs a prototype: the species' shoot
+  system, grown once by the botanical front end. The prototype supplies the carrier's drawn twigs, its cluster cards
+  and their tiles.
+- Each species is grown botanically once, and every tree of that species shares the result.
+- Everything downstream of the skeleton is shared. A shared spec runs it on both front ends.
+
+### Reuse map
+
+| piece | graph front end | botanical front end |
+| :--- | :--- | :--- |
+| framework: `tree_skeleton_grow` (graph rules, roots, flare, self-pruning, scars) | unchanged | unchanged |
+| `tree_skeleton_compute_pipe_radii`, joint mechanics, `tree_skeleton_assign_skin_joints` / `_bind_` | unchanged | unchanged |
+| `tree_skeleton_grow_shoots`, `shoot_systems_simulate` | run once per species, on the prototype's carrier | per tree, unchanged |
+| `tree_mesh_compute_branch_rings`, `tree_mesh_build_bark` | unchanged, over framework plus grafted prototype wood | unchanged |
+| `tree_clusters`, `tree_cluster_cards`, `_press`, `_tiles`, `_atlas_pack`, `_bake` | run on the prototype, once per species | per tree, unchanged |
+| `tree_cluster_representatives` | its cover chosen over the prototypes | per tree, unchanged |
+| `tree_mesh_build_clusters` | placement from prototype instances (changed) | unchanged |
+| `tree_lod_plan` | counts prototype instances at each candidate error (changed) | unchanged |
+| `foliage_collect_attachments` | a carrier with a prototype has no leaves of its own (changed) | unchanged |
+| `make_bark_material`, `make_foliage_material` | cached per species (new cache, same code) | per tree, unchanged |
+| `tree_render_cost`, `TREE_RENDER_COST_CEILING` | same gate | same gate |
+| new | the prototype (grow, cut, bake, cache), carrier spacing from its sleeve, the graft | none |
+
+## The skeleton contract
+
+Downstream reads each field below. Today's writers:
+
+| field | read by | graph writes | shoots write |
+| :--- | :--- | :---: | :---: |
+| nodes, segments, frames, radii, `t_norm`, `arc_s`, branch chain, parent, `attach_t`, length, base radius | everything | yes | yes |
+| `branch_generator` | attachments (`foliage_rules[].source`), bark (`species.branches[g]`), rig (`root`), mechanics, pipe radii | yes | yes (rule target) |
+| `branch_level` | rig bend limit, bark, attachments, girth | yes | yes |
+| `branch_dead` | attachments, bark, mechanics, pipe radii | yes (self-pruning) | yes (burial) |
+| `branch_unit_offset` / `_count`, `unit_start_t` | attachments (leaves per annual unit), mechanics, `foliage_unit_cards` | no | yes |
+| scars | bark knots, bark material | yes | no |
+| `crown_center`, `crown_radii` | attachments, cards, AO, bark, senescence | yes | yes, every season (G0 review: one law since, `tree_skeleton_fit_crown_frame`) |
+| `branch_phase_hash` | attachments, bark, unit cards | yes | yes |
+| joints, `joint_rotation` | rig, bind | (written by the rig, after growth) | (written by the rig, after growth) |
+
+The contract is already nearly symmetric:
+- Annual units are the one field only the shoots write.
+- `foliage_collect_attachments` already has a branch for a carrier without units: it derives the carrier's leaf count
+  from the card density.
+
+The graph front end adds one record: which carriers hang a prototype, which prototype, at what scale and turn. That
+record is new data on the skeleton, not a new branch kind.
+
+**The contract spec** generates every preset with each front end. On each tree it runs the gates every tree must pass:
+- the cost gate;
+- the bark seam and skinning spec;
+- every leaf or card bound to at most 4 joints;
+- the crown-density measure against the botanical tree's.
+
+It loops over the front ends inside plain `test()`s, so a field one front end forgets fails there instead of degrading
+quietly.
+
+## Forks
+
+### G-F1: where the graph stops
+
+**(a) At the framework (mine).** The graph grows its rules' branches. Shoots start where the prototype hangs.
+- Measured: LOD0 draws 89–98% of the framework on the oak, maple, willow and spruce, and 0.02–1.3% of the shoots.
+- The shoots LOD0 does draw (up to 252 on the pine) come from the prototype's own drawn wood (G-F2).
+
+**(b) At the LOD0 error.** The graph keeps growing branches until they thin past the error.
+- This needs graph rules for orders the presets never authored, the twig orders the shoots now grow.
+- It brings back authored densities for exactly the part botany was brought in to derive.
+
+### G-F2: what a prototype carries onto its carrier
+
+**(a) Its drawn wood plus its cuts, at every error on the ladder (mine).**
+- Every LOD error the plan can choose is a √2 step from 1 cm. For each step, the prototype stores:
+  - the wood it draws (shoots thicker than that error, a few branches);
+  - the clusters cut there.
+- When the plan picks an error, each carrier gets the prototype's wood at that error, grafted into the skeleton, plus
+  the prototype's cards at that error. Rig, bark and seams then run on that wood as on any other.
+- `tree_lod_plan` searches the same errors. A prototype's triangles at each error are precomputed, so the plan's cost
+  per candidate does not grow with the shoots.
+
+**(b) One cluster card per carrier.** This loses LOD0's drawn shoots: 252 on the pine, 121–131 on the birch and
+willow. They are the twig wood these trees show up close.
+
+### G-F3: how the graph presets get their density
+
+**(a) From the prototype's sleeve (mine).** This was fork 2 of `CROWN_FULLNESS_BRIEF_2026_10_26.md`, never built.
+- A carrier's shoot system has a measurable reach. The prototype gives it once per species.
+- Terminal carriers are spaced so their sleeves tile the crown envelope, the way card density was derived from the
+  leaf sleeve (`foliage_cards_per_metre`).
+- The terminal rule's `count` becomes an outcome. The scaffold above it keeps today's authored rules, the same ones
+  the botanical presets use for their framework.
+
+**(b) Fitted from a botanical tree.** Grow the species' botanical tree once and measure laterals per metre at each
+order. This costs a whole botanical tree per species, and it fits the graph to one seed's outcome.
+
+**(c) Authored per preset.** Rejected before: "no rule like Oak gets 3 stubs".
+
+### G-F4: what a prototype is grown on, and in what light
+
+**(a) A framework terminal carrier of the species' median length, in open light, for the preset's `age` (mine).**
+- A few prototypes per species, as few as keep the carriers' lengths within the scaling the leaves allow. This is the
+  representatives' rule one level up: a prototype drawn on a carrier is scaled by their length ratio, and that scale
+  must stay within the tree's own leaf-size spread (p10..p90 of `attachments.scales`).
+- With no simulated neighbours, the crown's own shading is lost. The botanical crown sheds shaded shoots; the graph
+  crown keeps them.
+- Open light is what the presets mostly see anyway: 60–100% of candidates are in saturating light (crown fullness
+  brief).
+
+**(b) Sun and shade prototypes, picked by depth in the crown.** Twice the prototypes. Build it only if (a)'s crown
+density measures outside the botanical tree's.
+
+### G-F5: the pine and the shrub
+
+These two have no graph framework: the pine's was removed by S1, and the shrub's is 17 branches with the shoots doing
+the rest.
+
+**(a) Restore the pine's framework rules from 4a3a41928^ (mine).** For the shrub, keep its 17-branch framework and let
+the prototypes do the rest. The botanical pine stays on S1.
+
+**(b) Grow their framework from a botanical run.** Same objection as G-F3 (b).
+
+### G-F6: how callers choose
+
+**(a) An explicit option on `generate_tree`, `growth: TreeGrowth.Graph | TreeGrowth.Botanical`, with Graph as the
+default (mine).** Trees are real-time assets first. A hero tree asks for Botanical.
+
+**(b) A separate entry point per front end.** This duplicates the asset assembly that both front ends share.
+
+### G-F7: the self-organizing plan's S6
+
+S6 removes the graph's crown machinery. With two front ends, the graph is a product, so **S6 is dropped (mine)**.
+S2–S5 stay parked as before, only within the cost gate.
+
+## Decisions (2026-10-28)
+
+Alex took my picks on G-F1 to G-F7. One change of timing: `growth` defaults to Botanical until G3. Until then the
+graph trees are bare, and every caller that passes no `growth` (the playground, `place_tree`) would get them.
+
+## Stages
+
+Each stage gives the cost gate, crown density against the botanical tree, and time per tree, for every preset.
+
+| stage | what | done when |
+| :--- | :--- | :--- |
+| G0 | The contract spec over both front ends; materials cached per species; `growth` option; the pine's framework rules restored | Both front ends pass every shared gate; the graph trees are still bare |
+| G1 | The prototype: a single carrier grown by `tree_skeleton_grow_shoots`, cut and baked at every error, cached by the species hash | Its cost, sleeve and leaf area measured per species |
+| G2 | Carrier spacing from the sleeve (G-F3 a) | Graph crowns' FIA side density within the botanical tree's |
+| G3 | Prototypes on carriers: graft, cards, one atlas per species (G-F2 a, G-F4 a) | Every gate green on both front ends; a graph tree, once its species is cached, no slower than today's graph-only tree without its atlas and materials (0.1–0.4 s) |
+| G4 | Docs: FOLIAGE_DESIGN §7, CHANGELOG, the parked plan's S6 struck | |
+
+Not in scope: runtime LOD switching, impostors, more skinning influences.
+
+## G0 landed
+
+- **Two front ends.** `TreeGrowth.Graph` / `TreeGrowth.Botanical`, passed as `generate_tree`'s `growth`.
+  - `tree_skeleton_grow_framework` is the generator graph alone: the old `tree_skeleton_grow` up to the pipe model.
+  - `tree_skeleton_grow` is that framework, then `tree_skeleton_grow_shoots`.
+- **The contract, measured on every preset (seed 1337).** The botanical tree's first branches are the graph tree:
+  - every node in the same place, on the same branch;
+  - every branch from the same generator, on the same parent;
+  - no annual units on the graph tree.
+- **Girth is the one difference.** The shoots thicken the framework they grow on: a botanical node is up to 1.33x
+  (maple) to 8.8x (birch) the graph tree's radius. The pine's is 50x, as its graph framework is only its seed.
+  A prototype's leaf has to reach the framework's pipe model for the graph tree's wood to match (G3).
+- **The pine's graph framework.** `make_tree_species_preset(preset, overrides, growth)` gives the pine for
+  `TreeGrowth.Graph` the framework it had at 4a3a41928^: an 11.2 m stem, 32 whorl boughs, 14 inter-whorl branches,
+  twigs on both, and needles on all four. It is 10.68 m tall against the seed-grown pine's 10.76 m, less than a year's
+  leader growth apart.
+- **Materials per species.** A `TreeSpeciesCache` passed to `generate_tree` shares each material between the
+  trees whose species make it alike.
+  - The bark material is keyed on `bark_material`, the leaf atlas on `foliage` and `foliage_material`. The atlas
+    is made from a species holding those two alone, so the key is everything it can read. The graph and the
+    seed-grown pine share both.
+  - Each is made when a tree first asks for it, so a tree drawn with the caller's own materials makes none.
+  - Each tree clones the leaf material, so its own leaves' tint scale stays its own.
+  - **Changed for the botanical front end too:** a tree's bark no longer changes with its seed: every bark has the
+    same noise (`make_bark_material`'s own seed). The leaf atlas never depended on the seed (0 texels differ between
+    seeds 1 and 2 on the maple, oak and pine). This follows from sharing materials per species, but none of G-F1 to
+    G-F7 decided it. Per-seed bark would cost a cache entry per seed.
+- **Specs.**
+  - The cost gate, the bark-moves-with-its-rig spec and the each-LOD-on-its-own-rig spec now run on both front ends.
+  - New specs: the framework contract, `growth` picking the front end and the species, the graph pine, and the cache.
+- **Two spec assumptions failed on graph trees; both are the rules working, not defects.**
+  - The graph oak's LOD2 (11.3 cm) needs no joint: its wood, with less leaf to catch the wind, nowhere bends past
+    the error. Its rig is the root alone, so it has no wind rig.
+  - The graph shrub's LOD2 (seed 7) draws 5 branches, 6 ring pairs. The bark spec's guard against checking nothing
+    is now that every drawn branch at every LOD is examined, and 30 ring pairs per tree.
+  - The per-LOD rig test now requires a wind rig exactly when the LOD has a joint beyond the root.
+- **Every preset fits the ceiling on both front ends** (seed 1337, LOD0/1/2 triangles per m², joints per m²):
+
+| preset | graph | botanical |
+| :--- | :--- | :--- |
+| oak | 662/363/64, 10.1 | 565/293/70, 10.3 |
+| pine | 587/287/73, 13.2 | 218/218/43, 4.0 |
+| birch | 626/318/89, 9.7 | 444/233/73, 10.7 |
+| willow | 633/348/72, 16.4 | 397/397/60, 8.2 |
+| maple | 736/308/89, 9.2 | 560/396/59, 5.5 |
+| spruce | 658/334/87, 14.7 | 502/313/61, 11.1 |
+| shrub | 452/313/87, 13.2 | 312/312/77, 10.8 |
+
+  The palm and the fern have no shoot rules and are the same on both.
+
+- **Crown density and time per tree** (seed 1337; FIA side and below density at LOD0; time to every LOD's bark and cards
+  built, with the species' materials made / already in the cache):
+
+| preset | graph density, side / below | graph time | botanical density, side / below | botanical time |
+| :--- | :--- | :--- | :--- | :--- |
+| oak | 0.37 / 0.36 | 1.56 / 1.10 s | 0.46 / 0.46 | 4.35 / 4.16 s |
+| pine | 0.30 / 0.29 | 1.77 / 1.17 s | 0.25 / 0.31 | 14.20 / 13.29 s |
+| birch | 0.24 / 0.31 | 1.10 / 0.60 s | 0.52 / 0.72 | 7.28 / 6.90 s |
+| willow | 0.38 / 0.23 | 1.92 / 1.49 s | 0.71 / 0.68 | 17.31 / 15.35 s |
+| maple | 0.37 / 0.33 | 1.89 / 1.01 s | 0.43 / 0.43 | 6.79 / 5.88 s |
+| spruce | 0.21 / 0.21 | 1.41 / 0.89 s | 0.25 / 0.40 | 11.76 / 11.42 s |
+| shrub | 0.38 / 0.28 | 0.42 / 0.06 s | 0.64 / 0.58 | 1.69 / 1.44 s |
+
+  - The graph trees fall short of the botanical trees' density everywhere except the pine. The pine's graph framework
+    carries needles on the stem, boughs, inter-whorl branches and twigs, and is denser from the side than the
+    seed-grown pine.
+  - With its materials cached, a graph tree's remaining time is mostly its own atlas bake, which G3 replaces with the
+    species' prototype tiles.
+- **Review (independent, adversarial).** It found no defect in the botanical skeleton or geometry. Fixed:
+  - species materials were made even for a tree drawn with the caller's own;
+  - the cache was keyed on the whole config, so the two pines and differently sized crowns made the same atlas twice;
+  - the bark was seeded by a hash that leaves out some of its fields;
+  - the restored pine framework carried `radial_segments_*` keys, which L1 removed;
+  - two spec guards had been weakened for the botanical trees as well;
+  - the pine preset's comment and `place_tree`'s docs were stale.
+  - `growth` is asserted to be a `TreeGrowth`.
+  - Left as they are: `growth` and `cache` reach `generate_tree` only through an options object, not with a
+    preset name or a `TreeSpeciesConfig` instance, as `seed` and the custom materials do.
+
+## Reuse review (2026-10-28)
+
+Alex asked for an adversarial review of G0 focused on sharing before G1. Fixed in G0:
+
+- **One crown frame law.** The framework set the frame from the authored envelope; the shoot simulation rewrote it
+  every season from its own box. Graph and botanical trees disagreed by up to 2.8 m (willow's centre). Both now end
+  on `tree_skeleton_fit_crown_frame`: the box of every living branch a shoot rule grows on or grows. A species
+  without shoot rules keeps its envelope's. The graph oak's centre is now 5.09 m, as the botanical oak's (the
+  envelope gave 6.60). The botanical frame moves slightly, since it now includes the last season's growth.
+- **The graph pine is the seed-grown pine's generators, overridden, with its shoot system.**
+  - Its stem and boughs are the seed-grown pine's, given the framework's length and shape. Its roots and twig
+    system are the seed-grown pine's own objects.
+  - It has the conifer shoot rules on boughs, inter-whorl branches and twigs again. The first restore had dropped
+    them, and G1 grows its prototypes from them.
+  - Its generator numbering still differs from the seed-grown pine's (inter-whorl at 2, roots at 4), since a shoot
+    rule's target must follow every carrier.
+- **The cache is core's `HashMap`**, keyed on the configs' own `hash`/`equals`. A spec now checks every preset's
+  cached atlas and bark against the whole species' materials.
+- **The contract spec checks the frame law on both front ends, and that what died in the framework died in both.**
+
+For G3, measured or read, not settled:
+
+- **Grafting per error breaks the one-skeleton LOD contract** (`tree_lod_plan` nests every LOD's joints on one
+  skeleton). Grafting a prototype's finest wood once and letting `tree_mesh_compute_branch_rings` cull it per error
+  reuses the planner instead of storing wood per error.
+- **A prototype's leaves are lit and tinted for its own crown frame** (facing, maturity, sun, tint) and its cards face
+  away from its own centre. Drawn on a host they need the host's frame.
+- **The host's rig must carry the prototype's leaf load**, or the graph rig stays as under-loaded as G0's (the graph
+  oak's LOD2 has no joint).
+- **The texture gate charges each tree for its whole atlas**, while the atlas becomes the species'.
+- **Girth:** the graph's wood comes from the pipe pass, the botanical from `ShootGirth`. A graft must not add a third
+  law.
+- **The botanical tree is the degenerate case of G3:** its own single prototype, placed once. One path for both
+  instead of a fork in `generate_tree`'s cluster block.
+- **Species-level cutout work still runs per call** (`foliage_atlas_cutout` in the simulation and the joint
+  mechanics: 9-72 ms each, once per rig).
+
+## G1 landed
+
+`tree_shoot_prototypes(species, leaf_material, cutout)`, cached by `TreeSpeciesCache.prototypes`, keyed on the whole
+species but its seed.
+
+- **Where they grow.**
+  - The species' graph framework is grown once, at seed 0.
+  - Each prototype is grown in place on one of the framework's carriers (`tree_skeleton_grow_shoots_on`). So it is as
+    old as that carrier is in the tree, kept out of the framework's wood, and lit by its own leaves alone.
+  - **It stays where it grew.** Every prototype, its carrier and its shoots, is copied where it grew
+    (`tree_skeleton_copy_branches`) into one skeleton, the sheet. The sheet is given the framework's crown frame, so its
+    leaves are collected, cut and baked as the tree's own would be: the same gravity, height and crown.
+- **Which.**
+  - For each generator the shoot rules grow on, the median carrier is grown first. Its leaves' spread
+    (`foliage_scale_spread`: p10/p50 and p90/p50 of their sizes, which the representatives also use) bounds how far a
+    prototype may be scaled.
+  - Prototypes are then added, each the longest carrier whose scaled reach still meets where the last one stopped,
+    until they reach without a gap from the shortest carrier to the longest.
+  - `length` is the carrier's length in the framework, which a host carrier is scaled against.
+- **Cut.**
+  - The sheet is cut at every error from 1 cm in `TREE_LOD_ERROR_STEP` steps (the plan's, now exported) to the first
+    error that draws no wood.
+  - It goes through the same atlas path a tree's own LODs take: `tree_cluster_atlas`, now shared by `generate_tree`,
+    with each error's rings planned once.
+  - The texture budget is the ceiling over the prototypes' side areas together.
+  - `tree_clusters` hangs a whole tree's cut from that tree's own root, so the sheet, which holds a tree per prototype,
+    is cut per prototype. For a single tree that is branch 0's root, as before.
+- **The representatives' greedy was quadratic in cuts.**
+  - Every pick scored every candidate against every cut. The sheet's 10-14 errors made that 85% of the time: the
+    willow's prototypes took 414 s.
+  - It now counts each candidate's undrawn cuts in its size window with a Fenwick tree a LOD. Only the tied candidates
+    sum their unlikeness, over their window, in cut order.
+  - On the same inputs the picks, texels and placements are identical to the bit (oak, shrub, maple, pine, the shrub's
+    prototypes).
+  - The pine's representatives went from 46.4 s to 6.3 s, and the maple's from 2.3 s to 0.55 s. That speeds up every
+    tree's own bake too.
+- **Measured** (seed 1337 species, graph pine; the time is once per species, the atlas bake included):
+
+| species | prototypes | time | tiles | errors | sleeve p90, median (range) | leaf per carrier metre, median | other seeds' carriers out of reach |
+| :--- | ---: | ---: | ---: | ---: | :--- | :--- | :--- |
+| oak | 19 | 10.9 s | 14 | 12 | 0.25 m (0.02-0.97) | 1.10 m²/m | 38 / 450, worst 5.7x |
+| pine | 27 | 16.3 s | 9 | 14 | 0.26 m (0.00-1.16) | 0.18 m²/m | 32 / 553, worst 5.4x |
+| birch | 18 | 16.5 s | 20 | 10 | 0.40 m (0.00-1.13) | 2.03 m²/m | 9 / 166, worst 1.6x |
+| willow | 14 | 39.6 s | 24 | 12 | 0.63 m (0.00-1.48) | 4.10 m²/m | 30 / 248, worst 2.2x |
+| maple | 16 | 7.8 s | 13 | 12 | 0.14 m (0.01-0.41) | 0.93 m²/m | 13 / 298, worst 2.2x |
+| spruce | 27 | 17.6 s | 23 | 14 | 0.15 m (0.00-0.47) | 0.23 m²/m | 45 / 554, worst 4.8x |
+| shrub | 6 | 1.6 s | 23 | 10 | 0.68 m (0.13-1.20) | 7.33 m²/m | 16 / 52, worst 1.8x |
+
+  - The sleeve is the 90th-percentile distance of a prototype's leaves from its carrier. A sleeve of 0.00 is a carrier
+    on which no shoot grew; its own annual units carry its leaves.
+  - "Out of reach" counts the carriers of seeds 1, 7, 4242 and 1337 that no prototype reaches within the leaves'
+    spread. The cover is gapless across seed 0's range, so these are carriers shorter or longer than any seed 0 grew.
+    G3 has to draw them with the nearest prototype, scaled past the spread.
+  - The leaves' size spread is narrow: p10/p50 0.82-0.87, p90/p50 1.11-1.18. Only the spruce's stem is wider, at
+    0.54-2.25. The carriers' lengths span 6x (oak's boughs) to 100x (spruce's twigs).
+- **Review (independent, adversarial).** Fixed:
+  - **The first version lifted each prototype into its carrier's frame.** That turned its leaves' gravity and sky with
+    the carrier: the oak's mean leaf up·Y fell from 0.70 in place to 0.29. All its prototypes were then fitted under one
+    crown frame stacked at the origin. Both made the atlas from leaves no tree grows.
+  - **A gapped cover** left 8-17% of other seeds' oak carriers out of reach.
+  - **Grown lengths:** `length` was the carrier's grown length, extension included, up to 11x the framework's on the
+    pine.
+  - **Copied levels and frame:** copies were re-levelled from their first branch, and a lateral's first node was hung
+    from the start of its parent's segment, not the node it hung from. The new round-trip spec caught the second.
+  - **Duplicated code:** the percentile law and the error step were copies, now shared; the rings were planned twice.
+  - **Weak specs:** a round trip blind to anything untransformed, a cover spec that only restated the greedy, and no
+    check that a prototype keeps the leaves it grew. Now the specs check:
+    - the sheet's wood is the in-place wood, node for node;
+    - its crown is the framework's;
+    - its leaves hang on the same branches at the same points;
+    - the cover is gapless and has no prototype to spare.
+  - A card's turn, size and small offset round its shoot come from the tree's one random stream, in collection order.
+    So a prototype's leaves match the in-place ones in where they hang and in their sun, not card for card.
+
+### G-F8: how many prototypes (new, from G1's measurement)
+
+**(a) Keep G-F4's rule (mine).**
+- It is per-species work, cached, and no tree pays for it: 1.6-39.6 s once per species.
+- It keeps leaves at their own size: the alternative, scaling one prototype across a carrier range 6-100x long, would
+  draw the oak's bough leaves from a third to twice their size (its boughs run 0.62-3.90 m about a 1.9 m median).
+
+**(b) Fewer prototypes, drawn at true size on the carriers nearest their length.** No leaf is scaled, but a host
+carrier longer than its prototype is drawn bare past the prototype's reach, and a shorter one overhangs. That density
+loss would only show at G3.
+
+**G-F8 decided (mine, Alex left it to me, 2026-10-28): (a).** Each species grows its prototypes once, and the
+leaves keep their size.
+
+## G3 landed: prototypes drawn on a graph tree's carriers
+
+Alex, 2026-10-28: the botanical generator is for hero pieces, big meshes that look and move beautifully at LOD0. The
+graph generator is the daily driver, for most trees. Keep the blast radius to the generator, and build for the long
+term.
+
+**How a graph tree draws its prototypes** (`tree_shoot_instances`):
+- **Choice.** Every living carrier takes the prototype of its generator nearest its length in ratio.
+- **Scaled by the ladder.** That ratio is drawn as the nearest power of the error ladder's step (√2): within ±19%,
+  so with the species' leaf spread, at 1, as the prototype grew.
+  - Wood, girth, leaves and cards scale alike, by `TREE_LOD_ERROR_STEP` to the instance's `shift`.
+  - At the tree's error, the tree draws as wood exactly what the prototype's cuts, `shift` steps finer, leave to
+    wood. A host error divided by such a scale is again a step of the ladder.
+- **Turned about the vertical only**, so up stays up, as the prototype's leaves were lit and baked.
+- **The tree's own framework stays**, so a seed still varies the tree. Each carrier keeps its course and takes:
+  - the prototype's growth past its framework's tip (`tree_skeleton_extend_branch`, the shoot simulation's own
+    extension, now shared), turned to continue from the tree's carrier's tip;
+  - its annual units;
+  - its girth.
+- **The wood any LOD can draw** (what the finest error draws) is grafted onto the carrier
+  (`tree_skeleton_copy_branch`, which carries one branch through a placement). Each shoot system lands on the tree's
+  carrier where it hangs on the prototype's. The rig, the bark mesher and the LOD plan take it as the tree's own, so
+  the one-skeleton contract holds and the LODs' joints nest.
+- **Its girth holds together** (`tree_skeleton_floor_girth`): no branch is thinner than what grows from it, and none
+  thickens toward its tip. It only raises.
+- **Everything else is the prototype's** (`tree_shoot_instance_cards`):
+  - Each card's tile lies where the prototype's did, from the place on the tree where it hangs.
+  - It is skinned as the nearest drawn wood holds it (`tree_cluster_hang`, from `tree_clusters`).
+  - It is drawn from the species' atlas through the same `tree_mesh_build_clusters`.
+  - Per tree there is no leaf collection, no cutting, no representatives and no bake.
+- **The skeleton contract gains three records:**
+  - `branch_instance`: the leaf collector leaves an instance's branches to its prototype;
+  - `segment_carried_leaf_area` and `segment_carried_reach`: the shoot systems no LOD draws as wood, weighed by the
+    mechanics' own law (`leaf_area`, now reported). The wind's mechanics load the segment each hangs from.
+- **The LOD plan, the side area and the cost:**
+  - The LOD plan counts the instances' cards (`tree_lod_plan`'s `cards`).
+  - The grown side area includes every leaf the prototypes draw, those on a carrier where the carrier runs
+    (`tree_grown_side_area`'s `carried`).
+  - `TreeAsset.side_area` holds it once, and `tree_render_cost` reads it.
+- **What the asset records.** `TreeAsset.shoot_prototypes` and `shoot_instances` record what a graph tree draws.
+  `tree_crown_opacity` measures a graph tree's leaves from them.
+- **Caching.**
+  - Without a cache, every call shares `TREE_SPECIES_CACHE`: a species' prototypes grow once in a program, and
+    `clear()` lets them go.
+  - A caller's own leaf material bakes the prototypes from it, cached per species and material.
+  - A caller's own species goes through `generate_tree({ species, growth })`.
+
+**Measured** (seed 7 trees, the species already cached; LOD0/1/2 triangles per m² and LOD0 joints per m²). The machine
+ran 30-45% slower than for the G1 numbers, the botanical trees included:
+
+| preset | graph side density / botanical | graph tree / botanical tree | triangles per m² | joints per m² | texture B/m² |
+| :--- | :--- | :--- | :--- | :--- | ---: |
+| oak | 0.51 / 0.46 | 0.88 s / 2.9 s | 606/323/93 | 11.4 | 51,945 |
+| pine | 0.34 / 0.25 | 2.60 s / 9.6 s | 342/342/83 | 5.3 | 45,018 |
+| birch | 0.64 / 0.52 | 1.92 s / 7.2 s | 388/388/54 | 9.3 | 65,931 |
+| willow | 0.74 / 0.69 | 3.55 s / 11.9 s | 371/371/93 | 7.7 | 55,993 |
+| maple | 0.40 / 0.43 | 0.57 s / 5.2 s | 703/371/66 | 7.6 | 23,884 |
+| spruce | 0.23 / 0.25 | 2.22 s / 10.9 s | 518/301/86 | 13.7 | 29,311 |
+| shrub | 0.65 / 0.66 | 0.21 s / 1.4 s | 390/390/57 | 13.6 | 170,215 |
+
+- Every graph tree fits the ceiling. The palm and the fern have no shoot rules and are grown as before.
+- The first tree of a species also grows its prototypes: 1.8 s (shrub) to 44 s (willow).
+- **The review's measures, on oak 7, birch 1337, willow 7, pine 7, spruce 7 and maple 7:**
+  - Carriers thicker than their parents: none (were up to 12x).
+  - Wood drawn while its parent is not: none (were up to 14).
+  - Instance wood drawn unlike its prototype's cuts: 4 of about 196,000 checks, each where the girth floor thickened
+    a carrier to hold what grows from it.
+  - The pine's carriers bend p50 5.7°, p90 10.8° where their growth carries on, against 5.4° and 9.9° on the
+    prototype (were 33-40° p50, up to 143°).
+- **Per tree, the time is the LOD plan** over the grafted wood, whose drawable shoots run to 9,214 branches on the
+  willow. The botanical tree pays the same plan cost. Measured, not argued: G3's done-when, 0.1-0.4 s a tree, is not
+  met above the shrub. It assumed a tree of framework alone. The plan's cost is shared with the botanical front end,
+  and so is its fix.
+- **Looked at** (the playground, LOD0, before the review): the oak, the pine and the willow draw their prototypes
+  along their boughs.
+
+**Review (independent, adversarial), fixed:**
+- **Girth.** Carriers took their prototype's girth unscaled, up to 12x their parent's: wood floated, and cards fell
+  out of step with the wood. Fixed by the ladder-scaled girth and the girth floor.
+- **Extensions** were translated, not turned: 33-40° bends at the junction.
+- **No default cache.** Every caller without one regrew the species' prototypes, 12-43 s each time.
+- **The config form.** `generate_tree(config)` grew any config by the graph, and the botanical pine's seed-grown
+  config became one seed-0 prototype. Now documented, with the `species` option for choosing.
+- **Cards were placed relative to the wood that held them.** When they walked up to it, they moved by up to 1.55 m
+  and popped between LODs.
+- **Leaves on a carrier** were placed along the prototype's course, not the tree's.
+- **The carried reach** was counted from a segment's middle twice.
+- **Duplicated code:** the placement transform and the point on a chain (now `tree_branch_placement_apply` and
+  `shoot_locate_on_chain`).
+- **Specs** that only restated their code, or ran on one tree.
+
+**Open, measured:**
+- **Other seeds' carriers.** Those shorter or longer than any of seed 0's are drawn with the nearest prototype at
+  their ladder scale, past the leaves' spread. That is 2-31% of carriers, up to 5.7x (G1).
+- **Shoot angles.** A shoot leaves the tree's carrier at the angle it left the prototype's, which follows its own
+  course: a p50 of 20° off the tree's local course (review, oak).
+
+## G2 dropped (measured)
+
+G2 was to space a graph tree's carriers by its prototypes' sleeves until its crown filled. It isn't needed:
+- A graph tree's framework is the botanical tree's own, node for node (the G0 contract).
+- Its prototypes fill that framework as the botany does: its side density is within -0.03 to +0.14 of the botanical
+  tree's (above).
+- Respacing the carriers would make its framework differ from the botanical tree's, and break that contract, for
+  density it already has.
+
+## G4 landed
+
+- `generate_tree` grows by the generator graph unless asked otherwise. A preset's name is grown that way too.
+  `make_tree_species_preset` still describes the botanical species unless asked for the graph's (only the pine
+  differs).
+- Specs of per-leaf behaviour (seasons, tints, the leaf-area measure) ask for the botanical tree, which holds its own
+  leaves.
+- The self-organizing framework plan's S6 is struck (G-F7).
+
+## Not measured yet
+
+- The cost of growing a prototype. Its upper bound is the species' whole botanical grow (0.3–5.6 s), once per
+  species. G1 measures it.
+- Whether open-light prototypes keep the crown's density (G-F4). G2 measures it.

package/src/generation/foliage/analysis/tree_crown_opacity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree_crown_opacity.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_crown_opacity.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAVW,OAAO,uBAAuB,EAAE,SAAS;IAExB,GAAG,GAApB,MAAM;IACW,gBAAgB,GAAjC,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,kBAAkB,GAAnC,MAAM;SACN,YAAY,GACV,YAAY,CAqBxB;6BAxD4B,mBAAmB"}
+{"version":3,"file":"tree_crown_opacity.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_crown_opacity.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAVW,OAAO,uBAAuB,EAAE,SAAS;IAExB,GAAG,GAApB,MAAM;IACW,gBAAgB,GAAjC,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,kBAAkB,GAAnC,MAAM;SACN,YAAY,GACV,YAAY,CAqBxB;6BAzD4B,mBAAmB"}

package/src/generation/foliage/analysis/tree_crown_opacity.js

@@ -12,7 +12,8 @@ import { foliage_card_reach } from "../skeleton/foliage_card_density.js";
  * @returns {number}
  */
 function median_card_length(asset) {
-    const attachments = asset.attachments;
+    // a tree grown by its generator graph draws its prototypes' leaves
+    const attachments = asset.shoot_prototypes !== null ? asset.shoot_prototypes.attachments : asset.attachments;
     assert.greaterThan(attachments.count, 0, 'a leafless tree has no card length: pass microhole_radius');
     const scales = attachments.scales.slice(0, attachments.count).sort();
     return foliage_card_reach(foliage_tile_layout(asset.config), scales[scales.length >> 1]);

package/src/generation/foliage/analysis/tree_render_cost.d.ts

@@ -16,12 +16,14 @@ export function tree_envelope_side_area(position_arrays: Array<ArrayLike<number>
  * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
  * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} leaves every leaf's card
  *        (`tree_mesh_build_foliage`), `null` for a leafless tree
+ * @param {Float32Array|null} [carried] the cards of the leaves it draws but does not hold, its shoot prototypes'
+ *        (`tree_shoot_instance_leaves`): positions
  * @returns {number}
  */
-export function tree_grown_side_area(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null): number;
+export function tree_grown_side_area(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null, carried?: Float32Array | null): number;
 /**
  * @typedef {Object} TreeRenderCost
- * @property {number} side_area m^2, `tree_grown_side_area`: what the tree grew shows from the side
+ * @property {number} side_area m^2, `tree_grown_side_area`: what the tree grew shows from the side (`TreeAsset.side_area`)
  * @property {number[]} triangles bark and foliage triangles of each LOD
  * @property {number[]} triangle_density each LOD's triangles per m^2 of `side_area`
  * @property {number[]} joints each LOD's wind joints
@@ -57,7 +59,7 @@ export const TREE_RENDER_COST_CEILING: {
 };
 export type TreeRenderCost = {
     /**
-     * m^2, `tree_grown_side_area`: what the tree grew shows from the side
+     * m^2, `tree_grown_side_area`: what the tree grew shows from the side (`TreeAsset.side_area`)
      */
     side_area: number;
     /**

package/src/generation/foliage/analysis/tree_render_cost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree_render_cost.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_render_cost.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,yDAJW,MAAM,UAAU,MAAM,CAAC,CAAC,WACxB,MAAM,GACJ,MAAM,CA8ClB;AAiBD;;;;;;;;GAQG;AACH,+CALW,OAAO,6BAA6B,EAAE,YAAY,UAClD,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,GAElE,MAAM,CAYlB;AAaD;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,cAAc,CAgC1B;AA/FD;;;;;;;;;;;;GAYG;AACH,uCAFU;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAC,CAE4C;;;;;eAoCpH,MAAM;;;;eACN,MAAM,EAAE;;;;sBACR,MAAM,EAAE;;;;YACR,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;mBACR,MAAM;;;;qBACN,MAAM"}
+{"version":3,"file":"tree_render_cost.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_render_cost.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,yDAJW,MAAM,UAAU,MAAM,CAAC,CAAC,WACxB,MAAM,GACJ,MAAM,CA8ClB;AAiBD;;;;;;;;;;GAUG;AACH,+CAPW,OAAO,6BAA6B,EAAE,YAAY,UAClD,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,YAEpE,YAAY,GAAC,IAAI,GAEf,MAAM,CAelB;AAaD;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,cAAc,CA6B1B;AAjGD;;;;;;;;;;;;GAYG;AACH,uCAFU;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAC,CAE4C;;;;;eAyCpH,MAAM;;;;eACN,MAAM,EAAE;;;;sBACR,MAAM,EAAE;;;;YACR,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;mBACR,MAAM;;;;qBACN,MAAM"}