lecodes-cli 2.5.1 → 2.8.0

package/package.json

@@ -1,37 +1,37 @@
 {
   "name": "lecodes-cli",
-  "version": "2.5.1",
+  "version": "2.8.0",
   "dependencies": {
     "@letary/chisel": "^0.15.0",
     "jimp": "^1.6.1",
-    "lecodes-sdk": "2.5.1",
-    "selfsigned": "^2.4.1"
+    "lecodes-sdk": "2.8.0",
+    "selfsigned": "^2.4.1",
+    "typescript": "^5.8.3"
   },
   "devDependencies": {
     "lecodes-design": "https://storage.yandexcloud.net/le-codes/releases/packages/lecodes-design/lecodes-design-0.11.0.tgz",
-    "lecodes-headless": "2.5.1",
+    "lecodes-headless": "2.8.0",
     "qrcode-terminal": "^0.12.0",
     "lecodes-3d-editor": "https://storage.yandexcloud.net/le-codes/releases/packages/lecodes-3d-editor/lecodes-3d-editor-0.9.0.tgz",
-    "lecodes-assets": "2.5.1",
+    "lecodes-assets": "2.8.0",
     "lecodes-creator-nav": "0.19.0",
-    "lecodes-gl-lite": "2.5.1",
-    "lecodes-web-frame": "2.5.1",
-    "lecodes-web-player": "2.5.1",
-    "lecodes-web-shared": "2.5.1",
+    "lecodes-gl-lite": "2.8.0",
+    "lecodes-web-frame": "2.8.0",
+    "lecodes-web-player": "2.8.0",
+    "lecodes-web-shared": "2.8.0",
     "lecodes-web-lite": "2.0.7",
     "heic-decode": "^2.1.0",
-    "marcidb-embedded": "^0.15.0",
+    "marcidb-embedded": "^0.18.0",
     "sharp": "^0.35.2"
   },
   "peerDependencies": {
     "lecodes-design": "^0.11.0",
-    "lecodes-headless": "^2.5.1",
+    "lecodes-headless": "^2.8.0",
     "lecodes-3d-editor": "^0.9.0",
-    "lecodes-assets": "^2.5.1",
+    "lecodes-assets": "^2.8.0",
     "heic-decode": "^2.1.0",
-    "marcidb-embedded": "^0.15.0",
-    "sharp": "^0.35.2",
-    "typescript": "^5.8.3"
+    "marcidb-embedded": "^0.18.0",
+    "sharp": "^0.35.2"
   },
   "bin": {
     "lecodes": "dist/index.js"
@@ -64,9 +64,6 @@
     "lecodes-assets": {
       "optional": true
     },
-    "typescript": {
-      "optional": true
-    },
     "marcidb-embedded": {
       "optional": true
     },

package/runtime/materials/foliage-cards.mat

@@ -55,7 +55,8 @@ material {
         { type : sampler2d, name : windNoise },
         { type : float4,    name : plant },
         { type : float4[8], name : benders },
-        { type : float4[8], name : benderMotion }
+        { type : float4[8], name : benderMotion },
+        { type : float,     name : debugMode }       // the impostor lab's DEBUG VIEW (glb.cpp CREATOR_FOLIAGE_DEBUG; 0 = off): 1 albedo, 2 hull normal as colour, 3 the sky term on white — the sun off in all three
     ]
 }
 
@@ -85,7 +86,10 @@ vertex {
         // (`leaf.z`, narrowed toward the view line into the light; less deep in the crown), one scalar the fragment
         // multiplies by the light's colour, intensity and SHADOW
         float ao = mix(1.0, f.vao, clamp(materialParams.leaf.w, 0.0, 1.0));
-        vec3 ambient = shIrradianceV(f.hull) * frameUniforms.iblLuminance * ao;
+        // + THE SKY THROUGH THE LEAF (look.x, Foliage `skyThrough`): a card below the crown's middle faces down and would
+        // read the environment's ground alone - a tenth of the zenith under an overcast sky, the lower half of every plant
+        // black (2026-11-04) - so the thin leaf adds that share of the sky on its other side
+        vec3 ambient = (shIrradianceV(f.hull) + materialParams.look.x * shIrradianceV(-f.hull)) * frameUniforms.iblLuminance * ao;
         vec3 l = frameUniforms.lightDirection;
         vec3 v = normalize(getWorldCameraPosition() - f.wp);
         float wrap = clamp(materialParams.sway.w, 0.0, 1.0);
@@ -125,6 +129,15 @@ fragment {
         material.reflectance = 0.0;
         material.ambientOcclusion = 0.0;   // Filament's IBL off: the ambient is the vertex shader's, below
         material.emissive = vec4(base.rgb * variable_lightv.rgb, 0.0);
+        // THE DEBUG VIEW (debugMode, the impostor lab): the alpha path above stays, only the colour changes; the sun is
+        // off (surfaceShading returns 0). 1 = the albedo, 2 = the hull normal (world) ×½+½, 3 = the sky term on white
+        float dbg = materialParams.debugMode;
+        if (dbg > 0.5) {
+            vec3 hn = variable_radial.xyz;
+            float hl = length(hn);
+            hn = hl > 1e-5 ? hn / hl : vec3(0.0, 1.0, 0.0);
+            material.emissive = vec4(dbg < 1.5 ? base.rgb : dbg < 2.5 ? hn * 0.5 + 0.5 : variable_lightv.rgb, 0.0);
+        }
     }
 
     // PER LIGHT (the sun first): the vertex shader's wrapped Lambert + translucency scalar, times the light and its
@@ -132,6 +145,7 @@ fragment {
     // from the crown's own card-on-card one, and a young pine at full strength went black (2026-10-18). A lamp gets the
     // sun's scalar too — the lean tier is for cards seen from a distance, where a lamp's own angle on a leaf is not read
     vec3 surfaceShading(const MaterialInputs materialInputs, const ShadingData shadingData, const LightData lightData) {
+        if (materialParams.debugMode > 0.5) return vec3(0.0);   // the debug view: no sun
         float lit = mix(1.0, lightData.visibility, clamp(materialParams.leaf.y, 0.0, 1.0));
         float reach = lightData.colorIntensity.w * lightData.attenuation * lit;
         return shadingData.diffuseColor * lightData.colorIntensity.rgb * (reach * (variable_lightv.w + variable_leafv.x) / PI);

package/runtime/materials/foliage-impostor.mat

@@ -24,14 +24,22 @@
 //     A point p seen in a frame at a = ½ + ½·dot(p - c, right)/r, b = ½ + ½·dot(p - c, up)/r (a right, b UP) lands at
 //     the atlas uv ((i + a)/A, (k + 1 - b)/E) on the grid, ((i + a)/N, (j + 1 - b)/N) on the octahedron — image row 0
 //     at the top, the glTF convention (flipUV false, getUV0() raw).
-//   • baseColorMap: rgb = albedo (sRGB), a = coverage. metallicRoughnessMap (linear): rg = the crown's HULL normal
-//     (what the cards shade by: from 0.6 of the plant's height over its origin to the surface, foliage-wind.vs f.hull)
-//     in OBJECT space, packed with the FULL-sphere octahedral map ×½+½ (normalDecode below, the baker's normalEncode —
+//   • baseColorMap: rgb = albedo (sRGB), a = COVERAGE, fractional: the baker takes S×S samples a texel (default 8×8) and
+//     stores covered / S². metallicRoughnessMap (linear): rg = the SHADING normal in OBJECT space — a card sample's the
+//     crown's HULL normal (what the cards shade by: from 0.6 of the plant's height over its origin to the surface,
+//     foliage-wind.vs f.hull), a bark sample's the MESH normal (the interpolated vertex NORMAL turned toward the frame's
+//     viewer: what foliage.mat lights the bark by), averaged over the texel's samples —
+//     packed with the FULL-sphere octahedral map ×½+½ (normalDecode below, the baker's normalEncode —
 //     not the frame layout's hemi impEncode/impDecode; its seam pole at the corners is object −Y): a far-side leaf keeps a normal that looks away, which is the
 //     crown's shading; b = the DEPTH along the frame's view axis, z = dot(p - c, d)/r stored z·½+½ (1 = the point
 //     nearest this frame's viewer, ½ = the quad plane, 0 = the farthest); a = the baked sky visibility (vertexAo.ts'
-//     COLOR_0.r). An uncovered texel carries its nearest covered neighbour's data (the dilation): a depth read just
-//     outside a silhouette continues the surface, while the coverage there stays under the cutoff.
+//     COLOR_0.r). occlusionMap (linear, NOT an occlusion): r = the BARK fraction of the texel's covered samples (an
+//     opaque glTF material is bark, a MASK one a card), g = 0, b = the BARK's OCCLUSION: what foliage.mat darkens the bark's
+//     ambient by beyond the sky visibility (its baked cavity x its occlusion map x its normal map's cavity), 1/255 at least
+//     - b = 0 is an atlas from before the channel and reads 1. g = 0 marks the map present: the engine's default for
+//     an unbound sampler is a 1×1 white (g = 1), so the shader reads bark = r·(1 - g) and an older atlas reads none.
+//     An uncovered texel carries its nearest covered neighbour's data, albedo and bark (the dilation): a depth read just
+//     outside a silhouette continues the surface, while the coverage there stays 0.
 //
 // THE QUAD: 4 vertices whose POSITION is ignored (the baker writes the sphere's box corners there only so gltfio's
 // culling box is right); TEXCOORD_0 is the corner id, corner = uv·2-1 (x right, y up). The vertex shader takes the
@@ -43,11 +51,20 @@
 // (i+1,k+1) (i,k+1) (i+1,k) with (t.x+t.y-1, 1-t.x, 1-t.y), so the picture morphs between neighbouring views instead of
 // popping. On the grid i+1 wraps mod A and k+1 stops at the top row (min(k+1, E-1)); on the octahedron both stop at N-1.
 //
+// THE WIND (2026-11-04): the quad sways with its tree. Each corner's world position is bent by the cards' own plant-level
+// lean (foliage-wind.vs foliageField + foliageBend, included under FOLIAGE_BEND_ONLY): the wind field and the gust at the
+// plant's root, the rotation about the root across the wind growing with the corner's distance from it, by the same
+// `wind` / `sway` / `profile` the engine writes to every foliage material. The leaves' shiver and the benders' touch stay
+// out (below a far tree's pixel; the touch is grass-scale). Only the drawn position moves: p, the frame pick and the
+// lighting data describe the still tree. The depth variants run the same vertex code, so the shadow leans too. The A/B is
+// `Foliage.configure({ wind: false })` (a zero field: no axis to bend about).
+//
 // THE VARYINGS (Filament caps custom variables at 5; four used):
 //   impFrames = (frame0, frame1, frame2, hash) — a frame packed as i·E + k (grid) / i·N + j (octahedron); hash = the
 //               cards' per-instance tint hash
 //   impPos    = (p.xyz, w0)                     — p = the fragment's offset from c in object space (linear over the quad)
-//   impW      = (w1, alive, 0, 0)               — w2 = 1 - w0 - w1; alive = the distance fade (`fade`, as the cards)
+//   impW      = (w1, alive, lodEst, 0)          — w2 = 1 - w0 - w1; alive = the distance fade (`fade`, as the cards);
+//               lodEst = the coverage boost's mip term, max(mip - 1, 0) (THE FRAGMENT)
 //   impRot    = the model's rotation as a quaternion (its columns normalised): getWorldFromModelMatrix() exists in the
 //               vertex stage only, and the fragment needs it to take the atlas' object-space normal to the world
 // The frame choice and the weights depend on the CENTRE's direction alone, so they are the same at the four corners:
@@ -55,12 +72,28 @@
 //
 // THE FRAGMENT: per frame, unpack its index (grid: i = floor(packed/E), k = packed - i·E; octahedron: by N), decode its
 // direction (the grid's d(az_i, el_k) / the octahedron's decode), build its basis, project p onto it (no parallax — see the note at the
-// sample) and read both atlases; blend by the weights. Alpha = Σ w·a (× the distance fade): the glTF cutoff's mask
-// threshold cuts it, alphaToCoverage softens it as on the cards. The normal: normalDecode(data.rg) per frame — already
+// sample) and read the three maps; blend by the weights. Alpha = Σ w·a (× the distance fade), the FRACTIONAL coverage of
+// a porous crown: the glTF's mask threshold cuts it like a card's, and under MSAA alphaToCoverage turns the fraction into
+// samples. Before the cut, the colour pass takes a COVERAGE BOOST: alpha × (1 + look.w × max(mip − 1, 0)), capped at 1,
+// look.w = the same Foliage `coverage` the cards use. mip = log2(frameTexels / quadPixels), the atlas mip the quad
+// actually reads: frameTexels = a frame's height in texels (the atlas' height / its frame rows), quadPixels = the quad's
+// projected height (2r × P[1][1] / the eye's distance to the sphere's centre × the viewport's height / 2). Not the cards'
+// rule (log2(dist / 8 m): a proxy for THEIR texture mip, whose blur and cut lose a card's coverage) — the atlas stores the
+// TRUE coverage, exact until a frame texel shrinks under a screen pixel and its mips average a sparse crown down past
+// the cut, so the boost starts only at the atlas' second mip. Measured 2026-11-04: the cards' rule made a far quad
+// denser than the mesh (both / mesh only / quad only 57 / 4 / 39 against 56 / 26 / 18 without). coverage 0 = the A/B.
+// The depth variants keep their own rule, no boost, as the cards'. (A dither of the fraction was built and rejected, 2026-11-04: the mesh over-covers its thin needles under its
+// hard mask - mip alpha, the cards' distance boost - and against it the honest coverage read sparse, a ghost tree; the
+// cut matched the mesh's coverage.) The depth variants (the shadow map, the prepass) keep the cards' hard rule — a
+// texel past half the cutoff casts —, so the shadow stays solid. The normal: normalDecode(data.rg) per frame — already
 // in object space, no basis —, blended, normalised, turned to the world by the quaternion. THE LIGHT is
 // foliage-cards.mat's, per pixel: the ambient = the sky's SH on that normal × the exposure × the baked AO (by leaf.w) as
 // emissive (Filament's IBL off), the sun = a wrapped Lambert (sway.w) + the back-lit translucency (leaf.z) in one scalar
-// (gSun) that surfaceShading() multiplies by the light, its attenuation and its SHADOW (by leaf.y). The per-pixel normal
+// (gSun) that surfaceShading() multiplies by the light, its attenuation and its SHADOW (by leaf.y). THE BARK (b = the bark
+// map blended like the data): the sun = mix(that leaf scalar, max(n·l, 0) — no wrap, no translucency —, b), the shadow
+// share of the map and of the self-shadow mix(leaf.y, 1, b): bark takes a shadow in full, a card its leaf.y share (as
+// foliage.mat against foliage-cards.mat); the ambient stays SH(n) × AO, n already the bark's own normal there. The
+// per-copy tint covers both (foliage.mat tints its bark too). The per-pixel normal
 // also becomes Filament's shading normal, the one its lights loop tests (dot(n, l) > 0) before it reads the shadow map.
 //
 // THE SELF-SHADOW: a flat quad never shades itself through the shadow map, and at these distances the mesh's own
@@ -81,8 +114,8 @@
 // multiplied by 1 - occl. The term is 1 with the sun under the horizon; `impostorSelfShadow` mixes it in (1 = on;
 // glb.cpp writes the 1, CREATOR_IMPOSTOR_SELFSHADOW=0 a 0). The depth variants (the shadow map, the prepass) skip it.
 //
-// The engine treats it as foliage (it declares `benders`) and writes the whole foliage block; the wind is not applied
-// (a far tree's sway is below a pixel). `Material.foliageImpostor` in the SDK; Model.load({ foliage: 'tree' }) arms it
+// The engine treats it as foliage (it declares `benders`) and writes the whole foliage block; of the wind only the
+// plant-level bend applies (THE WIND above). `Material.foliageImpostor` in the SDK; Model.load({ foliage: 'tree' }) arms it
 // with the bark and the cards, and the GLB provider picks it for a material whose extras carry `lecodes.impostor`
 // ([A, cx, cy, cz, r, E] → impostorGrid = (A, E) / impostor; E = 0 or missing = the octahedron, N = the first number).
 
@@ -131,11 +164,16 @@ material {
         // ---- the impostor (the GLB material's extras `lecodes.impostor` = [A, cx, cy, cz, r, E]) ----
         { type : float4,    name : impostor, precision : high },      // (c.xyz, r): the level-0 bounding sphere, object space
         { type : float2,    name : impostorGrid, precision : high },  // (A, E): A azimuths × E rows; (N, 0): N×N octahedron
-        { type : float,     name : impostorSelfShadow }               // the self-shadow from the atlas: 1 on, 0 off (glb.cpp writes 1)
+        { type : float,     name : impostorSelfShadow },              // the self-shadow from the atlas: 1 on, 0 off (glb.cpp writes 1)
+        { type : float,     name : debugMode }                        // the impostor lab's DEBUG VIEW (glb.cpp CREATOR_FOLIAGE_DEBUG; 0 = off): 1 albedo, 2 hull normal as colour, 3 the sky term on white — the sun off in all three
     ]
 }
 
 vertex {
+    // the wind's plant-level bend (foliageField / foliageBend) without the cards' per-vertex half (a quad has no COLOR_0)
+#define FOLIAGE_BEND_ONLY
+#include "foliage-wind.vs"
+
     // the hemi-octahedral map, [0,1]² <-> a unit direction with y ≥ 0 (the baker's TS is the same formula)
     highp vec3 impDecode(highp vec2 uv) {
         highp float u = uv.x * 2.0 - 1.0;
@@ -198,6 +236,11 @@ vertex {
         highp vec3 up = cross(d, right);
         highp vec3 p = (corner.x * right + corner.y * up) * r;
         material.worldPosition.xyz = (model * vec4(c + p, 1.0)).xyz;
+        // THE WIND: the corner leans by the cards' own plant-level bend at its place (foliage-wind.vs foliageBend: the
+        // field at the root, the rotation growing with the distance from it) - the drawn quad only; p, the frame pick and
+        // the lighting data keep the still tree
+        highp vec3 uOrigin = (getUserWorldFromWorldMatrix() * vec4(model[3].xyz, 1.0)).xyz;
+        material.worldPosition.xyz = foliageBend(material.worldPosition.xyz, model[3].xyz, foliageField(uOrigin, getUserTime().x));
 #if defined(HAS_ATTRIBUTE_TANGENTS)
         // the quad's geometric normal faces the eye (the shadow lookup's normal bias reads it; the mesh's NORMAL is a dummy)
         highp float dwl = length(dW);
@@ -238,7 +281,6 @@ vertex {
         }
 
         // the cards' per-instance tint hash, bit for bit (foliage-wind.vs: the USER world origin of the instance)
-        highp vec3 uOrigin = (getUserWorldFromWorldMatrix() * vec4(model[3].xyz, 1.0)).xyz;
         float hash = fract(sin(dot(uOrigin.xz, vec2(12.9898, 78.233))) * 43758.5453);
         // the distance fade (foliage-wind.vs `alive`, measured to the sphere's centre)
         float fadeEnd = materialParams.fade.y;
@@ -247,15 +289,23 @@ vertex {
         // packed i·E + k (grid) / i·N + j (octahedron: E = N)
         material.impFrames = vec4(f0.x * E + f0.y, f1.x * E + f1.y, f2.x * E + f2.y, hash);
         material.impPos = vec4(p, w.x);
-        material.impW = vec4(w.y, alive, 0.0, 0.0);
+        // the coverage boost's term: the atlas mip the quad reads, past the first (the header) — a frame's texels against
+        // the quad's projected height (2r in the world, the model's scale included, at the eye's distance to the centre)
+        highp float frameTexels = float(textureSize(materialParams_baseColorMap, 0).y) / E;
+        highp float rW = r * length(model[1].xyz);
+        highp float quadPixels = 2.0 * rW * getClipFromViewMatrix()[1][1] / max(length(dW), 1e-3) * frameUniforms.resolution.y * 0.5;
+        float lodEst = max(log2(frameTexels / max(quadPixels, 1e-3)) - 1.0, 0.0);
+        material.impW = vec4(w.y, alive, lodEst, 0.0);
         mat3 R = mat3(normalize(model[0].xyz), normalize(model[1].xyz), normalize(model[2].xyz));
         material.impRot = impQuat(R);
     }
 }
 
 fragment {
-    // from material() for surfaceShading(): the sun's scalar at this pixel — the wrapped Lambert + the translucency
+    // from material() for surfaceShading(): the sun's scalar at this pixel — the wrapped Lambert + the translucency (the
+    // bark's plain Lambert by its share) — and the bark fraction (the shadow map's share: mix(leaf.y, 1, gBark))
     float gSun = 0.0;
+    float gBark = 0.0;
 
     highp vec3 impDecode(highp vec2 uv) {
         highp float u = uv.x * 2.0 - 1.0;
@@ -322,15 +372,26 @@ fragment {
     // PARALLAX (the next step, not built): the data map's depth (b) exists now — the self-shadow reads it; offsetting p
     // along the view by it before the projection would line the three frames up and cut the ghosting between them.
     void impFrame(highp float packed, bool isGrid, highp vec2 cells, highp float r, highp vec3 p, highp vec2 inset,
-                  out vec4 base, out vec4 data, out highp vec3 dk, out highp vec3 rk, out highp vec3 uk) {
+                  out vec4 base, out vec4 data, out highp vec2 uv, out highp vec3 dk, out highp vec3 rk, out highp vec3 uk) {
         highp float fi = floor(packed / cells.y + 0.5 / cells.y);
         highp float fk = packed - fi * cells.y;
         impBasis(fi, fk, isGrid, cells, dk, rk, uk);
-        highp vec2 uv = impUv(fi, fk, cells, dot(p, rk) / r, dot(p, uk) / r, inset);
+        uv = impUv(fi, fk, cells, dot(p, rk) / r, dot(p, uk) / r, inset);
         base = texture(materialParams_baseColorMap, uv);
         data = texture(materialParams_metallicRoughnessMap, uv);
     }
 
+    // a frame's bark fraction (the occlusion map's r; g = 0 says the map is there — the default white reads 0)
+    float impBark(highp vec2 uv) {
+        vec2 o = texture(materialParams_occlusionMap, uv).rg;
+        return o.r * (1.0 - o.g);
+    }
+    // a frame's bark occlusion (the occlusion map's b; 0 = an atlas without the channel, and the default white, read 1)
+    float impBarkOcc(highp vec2 uv) {
+        float b = texture(materialParams_occlusionMap, uv).b;
+        return b > 0.0 ? b : 1.0;
+    }
+
     // the sky's SH irradiance on n (foliage-cards.mat's shIrradianceV; Filament's own is not in every variant's fragment)
     vec3 impSky(const vec3 n) {
         return max(
@@ -386,9 +447,10 @@ fragment {
 
         vec4 b0, b1, b2, t0, t1, t2;
         highp vec3 d0, d1, d2, r0, r1, r2, u0, u1, u2;
-        impFrame(fr.x, isGrid, cells, r, p, inset, b0, t0, d0, r0, u0);
-        impFrame(fr.y, isGrid, cells, r, p, inset, b1, t1, d1, r1, u1);
-        impFrame(fr.z, isGrid, cells, r, p, inset, b2, t2, d2, r2, u2);
+        highp vec2 uv0, uv1, uv2;
+        impFrame(fr.x, isGrid, cells, r, p, inset, b0, t0, uv0, d0, r0, u0);
+        impFrame(fr.y, isGrid, cells, r, p, inset, b1, t1, uv1, d1, r1, u1);
+        impFrame(fr.z, isGrid, cells, r, p, inset, b2, t2, uv2, d2, r2, u2);
         vec4 base = (b0 * w.x + b1 * w.y + b2 * w.z) * materialParams.baseColorFactor;
         // the distance fade thins the tree like the cards (the mask threshold does the cutting)
         base.a *= variable_impW.y;
@@ -398,7 +460,12 @@ fragment {
         if (base.a >= 0.5 * cut) base.a = max(base.a, cut);
         material.baseColor = base;
 #else
+        // the coverage boost (the header: the atlas' own mip past the first, the cards' `look.w`): a far crown keeps its share
+        base.a = min(base.a * (1.0 + materialParams.look.w * variable_impW.z), 1.0);
         vec4 data = t0 * w.x + t1 * w.y + t2 * w.z;
+        float bark = clamp(impBark(uv0) * w.x + impBark(uv1) * w.y + impBark(uv2) * w.z, 0.0, 1.0);
+        gBark = bark;
+        float barkOcc = impBarkOcc(uv0) * w.x + impBarkOcc(uv1) * w.y + impBarkOcc(uv2) * w.z;
         highp vec3 nObj = impNormal(t0) * w.x + impNormal(t1) * w.y + impNormal(t2) * w.z;
         highp float nl = length(nObj);
         nObj = nl > 1e-5 ? nObj / nl : d0;
@@ -417,8 +484,11 @@ fragment {
         // THE LIGHT, foliage-cards.mat's per-vertex model at the pixel: the sky's SH on the crown's normal darkened by the
         // baked sky visibility (leaf.w), and the sun's wrapped Lambert + translucency for surfaceShading()
         float vao = data.a;
-        float ao = mix(1.0, vao, clamp(materialParams.leaf.w, 0.0, 1.0));
-        vec3 ambient = impSky(n) * frameUniforms.iblLuminance * ao;
+        // the bark's share also takes its own occlusion in full (foliage.mat: occ x cavity on the ambient, the sky
+        // visibility alone by leaf.w) - measured 2026-11-04 on a Chernobyl pine: without it the quad's trunk read 15 % brighter
+        float ao = mix(1.0, vao, clamp(materialParams.leaf.w, 0.0, 1.0)) * mix(1.0, barkOcc, bark);
+        // + the sky through the leaf on the cards' share (foliage-cards.mat look.x), the bark's share opaque
+        vec3 ambient = (impSky(n) + materialParams.look.x * (1.0 - bark) * impSky(-n)) * frameUniforms.iblLuminance * ao;
         highp vec3 l = frameUniforms.lightDirection;
         highp vec3 v = getWorldViewVector();
         float wrap = clamp(materialParams.sway.w, 0.0, 1.0);
@@ -426,7 +496,8 @@ fragment {
         float back = max(-dot(n, l), 0.0);
         float vl = pow(max(dot(-v, l), 0.0), 4.0);
         float through = clamp(materialParams.leaf.z, 0.0, 1.0) * back * (0.5 + 0.5 * vl) * mix(1.0, vao, 0.5);
-        gSun = NoL + through;
+        // the bark's share: a plain Lambert on its own normal (foliage.mat's opaque variant: no wrap, no translucency)
+        gSun = mix(NoL + through, max(dot(n, l), 0.0), bark);
 
         // THE SELF-SHADOW from the atlas: the frames around the sun are the tree's own shadow map (the header). The
         // pixel's surface point (offset from c, object space), the three view frames' points blended by their weights:
@@ -463,8 +534,8 @@ fragment {
         bool inSun = lo.y >= 0.0;   // the sun above the horizon
         float selfShadow = inSun ? 1.0 - occl : 1.0;
         // by the cards' share of the shadow map (leaf.y, foliage-cards.mat surfaceShading: a crown never goes black under its
-        // own shadow), and the knob
-        selfShadow = mix(1.0, selfShadow, materialParams.impostorSelfShadow * clamp(materialParams.leaf.y, 0.0, 1.0));
+        // own shadow) — the bark's in full —, and the knob
+        selfShadow = mix(1.0, selfShadow, materialParams.impostorSelfShadow * mix(clamp(materialParams.leaf.y, 0.0, 1.0), 1.0, bark));
         gSun *= selfShadow;
 
         material.baseColor = base;
@@ -473,12 +544,18 @@ fragment {
         material.reflectance = 0.0;
         material.ambientOcclusion = 0.0;   // Filament's IBL off: the ambient is ours, as emissive
         material.emissive = vec4(base.rgb * ambient, 0.0);
+        // THE DEBUG VIEW (foliage-cards.mat's): 1 = the albedo, 2 = the hull normal (world) ×½+½, 3 = the sky term on
+        // white; the sun off (surfaceShading returns 0), the alpha untouched
+        float dbg = materialParams.debugMode;
+        if (dbg > 0.5) material.emissive = vec4(dbg < 1.5 ? base.rgb : dbg < 2.5 ? n * 0.5 + 0.5 : ambient, 0.0);
 #endif
     }
 
     // PER LIGHT (the sun first): the pixel's sun scalar times the light and its SHADOW, by leaf.y — foliage-cards.mat's rule
+    // — on the cards' share, in full on the bark's (foliage.mat)
     vec3 surfaceShading(const MaterialInputs materialInputs, const ShadingData shadingData, const LightData lightData) {
-        float lit = mix(1.0, lightData.visibility, clamp(materialParams.leaf.y, 0.0, 1.0));
+        if (materialParams.debugMode > 0.5) return vec3(0.0);   // the debug view: no sun
+        float lit = mix(1.0, lightData.visibility, mix(clamp(materialParams.leaf.y, 0.0, 1.0), 1.0, gBark));
         float reach = lightData.colorIntensity.w * lightData.attenuation * lit;
         return shadingData.diffuseColor * lightData.colorIntensity.rgb * (reach * gSun / PI);
     }

package/runtime/materials/foliage.mat

@@ -97,7 +97,10 @@ material {
         // per bender: xy = travel direction on the ground (unit, or 0 when still), z = speed weight 0..1
         // (creator-gl smooths the velocity over ~0.2 s) — near a plant's centre the lean follows the
         // travel direction instead of the radial one, so crossing a bush never flips it (2026-09-12)
-        { type : float4[8], name : benderMotion }
+        { type : float4[8], name : benderMotion },
+        // the impostor lab's DEBUG VIEW (glb.cpp CREATOR_FOLIAGE_DEBUG; 0 = off): 1 albedo, 2 the crown's hull normal as
+        // colour (what the impostor atlas stores for every texel, bark included), 3 the sky term on white — the sun off
+        { type : float,     name : debugMode }
     ]
 }
 
@@ -192,6 +195,13 @@ fragment {
         material.reflectance = 0.35;       // a faint sheen on the bark under grazing light (f0 ≈ 0.02; the lobe is in surfaceShading)
         material.ambientOcclusion = 0.0;   // Filament's IBL off (the header of lightmap.mat)
         material.emissive = vec4(color + glow, 0.0);
+        float dbg = materialParams.debugMode;
+        if (dbg > 0.5) {
+            vec3 hn = variable_radial.xyz;
+            float hl = length(hn);
+            hn = hl > 1e-5 ? hn / hl : vec3(0.0, 1.0, 0.0);
+            material.emissive = vec4(dbg < 1.5 ? base.rgb : dbg < 2.5 ? hn * 0.5 + 0.5 : shIrradiance(ns) * ao * frameUniforms.iblLuminance, 0.0);
+        }
     }
 
     // PER LIGHT (Filament's loop: the sun first, then the lamps in range), with the light's shadow in `visibility` -
@@ -201,6 +211,7 @@ fragment {
     // faces the viewer, double-sided) narrowed toward the view line into the light, as HDRP's thin-surface transmission
     // does.
     vec3 surfaceShading(const MaterialInputs materialInputs, const ShadingData shadingData, const LightData lightData) {
+        if (materialParams.debugMode > 0.5) return vec3(0.0);   // the debug view: no sun
         vec3 ns = gNs;
         vec3 v = getWorldViewVector();
         vec3 l = lightData.l;

package/runtime/materials/grass.mat

@@ -144,9 +144,12 @@ vertex {
             // beside it (a 1.5 m bush with the open sky's SH on its top was a lamp in the shade - the owner, 2026-10-18);
             // the open sky is reached at the crowns' level, CANOPY metres up
             up = clamp((f.uwp.y - f.uOrigin.y) / CANOPY, 0.0, 1.0);
-            ambient = mix(groundAmbient, skyAmbient, up);
-        }
-        ambient *= ao;
+            // the ground's share takes NO vertex AO: the terrain texel under the plant already carries the plant's own
+            // baked shadow (a fern's centre read its self-occlusion three times over - the ground's E, the down-facing
+            // hull's quarter and its own vao - and went black under an overcast sky, 2026-11-04); the open sky's share
+            // keeps it, that is the vertex's own depth in the plant
+            ambient = mix(groundAmbient, skyAmbient * ao, up);
+        } else ambient *= ao;
         vec3 l = frameUniforms.lightDirection;
         vec3 v = normalize(getWorldCameraPosition() - f.wp);
         float wrap = clamp(materialParams.sway.w, 0.0, 1.0);