@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/src/vegetation/stylizedTree.js

@@ -98,6 +98,187 @@ function seededRandom(seed) {
   };
 }
 
+/**
+ * Canopy pruning — decide which branch tips carry foliage and which are bared.
+ *
+ * A recursive skeleton puts a tuft on every terminal twig, and terminal twigs
+ * fill the crown volume evenly. The result is always a dome, however the
+ * individual tufts are shaped: a hundred small masses packed shoulder to
+ * shoulder is a dome, and forty larger ones is a bigger dome. That is correct
+ * for a broadleaf and it is wrong for anything whose identity is DISCRETE
+ * foliage masses with sky and bare limb between them.
+ *
+ * Three independent policies, applied in this order. Each is off by default,
+ * so a caller that passes nothing — or a bare `padCount`, the original
+ * signature — gets exactly the geometry it always did.
+ *
+ *   crownBase   Bare every tip below this fraction of the crown's own
+ *               vertical extent. A skeleton that branches low enough to read
+ *               multi-stemmed also hangs foliage all the way down that low
+ *               wood and buries the trunk it just built; on a garden tree the
+ *               trunk is half the subject. This lifts the skirt WITHOUT
+ *               raising `branches.start`, so the limb structure keeps its low
+ *               fork and only the foliage moves.
+ *
+ *   layers      Horizontal PLATES: keep tips inside `count` bands across the
+ *               crown height and bare the tips between them. Pad pruning
+ *               (below) spaces masses isotropically, which is right for a
+ *               cloud-pruned pine — a pine's pads are a 3D scatter. It is
+ *               wrong for the layered broadleaves, whose signature is flat
+ *               tiers with sky and limb showing BETWEEN them: an Acer
+ *               palmatum, a dogwood, a Japanese hornbeam. Isotropic spacing
+ *               can never produce that structure at any count, because the
+ *               structure is anisotropic. Bands are placed edge to edge
+ *               across the crown (the lowest sits at the crown base, the
+ *               highest at the apex) so pruning never decapitates the tree.
+ *
+ *   padCount    Keep this many well-separated survivors by farthest-point
+ *               sampling, seeded from the topmost tip, so kept pads spread
+ *               over the whole crown instead of clumping. This is what makes
+ *               a cloud-pruned pine possible at all.
+ *
+ * Every policy is a pure function of the skeleton: same tree, same pruning,
+ * every build. Bared attachments use the existing `densityScale: 0` override,
+ * which is already the documented way to strip a branch, so nothing new is
+ * needed downstream. `densityBoost` multiplies the survivors' card counts, so
+ * a crown can be restructured into plates at an unchanged card total instead
+ * of simply losing the foliage the pruning removed.
+ *
+ * A caller's own override for an attachment always wins: pruning is a layout
+ * policy, not an authority over explicit per-branch authoring.
+ */
+export function resolvePadPruning(attachments, options = null, existingOverrides = null) {
+  const total = Array.isArray(attachments) ? attachments.length : 0;
+  if (!total) return existingOverrides;
+
+  // The original signature took the pad count positionally.
+  const config = (options && typeof options === 'object') ? options : { padCount: options };
+  const padCount = Number.isFinite(config.padCount) ? Math.round(config.padCount) : 0;
+  const crownBase = Number.isFinite(config.crownBase)
+    ? THREE.MathUtils.clamp(config.crownBase, 0, 0.95)
+    : 0;
+  const layers = config.layers && typeof config.layers === 'object' ? config.layers : null;
+  const layerCount = layers && Number.isFinite(layers.count) ? Math.round(layers.count) : 0;
+  const layerThickness = layers && Number.isFinite(layers.thickness)
+    ? THREE.MathUtils.clamp(layers.thickness, 0.02, 1)
+    : 0.5;
+  const layerJitter = layers && Number.isFinite(layers.jitter)
+    ? THREE.MathUtils.clamp(layers.jitter, 0, 1)
+    : 0;
+  const densityBoost = Number.isFinite(config.densityBoost)
+    ? THREE.MathUtils.clamp(config.densityBoost, 0.1, 12)
+    : 1;
+  const hasHeightPolicy = crownBase > 0 || layerCount >= 2;
+  const hasPadPolicy = padCount > 0 && padCount < total;
+  if (!hasHeightPolicy && !hasPadPolicy && densityBoost === 1) return existingOverrides;
+
+  let alive = new Array(total);
+  for (let i = 0; i < total; i += 1) alive[i] = true;
+
+  if (hasHeightPolicy) {
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (let i = 0; i < total; i += 1) {
+      const { y } = attachments[i].position;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+    }
+    const span = Math.max(maxY - minY, 1e-4);
+    // Crown height is measured on the attachments themselves, not on the
+    // trunk anchor: it is the foliage envelope that is being restructured,
+    // and a leaning or gnarled trunk makes anchor-relative height a
+    // different quantity per variant.
+    const heights = new Float64Array(total);
+    for (let i = 0; i < total; i += 1) heights[i] = (attachments[i].position.y - minY) / span;
+
+    if (crownBase > 0) {
+      for (let i = 0; i < total; i += 1) if (heights[i] < crownBase) alive[i] = false;
+    }
+
+    if (layerCount >= 2) {
+      // Re-normalize above the lifted skirt so the plates divide the foliage
+      // that actually survives rather than the empty band below it.
+      const base = crownBase > 0 ? crownBase : 0;
+      const usable = Math.max(1 - base, 1e-4);
+      const pitch = 1 / (layerCount - 1);
+      const halfWidth = (layerThickness * pitch) / 2;
+      const centres = new Float64Array(layerCount);
+      for (let k = 0; k < layerCount; k += 1) {
+        // Deterministic per-plate wobble: real tiers are not a comb.
+        const wobble = layerJitter
+          ? (Math.sin((k + 1) * 12.9898) * 43758.5453 % 1 + 1) % 1 - 0.5
+          : 0;
+        centres[k] = k * pitch + wobble * layerJitter * pitch;
+      }
+      for (let i = 0; i < total; i += 1) {
+        if (!alive[i]) continue;
+        const t = (heights[i] - base) / usable;
+        let inside = false;
+        for (let k = 0; k < layerCount; k += 1) {
+          if (Math.abs(t - centres[k]) <= halfWidth) { inside = true; break; }
+        }
+        if (!inside) alive[i] = false;
+      }
+      // A band-pass that keeps nothing is a bug, not a style. Fall back to
+      // the un-plated crown rather than shipping an invisible tree.
+      if (!alive.some(Boolean)) alive = new Array(total).fill(true);
+    }
+  }
+
+  if (hasPadPolicy) {
+    const candidates = [];
+    for (let i = 0; i < total; i += 1) if (alive[i]) candidates.push(i);
+    if (candidates.length > padCount) {
+      // Seed from the highest surviving tip: a garden tree's uppermost mass
+      // is the one a viewer registers first, so it is never the one pruned.
+      let firstSlot = 0;
+      for (let s = 1; s < candidates.length; s += 1) {
+        if (attachments[candidates[s]].position.y > attachments[candidates[firstSlot]].position.y) {
+          firstSlot = s;
+        }
+      }
+      const chosen = [firstSlot];
+      const nearest = new Float64Array(candidates.length);
+      for (let s = 0; s < candidates.length; s += 1) {
+        nearest[s] = attachments[candidates[s]].position
+          .distanceToSquared(attachments[candidates[firstSlot]].position);
+      }
+      nearest[firstSlot] = -1;
+      while (chosen.length < padCount) {
+        let best = -1;
+        let bestDistance = -1;
+        for (let s = 0; s < candidates.length; s += 1) {
+          if (nearest[s] > bestDistance) { bestDistance = nearest[s]; best = s; }
+        }
+        if (best < 0 || bestDistance <= 0) break;
+        chosen.push(best);
+        nearest[best] = -1;
+        for (let s = 0; s < candidates.length; s += 1) {
+          if (nearest[s] < 0) continue;
+          const distance = attachments[candidates[s]].position
+            .distanceToSquared(attachments[candidates[best]].position);
+          if (distance < nearest[s]) nearest[s] = distance;
+        }
+      }
+      const keptSlots = new Set(chosen);
+      for (let s = 0; s < candidates.length; s += 1) {
+        if (!keptSlots.has(s)) alive[candidates[s]] = false;
+      }
+    }
+  }
+
+  const overrides = { ...(existingOverrides ?? {}) };
+  for (let i = 0; i < total; i += 1) {
+    if (overrides[i]) continue;
+    if (!alive[i]) {
+      overrides[i] = { densityScale: 0, cardsPerCluster: 0 };
+    } else if (densityBoost !== 1) {
+      overrides[i] = { densityScale: densityBoost };
+    }
+  }
+  return overrides;
+}
+
 // Curved trunk along a seeded 3D spine. Returns { geometry, canopyAnchor }:
 // the anchor is the spine's top, so the crown follows the trunk's lean.
 //
@@ -758,6 +939,12 @@ export function createBranchingTreeSkeleton({
     twist = 0,
     gnarl = 0,
     lean = 0,
+    // World heading of the bow, and the lean heading relative to it — the same
+    // meaning they carry on the space-colonization generator. Without them a
+    // stand of wind-shaped trees leans a different way per seed, which reads
+    // as damage rather than as wind. null keeps the historical seeded pick.
+    bendDirection = null,
+    leanOffset = null,
   } = trunk;
   const rand = seededRandom(seed * 4.87 + 2.3);
   let randKey = 0;
@@ -807,11 +994,19 @@ export function createBranchingTreeSkeleton({
   const workVector = new THREE.Vector3();
   const workAxis = new THREE.Vector3();
   const workQuaternion = new THREE.Quaternion();
-  const trunkBendHeading = seededRandom(seed * 9.17 + 4.3)(17) * Math.PI * 2;
+  // The bow's world heading. Tilting about a horizontal axis displaces the
+  // trunk 90° away from that axis, so an authored heading is stored rotated
+  // back by a quarter turn — that way `bendDirection` means "the direction the
+  // trunk bows toward", identical to the space-colonization generator.
+  const seededBendHeading = seededRandom(seed * 9.17 + 4.3)(17) * Math.PI * 2;
+  const trunkBowHeading = bendDirection == null
+    ? seededBendHeading + Math.PI / 2
+    : bendDirection;
+  const trunkBendAxisHeading = trunkBowHeading - Math.PI / 2;
   const trunkBendAxis = new THREE.Vector3(
-    Math.cos(trunkBendHeading),
+    Math.cos(trunkBendAxisHeading),
     0,
-    Math.sin(trunkBendHeading),
+    Math.sin(trunkBendAxisHeading),
   );
 
   // { origin, quaternion, length, radius, level, segments } — BFS like EZ.
@@ -1069,9 +1264,18 @@ export function createBranchingTreeSkeleton({
   // Trunk: optional initial lean carries the classic trunk styles over.
   const rootQuaternion = new THREE.Quaternion();
   if (!spinePoints && lean) {
-    const heading = next() * Math.PI * 2;
+    // The seeded draw is consumed either way, so pinning the lean direction
+    // never shifts the rest of this tree's random stream and every existing
+    // seed keeps its exact geometry.
+    const seededLeanHeading = next() * Math.PI * 2;
+    const leanHeading = leanOffset == null
+      ? seededLeanHeading + Math.PI / 2
+      : trunkBowHeading + leanOffset;
+    const leanAxisHeading = leanHeading - Math.PI / 2;
     rootQuaternion.setFromAxisAngle(
-      new THREE.Vector3(Math.cos(heading), 0, Math.sin(heading)), lean * 0.45);
+      new THREE.Vector3(Math.cos(leanAxisHeading), 0, Math.sin(leanAxisHeading)),
+      lean * 0.45,
+    );
   }
   queue.push({
     origin: new THREE.Vector3(0, 0, 0),
@@ -1130,88 +1334,6 @@ export const TREE_TRUNK_STYLES = Object.freeze({
     height: 1.8, radiusBottom: 0.24 },
 });
 
-// Ready-made example recipes, ordered least → most complex configuration.
-// Used by Tree Lab and the playground scene's showcase row; each is a
-// complete options object for `new StylizedTree(...)`.
-export const STYLIZED_TREE_EXAMPLES = Object.freeze([
-  // 1. Baseline: straight trunk, default crown, one flat color.
-  { seed: 3, size: 1.7, canopyColor: 0x4da258, leafDensity: 1,
-    trunk: TREE_TRUNK_STYLES.straight },
-  // 2. Leaning trunk, same simple crown.
-  { seed: 8, size: 1.8, canopyColor: 0x54a85e, leafDensity: 1,
-    trunk: TREE_TRUNK_STYLES.leaning },
-  // 3. Slight see-through: gap pockets open, branches peek through.
-  { seed: 5, size: 1.9, canopyColor: 0x5eb063, leafDensity: 0.85,
-    trunk: TREE_TRUNK_STYLES.leaning },
-  // 4. Curved trunk + its own irregular crown layout.
-  { seed: 11, size: 2.0, canopyColor: 0x58ab5c, leafDensity: 0.95,
-    trunk: TREE_TRUNK_STYLES.curved },
-  // 5. Color picked from a list, per-seed (forest variation from one spec).
-  { seed: 17, size: 2.0, canopyColor: [0x4da258, 0x7fb84e, 0x9cbf46], leafDensity: 0.95,
-    trunk: TREE_TRUNK_STYLES.curved },
-  // 6. Wide-and-shallow crown (X reach 1.6, Z reach 0.7).
-  { seed: 9, size: 2.0, canopyColor: 0x6db54f, leafDensity: 0.95,
-    canopyWidth: 1.6, canopyDepth: 0.7, trunk: TREE_TRUNK_STYLES.leaning },
-  // 7. Autumn blend: seeded mix between two colors.
-  { seed: 21, size: 2.1, canopyColor: { from: 0xe8a33c, to: 0xd96f29 }, leafDensity: 0.9,
-    trunk: TREE_TRUNK_STYLES.curved },
-  // 8. Gnarled old tree: knotted growth, sparser crown shows the wood.
-  { seed: 14, size: 2.0, canopyColor: 0x8f9e44, leafDensity: 0.72,
-    trunk: TREE_TRUNK_STYLES.gnarled },
-  // 9. Bonsai: corkscrew twist, flat wide pads, HSL-range blossom color.
-  { seed: 26, size: 1.7, leafDensity: 0.8, canopyWidth: 1.4, canopyDepth: 1.2,
-    canopyColor: { hue: [0.9, 1.0], saturation: [0.45, 0.6], lightness: [0.62, 0.72] },
-    trunk: TREE_TRUNK_STYLES.bonsai },
-  // 10. The Liyue golden gingko: fat-based serpentine trunk (bow right,
-  //     top swept hard left, S locked by leanOffset), extra-wide crown,
-  //     pinned pale-gold highlight tone. bendDirection 0 keeps the S in the
-  //     X-Y plane so the silhouette reads head-on in the showcase row.
-  { seed: 12, size: 2.4, canopyColor: 0xf5c531, canopyPalette: { crown: 0xffe98a },
-    leafDensity: 0.95, canopyWidth: 1.5,
-    skeleton: { radialSegments: 10 },
-    trunk: { ...TREE_TRUNK_STYLES.swooping, bend: 0.5, lean: 0.95,
-      bendDirection: 0, height: 2.0, radiusBottom: 0.28 } },
-  // 11. Sumeru-style: long bare pale limbs reaching out of the crown with
-  //     violet leaf bushes only at the branch ends (leafPlacement 'tips').
-  { seed: 31, size: 2.3, pale: true, canopyColor: 0x8578e6,
-    canopyPalette: { crown: 0xbdb2ff },
-    leafDensity: 0.9, canopyWidth: 1.45, leafPlacement: 'tips',
-    trunkReceiveShadow: false,
-    skeleton: { attractionCount: 70, influenceRadius: 1.35 },
-    trunk: { ...TREE_TRUNK_STYLES.curved, bend: 0.3, lean: 0.35, gnarl: 0.45,
-      height: 1.9, radiusBottom: 0.26 } },
-  // 12. MASSIVE climbable Sumeru tree: thick bare limbs long and low enough
-  //     to stand or sit on (scenes read `climbable: true` and collide the
-  //     wood as a trimesh instead of a trunk capsule), sparse skeleton so
-  //     the pale limbs stay on show, foliage clouds only at the limb ends.
-  { seed: 46, size: 4.0, pale: true, climbable: true,
-    canopyColor: 0x8578e6, canopyPalette: { crown: 0xbdb2ff },
-    leafDensity: 0.92, canopyWidth: 1.75, canopyDepth: 1.2,
-    leafPlacement: 'tips', trunkReceiveShadow: false,
-    skeleton: { attractionCount: 55, influenceRadius: 1.7, killRadius: 0.55,
-      segmentLength: 0.36, attractionReach: 0.95, radialSegments: 14,
-      tipRadius: 0.05, minLimbRadius: 0.04, maxNodes: 130 },
-    canopy: { cardsPerCluster: 12, clusterRadius: 0.62 },
-    trunk: { ...TREE_TRUNK_STYLES.leaning, bend: 0.24, lean: 0.42,
-      height: 1.4, radiusBottom: 0.48 } },
-]);
-
-// Centered X offsets for a showcase row: cumulative spacing from each tree's
-// approximate crown footprint, so a massive example doesn't swallow its
-// neighbors the way fixed spacing would.
-export function layoutTreeRow(configs, { margin = 1.6 } = {}) {
-  const footprints = configs.map((config) =>
-    (config.size ?? 1) * (config.canopyWidth ?? 1) * 2.3 + 1.4);
-  const offsets = [];
-  let cursor = 0;
-  footprints.forEach((footprint, index) => {
-    if (index > 0) cursor += (footprints[index - 1] + footprint) / 2 + margin;
-    offsets.push(cursor);
-  });
-  const center = cursor / 2;
-  return offsets.map((offset) => offset - center);
-}
-
 // Recipe documents: a plant serialized as { schema, version, type, options }.
 // The options are exactly what the constructor takes, so a recipe rebuilds
 // the identical plant (generation is deterministic per seed). Defined here —
@@ -1289,6 +1411,24 @@ function booleanOption(value, fallback) {
   return value === undefined ? fallback : Boolean(value);
 }
 
+// `canopy.padLayers` — the horizontal-plate band-pass. A count below 2 is not
+// a plate structure (one band is the whole crown), so it resolves to null
+// rather than silently pruning to a single slab.
+function padLayerOption(value, fallback) {
+  if (value === undefined) return fallback;
+  if (value === null || typeof value !== 'object') return null;
+  const count = integerNumber(value.count, 0, { min: 0, max: 24 });
+  if (count < 2) return null;
+  return Object.freeze({
+    count,
+    // Fraction of each band's pitch that carries foliage; the rest is the
+    // gap a viewer sees sky and limb through.
+    thickness: finiteNumber(value.thickness, 0.5, { min: 0.02, max: 1 }),
+    // Deterministic per-band height wobble, as a fraction of the pitch.
+    jitter: finiteNumber(value.jitter, 0, { min: 0, max: 1 }),
+  });
+}
+
 function colorArray(value, fallback) {
   if (value?.isColor) return value.clone().convertLinearToSRGB().toArray();
   if (Array.isArray(value) && value.length >= 3) {
@@ -1398,6 +1538,29 @@ export const DEFAULT_STYLIZED_TREE_SETTINGS = Object.freeze({
     clusterRadius: 0.48,
     frondCount: 7,
     frondLength: 1.25,
+    // Bare every branch tip below this fraction of the crown's own vertical
+    // extent, lifting the foliage skirt so the trunk and the lower limb
+    // structure read as form. 0 = no lift, which is every historical tree.
+    crownBase: 0,
+    // Keep only this many well-separated foliage attachments and bare the
+    // rest, so the crown reads as discrete pads with visible limb between
+    // them. null = no pruning, which is every historical tree.
+    padCount: null,
+    // Multiplies the card count of every tip that SURVIVES pruning, so a
+    // crown can be restructured into plates or pads at an unchanged card
+    // total instead of simply losing the foliage the pruning removed.
+    padDensityBoost: 1,
+    // Horizontal plates: { count, thickness, jitter }. Keeps tips inside
+    // `count` bands across the crown height and bares the tips between them,
+    // which is the structure of a layered broadleaf and the one thing
+    // isotropic pad pruning cannot produce. null = no plating.
+    padLayers: null,
+    // 0..1, layered-sprays only. Rotates each tuft's spray disc from
+    // across-the-twig (0) to world-horizontal (1). See stylizedTreeFoliage.
+    plateAlignment: 0,
+    // Drops the outer edge of each spray disc as a fraction of its radius, so
+    // a plate sags rather than reading as a machined shelf. 0 = flat.
+    plateDroop: 0,
     shellFill: true,
     sprayLayers: 3,
     spraySpread: 0.8,
@@ -1422,37 +1585,15 @@ export const DEFAULT_STYLIZED_TREE_SETTINGS = Object.freeze({
   }),
 });
 
-// Named tree presets (grouped partial settings): 'default' is the baseline;
-// 'call_me_sensei' is the studio-managed signature look, curated and updated
-// over releases. Community presets register alongside them via
-// registerStylizedTreePreset().
+// Named runtime settings: npm ships only the neutral baseline. Authored tree
+// recipes live in the public Gallery and may be registered explicitly after
+// MCP discovery when an application wants name-based selection.
 const stylizedTreePresetRegistry = new Map([
   ['default', Object.freeze({
     description: 'Baseline stylized tree.',
     label: 'Default',
     settings: Object.freeze({}),
   })],
-  ['call_me_sensei', Object.freeze({
-    description: 'Studio-managed signature tree, curated by Call Me Sensei and updated over releases. Open broadleaf with visible branching: leaf clusters sit at the branch tips instead of filling a solid shell, so the limb structure reads through the crown.',
-    label: 'Call Me Sensei',
-    settings: Object.freeze({
-      skeleton: Object.freeze({ attractionCount: 55, influenceRadius: 1.35 }),
-      tree: Object.freeze({
-        canopyWidth: 1.35,
-        leafDensity: 1.15,
-        leafPlacement: 'tips',
-        trunkColor: Object.freeze([0.58, 0.36, 0.2]),
-      }),
-      trunk: Object.freeze({
-        ...TREE_TRUNK_STYLES.curved,
-        bend: 0.24,
-        gnarl: 0.22,
-        height: 1.9,
-        lean: 0.24,
-        radiusBottom: 0.2,
-      }),
-    }),
-  })],
 ]);
 
 /**
@@ -1592,6 +1733,12 @@ export function createStylizedTreeSettings(options = {}) {
       clusterRadius: finiteNumber(canopySource.clusterRadius, base.canopy.clusterRadius, { min: 0.01 }),
       frondCount: integerNumber(canopySource.frondCount, base.canopy.frondCount, { min: 3, max: 24 }),
       frondLength: finiteNumber(canopySource.frondLength, base.canopy.frondLength, { min: 0.1, max: 4 }),
+      crownBase: finiteNumber(canopySource.crownBase, base.canopy.crownBase, { min: 0, max: 0.95 }),
+      padCount: nullableNumber(canopySource.padCount, base.canopy.padCount, { min: 1, max: 2000 }),
+      padDensityBoost: finiteNumber(canopySource.padDensityBoost, base.canopy.padDensityBoost, { min: 0.1, max: 12 }),
+      padLayers: padLayerOption(canopySource.padLayers, base.canopy.padLayers),
+      plateAlignment: finiteNumber(canopySource.plateAlignment, base.canopy.plateAlignment, { min: 0, max: 1 }),
+      plateDroop: finiteNumber(canopySource.plateDroop, base.canopy.plateDroop, { min: 0, max: 2 }),
       shellFill: booleanOption(canopySource.shellFill, base.canopy.shellFill),
       sprayLayers: integerNumber(canopySource.sprayLayers, base.canopy.sprayLayers, { min: 1, max: 12 }),
       spraySpread: finiteNumber(canopySource.spraySpread, base.canopy.spraySpread, { min: 0.05, max: 4 }),
@@ -2469,16 +2616,25 @@ export class StylizedTree extends THREE.Group {
             baseZ + Math.sin(bend) * (baseRadius * 0.2 + length * t),
           ];
         };
+        // The tip has to end UNDER the surface. The historical profile dived
+        // to a fixed -0.18 however far the root ran, so every preset beyond a
+        // stub laid a long tapered spike flat on the ground in full view —
+        // this is why `medium` and `large` read as black spider legs around
+        // the collar in any frame low enough to see the base, and it lands
+        // squarely on the Gate 1 ground-contact shot. Diving in proportion to
+        // the root's own reach keeps the collar flare on show and puts the
+        // rest of the root where a root belongs.
+        const dive = Math.max(0.18, length * 0.44);
         const tube = createBranchTubeGeometry({
           flareBase: false,
           irregularity: 0.2,
           points: [
             pointAt(0, collarY),
             pointAt(0.2, collarY * 0.45),
-            pointAt(0.4, 0.0),
-            pointAt(0.6, -0.03),
-            pointAt(0.8, -0.07),
-            pointAt(1, -0.18),
+            pointAt(0.4, -dive * 0.1),
+            pointAt(0.6, -dive * 0.3),
+            pointAt(0.8, -dive * 0.6),
+            pointAt(1, -dive),
           ],
           radialSegments: 7,
           radiusEnd: baseRadius * rootSpec.radius * 0.4,
@@ -2550,9 +2706,22 @@ export class StylizedTree extends THREE.Group {
     // Only forward canopy values that differ from the defaults, so the
     // tips-placement geometry presets below keep winning unless the caller
     // explicitly overrides them (exactly the legacy sparse-options behavior).
+    //
+    // That difference test cannot distinguish "not supplied" from "supplied,
+    // and equal to the module default", so a caller that authors the
+    // documented default gets the preset instead — cardsPerCluster: 5 lands
+    // as the branching preset's 2, silently halving the canopy. Callers that
+    // do know which fields they were handed may declare them in
+    // `canopy.explicit`, and those are forwarded whatever their value.
+    // Nothing that omits `explicit` changes behaviour.
+    const explicitCanopyKeys = new Set(
+      Array.isArray(settings.canopy.explicit) ? settings.canopy.explicit : [],
+    );
     const canopyOverrides = {};
     for (const [key, value] of Object.entries(settings.canopy)) {
-      if (!(key in DEFAULT_STYLIZED_TREE_SETTINGS.canopy) ||
+      if (key === 'explicit') continue;
+      if (explicitCanopyKeys.has(key) ||
+          !(key in DEFAULT_STYLIZED_TREE_SETTINGS.canopy) ||
           !sameSettingValue(value, DEFAULT_STYLIZED_TREE_SETTINGS.canopy[key])) {
         canopyOverrides[key] = value;
       }
@@ -2589,7 +2758,16 @@ export class StylizedTree extends THREE.Group {
           ? { shellFill: true, shellBudget: extraBlobs.length * 8 }
           : { shellFill: false, ...(attachments.length ? {} : { cardCount: 0 }) })
         : {}),
-      attachmentOverrides: branchOverrides,
+      attachmentOverrides: resolvePadPruning(
+        attachments,
+        {
+          crownBase: settings.canopy.crownBase,
+          densityBoost: settings.canopy.padDensityBoost,
+          layers: settings.canopy.padLayers,
+          padCount: settings.canopy.padCount,
+        },
+        branchOverrides,
+      ),
       blobs: (generator === 'drawn' || generator === 'branching') && extraBlobs.length
         ? extraBlobs : blobs,
     });
@@ -2604,6 +2782,19 @@ export class StylizedTree extends THREE.Group {
       vegetationShader,
     });
 
+    // A caller can select the style either as `preset` or by handing over the
+    // vegetation shader profile itself (a string, or { style } / { preset } —
+    // the same shape setVegetationShader accepts). Testing only `options.preset`
+    // meant every generator that forwards `vegetationShader` but not `preset` —
+    // BranchTree among them — silently built a bare, untextured trunk.
+    const requestedStyleId = String(
+      options.preset
+      ?? (typeof vegetationShader === 'string'
+        ? vegetationShader
+        : vegetationShader?.style ?? vegetationShader?.preset ?? ''),
+    ).trim();
+    const styleDefaultSurfaceProfile = TREE_SURFACE_PROFILE_DEFAULTS[requestedStyleId] ?? null;
+
     this.trunkMesh = new THREE.Mesh(
       trunkGeometry,
       trunkMaterial ?? createWoodySurfaceNodeMaterial({
@@ -2612,11 +2803,8 @@ export class StylizedTree extends THREE.Group {
         map: trunkMap ?? (
           trunkSurfaceProfile && trunkSurfaceProfile !== 'none'
             ? createTreeSurfaceTexture({ profileId: trunkSurfaceProfile, seed })
-            : options.preset === 'call_me_sensei'
-              ? createTreeSurfaceTexture({
-                profileId: TREE_SURFACE_PROFILE_DEFAULTS.call_me_sensei,
-                seed,
-              })
+            : styleDefaultSurfaceProfile
+              ? createTreeSurfaceTexture({ profileId: styleDefaultSurfaceProfile, seed })
               : null
         ),
         sceneShadowStrength: trunkReceiveShadow ? 1 : 0,
@@ -2630,9 +2818,7 @@ export class StylizedTree extends THREE.Group {
       ? null
       : trunkSurfaceProfile && trunkSurfaceProfile !== 'none'
         ? trunkSurfaceProfile
-        : options.preset === 'call_me_sensei'
-          ? TREE_SURFACE_PROFILE_DEFAULTS.call_me_sensei
-          : null;
+        : styleDefaultSurfaceProfile;
     this.trunkMesh.material.userData.toonlabBarkSurface = {
       profileId: selectedTrunkSurfaceProfile,
       source: authoredTrunkMap