@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/types/styles/sceneStyleRuntime.d.ts

@@ -80,6 +80,7 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
                     z: number;
                 };
             };
+            setSunDirection(direction?: any): any[];
             advanceTime(hoursDelta: any): {
                 accentScale: any;
                 ambientScale: any;
@@ -311,6 +312,7 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
                     z: number;
                 };
             };
+            readonly sunDirection: any[];
             readonly manager: {
                 addLight: (descriptorSource: any) => string;
                 addToScene: (nextScene: any) => /*elided*/ any;
@@ -578,6 +580,7 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
                     z: number;
                 };
             };
+            setSunDirection(direction?: any): any[];
             advanceTime(hoursDelta: any): {
                 accentScale: any;
                 ambientScale: any;
@@ -809,6 +812,7 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
                     z: number;
                 };
             };
+            readonly sunDirection: any[];
             readonly manager: {
                 addLight: (descriptorSource: any) => string;
                 addToScene: (nextScene: any) => /*elided*/ any;
@@ -1083,6 +1087,7 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
             z: number;
         };
     };
+    setSunDirection(direction?: any): any[];
     /**
      * Replaces the physical SkySystem condition while preserving the active
      * style bundle's sky/cloud presentation and coordinated lighting frame.
@@ -1352,6 +1357,7 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
                 z: number;
             };
         };
+        setSunDirection(direction?: any): any[];
         advanceTime(hoursDelta: any): {
             accentScale: any;
             ambientScale: any;
@@ -1583,6 +1589,7 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
                 z: number;
             };
         };
+        readonly sunDirection: any[];
         readonly manager: {
             addLight: (descriptorSource: any) => string;
             addToScene: (nextScene: any) => /*elided*/ any;
@@ -1751,8 +1758,21 @@ export function createSceneStyleRuntime({ collision, collisionAdapter, collision
             uncoveredTargetIds: readonly any[];
         }>;
         readonly ready: boolean;
+        readonly health: Readonly<{
+            backend: "node" | "classic-webgl-unused";
+            casterCount: number;
+            farReady: boolean;
+            hiddenNonCasterCount: number;
+            ok: boolean;
+            ready: boolean;
+            reason: string;
+            renderCount: number;
+            sunName: any;
+        }>;
         readonly renderCount: number;
         readonly shadowTexture: any;
+        readonly nearShadowTarget: any;
+        readonly farShadowTarget: any;
         readonly shadowMatrix: import("three").Matrix4;
         readonly farShadowTexture: any;
         dispose: () => void;

package/types/vegetation/branchTree.d.ts

@@ -1,10 +1,14 @@
 // Source inference fallback: public names retained with permissive signatures.
+export const BRANCH_TREE_ARCHITECTURE: any;
+export const BRANCH_TREE_CANOPY_ARCHITECTURES: any;
 export const BRANCH_TREE_DOCUMENT_TYPE: any;
 export const BRANCH_TREE_DOCUMENT_VERSION: any;
 export const BRANCH_TREE_LEAF_SHAPES: any;
 export class BranchTree { constructor(...args: any[]); [key: string]: any; }
 export const DEFAULT_BRANCH_TREE_SETTINGS: any;
+export function branchTreeStylizedOptions(...args: any[]): any;
 export function createBranchTree(...args: any[]): any;
 export function createBranchTreeDocument(...args: any[]): any;
+export function createBranchTreeRecipe(...args: any[]): any;
 export function createBranchTreeSettings(...args: any[]): any;
 export function parseBranchTreeDocument(...args: any[]): any;

package/types/vegetation/index.d.ts

@@ -1,5 +1,7 @@
 // Source inference fallback: public names retained with permissive signatures.
 export const BARK_SHADER: any;
+export const BRANCH_TREE_ARCHITECTURE: any;
+export const BRANCH_TREE_CANOPY_ARCHITECTURES: any;
 export const BRANCH_TREE_DOCUMENT_TYPE: any;
 export const BRANCH_TREE_DOCUMENT_VERSION: any;
 export const BRANCH_TREE_LEAF_SHAPES: any;
@@ -37,11 +39,9 @@ export const GRASS_SHADER_PROFILE: any;
 export const GRASS_SHADER_PROFILE_DOCUMENT_TYPE: any;
 export const GRASS_SHADER_PROFILE_SCHEMA_VERSION: any;
 export const LEAF_SHAPE_PRESETS: any;
-export const LEGACY_TREE_IDS: any;
-export const LEGACY_TREE_PRESETS: any;
+export const NEEDLE_LEAF_SHAPES: any;
 export class RetainedGrassClumpField { constructor(...args: any[]); [key: string]: any; }
 export const STYLIZED_FOREST_IMPOSTOR_QUALITY: any;
-export const STYLIZED_TREE_EXAMPLES: any;
 export const STYLIZED_TREE_SETTING_FIELD_SCHEMA: any;
 export const STYLIZED_TREE_SETTING_GROUPS: any;
 export class StylizedBush { constructor(...args: any[]); [key: string]: any; }
@@ -63,6 +63,7 @@ export const TREE_SHADER_DOCUMENT_TYPE: any;
 export const TREE_SHADER_PROFILE: any;
 export const TREE_SHADER_SCHEMA_VERSION: any;
 export const TREE_SURFACE_PROFILES: any;
+export const TREE_SURFACE_PROFILE_ALIASES: any;
 export const TREE_SURFACE_PROFILE_DEFAULTS: any;
 export const TREE_TRUNK_STYLES: any;
 export const UNDERSTORY_AERIAL_FADE: any;
@@ -89,6 +90,7 @@ export function applyGrassShader(...args: any[]): any;
 export function applyVegetationShader(...args: any[]): any;
 export function applyVegetationShaderScope(...args: any[]): any;
 export function bakeFoliageGeometry(...args: any[]): any;
+export function branchTreeStylizedOptions(...args: any[]): any;
 export function combineMasks(...args: any[]): any;
 export function createBakedFoliageMaterial(...args: any[]): any;
 export function createBakedLeafTexture(...args: any[]): any;
@@ -96,6 +98,7 @@ export function createBarkGradientMap(...args: any[]): any;
 export function createBarkShaderSettings(...args: any[]): any;
 export function createBranchTree(...args: any[]): any;
 export function createBranchTreeDocument(...args: any[]): any;
+export function createBranchTreeRecipe(...args: any[]): any;
 export function createBranchTreeSettings(...args: any[]): any;
 export function createBranchTubeGeometry(...args: any[]): any;
 export function createBranchingTreeSkeleton(...args: any[]): any;
@@ -103,6 +106,7 @@ export function createCallMeSenseiGrassField(...args: any[]): any;
 export function createCallMeSenseiGrassMaterial(...args: any[]): any;
 export function createCanopyBlobs(...args: any[]): any;
 export function createCapEdgeWeight(...args: any[]): any;
+export function createCurveFrame(...args: any[]): any;
 export function createDensityWeightMask(...args: any[]): any;
 export function createFlowerBloomNodeMaterial(...args: any[]): any;
 export function createFlowerHeadBillboardNodeMaterial(...args: any[]): any;
@@ -126,7 +130,6 @@ export function createGrassShaderProfileSettings(...args: any[]): any;
 export function createGrassShaderSettings(...args: any[]): any;
 export function createImportedVegetationMaterial(...args: any[]): any;
 export function createLeafSpriteTexture(...args: any[]): any;
-export function createLegacyTree(...args: any[]): any;
 export function createNoisePatchMask(...args: any[]): any;
 export function createOrganLeafSpriteTexture(...args: any[]): any;
 export function createSlopeMask(...args: any[]): any;
@@ -152,8 +155,6 @@ export function deriveCanopyPalette(...args: any[]): any;
 export function disposeExportGroup(...args: any[]): any;
 export function getFlowerPresetOptions(...args: any[]): any;
 export function getGrassPresetOptions(...args: any[]): any;
-export function getLegacyTreePreset(...args: any[]): any;
-export function getLegacyTreePresetOptions(...args: any[]): any;
 export function getStylizedTreePresetOptions(...args: any[]): any;
 export function getTreeSurfaceProfileOptions(...args: any[]): any;
 export function getVegetationMaterialContract(...args: any[]): any;
@@ -162,7 +163,6 @@ export function getVegetationShaderScopeExcludedFields(...args: any[]): any;
 export function getVegetationShaderScopeFieldSchema(...args: any[]): any;
 export function getVegetationShaderScopeSettingGroups(...args: any[]): any;
 export function isVegetationSharedShaderGroup(...args: any[]): any;
-export function layoutTreeRow(...args: any[]): any;
 export function loadCallMeSenseiGrassClump(...args: any[]): any;
 export function loadCompiledTreeAsset(...args: any[]): any;
 export function matchGrassColorPalette(...args: any[]): any;
@@ -187,7 +187,9 @@ export function registerStylizedTreePreset(...args: any[]): any;
 export function registerVegetationShaderPreset(...args: any[]): any;
 export function resolveCanopyColor(...args: any[]): any;
 export function resolveGrassColorPalette(...args: any[]): any;
+export function resolvePadPruning(...args: any[]): any;
 export function resolveTreeDitherMode(...args: any[]): any;
+export function resolveTreeSurfaceProfileId(...args: any[]): any;
 export function resolveVegetationShaderPreset(...args: any[]): any;
 export function resolveVegetationShaderRoleSettings(...args: any[]): any;
 export function sanitizeGrassPresetSettings(...args: any[]): any;

package/types/vegetation/scatter.d.ts

@@ -1,6 +1,7 @@
 // Source inference fallback: public names retained with permissive signatures.
 export function combineMasks(...args: any[]): any;
 export function createCapEdgeWeight(...args: any[]): any;
+export function createCurveFrame(...args: any[]): any;
 export function createDensityWeightMask(...args: any[]): any;
 export function createNoisePatchMask(...args: any[]): any;
 export function createSlopeMask(...args: any[]): any;

package/types/vegetation/stylizedTree.d.ts

@@ -1,6 +1,5 @@
 // Source inference fallback: public names retained with permissive signatures.
 export const DEFAULT_STYLIZED_TREE_SETTINGS: any;
-export const STYLIZED_TREE_EXAMPLES: any;
 export const STYLIZED_TREE_SETTING_FIELD_SCHEMA: any;
 export const STYLIZED_TREE_SETTING_GROUPS: any;
 export class StylizedTree { constructor(...args: any[]); [key: string]: any; }
@@ -13,7 +12,7 @@ export function createStylizedTreeSettings(...args: any[]): any;
 export function createTreeSkeleton(...args: any[]): any;
 export function createTreeTrunkGeometry(...args: any[]): any;
 export function getStylizedTreePresetOptions(...args: any[]): any;
-export function layoutTreeRow(...args: any[]): any;
 export function polarProfileFromOutline(...args: any[]): any;
 export function registerStylizedTreePreset(...args: any[]): any;
+export function resolvePadPruning(...args: any[]): any;
 export function serializableTreeOptions(...args: any[]): any;

package/types/vegetation/stylizedTreeFoliage.d.ts

@@ -1,5 +1,6 @@
 // Source inference fallback: public names retained with permissive signatures.
 export const LEAF_SHAPE_PRESETS: any;
+export const NEEDLE_LEAF_SHAPES: any;
 export class StylizedTreeFoliage { constructor(...args: any[]); [key: string]: any; }
 export const TREE_FOLIAGE_ARCHITECTURES: any;
 export const TREE_FOLIAGE_BLOBS: any;

package/types/version.d.ts

@@ -1 +1 @@
-export const TOONLAB_VERSION: "0.4.19";
+export const TOONLAB_VERSION: "0.4.21";

package/agents/references/geology-playbook.md

@@ -1,118 +0,0 @@
-# Geology assembly playbook
-
-Use this reference with `karst-cliff-construction` and `outdoor-world`. It
-describes reusable landform craft without depending on project-specific
-helpers, asset IDs, or a frozen catalog count.
-
-## 1. Establish the parent mass
-
-Approve an untextured continuous terrain/heightfield silhouette first:
-headlands, bays, terraces, tower envelopes, channel, beach, and submerged bed.
-Catalog rocks dress and articulate that parent mass; they must not be the only
-thing preventing the world from reading as hollow.
-
-Reject before dressing when:
-
-- the hero silhouette is wrong;
-- the channel or beach footprint is clogged;
-- the cliff is a thin wall with no top/underwater continuation;
-- separate towers overlap into one clump from an approved camera.
-
-## 2. Select donors by visible role
-
-Query the connected ToonLab OSS or Pro catalog and shortlist with positive
-`dimensionsMeters`, taxonomy, scale class, and immutable preview/asset URLs.
-Family names and tags are search hints, not visual proof. Review contact sheets
-or finalists under one neutral material and camera azimuth.
-
-Useful morphology:
-
-| Role | Visible requirement |
-|---|---|
-| Primary face | Broad load-bearing plane, gravity-aligned relief, no prop-like outline |
-| Corner/termination | A turn or return face that buries cleanly into the parent mass |
-| Bedding ledge | A real horizontal lip with enough depth to cast a recess shadow |
-| Buttress/wedge | A seam bridge whose rear and toe can be buried |
-| Waterline notch | Rounded or undercut lip that continues below the surface |
-| Talus | Small jointed collapse block; free rotation is appropriate only here |
-
-Choose target dimensions in metres from the published native dimensions.
-Reject missing or invalid dimensions before download. Avoid solving an entire
-wall by stretching one small donor; report mean/max scale and worst axis ratio
-per structural role.
-
-## 3. Build courses, not rubble
-
-Primary faces share a near-common up axis and facing. Vary crop, burial,
-neighbour overlap, tier, yaw silhouette, and moderate scale; do not tumble
-load-bearing panels. Free three-axis tumbling belongs to collapse products.
-
-Starting burial ranges, to be verified in silhouette:
-
-- primary faces: bury roughly 30–60% of module depth;
-- bedding ledges: bury the rear majority so only the lip projects;
-- tower cores: seat the footing/course overlap, not most of the tower;
-- talus: rest in contact and bury enough to remove floating toes.
-
-Build in this order:
-
-1. primary faces at noses, re-entrants, terminations, and terrace breaks;
-2. bridging ledges, buttresses, crevice wedges, and recessed corbels;
-3. waterline/submerged continuation and restrained talus;
-4. vegetation caps and story dressing.
-
-If a placement helper automatically splits an oversized request into a stack,
-make that result explicit and refusable. Subdivision must not introduce yaw,
-pitch, or roll jitter unless the caller deliberately requests a tumbled role.
-
-## 4. Publish shared formation contracts
-
-Sibling modules must consume the same world-space values rather than derive
-private approximations:
-
-- parent height/envelope;
-- water level and submerged bed;
-- bedding elevation ladder;
-- visible face plane/standoff;
-- cliff-top and vegetation-cap polygons;
-- fall lips, landing pools, and exclusion zones.
-
-One useful bedding ladder is `base + courseIndex * spacing`; derive `base` and
-`spacing` from the terrain terracing/style rather than copying the qualifying
-scene's numbers. Align visible beds across neighbouring formations.
-
-## 5. Unify the material treatment
-
-Use one intentional parent lithology. The rock shader can replace source
-albedo and apply one projected treatment across morphologically compatible
-donors, but it cannot change incompatible geometry into the same geology.
-Record any cross-taxonomy donor override and judge the result from silhouette,
-bedding, and surface response.
-
-Prefer one `applyRockShader(formationRoot, settings)` call. Verify the report's
-texture source and shadow defaults. Use `setRockShaderSceneState` for the
-current water level so the wet band follows the shoreline.
-
-## 6. Prevent recognizable repetition
-
-Repeated asset ids are normal modular modelling. Repeated camera-facing
-silhouettes are the defect. For nearby copies vary at least three of: visible
-crop/burial, tier, neighbour overlap, meaningful scale, and camera-facing yaw.
-Never use regular spacing or a visible kit row.
-
-Placement metrics are rejection floors. They cannot prove that the rendered
-formation reads as one mass.
-
-## 7. Verify before approval
-
-- Wait for application readiness and a stable rendered scene graph.
-- Capture hero, wide, close, flyover, and top-down views.
-- Isolate terrain, rock formation, water, and lighting when assigning a defect.
-- Scan world-space extents for accidental slabs, dams, or oversized caps.
-- Report module counts, donor dimensions, transformed dimensions, burial,
-  per-role scale statistics, and active LODs.
-- Squint at the silhouette: if individual boulders or a sawtooth crest remain
-  legible, the cliff is still a pile.
-
-Automated checks may reject gaps, invalid scale, and repeated transforms. Only
-rendered multi-view evidence can approve the formation.

package/agents/skills/claude/karst-cliff-construction/SKILL.md

@@ -1,258 +0,0 @@
----
-name: karst-cliff-construction
-description: Experimental research guidance for assembling a stylized cliff, gorge, karst tower, or sea stack from catalog rocks, including silhouette selection, parent geology, transform grammar, and measurable rubble-pile rejection gates; not a supported automatic cliff builder.
----
-
-# Experimental cliff construction from catalog rocks
-
-This is retained as research and review guidance. ToonLab can find rocks,
-report their dimensions/taxonomy, and shade supplied geometry, but neither the
-package nor an LLM is currently qualified to turn those assets into a polished
-cliff automatically. Use it only for an explicit experiment, record every
-manual placement/transform decision, and do not present success as a stable
-one-shot feature.
-
-This is the assembly craft that sits between `rockgen` (which makes a rock) and
-the `outdoor-world` skill (which owns the whole scene). Read
-`../outdoor-world/SKILL.md` first for the landform-before-props ordering and the
-rejection gates; this skill is how you actually execute the rock layer. Read
-the agent-neutral
-[geology playbook](../../../references/geology-playbook.md) for the compact
-morphology, course, burial, and verification reference.
-
-Everything here was derived by building a reference-driven karst gorge from the
-full catalog available during qualification and having it rejected
-several times. Catalog contents change; query the connected OSS or Pro MCP
-surface instead of assuming a fixed asset count or frozen family membership.
-The failure modes are listed as prominently as the method, because they are
-what cost the time.
-
-## The single most important rule
-
-**A cliff is one mass. Individual rocks must not be legible as individual
-rocks.**
-
-Squint at the frame from the hero camera. If you can pick out separate boulders
-in the wall face, the formation has failed, no matter how good the rocks are or
-how correct the metrics look. Every rule below exists to serve that one read.
-
-The characteristic failure is an **angular rubble pile**: many modules at many
-orientations, each individually readable, with a sawtooth crest. It looks like
-quarry spoil. It happens because tumbling every rock feels like variety, and
-because an anti-repetition gate seems to demand it. It does not.
-
-## Selection: look, do not read tags
-
-**Family names do not guarantee silhouette.** In the tested catalog snapshot,
-`column-field` contains no columnar geometry at all; `broad-wall` is mostly
-hourglass pedestals; the only assets that genuinely read as vertical fluting
-live in `vertical-face`. Selecting by `familyId` or by tag produces the wrong
-formation when the current previews disagree with the label.
-
-So: **render contact sheets and choose visually.** Download the catalog
-thumbnails, lay them out in a labelled grid per family, and look at every one
-before choosing. Better still, render the actual GLBs under a single flat
-material at the intended camera azimuth — thumbnails show baked material colour,
-which is discarded at runtime (see below), so silhouette is the only thing that
-matters and the thumbnail can mislead you about it.
-
-Budget an hour for this. It is the highest-leverage hour in the whole job.
-
-**Use the published donor dimensions.** Current OSS and Pro rock search results
-include positive `dimensionsMeters.width`, `.height`, and `.depth`. Reject a
-record with missing, zero, negative, or axis-ambiguous dimensions before
-download. Load a finalist only to verify silhouette/material compatibility,
-not to discover its size. Drive placement from **target metres**, never from a
-raw scale multiplier. A project helper such as `place({ height: 40 })` is
-reviewable; `scale: 6.3` is not a ToonLab contract or an art-direction decision.
-
-## Geology: one parent rock, many catalog families
-
-A formation must read as **one lithology**. Limestone, sandstone and granite do
-not alternate between adjacent modules unless the level authors a readable fault.
-
-This can conflict with selecting by silhouette, because useful shapes may span
-families with different `taxonomy.geology`. Treat geology as meaningful search
-metadata, but allow an intentional stylized donor override when the visible
-morphology is compatible and one material treatment makes the formation read
-as a deliberate parent rock. Record that override; never imply that replacing
-albedo changes the source mesh's physical morphology.
-
-So the working method is:
-
-1. Select every rock by **role and silhouette**, ignoring its geology tag.
-2. Apply the rock shader to the whole formation root with one settings object.
-3. Verify that every included part reports the same intended texture source and
-   material profile. One root call is the safest way to prevent call-site drift;
-   repeated calls with byte-identical settings are visually equivalent.
-
-Two consequences worth knowing before you are surprised by them:
-
-- Baked green grass caps on some catalog rocks **disappear** under `replace`.
-  Re-create caps deliberately, via the shader's grass layer or via vegetation.
-- Per-part calls invite accidental settings drift. Prefer the formation root
-  unless a deliberately distinct lithology needs its own documented pass.
-
-For a genuinely different stone in the same frame — a quarried quay against a
-natural cliff — mark those meshes `userData.rockShaderExclude = true`, run the
-main pass, then clear the flag and run a second pass over just that group.
-Order matters: setting the flag before your own pass silently disables it.
-
-### Matching geology to real morphology
-
-Choose donors by what the landform actually does, not by name:
-
-| Landform feature | What to look for |
-|---|---|
-| Rillenkarren (vertical dissolution runnels on karst) | Parallel vertical prism relief — columnar-basalt donors read as this almost exactly |
-| Broad fluted wall envelope | Barrel-curved faces with wide vertical creases |
-| Bedding partings | Donors with true horizontal lips and shelf stacks |
-| Undercut karst tower | Inverted flares — wider at mid-height than at the base |
-| Solution notch at the waterline | River-worn blocks with a rounded overhanging lip |
-| Collapse product below a wall | Jointed angular blocks, tumbled freely — the one place tumbling is correct |
-
-## The transform grammar
-
-Per role, and these ranges are the difference between a landform and a pile:
-
-**Primary wall faces.** Share a near-common up axis and a near-common facing.
-Yaw varies the silhouette *edge*, not the rock's orientation. Pitch and roll
-near zero — fluting is gravity-parallel, and a tilted flute reads as a mistake.
-Bury 30–60 % of module depth. Present the face, not the corners.
-
-**Corners and terminations.** Yaw is set by the turn, not jittered. Turn the
-broad mass toward the coastline change and bury the return face into its
-neighbour so it never shows a free edge.
-
-**Shelves and bedding ledges.** Rotate a useful plane upward, crop the rear into
-the parent mass, and support the underside with a face or buttress so the
-overhang is a shadowed recess rather than a lit floating slab.
-
-**Crevice wedges.** The one primary role where roll is large — 8–15° — because a
-wedge is *supposed* to be jammed at an angle.
-
-**Talus and waterline blocks.** Free three-axis rotation, 0.7–1.4 non-uniform
-scale, always resting in contact with the surface below.
-
-### Scale discipline
-
-**Cap the uniform scale, and audit it.** Blowing a 6 m donor up 22× is what makes
-a wall read as stretched rather than stacked: the projected texture smears, the
-silhouette loses its authored detail, and one module tries to do the work of a
-course. Prefer more modules near native size over fewer giant ones.
-
-Instrument it. Report per-role mean and max uniform scale and the worst axis
-ratio, and warn loudly when a role exceeds its ceiling, so a wall module cannot
-silently stretch a donor. A run that measured `mean 6.35, max 22.3, worst axis
-ratio 4.08` was visibly stretched and nobody noticed until an art director said
-"why is it stretched".
-
-### Placement helpers must not reinterpret intent
-
-An oversized authored wall module must never silently become a jittered stack.
-Make any over-ceiling substitution **explicit and refusable**: accept an option
-such as `onOverCeiling: 'reject' | 'shrink' | 'stack'`, default load-bearing wall
-roles to `reject`, and return/report the actual strategy and placement count.
-Reserve `stack` for an intentional course plan; reserve tumbling for talus.
-
-Keep course variation separate from scatter variation. Load-bearing faces use
-`courseJitter: 0` unless the author requests a measured, small range; they must
-not inherit free yaw/roll jitter from a rubble scatter helper. Likewise, label
-Euler rotations by their local-axis order. A field named `pitch` is not a
-world-space lean after yaw. Prefer a world-space contract such as
-`leanInto: { direction, angle }`, or document and test the exact local axis.
-
-## Anti-repetition, correctly understood
-
-The gate is **recognizable repetition**, not a repeated asset id. Reusing a good
-modular rock is normal environment modelling.
-
-Two copies of one id must not present the same camera-facing silhouette. Satisfy
-at least three of: yaw differs ≥ 25° against the camera-facing normal; different
-tier; uniform scale differs ≥ 25 %; burial fraction differs ≥ 8 points so a
-different portion of the outline survives; different overlapping neighbour.
-
-Absolute prohibitions: no twins within ~35 m at the same tier; no regular
-spacing interval; no kit rows.
-
-**Audit it, but do not trust the audit.** A placement-based audit scores
-positions and transforms — it cannot see the rendered silhouette. Zero offences
-and a rubble pile are entirely compatible. The audit is a floor, not approval.
-
-## Structural coherence
-
-**Bedding must be continuous across formations.** Beds are the same beds. Derive
-one elevation ladder for the whole scene — ideally from the terrain's own
-terracing, so rock and parent mass agree — and place every bedding ledge on it.
-Bands that line up across neighbouring towers at equal elevation is the single
-detail that sells a karst formation.
-
-**Publish it.** The wall that computes the ladder should expose it, and every
-other formation should read it rather than re-deriving. Be aware of build order:
-if a composer builds parts in sequence, a later part cannot read an earlier
-part's published values through a context object that is only assigned after the
-whole composer returns. Pass shared values through the composer explicitly, or
-have each part fall back to a documented constant and log which path ran.
-
-Publish a shared **face plane** as well as the terrain/height envelope. Shelves,
-bridges, falls, vegetation lips, and sibling wall modules must read the same
-world-space surface contract instead of hard-coding a standoff against a wall
-revision that can move later.
-
-**Bridge every seam.** After the primary masses, rasterise their footprints,
-find pairs with a traceable boundary, and wedge shelves, buttresses and crevice
-slabs across them, each with a corbel tucked beneath so the overhang is a
-shadowed recess. Terrain must never show through a gap between rocks.
-
-**Do not let painted detail do geometry's job.** Horizontal stratification drawn
-into a projected texture becomes a stretched line on a scaled rock, and thin
-crack layers alias into dashed "stitched" lines at any realistic tile
-resolution. Deliver bedding as **stacked silhouettes** — real courses with real
-overhangs — and reserve the texture for surface grain.
-
-## Build order
-
-Do not start by scattering rocks.
-
-1. **Macro landform.** A continuous heightfield with the full silhouette:
-   headlands, bays, terraces, the channel, the bed. Approve it untextured. If
-   the macro silhouette is wrong, no rock dressing saves it.
-2. **Primary structure.** Large faces at structural events only — noses,
-   re-entrants, terminations, terrace breaks. Subordinate to the macro mass.
-3. **Secondary structure.** Bridging shelves, buttresses, crevice wedges.
-4. **Tertiary dressing.** Waterline notch, submerged continuation, minimal
-   talus, story detail.
-
-Talus quantity is a geology decision, not a dressing preference. A dissolution
-gorge has almost none; a frost-shattered alpine face has fans. An evenly spread
-scree carpet is always wrong.
-
-## Verification
-
-Numeric checks reject obvious failure; only looking can approve.
-
-- **Isolate before blaming.** Render subsystems alone — with their light rig, or
-  you get black — to attribute a defect. A "flowing water" texture on the cliffs
-  turned out to be the terrain's ground shader, not the waterfalls, and only an
-  isolation capture settled it.
-- **Scan for outliers.** Traverse the scene for meshes above a size threshold and
-  print path, world extent and position. This catches the 104 m slab damming a
-  72 m channel that nobody sees because it reads as "background".
-- **Squint at the silhouette first**, before texture, before colour. One mass or
-  a pile.
-- **Judge from every approved camera**: hero, wide, close, flyover, top-down. A
-  formation can read as one mass from the hero and as a kit row from above.
-- **Settle the scene before screenshotting.** Modules resolve async work — GLB
-  loads, render passes — after their factory returns. Wait for a stable scene
-  graph, not a fixed frame count, or you will review a frame with subsystems
-  missing while the manifest claims they are present.
-
-## Performance notes that shape the art
-
-- The rock shader creates a **material per mesh**, so instancing is unavailable
-  and every tertiary rock costs a draw call. Budget the tertiary layer.
-- Catalog GLBs carry baked LODs; use the higher indices for distant modules.
-- Catalog GLBs can require KTX2/Draco decoders. Create one shared transcoder set
-  with `createModelAssetTranscoders({ decoderBasePath, renderer })`, pass it to
-  every `loadModelAsset(url, { transcoders })` call, and dispose it once after
-  all model loads. Do not construct decoder/transcoder resources per rock.