@woosh/meep-engine 3.52.0 → 3.54.0

package/src/generation/foliage/FOLIAGE_PLAN.md

@@ -0,0 +1,198 @@
+# 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/animation/build_tree_wind_rig.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Constructs a GPU fluid-driven `FoliageWindRig` (`name = "foliage_wind"`) for the structural
+ * `Skin` joints (`SceneNode` indices `1 .. J`) of a procedurally generated tree.
+ *
+ * Joint `0` (`SceneNode` index `1`, at the trunk base `(0, 0, 0)`) remains anchored at its bind
+ * pose so the base of the trunk never pivots off the ground, while upper trunk and branch joints
+ * carry physically derived Euler-Bernoulli cantilever compliance, natural frequency, damping ratio,
+ * branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
+ * dispatches `shader_foliage_wind_apply` to sample Meep's 3D fluid simulation wind field
+ * (`GPUSceneWind`: `GlobalFluidEffector` far-field + 3D MAC `GPUFluidCascadeStack` wakes/vortices)
+ * at each bone's world position and step a 2nd-order damped oscillator directly into `pose_accumulator`.
+ *
+ * @param {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>} skin_info
+ * @param {TreeWindConfig|Object} [wind_config]
+ * @returns {FoliageWindRig|null}
+ */
+export function build_tree_wind_rig(skin_info: ReturnType<typeof import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>, wind_config?: TreeWindConfig | any): FoliageWindRig | null;
+import { TreeWindConfig } from "../config/TreeWindConfig.js";
+import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
+//# sourceMappingURL=build_tree_wind_rig.d.ts.map

package/src/generation/foliage/animation/build_tree_wind_rig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_tree_wind_rig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/animation/build_tree_wind_rig.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,6GAAsG,gBACtG,cAAc,MAAO,GACnB,cAAc,GAAC,IAAI,CAuF/B;+BAvG8B,6BAA6B;+BAD7B,6DAA6D"}

package/src/generation/foliage/animation/build_tree_wind_rig.js

@@ -0,0 +1,108 @@
+import { PI2 } from "../../../core/math/PI2.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { FoliageWindJoint } from "../../../shade/renderer/animation/foliage/FoliageWindJoint.js";
+import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
+import { TreeWindConfig } from "../config/TreeWindConfig.js";
+
+/**
+ * Constructs a GPU fluid-driven `FoliageWindRig` (`name = "foliage_wind"`) for the structural
+ * `Skin` joints (`SceneNode` indices `1 .. J`) of a procedurally generated tree.
+ *
+ * Joint `0` (`SceneNode` index `1`, at the trunk base `(0, 0, 0)`) remains anchored at its bind
+ * pose so the base of the trunk never pivots off the ground, while upper trunk and branch joints
+ * carry physically derived Euler-Bernoulli cantilever compliance, natural frequency, damping ratio,
+ * branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
+ * dispatches `shader_foliage_wind_apply` to sample Meep's 3D fluid simulation wind field
+ * (`GPUSceneWind`: `GlobalFluidEffector` far-field + 3D MAC `GPUFluidCascadeStack` wakes/vortices)
+ * at each bone's world position and step a 2nd-order damped oscillator directly into `pose_accumulator`.
+ *
+ * @param {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>} skin_info
+ * @param {TreeWindConfig|Object} [wind_config]
+ * @returns {FoliageWindRig|null}
+ */
+export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig()) {
+    const cfg = wind_config && wind_config.isTreeWindConfig ? wind_config : TreeWindConfig.from(wind_config);
+    if (!cfg.enabled || !skin_info || skin_info.joint_count <= 0) {
+        return null;
+    }
+
+    const rig = new FoliageWindRig();
+    rig.name = "foliage_wind";
+    rig.root = 0; // SceneNode 0 is the tree root in SceneBundle
+
+    const r0 = (skin_info.joint_radii && skin_info.joint_radii.length > 0)
+        ? Math.max(0.02, skin_info.joint_radii[0])
+        : 0.25;
+
+    const start_joint = skin_info.joint_count === 1 ? 0 : 1;
+
+    // Count how many driven joints share the same structural level along each joint's ancestor chain
+    // so serial chains of joints on the same trunk/bough divide the total branch deflection cleanly.
+    const same_level_chain_count = new Uint8Array(skin_info.joint_count);
+    for (let j = 0; j < skin_info.joint_count; j++) {
+        const lvl = skin_info.joint_levels[j];
+        let count = 0;
+        let cur = j;
+        while (cur > 0) {
+            if (skin_info.joint_levels[cur] === lvl) {
+                count++;
+            }
+            cur = skin_info.joint_parents[cur];
+        }
+        same_level_chain_count[j] = Math.max(1, count);
+    }
+
+    for (let j = start_joint; j < skin_info.joint_count; j++) {
+        const level = skin_info.joint_levels[j];
+        const t_norm = j === 0 ? 0.5 : skin_info.joint_t_norms[j];
+        const phase = skin_info.joint_phases[j] * PI2;
+        const r_j = (skin_info.joint_radii && j < skin_info.joint_radii.length)
+            ? Math.max(0.005, skin_info.joint_radii[j])
+            : r0 * Math.pow(0.5, level);
+
+        let tx = skin_info.joint_tangents[j * 3];
+        let ty = skin_info.joint_tangents[j * 3 + 1];
+        let tz = skin_info.joint_tangents[j * 3 + 2];
+        const t_len = Math.hypot(tx, ty, tz);
+        if (t_len > 1e-6) {
+            tx /= t_len;
+            ty /= t_len;
+            tz /= t_len;
+        } else {
+            tx = 0.0;
+            ty = 1.0;
+            tz = 0.0;
+        }
+
+        const chain_div = Math.max(1, same_level_chain_count[j]);
+        const base_comp = level === 0
+            ? cfg.trunk_compliance * 0.18
+            : cfg.branch_compliance * 0.24 * (1.0 + 0.35 * (level - 1));
+        const radius_factor = level === 0
+            ? clamp(Math.pow(r0 / Math.max(r_j, 0.25 * r0), 0.35), 0.6, 1.6)
+            : clamp(Math.pow(r0 / Math.max(r_j, 0.08 * r0), 0.45), 0.8, 3.2);
+        const compliance = (base_comp * radius_factor * clamp(0.35 + 0.65 * t_norm, 0.3, 1.15)) / chain_div;
+
+        const natural_frequency = cfg.natural_frequency * (1.0 + 0.65 * level + 0.35 * t_norm);
+        const damping_ratio = clamp(cfg.damping_ratio * (1.0 + 0.12 * level), 0.05, 1.5);
+        const max_angle = clamp(
+            (cfg.max_bend_angle * (level === 0 ? 0.18 : (0.42 + 0.18 * Math.min(level, 2)))) / chain_div,
+            0.02,
+            0.85
+        );
+        const turbulence = clamp(cfg.turbulence * (level === 0 ? 0.35 : (0.65 + 0.35 * Math.min(level, 2))), 0.0, 1.0);
+
+        rig.joints.push(FoliageWindJoint.from({
+            target: j + 1, // SceneNode 0 is tree_root; Joint j is SceneNode (j + 1)
+            branch_axis: [tx, ty, tz],
+            compliance,
+            natural_frequency,
+            damping_ratio,
+            max_angle,
+            turbulence,
+            phase_offset: phase,
+        }));
+    }
+
+    return rig;
+}

package/src/generation/foliage/asset/TreeAsset.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Complete procedurally generated tree asset containing the botanical configuration,
+ * `TreeSkeleton`, `FoliageAttachmentSet`, shared procedural bark and foliage PBR `StandardShadeMaterial`s,
+ * skeletal wind `ShadeAnimationClip`, and the multi-LOD `TreeLODAsset[]` chain.
+ *
+ * Exposes top-level convenience getters (`.bark_geometry`, `.foliage_geometry`, `.bark_meshlet_geometry`,
+ * `.foliage_meshlet_geometry`, `.scene_bundle`, `.prefab`) aliasing `lods[0]`.
+ */
+export class TreeAsset {
+    /**
+     * Resolved species configuration used to generate this asset.
+     * @type {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig}
+     */
+    config: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig;
+    /**
+     * Directed botanical skeleton graph (`Graph` + `Transform64` + `Attribute`s).
+     * @type {import("../skeleton/TreeSkeleton.js").TreeSkeleton}
+     */
+    skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton;
+    /**
+     * Phyllotactic foliage card attachment transforms and ranks.
+     * @type {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet}
+     */
+    attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet;
+    /**
+     * Extracted structural skin joint descriptors.
+     * @type {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>}
+     */
+    skin_info: ReturnType<typeof import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>;
+    /**
+     * GPU fluid-driven foliage wind rig (`name = "foliage_wind"`), or `null` if wind disabled.
+     * @type {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
+     */
+    wind_rig: import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig | null;
+    /**
+     * Procedural bark PBR `StandardShadeMaterial` shared across all LODs.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    bark_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * Procedural foliage cutout PBR `StandardShadeMaterial` shared across all LODs.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    foliage_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * Progressive LOD asset chain (`lods[0]` = highest detail).
+     * @type {import("./TreeLODAsset.js").TreeLODAsset[]}
+     */
+    lods: import("./TreeLODAsset.js").TreeLODAsset[];
+    /**
+     * Highest-detail (`lods[0]`) bark `Geometry`.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    get bark_geometry(): import("../../../shade/renderer/geometry/Geometry.js").Geometry;
+    /**
+     * Highest-detail (`lods[0]`) foliage `Geometry`.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    get foliage_geometry(): import("../../../shade/renderer/geometry/Geometry.js").Geometry;
+    /**
+     * Highest-detail (`lods[0]`) bark `MeshletGeometry` (lazy memoized).
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    get bark_meshlet_geometry(): import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry;
+    /**
+     * Highest-detail (`lods[0]`) foliage `MeshletGeometry` (lazy memoized).
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    get foliage_meshlet_geometry(): import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry;
+    /**
+     * Highest-detail (`lods[0]`) `SceneBundle` (lazy memoized).
+     * @returns {import("../../../shade/renderer/loader/SceneBundle.js").SceneBundle|null}
+     */
+    get scene_bundle(): import("../../../shade/renderer/loader/SceneBundle.js").SceneBundle;
+    /**
+     * Highest-detail (`lods[0]`) compiled `Prefab` (lazy memoized).
+     * @returns {import("../../../engine/graphics3/prefab/Prefab.js").Prefab|null}
+     */
+    get prefab(): import("../../../engine/graphics3/prefab/Prefab.js").Prefab;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isTreeAsset: boolean;
+}
+//# sourceMappingURL=TreeAsset.d.ts.map

package/src/generation/foliage/asset/TreeAsset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeAsset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/TreeAsset.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,QAFU,OAAO,gCAAgC,EAAE,iBAAiB,CAEtD;IAEd;;;OAGG;IACH,UAFU,OAAO,6BAA6B,EAAE,YAAY,CAE5C;IAEhB;;;OAGG;IACH,aAFU,OAAO,wCAAwC,EAAE,oBAAoB,CAE5D;IAEnB;;;OAGG;IACH,WAFU,6GAAsG,CAE/F;IAEjB;;;OAGG;IACH,UAFU,OAAO,6DAA6D,EAAE,cAAc,GAAC,IAAI,CAEnF;IAEhB;;;OAGG;IACH,eAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE9E;IAErB;;;OAGG;IACH,kBAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE3E;IAExB;;;OAGG;IACH,MAFU,OAAO,mBAAmB,EAAE,YAAY,EAAE,CAE1C;IAEV;;;OAGG;IACH,qFAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,2GAEC;IAED;;;OAGG;IACH,8GAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,0EAEC;IAGL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B"}

package/src/generation/foliage/asset/TreeAsset.js

@@ -0,0 +1,111 @@
+/**
+ * Complete procedurally generated tree asset containing the botanical configuration,
+ * `TreeSkeleton`, `FoliageAttachmentSet`, shared procedural bark and foliage PBR `StandardShadeMaterial`s,
+ * skeletal wind `ShadeAnimationClip`, and the multi-LOD `TreeLODAsset[]` chain.
+ *
+ * Exposes top-level convenience getters (`.bark_geometry`, `.foliage_geometry`, `.bark_meshlet_geometry`,
+ * `.foliage_meshlet_geometry`, `.scene_bundle`, `.prefab`) aliasing `lods[0]`.
+ */
+export class TreeAsset {
+    /**
+     * Resolved species configuration used to generate this asset.
+     * @type {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig}
+     */
+    config = null;
+
+    /**
+     * Directed botanical skeleton graph (`Graph` + `Transform64` + `Attribute`s).
+     * @type {import("../skeleton/TreeSkeleton.js").TreeSkeleton}
+     */
+    skeleton = null;
+
+    /**
+     * Phyllotactic foliage card attachment transforms and ranks.
+     * @type {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet}
+     */
+    attachments = null;
+
+    /**
+     * Extracted structural skin joint descriptors.
+     * @type {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>}
+     */
+    skin_info = null;
+
+    /**
+     * GPU fluid-driven foliage wind rig (`name = "foliage_wind"`), or `null` if wind disabled.
+     * @type {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
+     */
+    wind_rig = null;
+
+    /**
+     * Procedural bark PBR `StandardShadeMaterial` shared across all LODs.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    bark_material = null;
+
+    /**
+     * Procedural foliage cutout PBR `StandardShadeMaterial` shared across all LODs.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    foliage_material = null;
+
+    /**
+     * Progressive LOD asset chain (`lods[0]` = highest detail).
+     * @type {import("./TreeLODAsset.js").TreeLODAsset[]}
+     */
+    lods = [];
+
+    /**
+     * Highest-detail (`lods[0]`) bark `Geometry`.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    get bark_geometry() {
+        return this.lods.length > 0 ? this.lods[0].bark_geometry : null;
+    }
+
+    /**
+     * Highest-detail (`lods[0]`) foliage `Geometry`.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    get foliage_geometry() {
+        return this.lods.length > 0 ? this.lods[0].foliage_geometry : null;
+    }
+
+    /**
+     * Highest-detail (`lods[0]`) bark `MeshletGeometry` (lazy memoized).
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    get bark_meshlet_geometry() {
+        return this.lods.length > 0 ? this.lods[0].bark_meshlet_geometry : null;
+    }
+
+    /**
+     * Highest-detail (`lods[0]`) foliage `MeshletGeometry` (lazy memoized).
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    get foliage_meshlet_geometry() {
+        return this.lods.length > 0 ? this.lods[0].foliage_meshlet_geometry : null;
+    }
+
+    /**
+     * Highest-detail (`lods[0]`) `SceneBundle` (lazy memoized).
+     * @returns {import("../../../shade/renderer/loader/SceneBundle.js").SceneBundle|null}
+     */
+    get scene_bundle() {
+        return this.lods.length > 0 ? this.lods[0].scene_bundle : null;
+    }
+
+    /**
+     * Highest-detail (`lods[0]`) compiled `Prefab` (lazy memoized).
+     * @returns {import("../../../engine/graphics3/prefab/Prefab.js").Prefab|null}
+     */
+    get prefab() {
+        return this.lods.length > 0 ? this.lods[0].prefab : null;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+TreeAsset.prototype.isTreeAsset = true;