lecodes-cli 2.3.1 → 2.4.1

package/dist/index.js

@@ -64,7 +64,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "lecodes-cli",
-    version: "2.3.1",
+    version: "2.4.1",
     dependencies: {
       "@letary/chisel": "^0.15.0",
       jimp: "^1.6.1",
@@ -88,7 +88,7 @@ var init_package = __esm(() => {
     },
     peerDependencies: {
       "lecodes-design": "^0.11.0",
-      "lecodes-headless": "^2.3.1",
+      "lecodes-headless": "^2.4.1",
       "lecodes-3d-editor": "^0.9.0",
       "lecodes-assets": "^0.2.1",
       "heic-decode": "^2.1.0",
@@ -158,7 +158,7 @@ var init_package = __esm(() => {
 });
 
 // ../../sdk/src/version.ts
-var SDK_VERSION = "2.3.1";
+var SDK_VERSION = "2.4.1";
 
 // src/cli/args.ts
 var isNegativeNumber = (s) => /^-(\d|\.\d)/.test(s), isValue = (s) => !s.startsWith("-") || isNegativeNumber(s), parseArgv = (argv, booleans = new Set) => {
@@ -171004,6 +171004,7 @@ var extractMatBlocks = (text) => {
   culling: "back",
   depthWrite: true,
   shadowMultiplier: false,
+  flipUV: true,
   params: [],
   samplers: [],
   fragmentCode: "",
@@ -171056,6 +171057,7 @@ var extractMatBlocks = (text) => {
       culling,
       depthWrite,
       shadowMultiplier: def.shadowMultiplier === true,
+      flipUV: def.flipUV !== false,
       params,
       samplers,
       fragmentCode,
@@ -215184,6 +215186,9 @@ var windowEnv = (opts) => {
   if (opts.frameRate !== undefined && process.env.CREATOR_FRAME_RATE === undefined) {
     env.CREATOR_FRAME_RATE = String(opts.frameRate);
   }
+  if (opts.vsync !== undefined && process.env.CREATOR_VSYNC === undefined) {
+    env.CREATOR_VSYNC = opts.vsync ? "1" : "0";
+  }
   if (opts.mouseEmulateTouch !== undefined && process.env.CREATOR_MOUSE_TOUCH === undefined) {
     env.CREATOR_MOUSE_TOUCH = opts.mouseEmulateTouch ? "1" : "0";
   }
@@ -215880,7 +215885,9 @@ var buildDesktop = async (flags) => {
     ...desktop ? { desktop: {
       window: desktop.window,
       ...desktop.mouseEmulateTouch !== undefined ? { mouseEmulateTouch: desktop.mouseEmulateTouch } : {},
-      ...desktop.virtualKeyboard !== undefined ? { virtualKeyboard: desktop.virtualKeyboard } : {}
+      ...desktop.virtualKeyboard !== undefined ? { virtualKeyboard: desktop.virtualKeyboard } : {},
+      ...desktop.frameRate !== undefined ? { frameRate: desktop.frameRate } : {},
+      ...desktop.vsync !== undefined ? { vsync: desktop.vsync } : {}
     } } : {}
   });
   if (config.icon) {
@@ -217893,6 +217900,7 @@ var run = defineCommand({
       renderScale: resolveRenderScale(flags["render-scale"], appCfg?.desktop?.renderScale),
       maxRenderSize: appCfg?.desktop?.maxRenderSize,
       frameRate: appCfg?.desktop?.frameRate,
+      vsync: appCfg?.desktop?.vsync,
       mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
       virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
       fps: flags.fps,
@@ -219049,6 +219057,7 @@ ${crashes.join(`
         title: win?.title ?? appCfg?.name ?? name,
         scale: resolveScale(undefined, win?.scale),
         frameRate: appCfg?.desktop?.frameRate,
+        vsync: appCfg?.desktop?.vsync,
         fps: flags.fps
       }).then(() => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."), (e) => warnErr(`Desktop host: ${e instanceof Error ? e.message : String(e)}`));
     }
@@ -228246,6 +228255,7 @@ init_browserAuth();
 init_cli();
 
 // src/web/build.ts
+init_compile();
 import { createHash as createHash9 } from "node:crypto";
 import { copyFileSync as copyFileSync2, cpSync as cpSync6, existsSync as existsSync53, mkdirSync as mkdirSync34, readFileSync as readFileSync42, readdirSync as readdirSync24, rmSync as rmSync17, statSync as statSync20, writeFileSync as writeFileSync36 } from "node:fs";
 import { dirname as dirname27, extname as extname2, join as join56, resolve as resolve35 } from "node:path";
@@ -228281,14 +228291,21 @@ var buildWeb = async (options) => {
   const base = normalBase(config.base);
   const warnings = [];
   const assetUrl = (path) => "assets" + encodeURI(path);
-  const collected = collectLocalEntries(root, manifest, "assets");
+  const collected = collectLocalEntries(root, manifest, "assets", { localShaders: true });
   const entries = collected.entries.filter((e) => {
     const abs = e.absPath ? resolve35(e.absPath) : null;
     return !(abs && (abs === out || abs.startsWith(out + "\\") || abs.startsWith(out + "/")));
   });
-  for (const w of collected.warnings)
-    if (!/shaders compile on the server/.test(w))
-      warnings.push(w);
+  warnings.push(...collected.warnings);
+  const shaders = new Map;
+  for (const entry of entries) {
+    if (entry.type !== "shader" || !entry.absPath)
+      continue;
+    const text = readFileSync42(entry.absPath, "utf8");
+    const hash = createHash9("sha256").update(text).digest("hex").slice(0, 16);
+    shaders.set(hash, JSON.stringify(buildLiteMaterialArtifact(text)));
+    entry.shaders = [{ platform: "opengl", src: `shaders/${hash}_opengl.filamat` }];
+  }
   const fontsHeader = await applyProjectFonts(entries, {
     mode: "vendor",
     root,
@@ -228374,6 +228391,12 @@ var buildWeb = async (options) => {
     mkdirSync34(dirname27(to), { recursive: true });
     copyFileSync2(entry.absPath, to);
   }
+  for (const [hash, artifact] of shaders) {
+    if (!js.includes(`shaders/${hash}_`))
+      continue;
+    mkdirSync34(join56(out, "shaders"), { recursive: true });
+    writeFileSync36(join56(out, "shaders", `${hash}_webgl-lite.filamat`), artifact);
+  }
   const app = readAppConfigAt(root);
   let html = readFileSync42(join56(lite, "index.html"), "utf8");
   const head = [];

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "lecodes-cli",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "dependencies": {
     "@letary/chisel": "^0.15.0",
     "jimp": "^1.6.1",
-    "lecodes-sdk": "2.3.1"
+    "lecodes-sdk": "2.4.1"
   },
   "devDependencies": {
     "lecodes-design": "https://storage.yandexcloud.net/le-codes/releases/packages/lecodes-design/lecodes-design-0.11.0.tgz",
-    "lecodes-headless": "2.3.1",
+    "lecodes-headless": "2.4.1",
     "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": "0.2.1",
     "lecodes-creator-nav": "0.19.0",
-    "lecodes-gl-lite": "2.3.1",
-    "lecodes-web-frame": "2.3.1",
-    "lecodes-web-player": "2.3.1",
-    "lecodes-web-shared": "2.3.1",
+    "lecodes-gl-lite": "2.4.1",
+    "lecodes-web-frame": "2.4.1",
+    "lecodes-web-player": "2.4.1",
+    "lecodes-web-shared": "2.4.1",
     "lecodes-web-lite": "2.0.2",
     "heic-decode": "^2.1.0",
     "marcidb-embedded": "^0.15.0",
@@ -24,7 +24,7 @@
   },
   "peerDependencies": {
     "lecodes-design": "^0.11.0",
-    "lecodes-headless": "^2.3.1",
+    "lecodes-headless": "^2.4.1",
     "lecodes-3d-editor": "^0.9.0",
     "lecodes-assets": "^0.2.1",
     "heic-decode": "^2.1.0",

package/runtime/materials/foliage-cards.mat

@@ -0,0 +1,251 @@
+// foliage-cards: the LEAN material of the vegetation tier's CARDS (leaves, needles, grass blades) — the same wind
+// (foliage-wind.vs) and the same parameters as foliage.mat, with the fragment cut to what a card seen past a few
+// metres needs (2026-10-18, the Forest testbed: foliage.mat's masked fragment was ~15 ms of a 49 ms frame on the
+// Radeon — a third of the forest). What moved or went:
+//   • the LIGHTING is PER VERTEX: the sky's SH on the crown's hull normal (the ambient) and the sun's wrapped
+//     Lambert + back-lit translucency (one scalar), interpolated over the card. Only the sun's SHADOW stays per
+//     pixel — Filament's lights loop hands it to surfaceShading() with every light (the material is `lit` with
+//     customSurfaceShading for that alone: an unlit material gets no shadow variant)
+//   • ONE texture read (the base colour); the normal map, metallic / roughness, occlusion and emissive maps are
+//     declared (gltfio fills them) and never read; no tangent frame (`requires` has no tangents)
+//   • no derivatives: the shading normal is the hull's (foliage.mat blends the card's own plane in), the mip
+//     coverage is estimated from the DISTANCE in the vertex shader (log2 of the distance over ~8 m), there is no
+//     edge fade
+//   • THE GROUND'S BAKED LIGHT is read per vertex too (groundLightV, 2026-10-18): the ambient under the vertex and the
+//     sun's baked share where the vertex's own sun ray meets the ground, so trees past the shadow map's reach stand in
+//     their neighbours' baked shadow; without a bound terrain the scene's sky lights every card
+// The engine treats it as foliage (it declares `benders`) and writes the same blocks; `Material.foliageCards`
+// in the SDK picks it for a model's MASK materials in place of foliage-masked.
+
+material {
+    name : foliage_cards,
+    shadingModel : lit,
+    customSurfaceShading : true,
+    specularAmbientOcclusion : simple,
+    doubleSided : true,
+    blending : masked,
+    alphaToCoverage : true,
+    flipUV : false,
+    requires : [ uv0, color ],
+    variables : [ variation, radial, lightv, baked ],
+    parameters : [
+        { type : float4,    name : baseColorFactor },
+        { type : sampler2d, name : baseColorMap },
+        { type : float,     name : metallicFactor },
+        { type : float,     name : roughnessFactor },
+        { type : float3,    name : emissiveFactor },
+        { type : float,     name : normalScale },
+        { type : float,     name : aoStrength },
+        { type : sampler2d, name : normalMap },
+        { type : float,     name : hasNormalMap },
+        { type : sampler2d, name : metallicRoughnessMap },
+        { type : sampler2d, name : occlusionMap },
+        { type : sampler2d, name : emissiveMap },
+        // ---- foliage (foliage.mat has every comment) ----
+        { type : float4,    name : wind },
+        { type : float4,    name : sway },
+        { type : float4,    name : fade },
+        { type : float4,    name : leaf },
+        { type : float4,    name : profile },
+        { type : float,     name : shiverDir },
+        { type : float4,    name : look },
+        { type : sampler2d, name : windNoise },
+        { type : float4,    name : plant },
+        { type : float4[8], name : benders },
+        { type : float4[8], name : benderMotion },
+        // ---- THE GROUND'S LIGHT (foliage.mat's block, read PER VERTEX here; 2026-10-18, the Forest's baked ground) ----
+        // level-wide, written by creator-gl once a terrain's rect is bound (glb.cpp bindGround / bindOptions)
+        { type : float4,    name : ground, precision : high },
+        { type : float4,    name : groundInv, precision : high },
+        { type : float4,    name : groundST, precision : high },
+        { type : sampler2d, name : lightmapLight, precision : high },
+        { type : sampler2d, name : lightmapAux },
+        { type : float,     name : lightScale },
+        { type : float4,    name : sunDir },
+        { type : float4,    name : sunLight, precision : high },
+        // ---- THE GROUND'S COLOUR (2026-10-18, glb.cpp foliageSetGroundTint): the terrain's control map (its four layers'
+        // weights) and each layer's mean colour; a card's base takes the colour of the soil under it, its top its own
+        { type : sampler2d, name : groundControl },
+        { type : float4[4], name : groundTint },
+        { type : float4,    name : groundTintOrigin, precision : high },   // xy = the terrain's world xz origin, z = bound
+        { type : float4,    name : groundTintInv, precision : high }       // the inverse of its world xz axes
+    ]
+}
+
+vertex {
+#include "foliage-wind.vs"
+#include "lightmap-sunmap.fs"
+
+    // THE GROUND'S LIGHT AT A VERTEX (foliage.mat reads it per pixel, under the pixel): true when the plant stands over
+    // the bound terrain. `ambient` = the terrain texel's irradiance under the vertex without the sun's part (lux, on the
+    // up normal) — the sky through the canopy, the bounce. `sunShare` = the baked share of the sun's disc at the point
+    // where THIS VERTEX'S OWN SUN RAY meets the ground (the plant's base height): what shades that point shades the
+    // vertex too — a neighbour's crown, or the crown above a card deep in it — so a tree past the shadow map's reach
+    // still stands in its neighbour's shadow, and the grass under a pine in the pine's. `lod` picks the pages' level
+    // (a far vertex over one texel of 25 cm would flicker between texels as it sways).
+    // the crowns' level over the ground: a vertex this high takes the open sky's ambient and its own crown's softened shadow
+    #define CANOPY 12.0
+
+    bool groundLightV(highp vec3 uwp, highp float baseY, float lod, out highp vec3 ambient, out float sunShare) {
+        ambient = vec3(0.0); sunShare = 1.0;
+        if (materialParams.ground.z < 0.5) return false;
+        highp vec2 d = uwp.xz - materialParams.ground.xy;
+        highp vec2 g = vec2(dot(materialParams.groundInv.xy, d), dot(materialParams.groundInv.zw, d));
+        if (g.x < 0.0 || g.y < 0.0 || g.x > 1.0 || g.y > 1.0) return false;   // off the terrain
+        highp vec2 luv = g * materialParams.groundST.xy + materialParams.groundST.zw;
+        highp vec3 E = textureLod(materialParams_lightmapLight, luv, lod).rgb * materialParams.lightScale;
+        ambient = E;
+        if (materialParams.sunDir.w > 0.5) {
+            highp ivec2 auxSize = textureSize(materialParams_lightmapAux, 0);
+            highp int level = clamp(int(lod + 0.5), 0, max(sunMapLevels(), 1) - 1);
+            // the sun's part out of the ground's E under the vertex: its illuminance x the share there x the cosine on the
+            // ground, taken as flat
+            float shareHere = sunMapAt(luv, auxSize, level);
+            ambient = max(E - materialParams.sunLight.rgb * (shareHere * max(materialParams.sunDir.y, 0.0)), vec3(0.0));
+            // the sun ray through the vertex, followed down to the plant's base height
+            vec3 s = materialParams.sunDir.xyz;   // TO the sun
+            highp vec3 foot = uwp - s * ((uwp.y - baseY) / max(s.y, 0.05));
+            d = foot.xz - materialParams.ground.xy;
+            g = clamp(vec2(dot(materialParams.groundInv.xy, d), dot(materialParams.groundInv.zw, d)), 0.0, 1.0);
+            sunShare = sunMapAt(g * materialParams.groundST.xy + materialParams.groundST.zw, auxSize, level);
+        }
+        return true;
+    }
+
+    vec3 shIrradianceV(const vec3 n) {
+        return max(
+            frameUniforms.iblSH[0].xyz
+            + frameUniforms.iblSH[1].xyz * n.y + frameUniforms.iblSH[2].xyz * n.z + frameUniforms.iblSH[3].xyz * n.x
+            + frameUniforms.iblSH[4].xyz * (n.y * n.x) + frameUniforms.iblSH[5].xyz * (n.y * n.z)
+            + frameUniforms.iblSH[6].xyz * (3.0 * n.z * n.z - 1.0) + frameUniforms.iblSH[7].xyz * (n.z * n.x)
+            + frameUniforms.iblSH[8].xyz * (n.x * n.x - n.y * n.y), 0.0);
+    }
+
+    void materialVertex(inout MaterialVertexInputs material) {
+        FoliageVertex f = foliageWind(material);
+        // COVERAGE from the distance (foliage.mat reads the atlas' mip level from the uv derivatives per pixel): the
+        // atlas texels under a pixel double every doubling of the distance past ~8 m, where a card is still read in
+        // full; `look.w` scales how much of that goes into the alpha
+        float lodEst = max(log2(max(f.dist, 1.0) / 8.0), 0.0);
+        material.radial = vec4(f.hull, lodEst);
+        // THE LIGHT, per vertex. Ambient = the sky's SH on the hull normal, as radiance under the camera's exposure
+        // (frameUniforms.iblLuminance holds it), darkened by the baked sky visibility by `leaf.w`. The sun = a wrapped
+        // Lambert on the hull (thin leaves let light past the terminator, `sway.w`) plus the translucency of a card lit
+        // from behind (`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 skyAmbient = shIrradianceV(f.hull) * frameUniforms.iblLuminance;
+        vec3 ambient = skyAmbient;
+        float sunShare = 1.0;
+        float up = 1.0;   // the vertex's height over the ground as a share of the canopy's (1 without a ground)
+        highp vec3 gAmb;
+        if (groundLightV(f.uwp, f.uOrigin.y, lodEst, gAmb, sunShare)) {
+            // THE BAKED GROUND'S LIGHT (the function above): its ambient on the hull normal by the hemisphere formula
+            // lightmapShade uses for a tilted normal (the light comes from above), as radiance E / pi under the camera's
+            // exposure. The crown's base takes the ground's ambient (the sky through the canopy), its top the open sky's
+            // SH - blended by the vertex's height over the plant; a grass blade is all ground
+            // the hemisphere formula alone gave a down-facing hull nothing (black needles under a young pine, the owner
+            // 2026-10-18): what a card sees below is the ground, lit by that same E and reflecting a quarter of it
+            vec3 groundAmbient = gAmb * mix(0.25, 1.0, (1.0 + f.hull.y) * 0.5) / PI * frameUniforms.exposure;
+            // by the height OVER THE GROUND, not within the plant: a bush's top is under the same crowns as the ground
+            // 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;
+        vec3 l = frameUniforms.lightDirection;
+        vec3 v = normalize(getWorldCameraPosition() - f.wp);
+        float wrap = clamp(materialParams.sway.w, 0.0, 1.0);
+        float NoL = max((dot(f.hull, l) + wrap) / (1.0 + wrap), 0.0);
+        float back = max(-dot(f.hull, 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, f.vao, 0.5);
+        material.lightv = vec4(ambient, NoL);
+        // .x = the baked share of the sun at this vertex (1 without a bound ground): surfaceShading takes it as a second
+        // shadow map on the direct light, the stricter of the two, never the product. .y = the translucency, which takes
+        // the shadow map ALONE: the bake's 64-ray share through the crown put out the glow of a back-lit crown (the
+        // multiple scattering a real crown has and this model lacks; the owner, 2026-10-18 "лес довольно тёмный")
+        // .z = the height share: near the ground a shadow is a NEIGHBOUR's and lands in full, at the crowns' level it is the
+        // crown's own and is softened by leaf.y (the scattering a real crown has); the fragment weighs the shadow by it.
+        // (The plants' SHADOW LOD is the LOD pass's, per renderable - lod.cpp gFoliageCast - not this shader's: a card-level
+        // discard in the depth variant saved 0.6 ms of the pass's 6.8, the renderables' vertices and draws are the cost)
+        // THE GROUND'S COLOUR at the plant's base: the layers' weights under the PLANT (one colour per plant - a varying
+        // that differs per vertex could not carry a packed value) times their mean colours; the fragment blends the card's
+        // colour toward it by `baked.w` - all of it at the ground, none from ~70 % of the plant's height up (a grass
+        // blade's base is its soil, a bush's crown its own leaves; a tree's cards never reach it). The colour rides
+        // `variation.w` packed 7 bits a channel (matc allows four variables with the colour attribute; vao was unused there)
+        float gtPacked = 0.0, gtBlend = 0.0;
+        if (materialParams.groundTintOrigin.z > 0.5) {
+            highp vec2 td = f.uOrigin.xz - materialParams.groundTintOrigin.xy;
+            highp vec2 tg = vec2(dot(materialParams.groundTintInv.xy, td), dot(materialParams.groundTintInv.zw, td));
+            if (tg.x >= 0.0 && tg.y >= 0.0 && tg.x <= 1.0 && tg.y <= 1.0) {
+                vec4 w = textureLod(materialParams_groundControl, tg, 0.0);
+                float ws = max(w.x + w.y + w.z + w.w, 1e-3);
+                vec3 soil = (materialParams.groundTint[0].rgb * w.x + materialParams.groundTint[1].rgb * w.y
+                           + materialParams.groundTint[2].rgb * w.z + materialParams.groundTint[3].rgb * w.w) / ws;
+                float base = 1.0 - clamp((f.uwp.y - f.uOrigin.y) / max(0.7 * f.plantH, 0.05), 0.0, 1.0);
+                vec3 q = floor(clamp(soil, 0.0, 1.0) * 127.0 + 0.5);
+                gtPacked = q.r * 16384.0 + q.g * 128.0 + q.b;
+                gtBlend = base * 0.85;
+            }
+        }
+        material.variation = vec4(f.hash, f.alive, f.tintN, gtPacked);
+        material.baked = vec4(sunShare, through, up, gtBlend);
+    }
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        vec4 base = texture(materialParams_baseColorMap, getUV0()) * materialParams.baseColorFactor;
+        // the per-instance tint and the leaves' world-noise patches (foliage.mat's comments)
+        float hash = variable_variation.x;
+        vec3 tint = mix(vec3(0.86, 0.94, 0.72), vec3(1.06, 1.02, 1.12), hash);
+        base.rgb *= mix(vec3(1.0), tint, materialParams.sway.z) * (1.0 - 0.18 * variable_variation.z);
+        // the ground's colour at the base (the vertex shader's note): the soil's mean colour in place of the card's
+        if (variable_baked.w > 0.0) {
+            highp float pk = variable_variation.w;
+            vec3 soil = vec3(floor(pk / 16384.0), mod(floor(pk / 128.0), 128.0), mod(pk, 128.0)) / 127.0;
+            base.rgb = mix(base.rgb, soil, variable_baked.w);
+        }
+        // the distance fade thins the card; the coverage holds a far crown's share over the cutoff (colour pass only:
+        // the shadow map's caster is fattened below already)
+        base.a *= variable_variation.y;
+#if defined(VARIANT_DEPTH)
+        float cut = getMaskThreshold();
+        if (base.a >= 0.5 * cut) base.a = max(base.a, cut);
+#else
+        base.a = min(base.a * (1.0 + materialParams.look.w * variable_radial.w), 1.0);
+#endif
+        material.baseColor = base;
+        material.metallic = 0.0;
+        material.roughness = 1.0;
+        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);
+    }
+
+    // PER LIGHT (the sun first): the vertex shader's wrapped Lambert + translucency scalar, times the light and its
+    // SHADOW (a card takes the shadow map by leaf.y only, foliage.mat's rule). The shadow is the STRICTER of the
+    // shadow map's and the baked ground's share at the vertex (groundLightV): past the map's reach the bake alone,
+    // within it the two agree on the same crowns and the min keeps them from doubling. 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) {
+        // the shadow MAP is always softened by leaf.y: it cannot tell a neighbour's shadow from the crown's own card-on-card
+        // one, and a young pine at full strength went black (2026-10-18). The BAKED share can: a neighbour's crown is in it
+        // through 64 alpha-tested rays, so it lands in full near the ground and softens to leaf.y at the crowns' level
+        float ky = clamp(materialParams.leaf.y, 0.0, 1.0);
+        float kB = mix(1.0, ky, variable_baked.z);
+        // the baked share is the SUN's: a lamp takes its own shadow map alone (foliage.mat's test for the sun)
+        bool sun = dot(lightData.l, frameUniforms.lightDirection) > 0.999;
+        float baked = sun ? mix(1.0, variable_baked.x, kB) : 1.0;
+        float lit = min(mix(1.0, lightData.visibility, ky), baked);   // the direct light
+        // the translucency takes the same two shadows at the HEIGHT weight (kB): a blade at the ground in a tree's baked shade
+        // gets none of the sun through it (the map alone leaked 30-40 % of the sun into every shaded clump, and all of it past
+        // castDistance - the owner, 2026-10-18 "трава светлая в тени"); a card at the crowns' level keeps leaf.y of it
+        float litT = sun ? mix(1.0, min(lightData.visibility, variable_baked.x), kB) : mix(1.0, lightData.visibility, ky);
+        float reach = lightData.colorIntensity.w * lightData.attenuation;
+        return shadingData.diffuseColor * lightData.colorIntensity.rgb * (reach * (lit * variable_lightv.w + litT * variable_baked.y) / PI);
+    }
+}