@woosh/meep-engine 3.60.4 → 3.60.5

package/src/generation/foliage/FOLIAGE_PLAN.md

@@ -1,198 +0,0 @@
-# Meep Procedural Foliage & Tree Generation System — Implementation Plan
-
-This implementation plan translates `FOLIAGE_DESIGN.md` (including all §9 adversarial review resolutions) into concrete, verifiable phases with exact file paths, function signatures, invariants, and co-located Vitest unit test suites.
-
----
-
-## Phase 1: Core Engine Primitives Leveraged (`Graph`, `Transform64`, `Attribute`)
-
-The foliage system directly composes Meep's existing primitives without modifying `BinaryTopology`:
-1. **`Graph` & `Edge` (`src/core/graph/v2/Graph.js`, `src/core/graph/Edge.js`)**: Directed skeletal graph (`EdgeDirectionType.Forward`).
-2. **`Transform64` & `t64_look_rotation` (`src/engine/ecs/transform/Transform64.js`, `t64_look_rotation.js`)**: Per-node and per-attachment 3D position, RMF quaternion orientation (`[R, S, T]`), and radius scale.
-3. **`Attribute` (`src/shade/renderer/geometry/Attribute.js`)**: Typed-array per-node, per-segment, and per-attachment data channels.
-
----
-
-## Phase 2: Species Configuration, Enums, Curves, & Botanical Presets
-Location: `packages/meep-engine/src/generation/foliage/config/` & `presets/`
-
-### Files & Signatures
-1. **`config/CrownEnvelopeType.js`**
-   - Enum: `Conical = 0`, `Spherical = 1`, `Hemispherical = 2`, `Cylindrical = 3`, `TaperedCylindrical = 4`, `Flame = 5`, `InverseConical = 6`, `TendFlame = 7`, `Weeping = 8`.
-2. **`config/PhyllotaxisMode.js`**
-   - Enum: `SpiralGolden = 0`, `AlternateDistichous = 1`, `Tristichous = 2`, `Opposite = 3`, `OppositeDecussate = 4`, `Whorled = 5`.
-3. **`config/FoliageCardType.js`**
-   - Enum: `FoldedVCard = 0`, `CrossCard = 1`, `TriStarCluster = 2`, `RibbedFrond = 3`, `OctagonalCutoutHull = 4`.
-4. **`config/TreePreset.js`**
-   - Enum: `Oak = "oak"`, `Pine = "pine"`, `Birch = "birch"`, `Willow = "willow"`, `Maple = "maple"`, `Spruce = "spruce"`, `Palm = "palm"`, `Shrub = "shrub"`, `Fern = "fern"`.
-5. **`config/BranchLevelConfig.js`**
-   - Fields:
-     - `level = 0`
-     - `segments = 8` (Hermite segments along branch spine)
-     - `radial_segments_max = 12` ($\ge 3$), `radial_segments_min = 4` ($\ge 3$)
-     - `length = 8.0`, `length_variance = 0.1`
-     - `length_profile: AnimationCurve` (scales child length along parent $t \in [0, 1]$)
-     - `radius_ratio = 0.06` (base radius relative to length, or pipe-model tip floor)
-     - `taper = 0.85`, `radius_profile: AnimationCurve`
-     - `bare_length_ratio = 0.25` (bare zone at base of this branch before children spawn)
-     - `child_count = 12` (number of lateral child nodes spawned along this branch)
-     - `phyllotaxis_mode = PhyllotaxisMode.SpiralGolden`, `whorl_count = 3`, `azimuth_jitter = 0.15`
-     - `insertion_angle = 0.75` (radians from parent tangent), `insertion_angle_variation = 0.2`, `insertion_angle_profile: AnimationCurve`
-     - `curvature = 0.15` (total pitch bend in radians), `curve_back = 0.0`, `spiral_twist = 0.0`
-     - `gravitropism = 0.1` (positive bends toward $-Y$, negative bends toward $+Y$), `phototropism = 0.15`
-     - `gnarl_strength = 0.1`, `gnarl_frequency = 0.35`
-     - `split_probability = 0.0`, `split_count = 2`, `split_angle = 0.4`
-     - `flare_amplitude = 0.0`, `flare_height_ratio = 0.18`, `flare_lobes = 5`, `flare_sharpness = 4.0`
-     - `flute_amplitude = 0.0`, `flute_frequency = 6`
-     - `collar_weld_rings = 2`, `collar_length_ratio = 0.08`, `collar_spread_upper = 0.25`, `collar_spread_lower = 0.45`, `collar_normal_blend = 0.85`
-   - Methods: `static from(options)`, `copy(other)`, `clone()`, `equals(other)`, `hash()`.
-6. **`config/CrownConfig.js`**
-   - Fields: `envelope_type = CrownEnvelopeType.Spherical`, `height = 10.0`, `radius = 4.5`, `base_height = 2.0`, `prune_ratio = 0.35`, `space_colonization_weight = 0.25`, `attraction_point_count = 160`, `attraction_radius = 2.5`, `kill_radius = 0.6`, `pipe_model_exponent = 2.3`, `pipe_model_weight = 0.65`, `sky_phototropism_mix = 0.6`.
-   - Methods: `static from(options)`, `copy(other)`, `clone()`, `equals(other)`, `hash()`.
-7. **`config/FoliageConfig.js`**
-   - Fields: `enabled = true`, `card_type = FoliageCardType.FoldedVCard`, `attach_min_level = 2`, `cards_per_branch = 10`, `terminal_rosette_count = 3`, `bare_ratio = 0.2`, `phyllotaxis_mode = PhyllotaxisMode.SpiralGolden`, `whorl_count = 2`, `insertion_angle = 0.85`, `card_width = 0.85`, `card_length = 0.95`, `size_variance = 0.2`, `fold_angle = 0.28`, `arch_height = 0.08`, `camber_droop = 0.1`, `frond_segments = 5`, `phototropism = 0.6`, `gravitropism = 0.25`, `angular_jitter = 0.25`, `normal_puffiness = 0.35`, `ao_core_darkening = 0.35`, `color_variation = 0.08`.
-   - Methods: `static from(options)`, `copy(other)`, `clone()`, `equals(other)`, `hash()`.
-8. **`config/BarkMaterialConfig.js` & `config/FoliageMaterialConfig.js`**
-   - `BarkMaterialConfig`: `resolution = 128`, `primary_color: Color`, `secondary_color: Color`, `moss_color: Color`, `moss_amount = 0.1`, `fissure_frequency = 8`, `fissure_depth = 0.65`, `lenticel_amount = 0.0` (birch horizontal marks), `roughness = 0.85`, `texel_density = 1.5`, `twist_uv = 0.0`.
-   - `FoliageMaterialConfig`: `resolution = 128`, `primary_color: Color`, `secondary_color: Color`, `autumn_tint = 0.0`, `leaf_shape = "lobed"` (`"ovate" | "lobed" | "serrated" | "palmate" | "needle" | "frond"`), `leaflets_per_cluster = 5`, `roughness = 0.58`, `vein_strength = 0.5`.
-9. **`config/TreeWindConfig.js` & `config/TreeLODConfig.js`**
-   - `TreeWindConfig`: `enabled = true`, `max_joints = 32`, `trunk_compliance = 0.012`, `branch_compliance = 0.045`, `natural_frequency = 2.8`, `damping_ratio = 0.32`, `turbulence = 0.28`, `max_bend_angle = 0.65`.
-   - `TreeLODConfig`: `level = 0`, `radial_scale = 1.0`, `longitudinal_scale = 1.0`, `max_branch_level = 3`, `min_branch_radius = 0.0`, `foliage_keep_ratio = 1.0`, `foliage_area_compensation_exponent = 0.42`, `simplify_cards = false`.
-10. **`config/TreeSpeciesConfig.js` + `config/TreeSpeciesConfig.spec.js`**
-    - Combines `name`, `preset`, `seed`, `crown: CrownConfig`, `levels: BranchLevelConfig[]`, `foliage: FoliageConfig`, `bark_material: BarkMaterialConfig`, `foliage_material: FoliageMaterialConfig`, `wind: TreeWindConfig`, `lods: TreeLODConfig[]`.
-    - Methods: `static from(options)`, `applyOverrides(overrides)`, `copy(other)`, `clone()`, `equals(other)`, `hash()`.
-11. **`presets/make_tree_species_preset.js` + `presets/make_tree_species_preset.spec.js`**
-    - `export function make_tree_species_preset(preset = TreePreset.Oak, overrides = {}): TreeSpeciesConfig`
-    - Botanically tuned configurations for `Oak`, `Pine`, `Birch`, `Willow`, `Maple`, `Spruce`, `Palm`, `Shrub`, `Fern`.
-
----
-
-## Phase 3: Skeleton Topology, Rotation-Minimizing Frames, & Hybrid Growth
-Location: `packages/meep-engine/src/generation/foliage/skeleton/`
-
-### Files & Signatures
-1. **`skeleton/TreeSkeleton.js` + `skeleton/TreeSkeleton.spec.js`**
-   - Wraps `graph = new Graph()`, `node_transforms: Transform64[]`, 3 per-node `Attribute`s (`attr_node_branch_info`, `attr_node_spine_param`, `attr_node_joint`), and 4 per-segment `Attribute`s (`attr_segment_endpoints`, `attr_segment_hermite_m0`, `attr_segment_hermite_m1`, `attr_segment_metrics`).
-   - Also holds flat branch metadata table (`branch_count`, `branch_root_vertex: Int32Array`, `branch_tip_vertex: Int32Array`, `branch_level: Uint8Array`, `branch_parent: Int32Array`, `branch_parent_edge: Int32Array`, `branch_length: Float32Array`, `branch_base_radius: Float32Array`, `crown_center: Float32Array(3)`, `crown_radii: Float32Array(3)`).
-   - `add_node(px, py, pz, tx, ty, tz, rx, ry, rz, radius, branch_id, level, parent_branch_id, t_norm, arc_s, phase_hash): number`
-     - Adds node `v` to `this.graph`, populates `this.node_transforms[v]` (`Transform64` with `setTranslation`, `t64_look_rotation`, `setScaleScalar(radius)`, `updateMatrix()`), and writes per-node `Attribute`s.
-   - `add_segment(v0, v1, m0x, m0y, m0z, m1x, m1y, m1z, length, parent_attach_t): number`
-     - Creates a directed `EdgeDirectionType.Forward` edge `v0 -> v1` in `this.graph` and writes per-segment `Attribute`s.
-   - `evaluate_segment_position(out, out_offset, edge_id, u)` & `evaluate_segment_tangent(out, out_offset, edge_id, u)`:
-     - Evaluates 3D cubic Hermite position/derivative via `spline3_hermite` / `spline3_hermite_derivative`.
-   - `copy(other)` & `clone()`:
-     - Deep-copies `this.graph`, `this.node_transforms`, and all `Attribute` buffers.
-2. **`skeleton/crown_envelope_evaluate.js` + `skeleton/crown_envelope_evaluate.spec.js`**
-   - `export function crown_envelope_evaluate(envelope_type, h_norm, prune_width_peak = 0.6, power_low = 1.5, power_high = 1.5): number`
-   - Evaluates the normalized radial envelope $S_{\text{env}}(h_{\text{norm}}) \in [0.05, 1.0]$ for all 9 `CrownEnvelopeType` modes.
-   - `export function crown_envelope_sdf(px, py, pz, crown_config): number` — signed distance to the 3D crown envelope around `+Y` trunk axis.
-3. **`skeleton/spine_frame_double_reflection.js` + `skeleton/spine_frame_double_reflection.spec.js`**
-   - `export function spine_frame_double_reflection(out, out_offset, x0, y0, z0, tx0, ty0, tz0, rx0, ry0, rz0, x1, y1, z1, tx1, ty1, tz1): void`
-   - Computes Wang et al. (2008) fourth-order Rotation-Minimizing Frame `[Rx1, Ry1, Rz1, Sx1, Sy1, Sz1]` at `(x1, y1, z1)` with full guards for $c_1 \le 10^{-12}$ (`tube_frame_transport` fallback), $c_2 \le 10^{-12}$ (identity second reflection), and Gram-Schmidt re-orthonormalization.
-4. **`skeleton/tree_skeleton_grow.js` + `skeleton/tree_skeleton_grow.spec.js`**
-   - `export function tree_skeleton_grow(config, out = new TreeSkeleton()): TreeSkeleton`
-   - Seeds `seededRandom(config.seed)` and computes a seed-derived 3D noise offset $\mathbf{o}_{\text{seed}}$.
-   - Populates space colonization attraction points in the crown envelope and builds `PointHashGrid3` once with `cell_size = config.crown.attraction_radius` and an external `Uint8Array` `alive` mask.
-   - Generates trunk ($l=0$) and recursive branch levels ($l=1 \dots L_{\max}$), handling phyllotaxis, `AnimationCurve` profiles, gravitropism (along $-Y$), phototropism (toward $+Y$ and radial crown exterior), `curl_noise_3d` gnarl, dichotomous/sympodial splitting, RMF transport, and Hermite tangent fitting.
-5. **`skeleton/tree_skeleton_compute_pipe_radii.js` + `skeleton/tree_skeleton_compute_pipe_radii.spec.js`**
-   - `export function tree_skeleton_compute_pipe_radii(skeleton, config): void`
-   - Post-order bottom-up pass over `skeleton.topology` vertices, accumulating $R_{\text{pipe}}(v) = (R_{\text{tip}}^\alpha + \sum_{e=(v\to u)} R_{\text{pipe}}(u)^\alpha)^{1/\alpha}$ and blending with parametric taper `radius_profile.evaluate(t)` via `config.crown.pipe_model_weight`.
-6. **`skeleton/tree_skeleton_assign_skin_joints.js` + `skeleton/tree_skeleton_assign_skin_joints.spec.js`**
-   - `export function tree_skeleton_assign_skin_joints(skeleton, max_joints = 32): { joint_count: number, joint_vertex_ids: Int32Array, joint_parents: Int32Array, joint_positions: Float32Array, joint_levels: Uint8Array, joint_phases: Float32Array }`
-   - Selects up to `max_joints` structural skeleton nodes in topological pre-order (`joint_parents[j] < j`) and assigns every skeleton vertex its `[primary_joint, parent_joint]` indices in `layer_node_joint`.
-
----
-
-## Phase 4: Bark & Foliage Mesh Synthesis, Collar Welding, & Canopy AO
-Location: `packages/meep-engine/src/generation/foliage/mesh/`
-
-### Files & Signatures
-1. **`mesh/branch_collar_project.js` + `mesh/branch_collar_project.spec.js`**
-   - `export function branch_collar_project(out_pos, out_pos_offset, out_norm, out_norm_offset, ring_x, ring_y, ring_z, tube_nx, tube_ny, tube_nz, child_tx, child_ty, child_tz, parent_px, parent_py, parent_pz, parent_tx, parent_ty, parent_tz, parent_radius, weld_factor, normal_blend): void`
-   - Projects lateral branch collar vertices onto the parent branch cylinder surface with bounded axial pullback ($|\tau| \le 1.25 R_p$) and interpolates vertex normals from the parent cylinder normal $\mathbf{n}_{\text{parent}}$ to $\mathbf{n}_{\text{child}}$.
-2. **`mesh/branch_ring_triangulate.js` + `mesh/branch_ring_triangulate.spec.js`**
-   - `export function branch_ring_triangulate(indices, index_cursor, ring0_start, m0, ring1_start, m1): number`
-   - `export function branch_apex_triangulate(indices, index_cursor, ring_start, m, apex_start): number`
-   - Enforces $m_0 \ge 3, m_1 \ge 3$, zippers unequal rings using exact integer cross-multiplication `(j0 + 1) * m1 <= (j1 + 1) * m0` with outward CCW winding, and guarantees **zero repeated vertex indices** (`i0 !== i1 && i1 !== i2 && i2 !== i0`).
-3. **`mesh/tree_mesh_build_bark.js` + `mesh/tree_mesh_build_bark.spec.js`**
-   - `export function tree_mesh_build_bark(skeleton, config, lod_config, skin_info = null, out = new Geometry()): Geometry`
-   - Sweeps all retained branches ($l \le \text{lod\_config.max\_branch\_level}$ and $R_0 \ge \text{lod\_config.min\_branch\_radius}$) using `spline3_hermite`, `spine_frame_double_reflection`, root buttress lobes, bark flutes, lateral collar welding (for `parent_attach_t < 0.95`), terminal fork blending (for `parent_attach_t >= 0.95`), quantized seamless bark UVs (`uv0`), wind weights (`uv1`), canopy/collar AO (`color`), and 4-joint skinning attributes (`joints`, `weights`).
-   - Calls `out.ensureBounds()` and `out.ensureTangents()`.
-4. **`mesh/foliage_collect_attachments.js` + `mesh/foliage_collect_attachments.spec.js`**
-   - `export function foliage_collect_attachments(skeleton, config): FoliageAttachmentSet`
-   - Generates phyllotactic attachment points, heliotropic/gravitropic orthonormal bases $(\mathbf{F}, \mathbf{U}, \mathbf{W})$ with outward hemisphere alignment ($\mathbf{U} \cdot \mathbf{n}_{\text{canopy}} \ge 0$), golden-ratio decimation rank $h_i = (i \cdot \varphi^{-1}) \bmod 1$, and inherited skin joint indices/weights.
-5. **`mesh/tree_mesh_build_foliage.js` + `mesh/tree_mesh_build_foliage.spec.js`**
-   - `export function tree_mesh_build_foliage(skeleton, attachments, config, lod_config, out = new Geometry()): Geometry`
-   - Filters attachments by $h_i < k_{\text{keep}}$, applies area compensation scaling $s_{\text{comp}} = k_{\text{keep}}^{-\eta}$, and emits the selected `FoliageCardType` (`FoldedVCard`, `CrossCard`, `TriStarCluster`, `RibbedFrond`, `OctagonalCutoutHull`) with `position`, `normal`, `uv0`, `uv1` (wind weights), `color` (AO + color jitter), and `joints`/`weights`.
-6. **`mesh/tree_mesh_apply_canopy_ao.js` + `mesh/tree_mesh_apply_canopy_ao.spec.js`**
-   - `export function tree_mesh_apply_canopy_ao(geometry, crown_center, crown_radii, options): void`
-   - Computes analytic crown ellipsoid + sky-exposure AO into `StandardAttributes.Color` and applies hemisphere-safe normal puffing ($\mathbf{n}_{\text{vertex}} \cdot \mathbf{n}_{\text{face}} \ge 0.55$) before `geometry.ensureTangents()`.
-
----
-
-## Phase 5: Procedural PBR Materials, Wind Clips, & Turn-Key Asset Pipeline
-Location: `packages/meep-engine/src/generation/foliage/material/`, `animation/`, `asset/`
-
-### Files & Signatures
-1. **`material/make_bark_material.js` + `material/make_bark_material.spec.js`**
-   - `export function make_bark_material(config = new BarkMaterialConfig(), seed = 1): StandardShadeMaterial`
-   - Synthesizes tileable `Sampler2D` $\to$ `ShadeImage` $\to$ `ShadeTexture` for bark Albedo (`ColorSpace.SRGB`), 2-channel Normal (`ColorSpace.None` / `LinearSRGB`, `TextureFilterType.LinearNormal`), and ORM (`ColorSpace.None` / `LinearSRGB`), sets `material.ambient_factors.set(1, 0)`, `TransparencyMode.Opaque`, `ShadeDrawSide.Front`.
-2. **`material/make_foliage_material.js` + `material/make_foliage_material.spec.js`**
-   - `export function make_foliage_material(config = new FoliageMaterialConfig(), seed = 1): StandardShadeMaterial`
-   - Synthesizes botanical leaf/needle cluster Albedo + Alpha mask (dilated straight RGB into $A=0$ texels with `AlphaMode.Straight` so GPU upload premultiplies cleanly once), Normal map (vein relief), and ORM map, sets `material.ambient_factors.set(1, 0)`, `TransparencyMode.AlphaTested`, `ShadeDrawSide.Double`, `transmission_factor = 0`.
-3. **`animation/build_tree_wind_rig.js` + `animation/build_tree_wind_rig.spec.js`**
-   - `export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig()): FoliageWindRig|null`
-   - Generates a GPU fluid-driven `FoliageWindRig` (`name: "foliage_wind"`) whose joints (`2..J`, with joint `0` / `SceneNode` `1` anchored at the trunk base) carry physical Euler-Bernoulli cantilever `compliance`, `natural_frequency`, `damping_ratio`, `max_angle`, `turbulence`, `branch_axis`, and `flutter_phase`. At runtime, `GPUAnimationManager` dispatches `shader_foliage_wind_apply` to sample `GPUSceneWind` (`chunk_wind_field_sample`) at each bone's world position and step a 2nd-order damped oscillator into `pose_accumulator`.
-4. **`asset/TreeLODAsset.js` & `asset/TreeAsset.js`**
-   - `TreeLODAsset`: holds `level`, `bark_geometry: Geometry`, `foliage_geometry: Geometry|null`, `bark_material: StandardShadeMaterial`, `foliage_material: StandardShadeMaterial`, `wind_rig: FoliageWindRig|null`, and **lazy memoized getters** `.bark_meshlet_geometry`, `.foliage_meshlet_geometry`, `.scene_bundle`, `.prefab`.
-   - `TreeAsset`: holds `config: TreeSpeciesConfig`, `skeleton: TreeSkeleton`, `attachments: FoliageAttachmentSet`, `skin_info`, `wind_rig: FoliageWindRig|null`, `bark_material: StandardShadeMaterial`, `foliage_material: StandardShadeMaterial`, `lods: TreeLODAsset[]`, plus convenience getters `.bark_geometry`, `.foliage_geometry`, `.bark_meshlet_geometry`, `.foliage_meshlet_geometry`, `.scene_bundle`, `.prefab` aliasing `lods[0]`.
-5. **`asset/generate_tree.js` + `asset/generate_tree.spec.js`**
-   - `export function generate_tree(options = {}): TreeAsset`
-   - Turn-key entry point accepting zero arguments (`generate_tree()`), a `TreeSpeciesConfig`, or `{ preset, seed, crown, levels, foliage, bark_material, foliage_material, wind, lod_count, eager_meshlets }`.
-6. **`asset/place_tree.js` + `asset/place_tree.spec.js`**
-   - `export function place_tree(scene_context, dataset, options = {}): PlacedTree`
-   - `export function unplace_tree(scene_context, dataset, placed): void`
-   - Accepts either an existing `tree` (`TreeAsset`) / `prefab` (`Prefab`) or generation options, constructs `Transform64` from `placement` or `{ position, rotation, rotation_y, scale }`, calls `prefab_place`, registers `FoliageWindRig`s on `scene_context.animation_manager` with position-derived phase offsets, and provides `unplace_tree` for complete cleanup.
-
----
-
-## Adversarial Review of the Implementation Plan
-
-Before beginning implementation, each phase of this plan was audited against the exact runtime contracts in `packages/meep-engine/src`:
-
-1. **`StandardAttributes.SkinningJoints` TypedArray Contract**:
-   - `geometry_obtain_attribute` always allocates a `Float32Array`, whereas `meshlet_encode_attribute` expects `StandardAttributes.SkinningJoints` (`'joints'`) to be backed by a `Uint16Array(vertex_count * 4)`.
-   - *Plan Adjustment*: `tree_mesh_build_bark` and `tree_mesh_build_foliage` will obtain `'joints'` via a dedicated `Uint16Array` attribute helper (`Attribute.from(new Uint16Array(vertex_count * 4), 4, StandardAttributes.SkinningJoints)`) and `'weights'` via `geometry_obtain_attribute(geometry, StandardAttributes.SkinningWeights, 4, vertex_count)`.
-2. **`Sampler2D.uint8(itemSize, width, height)` Parameter Order & Direct Buffer Writes**:
-   - `Sampler2D.uint8` takes `(itemSize, width, height)` with `itemSize` first.
-   - *Plan Adjustment*: `make_bark_material` and `make_foliage_material` will construct `Sampler2D.uint8(channels, resolution, resolution)` and write directly into `sampler.data` (`Uint8Array`) for fast zero-overhead texture synthesis.
-3. **`GPUAnimationManager` Clip Registration & Unregistration Order in `place_tree` / `unplace_tree`**:
-   - `GPUAnimationManager` methods are `register_clip(clip)`, `set_flags(clip_id, AnimationClipFlags.Playing | AnimationClipFlags.Loop)`, `set_time(clip_id, time)`, `set_playback_rate(clip_id, rate)`, `set_playback_weight(clip_id, weight)`, and `unregister_clip(clip_id)`.
-   - `register_clip` grants `GPUStateAuthorityFlags.TransformAttachment | GPUStateAuthorityFlags.Transform64` on target entities and registers an entity event listener on `dataset`.
-   - *Plan Adjustment*: In `unplace_tree(scene_context, dataset, placed)`, `animation_manager.unregister_clip(clip_id)` **must** be called **before** `prefab_unplace(scene_context, dataset, placed)` so target entities and their `GPUStateAuthority` components still exist in `dataset` when `unregister_clip` revokes GPU authority and removes the event listener.
-4. **Root Joint Binding for Unassigned / Root Vertices**:
-   - In `tree_skeleton_assign_skin_joints`, joint `0` (`SceneNode` index `1`) is placed at the trunk base `(0, 0, 0)`. Any vertex at the very base of the trunk (`t = 0`) binds with weight `1.0` to joint `0` (`joints = [0, 0, 0, 0]`, `weights = [1, 0, 0, 0]`), and `build_tree_wind_clip` keeps joint `0` stationary (or applies only micro-base flex) so the base of the trunk stays anchored to the ground during wind sway.
-
----
-
-## Step 7: Adversarial Review of the Implementation & Resolutions
-
-Following completion of Phases 1–5, a comprehensive adversarial review of the implementation was conducted across `src/core/geom/3d/topology/struct/binary/query/` and `src/generation/foliage/`. Every identified edge case and mathematical hazard was resolved and covered with regression unit tests:
-
-1. **Adaxial Crotch Root Selection in `branch_collar_project.js`**:
-   - *Finding*: For the upper (adaxial/crotch) half of a tilted lateral branch ($\alpha \in (0, \pi/2)$) originating on the parent spine axis, the ring offset $\mathbf{q}$ has a negative projection onto the emerging direction $\mathbf{u}$ ($b_{\text{half}} = \mathbf{q} \cdot \mathbf{u} < 0$). Selecting `Math.abs(t_plus) < Math.abs(t_minus)` caused $b_{\text{half}} < 0$ vertices to select $t_{\text{minus}} = \frac{-b_{\text{half}} - \sqrt{\Delta}}{\|\mathbf{u}\|^2}$, which satisfies $(\mathbf{q} + t_{\text{minus}}\mathbf{u})\cdot\mathbf{u} = -\sqrt{\Delta} < 0$ (the opposite back wall of the parent trunk!).
-   - *Resolution*: Always select the emerging ($+\mathbf{u}$) cylinder root $\tau = t_{\text{plus}} = \frac{-b_{\text{half}} + \sqrt{\Delta}}{\|\mathbf{u}\|^2}$, which algebraically guarantees $(\mathbf{q} + t_{\text{plus}}\mathbf{u})\cdot\mathbf{u} = +\sqrt{\Delta} \ge 0$ for all collar vertices regardless of the sign of $b_{\text{half}}$, and bias steep-angle radial projection into the $+\mathbf{u}$ hemisphere.
-2. **Parent RMF Transport & Singularity-Free Child RMF Initialization in `tree_skeleton_grow.js` and `foliage_collect_attachments.js`**:
-   - *Finding*: When interpolating the parent branch's Rotation-Minimizing Frame at `local_u` along `parent_e`, `spine_frame_double_reflection` was called with `SCRATCH_POS` for both start and end points (`c1 === 0`), skipping the spatial chord reflection from `p_v0` to `SCRATCH_POS`. Additionally, initializing the child branch RMF radial vector from `D_rad` when $\alpha \approx \pi/2$ caused near-collinearity with `T_c`.
-   - *Resolution*: Pass `p_v0`'s actual position and tangent as `(x0, y0, z0, tx0, ty0, tz0)` into `spine_frame_double_reflection`, and initialize the child branch's radial vector using the exact orthonormal vector in the $(\mathbf{T}_p, \mathbf{D}_{\text{rad}})$ plane: $\mathbf{R}_c = \cos(\alpha)\mathbf{D}_{\text{rad}} - \sin(\alpha)\mathbf{T}_p$, which has unit length and zero singularity across all $\alpha \in [0, \pi]$.
-3. **Dichotomous Split Frame Preservation & Interior Hermite Tangent Smoothing in `tree_skeleton_grow.js`**:
-   - *Finding*: During a dichotomous split, rotating `next_t` for fork 0 without rotating `next_r` broke frame orthogonality, and re-writing `m0` from `vertex_read_normal(branch_vertices[0])` overwrote continuation fork `f`'s departure tangent with fork 0's tangent at the shared split vertex.
-   - *Resolution*: Preserve the pre-split orthonormal triad `(pre_t, pre_r, pre_s)`, rotate both `T` and `R` around each fork's bend axis so every fork maintains an exact right-handed orthonormal triad, and smooth only interior vertices (`1 <= k < branch_edges.length`) so continuation forks retain their exact departure Hermite tangent `m0`.
-4. **Longitudinal Hermite Spline Resampling (`longitudinal_scale`), Watertight Apex Cones (`branch_apex_triangulate`), Collar Tip Guard, & Empty Skeleton Fallback in `tree_mesh_build_bark.js`**:
-   - *Finding*: `tree_mesh_build_bark.js` iterated over raw skeleton nodes without resampling by `lod_config.longitudinal_scale`, left branch tips uncapped, could pull short branch tips (`sample_steps <= collar_weld_rings`) back onto the parent trunk, and left the 4-vertex empty-skeleton fallback buffer zero-filled.
-   - *Resolution*: Resample each branch's Cubic Hermite spline chain into `sample_steps = Math.max(1, Math.round(E * long_scale))` longitudinal rings using `evaluate_segment_position`, `evaluate_segment_tangent`, and `spine_frame_double_reflection`; cap all branch tips into watertight cones via `branch_apex_triangulate`; guard collar welding with `i < sample_steps && t_norm < 0.65` using exact parent Hermite evaluation at `parent_local_u`; and populate a valid non-degenerate quad when `branch_plans.length === 0`.
-5. **Single-Joint Wind Clips (`max_joints: 1`), Static Trees (`wind: false`), & Foliage Texture Clamping**:
-   - *Finding*: `build_tree_wind_clip` returned a 0-channel clip when `joint_count === 1`; boolean shorthand `{ wind: false }` / `{ foliage: false }` was ignored by `applyOverrides`; `generate_tree` with `wind.enabled === false` still attached a `Skin` to `TreeLODAsset`; and foliage `ShadeTexture`s defaulted to `Repeat` wrapping along $V \in [0, 1]$.
-   - *Resolution*: Animate joint `0` (`SceneNode` index `1`) when `joint_count === 1`; support boolean shorthand in `TreeWindConfig.applyOverrides` and `FoliageConfig.applyOverrides`; omit `Skin` on `TreeLODAsset` when `wind.enabled === false`; bind rest-pose skins cleanly in `place_tree` when `wind: false`; and set `TextureWrapType.ClampToEdge` on foliage textures in `make_foliage_material.js`.
-
-

package/src/generation/foliage/LEAF_ARCHITECTURE_BRIEF_2026_10_26.md

@@ -1,158 +0,0 @@
-# Leaf Architecture
-
-## Problem
-
-The oak's cards did not look like oak leaves (Alex, 2026-10-26: "What the fuck is that?"). Two causes, both hacks:
-
-- **The leaf outline was code, not botany.** `foliage_leaf_silhouette.js` switched on a string, `"lobed"` (a ±28% sine
-  ripple, "oak-like"), `"serrated"` (a sawtooth), `"palmate"` (a cosine), each with hand-picked constants. The oak's
-  `"lobed"` blade was widest near its base, with shallow wavy edges: a Christmas tree.
-- **A whole shoot was painted flat into one texture.** The `"rosette"` arrangement drew 11 leaves from one point,
-  fanned over ±83°, each three-quarters as wide as long. They merged into one blob with 11 tips. A `TriStarCluster`
-  stood three of those on crossing planes, which is the star in the screenshot. Meanwhile the simulation grows the
-  real shoots, so the tile duplicated the shoot geometry and contradicted it.
-
-Fixing the oak's outline alone would have kept both hacks.
-
-## Principle
-
-- **A leaf is data, described as floras describe it.** Ellis et al. (2009), *Manual of Leaf Architecture*, gives the
-  vocabulary; each preset cites its flora.
-- **A card is one leaf, on its shoot.** Each leaf is a card at its own node, leaving the shoot at the rule's insertion
-  angle and turned by its phyllotaxis.
-- **Needles stay shoot cards.** Pine bears 1,560 needles per metre and spruce 2,450 (sourced in the presets). A card
-  per needle is out of reach, and the needle shoot is the unit those papers measure.
-
-## Design
-
-- **`LeafArchitecture`** (`FoliageMaterialConfig.leaf`):
-  - blade length, length/width ratio, where it is widest;
-  - apex and base angle and shape (`LeafApexShape`, `LeafBaseShape`; the angles measured as Ellis et al. define them,
-    a quarter of the blade's length from the tip or the base);
-  - lobation (`LeafLobation`), lobes, sinus depth, palmate spread and lateral lobe length;
-  - teeth per cm, tooth depth and order;
-  - secondary veins and their angle;
-  - petiole length;
-  - a compound leaf's leaflets and rachis.
-- **`leaf_geometry`** turns that into outline contours, veins and stems in metres:
-  - **Envelope:** a monotone cubic Hermite (Fritsch-Carlson) through the base, the base angle's point, the widest point,
-    the apex angle's point and the apex. The shapes set the end slopes. A rounded end is an elliptic arc; an acuminate
-    one is shallow, so the margin is concave near the tip.
-  - **Pinnate lobes:** the blade reaches only to the sinus floor, `1 - sinus_depth` of the outline's width. Each lateral
-    lobe is a rounded blade of its own along its secondary vein (so it leans by the vein's angle), out to the outline.
-    The veins leave the midvein evenly spaced.
-  - **Palmate lobes:** a blade per primary lobe, radiating across `lobe_spread`, over a body to the sinus floors.
-  - **Base lobes:** cordate and lobate bases are a cubic Bezier from the petiole sinus round the basal lobe, solved to
-    reach exactly `base_lobe_depth` below the petiole.
-  - **Teeth:** offset along the outline's normal, spaced along the untoothed margin, with a second order a third the
-    size.
-  - **Union:** every contour winds the same way, so the union of lobes, leaflets and petiole is filled by the nonzero
-    rule (`polygon2_rasterize_coverage`, exact across each row, 4 samples down it).
-- **`foliage_tile_layout`** (one place for every consumer):
-  - The mature leaf fills the tile within a 2% margin, attached at the bottom middle. Every tile draws at that scale,
-    so the card's size in metres is the leaf's (`card_size`).
-  - **Resolution:** the finest feature (a tooth, a sinus) is drawn 4 texels across. The narrowest stem is drawn 2
-    texels across, so wherever it falls it covers a whole texel and survives the alpha test.
-  - **Needle shoots:** a stretch of shoot as long as a needle, with the needles the shoot bears there
-    (`leaves_per_metre`), shared among the card's planes. Each plane draws the needles in its sector round the shoot,
-    foreshortened by their azimuth.
-- **`foliage_tile_raster`:**
-  - Coverage, veins stamped near each segment, distance to the margin and to the midvein by chamfer, camber,
-    bullation, and the petiole.
-  - The pigment, senescence and normal code of `make_foliage_material` is unchanged. It now skips the texels the leaf
-    leaves empty, which keep the dilated fill.
-- **Cards:**
-  - **Broadleaves:** a card per leaf. A short shoot's `leaves_per_short_shoot` sit at its tip. The presets draw
-    `CutoutHull` cards.
-  - **Needle cards** lie along the shoot.
-  - **Density path:** branches not grown by annual units keep it, on the layout's card size and anchor.
-
-## Sources per species
-
-| preset | leaf | sources | estimated, not found |
-| :--- | :--- | :--- | :--- |
-| oak (*Quercus robur*) | mean blade 10.6 and 12.0 cm; L/W 1.8, 1.64; width 0.81-0.85 of max at 0.5 L, 0.47-0.50 at 0.9 L; petiole 7.4-8.0% of blade | Boratyński et al. 2008, *Silva Fennica* 42: 115-124, Table 4. Fitted: widest at 0.675, apex angle 1.2, base 0.8 rad (both widths within 0.01) | auricle size, secondary angle |
-| | obovate; apex broadly rounded; sinuses 1/3-7/8 to midrib; entire; 5-7 secondaries | FNA vol. 3 | |
-| | 5-7 lobes a side | Flora of China | |
-| | up to 5 pairs; auricles usually strong | BSBI Plant Crib | |
-| birch (*Betula pendula*) | 3-7 × 2.5-5 cm, ovate-rhombic, acuminate, cuneate, doubly serrate | FNA | apex and base angles, teeth (1.3 a cm, 1.5 mm), widest point |
-| | 6-8 lateral veins; petiole 2-3 cm | FoC | |
-| | 2 leaves a short shoot | Maillette 1982 | |
-| willow (*Salix babylonica*) | 90-160 × 5-20 mm, L/W 5.5-10.5, acuminate, cuneate, serrulate; petiole 7-9 mm | FNA vol. 7 | angles, teeth (5 a cm, 0.3 mm), veins |
-| maple (*Acer rubrum*) | 6.8 cm, 39 cm² | Wilson 1966 | lobe outline, lateral lobe length 0.85, teeth (3 a cm, 1.5 mm) |
-| | 3 lobes; lateral axes 73-86° apart; midlobe 46-56% of blade; petiole 60-114% of blade; 2 leaf pairs a short shoot | Critchfield 1971 | |
-| | doubly serrate | Gleason & Cronquist | |
-| | base truncate to cordate | Trees and Shrubs Online | |
-| shrub (*Corylus avellana*) | 5-12 × 4-12 cm, abruptly acuminate, narrowly cordate, doubly serrate, ≤ 8 vein pairs | FNA | angles, base lobe depth, teeth (0.7 a cm, 2.5 mm) |
-| | petiole 6-12 mm | Trees and Shrubs Online | |
-| | 8 cm gives the 41 cm² of a sun leaf | Catoni et al. 2015 | |
-| pine, spruce needles | 52 mm [Niinemets & Lukjanova 2003]; spruce's 18 mm was already chosen | | widths 1.6 and 1 mm; needle angle 0.6 rad |
-| palm, fern | no species named: the old frond's sizes are kept | | everything |
-
-The botanical data was gathered by a research subagent from efloras.org (FNA, FoC), BSBI, VicFlora, Go Botany, Trees
-and Shrubs Online, SEINet and the papers above. Its quotes and URLs are in the session's scratchpad (`leaf/`).
-floranorthamerica.org refused access, and HAL (Kremer et al. 2002) is behind a bot check.
-
-## Measured
-
-*Seed 1337 unless noted; the "before" figures are from 49845ff00.*
-
-**Atlas, from the drawn tiles:**
-
-| preset | resolution | card | coverage | one leaf |
-| :--- | ---: | ---: | ---: | ---: |
-| oak | 128 | 12.7 cm | 0.208 | 33 cm² |
-| birch | 256 | 7.8 cm | 0.174 | 10.6 cm² |
-| willow | 512 | 13.9 cm | 0.073 | 14 cm² |
-| maple | 512 | 13.2 cm | 0.213 | 37 cm² |
-| shrub | 128 | 9.3 cm | 0.522 | 45 cm² |
-| pine | 256 | 9.8 cm (81 needles) | | |
-| spruce | 256 | 3.4 cm (44 needles) | | |
-| palm | 128 | | | |
-| fern | 128 | | | |
-
-Leaf areas against the sources:
-- maple: 37 cm² against Wilson's 39;
-- hazel: 45 cm² against Catoni's 41;
-- birch: 10.6 cm² against about 11 from FNA's sizes.
-
-**Cost:** cards, LOD0 triangles, and `generate_tree` time with the LOD0 meshes.
-
-| preset | cards | foliage tris | bark tris | generate + LOD0 |
-| :--- | ---: | ---: | ---: | ---: |
-| oak | 25,622 | 153,732 | 81,587 | 0.77 + 0.06 s |
-| pine | 3,554 | 21,324 | 39,817 | 0.71 + 0.03 s |
-| birch | 63,909 | 383,454 | 454,735 | 1.73 + 0.56 s |
-| willow | 113,001 | 678,006 | 410,091 | 1.81 + 0.46 s |
-| maple | 13,008 | 78,048 | 37,774 | 1.16 + 0.05 s |
-| spruce | 176,311 | 705,244 | 1,085,114 | 3.12 + 1.23 s |
-| shrub | 16,976 | 101,856 | 62,817 | 0.52 + 0.05 s |
-
-**Crowns,** measured with `foliage_measure_leaf_area` and `tree_crown_opacity`; "before" is 49845ff00:
-
-| preset | leaf m² (before) | crown LAI | side density | side transparency | below density | below transparency |
-| :--- | ---: | ---: | ---: | ---: | ---: | ---: |
-| oak | 89.4 (90.9) | 3.11 | 0.50 | 0.42 | 0.58 | 0.27 |
-| pine | 15.7 (35.0) | 0.74 | 0.34 | 0.64 | 0.35 | 0.62 |
-| birch | 70.4 (64.5) | 6.77 | 0.56 | 0.33 | 0.75 | 0.12 |
-| willow | 232.6 (136.3) | 6.43 | 0.75 | 0.18 | 0.74 | 0.19 |
-| maple | 50.7 (36.3) | 1.97 | 0.41 | 0.42 | 0.42 | 0.32 |
-| spruce | 78.4 (117.8) | 3.03 | 0.33 | 0.31 | 0.42 | 0.29 |
-| shrub | 62.5 (57.8) | 4.52 | 0.63 | 0.22 | 0.64 | 0.16 |
-
-- **Pine and spruce lost leaf area** because their old tiles overdrew. Every plane of a card drew all of its needles,
-  three times over on pine, and wider than the needles are. Now each needle is drawn once at its width.
-- **Willow gained,** its lanceolate leaves replacing a frond drawing. Its transparency, 0.18, is near FIA's 15%.
-
-## Open (measured, not argued)
-
-- **Card counts rose where a card used to hold several leaves:** birch 5×, willow 9×, oak 11×. Pine and spruce rose
-  2.4×, because a needle card now covers one needle length of shoot, not 2.4. That stretch is chosen, not sourced.
-- **Estimates:** the angles, tooth sizes and widest points the floras do not give are marked in each preset.
-- **Palm and fern** name no species, so their leaves are not sourced.
-- **Wind sail:**
-  - `TreeWindConfig.elastic_modulus` is fitted to the oak, whose leaf area moved by 2% (90.9 to 89.4 m²); it was not
-    refit.
-  - Pine's and spruce's sails fell with their leaf area (to 0.45 and 0.67), so they will sway less. That sway is not
-    measured.
-- **Transparency:** every crown but willow's is still far above FIA's 15% transparency.