@driftengine/core 4.4.2 → 4.5.0

package/dist/render/shaders/flat/main.js

@@ -82,6 +82,11 @@ export const MAIN_GLSL = `void main() {
    * the branch below builds a shaded result on top of it.
    */
   vec3 lit = albedo;
+  /* The light arriving at a glass pane from behind it, gathered in each light loop below and added
+     over the see-through at the end. Stays zero for anything that is not glass. See glass.ts. */
+  vec3 glassGlow = vec3(0.0);
+  float glassTransmission = uSeeThrough.z;
+  float glassFrost = uSeeThrough.w;
 
   if (uLightingEnabled != 0) {
     vec3 n = normalize(vNormal);
@@ -93,7 +98,13 @@ export const MAIN_GLSL = `void main() {
      * back of the sheet; what that gives up is a sliver at a curved silhouette, where a front face's
      * interpolated normal already leans away and is lit as the back.
      */
-    bool backFace = uDoubleSided != 0 && dot(n, uCameraPos - vWorldPos) < 0.0;
+    /*
+     * **Glass is two-sided whatever its material says**: a pane is symmetric, so from behind the
+     * side the eye sees is the one lit, and the light on its far side is what glows through it.
+     * Taken from the stored normal alone, a pane seen from behind glowed with the light on the
+     * eye's side and not with the sun shining through it.
+     */
+    bool backFace = (uDoubleSided != 0 || glassTransmission > 0.0) && dot(n, uCameraPos - vWorldPos) < 0.0;
     /*
      * The authored normal, before either relief perturbs it.
      *
@@ -312,9 +323,13 @@ export const MAIN_GLSL = `void main() {
     float surfaceNdl = dot(surfaceN, uDirectionalDir);
 #if DIRECTIONAL_SHADOWS
     float sunShade = shadowFactor(max(surfaceNdl, 0.0));
+    /* What the sun keeps through any glass on its way here: see sunGlassLookup. */
+    vec3 sunGlass = sunGlassTint(max(surfaceNdl, 0.0));
 #else
     float sunShade = 1.0;
+    vec3 sunGlass = vec3(1.0);
 #endif
+    vec3 sunColor = uDirectionalColor * sunGlass;
     /*
      * **How much sky this vertex can see, applied to the sun and to nothing else.**
      *
@@ -342,6 +357,8 @@ export const MAIN_GLSL = `void main() {
      */
     float sunFacing = smoothstep(0.0, 0.02, surfaceNdl);
     float direct = ndl * sunShade * sunFacing;
+    /* Glass: the sun on the far side of a pane lights it through the glass. See glassGlow. */
+    if (glassTransmission > 0.0) glassGlow += sunColor * max(-surfaceNdl, 0.0) * sunShade;
 
     /*
      * Hemispheric: sky above, ground below, mixed by which way the surface looks. An
@@ -388,7 +405,7 @@ export const MAIN_GLSL = `void main() {
      * smallest change available in a shader with a documented history of shared subexpressions
      * rounding differently when their neighbours move. See the night-emissive term.
      */
-    lit = albedo * (ambient + uDirectionalColor * direct * (1.0 - metal));
+    lit = albedo * (ambient + sunColor * direct * (1.0 - metal));
 
     /*
      * A sun highlight, for the few surfaces that ask for one.
@@ -450,7 +467,7 @@ export const MAIN_GLSL = `void main() {
      * before: \`sunSpec\` is \`vec3(vSpecular)\` at metal 0 and \`vSpecular\` defaults to 0.
      */
     vec3 sunHighlight =
-      uDirectionalColor * specularLobe(max(dot(n, halfway), 0.0), surfaceRoughness) * sunSpec * sunShade * sunFacing;
+      sunColor * specularLobe(max(dot(n, halfway), 0.0), surfaceRoughness) * sunSpec * sunShade * sunFacing;
     /*
      * The dielectric's share goes in here, where it has always gone, so the environment blend
      * below dims it by exactly the reflectance it always dimmed it by. The metal's share is added
@@ -1022,7 +1039,14 @@ export const MAIN_GLSL = `void main() {
       }
       if (falloff <= 0.0) continue;
       float ndl = max(dot(n, toLight / max(dist, 1e-4)), 0.0);
-      if (ndl <= 0.0) continue;
+      /*
+       * **A lamp behind a pane is not skipped when the surface is glass**: it lights the pane through
+       * the glass, shaped and shadowed like any lamp, and is added to glassGlow once its shape is
+       * known below. For everything else a lamp behind the surface is skipped here, as always.
+       */
+      float backNdl =
+        glassTransmission > 0.0 ? max(-dot(n, toLight / max(dist, 1e-4)), 0.0) : 0.0;
+      if (ndl <= 0.0 && backNdl <= 0.0) continue;
 
       /*
        * Normal-offset bias.
@@ -1075,7 +1099,17 @@ export const MAIN_GLSL = `void main() {
        */
       int shadowRead = clamp(shadowSlot, 0, MAX_LIGHTS - 1);
       int layer = shadowSlot >= 0 && shadowSlot < MAX_LIGHTS ? uPointShadowLayer[shadowRead] : -1;
+      /* What the panes between this receiver and the lamp let through, per map: lampGlass.ts. */
+      vec3 staticGlass = vec3(1.0);
+      vec3 liveGlass = vec3(1.0);
       if (layer >= 0 && shadowWeight > POINT_SHADOW_MIN_WEIGHT) {
+        staticGlass = pointGlassTint(
+          float(layer),
+          receiverPoint - uPointShadowProjection[shadowRead].xyz,
+          uPointShadowProjection[shadowRead].w,
+          uPointShadowNear[shadowRead],
+          uPointShadowSize[shadowRead]
+        );
         occl = mix(
           1.0,
           pointShadow(
@@ -1115,10 +1149,20 @@ export const MAIN_GLSL = `void main() {
           uLivePointShadowSize[shadowRead]
         );
         liveWeight = uLivePointShadowWeight[shadowRead];
+        liveGlass = pointGlassTint(
+          float(liveLayer),
+          receiverPoint - uLivePointShadowProjection[shadowRead].xyz,
+          uLivePointShadowProjection[shadowRead].w,
+          uLivePointShadowNear[shadowRead],
+          uLivePointShadowSize[shadowRead]
+        );
       }
       occl *= mix(1.0, liveOccl, liveWeight);
+      /* Each map's glass faded in by that map's presence, as its occlusion is. */
+      vec3 lampGlass = mix(vec3(1.0), staticGlass, uPointShadowWeight[shadowRead]) * mix(vec3(1.0), liveGlass, liveWeight);
 #else
       float occl = 1.0;
+      vec3 lampGlass = vec3(1.0);
 #endif
 
       // Blend occlusion out as the light fades, so a shadow can never be more
@@ -1239,6 +1283,8 @@ export const MAIN_GLSL = `void main() {
       float photometric = mix(1.0, iesGain, step(0.0, iesProfile));
 
       float shape = (uLightFalloff == 1 ? falloff : falloff * falloff) * coneFalloff * photometric;
+      glassGlow += lightColor * backNdl * shape * lightWeight * shaded * lampGlass;
+      if (ndl <= 0.0) continue;
       /*
        * The cookie tints rather than scales, because a mask may be coloured — a stained window is
        * the case that makes the difference — and a greyscale one is exactly a scale. Applied to
@@ -1277,7 +1323,7 @@ export const MAIN_GLSL = `void main() {
        */
       vec3 lampDiffuse = albedo * lightColor * ndl * shape * lightWeight * (1.0 - metal);
       lampOpen += lampDiffuse;
-      lampShadowed += lampDiffuse * shaded;
+      lampShadowed += lampDiffuse * shaded * lampGlass;
 
       /*
        * A lamp reflected in a polished surface, which point lights could not do at all.
@@ -1312,7 +1358,7 @@ export const MAIN_GLSL = `void main() {
           lightColor * sphereLobe(max(dot(n, lampHalfway), 0.0), surfaceRoughness, lightSourceRadius, dist)
           * lampSpec * shape * lightWeight;
         lampOpen += lampHighlight;
-        lampShadowed += lampHighlight * shaded;
+        lampShadowed += lampHighlight * shaded * lampGlass;
       }
       /*
        * The most any light in range shadows this point, for the emissive term below —
@@ -1373,7 +1419,11 @@ export const MAIN_GLSL = `void main() {
        */
       float signedForm = quadFormFactor(n, vWorldPos, c0, c1, c2, c3);
       float form = mix(max(0.0, signedForm), abs(signedForm), uAreaLightTwoSided[a]);
-      if (form <= 0.0) continue;
+      /* The form factor is linear in the normal, so the one seen from behind is its negation. */
+      float backForm = glassTransmission > 0.0
+        ? mix(max(0.0, -signedForm), abs(signedForm), uAreaLightTwoSided[a])
+        : 0.0;
+      if (form <= 0.0 && backForm <= 0.0) continue;
 
       /*
        * **How much of the rectangle this fragment can actually see past whatever is in the way.**
@@ -1400,6 +1450,7 @@ export const MAIN_GLSL = `void main() {
        * is a constant nobody has measured. \`docs/IMPROVEMENTS.md\` carries the row.
        */
       float areaOccl = 1.0;
+      vec3 areaGlass = vec3(1.0);
 #if POINT_SHADOWS
       /*
        * The sample position is pushed along the surface normal before the lookup, and it scales
@@ -1440,6 +1491,12 @@ export const MAIN_GLSL = `void main() {
           ),
           uAreaShadowWeight[a]
         );
+        /* What the panes before the rectangle let through, faded in as its occlusion is. */
+        areaGlass = mix(
+          vec3(1.0),
+          areaGlassTint(float(areaLayer), areaShadowFrom, uAreaShadowFar[a], uAreaShadowNear[a], right, up, halfSize),
+          uAreaShadowWeight[a]
+        );
       }
       int areaLiveLayer = uLiveAreaShadowLayer[a];
       if (areaLiveLayer >= 0) {
@@ -1457,13 +1514,28 @@ export const MAIN_GLSL = `void main() {
           ),
           uLiveAreaShadowWeight[a]
         );
+        areaGlass *= mix(
+          vec3(1.0),
+          areaGlassTint(
+            float(areaLiveLayer),
+            areaShadowFrom,
+            uLiveAreaShadowFar[a],
+            uLiveAreaShadowNear[a],
+            right,
+            up,
+            halfSize
+          ),
+          uLiveAreaShadowWeight[a]
+        );
       }
 #endif
 
+      glassGlow += uAreaLightColor[a] * backForm * areaOccl * areaGlass;
+      if (form <= 0.0) continue;
       /* Held back with the point lamps', and shadowed by the same term it always was. */
       vec3 areaDiffuse = albedo * uAreaLightColor[a] * form * (1.0 - metal);
       lampOpen += areaDiffuse;
-      lampShadowed += areaDiffuse * areaOccl;
+      lampShadowed += areaDiffuse * areaOccl * areaGlass;
 
       if (vSpecular > 0.0 || metal > 0.0) {
         /*
@@ -1490,7 +1562,7 @@ export const MAIN_GLSL = `void main() {
           vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);
           vec3 areaHighlight = areaSpec * uAreaLightColor[a] * coverage;
           lampOpen += areaHighlight;
-          lampShadowed += areaHighlight * areaOccl;
+          lampShadowed += areaHighlight * areaOccl * areaGlass;
         }
       }
     }
@@ -1550,6 +1622,9 @@ export const MAIN_GLSL = `void main() {
      * \`driftLight.ts\`.
      */
     if (driftShare > 0.0) {
+      if (glassTransmission > 0.0) {
+        glassGlow += driftLightIrradiance(vWorldPos, -n) * (driftShare * uDriftLight.w);
+      }
       lit += albedo * driftLightIrradiance(vWorldPos, n) * (driftShare * uDriftLight.w) * (1.0 - metal);
     }
 
@@ -1737,14 +1812,39 @@ export const MAIN_GLSL = `void main() {
    * splitting the specular out before the fog, which is a larger change to the one shader every
    * draw uses.
    */
-  if (uRefractStrength > 0.0) {
+  if (uSeeThrough.x > 0.0 || glassTransmission > 0.0) {
     vec3 refractN = normalize(vNormal);
     vec3 refractV = normalize(uCameraPos - vWorldPos);
-    vec2 screenUv = gl_FragCoord.xy / vec2(textureSize(uRefractScene, 0));
-    vec2 bent = clamp(screenUv + refractN.xy * uRefractStrength, vec2(0.0), vec2(1.0));
-    vec3 behind = texture(uRefractScene, bent).rgb;
-    float pathLength = uRefractThickness * vThickness / max(dot(refractN, refractV), 0.05);
-    shaded = behind * pow(uRefractTint, vec3(pathLength));
+    ivec2 snapSize = textureSize(uRefractScene, 0);
+    vec2 screenUv = gl_FragCoord.xy / vec2(snapSize);
+    vec2 bent = clamp(screenUv + refractN.xy * uSeeThrough.x, vec2(0.0), vec2(1.0));
+    /*
+     * **An explicit level, and frost is what picks it** — the 2026-08-07 rule, and the reason a
+     * frosted pane blurs rather than fades: the copy carries a mip chain on a frame that draws glass,
+     * so a milkier pane reads a coarser level of it. Level 0 on a copy with one level is exactly what
+     * \`texture()\` read here before, so plain refraction draws as it did.
+     */
+    /* Two short of the last level: a fully frosted pane still shows the large light and dark of what
+       is behind it, where the chain's last level is one texel, the whole frame's average. */
+    float levels = max(floor(log2(float(max(snapSize.x, snapSize.y)))) - 2.0, 0.0);
+    vec3 behind = textureLod(uRefractScene, bent, glassFrost * levels).rgb;
+    /* Unsigned: a pane passes the same light seen from either side, and so does its Fresnel. */
+    float cosView = max(abs(dot(refractN, refractV)), 0.05);
+    float pathLength = uSeeThrough.y * vThickness / cosView;
+    vec3 seen = behind * pow(uRefractTint, vec3(pathLength));
+    if (glassTransmission > 0.0) {
+      /*
+       * **Glass keeps its own surface and shows what is behind over it**, by how much it lets
+       * through and how little it reflects at this angle — Schlick's Fresnel at 0.04, the arithmetic
+       * \`glass.ts\` states. So a clear pane keeps its highlight, and a pane seen edge-on is a mirror.
+       * The glow of the lights behind it is added last, by how frosted it is.
+       */
+      float fresnel = 0.04 + 0.96 * pow(1.0 - cosView, 5.0);
+      shaded = mix(shaded, seen * uGlassTint, glassTransmission * (1.0 - fresnel)) +
+        applyOutputTransform(glassGlow * uGlassTint * (glassFrost * glassTransmission) * (1.0 - fog));
+    } else {
+      shaded = seen;
+    }
   }
   /*
    * The per-vertex alpha lane, folded in here rather than given an expression of its own so the

package/dist/render/shaders/flat/pointShadow.d.ts

@@ -1 +1 @@
-export declare const POINTSHADOW_GLSL = "/**\n * How much of one tap's occlusion survives its own penumbra.\n *\n * **How much of a shadow survives, as well as how soft it is.** A penumbra does not merely blur\n * with distance from its caster, it *takes over*: far enough from the occluder, relative to how\n * big the source is, every point on the receiver can see part of the flame and there is no umbra\n * left at all. The shadow is gone, not blurry. Without it, two columns lit by a brazier threw\n * full-strength edges fifteen metres across the terrace, and the gap between them read as a\n * spotlight cone with straight sides rather than as a fire.\n *\n * **Per tap, and it was once for the whole filter, taken from the centre tap alone.** That is a\n * blocker search of one sample standing in for twelve, and it is right wherever the taps agree \u2014\n * inside an umbra they all find the same occluder, so this returns exactly what the shared value\n * did, and the umbra is unchanged to the bit. It is wrong exactly where they disagree, which is\n * the silhouette: there the centre ray *misses*, so the search reports no occluder, the spread is\n * zero and the fade is switched off \u2014 while the taps that do land on the caster then draw at full\n * strength. What that paints is a hard one-texel line around a shadow whose interior has\n * correctly faded to nothing.\n *\n * Reported as shadows \"faded out but NOT shadow outlines, generating long lines around the\n * world\", and on a brazier as a bare square outline lying on the ground with no shadow inside it.\n *\n * **What it costs** is two multiplies and a divide per occluded tap, against a tap that has\n * already paid for a texture fetch. **What would make it wrong** is a filter wide enough that one\n * tap's occluder is not the occluder a neighbouring tap is estimating for, which is the same\n * limit the shared value had and is what `MAX_FILTER_RADIUS` bounds.\n */\nfloat tapStrength(float receiverDistance, float occluderDistance, float sourceRadius) {\n  float spread = max(receiverDistance - occluderDistance, 0.0) / max(occluderDistance, 0.05);\n  float penumbra = clamp(sourceRadius * spread * PENUMBRA_FADE, 0.0, 1.0);\n  return 1.0 - penumbra * penumbra;\n}\n\nfloat pointShadow(\n  highp sampler2DArray maps,\n  float layer,\n  vec3 toFrag,\n  float far,\n  float near,\n  float sourceRadius\n) {\n  /*\n   * The receiver's own distance, and it is the *radius* now rather than a cube face's local Z.\n   *\n   * That difference removes two things. Every tap of an angular disk shares this one number,\n   * where a cube needed each tap's own face-local Z recomputed \u2014 offsets changed it, and\n   * comparing them all against the centre ray drew repeated wedges on large receivers. And the\n   * stored value converts with a multiply instead of the perspective divide, which used to\n   * magnify whatever error the sample arrived with, worst near the far plane.\n   */\n  float dist = length(toFrag);\n\n  /*\n   * A receiver nearer than the near plane is not shadowed at all.\n   *\n   * The near plane already says \"nothing this close to the source is rendered into the\n   * map\", and a caller raises it so a fixture does not shadow its own housing. That was\n   * only ever applied to *casters*, so a surface inside the same distance still went\n   * through the comparison \u2014 against a map that, by the caller's own instruction, holds\n   * nothing about anything near it.\n   *\n   * Reported on a ceiling with recessed strip lights hung a hand's width below it: shadows\n   * that \"go on and off\" as the camera moves. The seams that made it unmissable are gone;\n   * the gate stays, because comparing against a map that holds nothing is still wrong.\n   *\n   * The gate is the caller's own number rather than a new constant. A consumer that wants\n   * the surface right beside its lamp to take a shadow can lower it, which is the same\n   * knob and the same meaning it has always had for the other side of the transaction.\n   */\n  if (dist <= near) return 1.0;\n\n  // Modest depth bias only. The heavy lifting is done by offsetting the\n  // sample position along the surface normal before this is called \u2014 see the\n  // call site \u2014 which is the cure for grazing receivers that depth bias alone\n  // cannot fix without peter-panning.\n  float bias = 0.04 + dist * 0.015;\n\n  /*\n   * Penumbra from the emitter's actual size.\n   *\n   * A shadow's softness is not a constant: it is set by how large the source is\n   * and how far the caster stands from the surface it falls on. Find the\n   * occluder with a centre tap, then widen the filter by\n   * sourceRadius * (receiver - occluder) / occluder \u2014 the real geometry of a\n   * penumbra. A bulb stays crisp; a flame goes soft with distance, which is\n   * what makes a fire read as a fire rather than a large lamp.\n   *\n   * textureLod(..., 0.0), not the implicit-derivative texture() call this replaced.\n   * pointShadowArray.ts allocates the array with texStorage3D at one storage level,\n   * NEAREST both filters \u2014 there is no mip to select, so the two calls fetch the\n   * identical texel. Not a quality trade; the output is bit-for-bit the same.\n   *\n   * It matters because implicit derivatives are only well-defined under *uniform*\n   * control flow, and this sits inside the light loop below. See AGENTS.md, 2026-08-07.\n   */\n  float centreStored = textureLod(maps, vec3(octEncode(toFrag), layer), 0.0).r;\n  float occluderDistance = centreStored >= 0.9999 ? dist : centreStored * far;\n  float spread = max(dist - occluderDistance, 0.0) / max(occluderDistance, 0.05);\n  /*\n   * Softness comes from *fading the shadow*, not from widening the filter.\n   *\n   * Four attempts went into widening it, and the fourth is what identified why\n   * none of them worked. The decisive observation was that the light pool looked\n   * right until a column entered it. With no occluder the penumbra estimate is zero,\n   * the filter stays at its floor, and the light pool is clean. The instant a\n   * column is found the filter widens \u2014 and a wide angular filter on a *cube*\n   * map is what crossed face seams. The artefact was never the columns' shadows;\n   * it was the search for their penumbra.\n   *\n   * The map has no seams now, so the cap could open. It has not, in this change:\n   * the storage moved and nothing else did, and the widening is a picture decision\n   * taken against a tree that already renders correctly.\n   */\n  float radius = clamp(sourceRadius * spread, 0.01, MAX_FILTER_RADIUS) + 0.012;\n\n  /*\n   * Taps are placed on a disk *perpendicular to the light ray*, turned by half a golden\n   * angle on every other column of pixels.\n   *\n   * Offsetting the ray by fixed 3D vectors was the earlier approach and it has\n   * two faults that only show on a wide filter. The offsets are not\n   * perpendicular to the ray, so part of each one moves the sample along its own\n   * depth instead of across the shadow; and twelve *fixed* taps at a large\n   * radius align, so the penumbra breaks into hard straight bands following the\n   * tap pattern \u2014 reported, on a brazier behind a rank of columns, as strange\n   * straight lines across the light pool.\n   *\n   * **The cure for that was a per-fragment hash, and it is what made the penumbra\n   * stipple.** Twelve taps are a coarse estimate of how much of the emitter this point can\n   * see; turning them by an unrelated angle at every pixel makes each pixel's error\n   * independent of its neighbour's, which is the definition of noise. Something has to\n   * average that back out, and this engine's lit pass is the last thing to touch the frame \u2014\n   * there is no blur and no temporal resolve behind it, so the noise reached the screen. Two\n   * games reported the same coarse cross-hatch across a light pool.\n   *\n   * **So the turn comes from a two-pixel tile instead, and the pair is averaged afterwards.**\n   * A pixel's own x parity picks one of two tap sets half a golden angle apart, and\n   * `main` folds the pair together once the light loop is over \u2014 see the resolve there. The\n   * pair's twenty-four taps are the filter; each pixel pays for twelve of them.\n   *\n   * **A *column* pair rather than a 2x2 square, and that was measured rather than assumed.**\n   * Four turns on a square tile, resolved with both derivatives, came back at 3.88 against this\n   * pair's 2.46 on the same build \u2014 because the second derivative hands the lower row of a quad\n   * the upper row's difference on hardware that answers a coarse derivative, and with four turns\n   * that is the wrong difference. Two turns keyed on the column alone make it the right one,\n   * which is why the tile's shape and the resolve are one decision rather than two.\n   *\n   * **Neither half works alone**, which is the same pairing `ambientOcclusion.ts` describes\n   * between its rotation tile and its blur. Measured on `demo/dev/pointshadow.html` at\n   * `?exposure=6`, as mean absolute luminance difference to the right and down neighbour over\n   * the mover's penumbra, on WebGL2: **4.60** for the per-fragment hash this replaces, **2.88**\n   * for this tile with no resolve \u2014 and a one-pixel vertical comb in the picture, which is the\n   * tile itself on screen \u2014 against **2.37** for the pair resolved. A frame with the shadow\n   * switched off measures 0.81, and WebGPU answers 4.56 and 2.33 for the same two builds.\n   *\n   * **Unchanged by the move to an octahedral map, and that is the point.** The offsets are\n   * angular perturbations of a direction, so every tap is still a direction and octEncode is\n   * defined on all of them. Nothing offsets in UV, so the map's border needs no wrap\n   * arithmetic and a tap that would have crossed a cube join lands on the adjacent texel.\n   */\n  vec3 fwd = normalize(toFrag);\n  vec3 up = abs(fwd.y) < 0.9 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0);\n  vec3 tu = normalize(cross(up, fwd));\n  vec3 tv = cross(fwd, tu);\n  /*\n   * Integer arithmetic, because this is a lattice: a shader compiler is free to implement\n   * `mod(x, 2.0)` as a multiply by a reciprocal, and a GPU here answers 3 for `3.0 % 3.0`.\n   * `gl_FragCoord.x` is the pixel's centre, so truncating it is the pixel's own column.\n   */\n  float angle = float(int(gl_FragCoord.x) & 1) * PCF_PAIR_TURN;\n  float ca = cos(angle);\n  float sa = sin(angle);\n\n  float lit = 0.0;\n  for (int i = 0; i < 12; i++) {\n    if (i >= uShadowFilterTaps) break;\n    vec2 disk = PCF_OFFSETS[i];\n    vec2 turned = vec2(disk.x * ca - disk.y * sa, disk.x * sa + disk.y * ca);\n    // Perpendicular to the ray, and *not* scaled by its length: the offsets are\n    // an angular perturbation of a direction, which is what the encoding takes.\n    vec3 sampleDir = toFrag + (tu * turned.x + tv * turned.y) * radius;\n    float stored = textureLod(maps, vec3(octEncode(sampleDir), layer), 0.0).r;\n    if (stored >= 0.9999) {\n      // Beyond the far plane nothing was rendered: treat as lit.\n      lit += 1.0;\n      continue;\n    }\n    float storedDistance = stored * far;\n    if (dist - bias > storedDistance) {\n      // A point shadow cannot outlive the finite light that casts it, so its\n      // occlusion fades smoothly before the light's far plane.\n      float reach = shadowReach(max(dist - storedDistance, 0.0), far);\n      lit += 1.0 - reach * tapStrength(dist, storedDistance, sourceRadius);\n    } else {\n      lit += 1.0;\n    }\n  }\n  return lit / float(max(uShadowFilterTaps, 1));\n}\n\n/**\n * The same filter for a source that has a *shape* rather than a radius.\n *\n * **One map from the rectangle's centre, and the rectangle's own extent as the filter's shape.**\n * That is the whole difference from `pointShadow` above, and it is what makes the result read as\n * one wide emitter rather than as a lamp: a bulb's penumbra is round, so a row of nine of them\n * gives nine round shadows that pile up darker where they overlap, and a strip's penumbra is a\n * strip \u2014 soft along the cable, tight across it, one shadow with one soft edge.\n *\n * **The taps land on the emitter's silhouette as this fragment sees it**, which is the part a\n * scalar radius cannot express. The rectangle's two axes are projected onto the plane across the\n * light ray and each keeps its own width, so the sample pattern is an ellipse rather than a disk,\n * and a rectangle seen edge-on along one axis has no penumbra in that direction \u2014 which is correct\n * and is what a strip light actually does. Four dot products and two square roots more than the\n * round filter.\n *\n * **The fade is driven by the *narrower* projected half extent, and the reason is a strip.** A\n * penumbra does not only blur a shadow, it takes over: past the point where every part of the\n * receiver can see part of the emitter there is no umbra left. Driven by the wider extent, a\n * three-metre cable would delete its own shadow at a metre of caster clearance \u2014 but across the\n * cable the source is nearly a line, so an umbra band survives there and only the length is\n * smeared. `min` keeps that band; `max` would erase it.\n *\n * **What it costs** is a second copy of the tap loop, about 30 lines, compiled into the eight\n * permutations that carry point shadows. Folding the two into one loop was the alternative and was\n * not taken: the shared form has to multiply the disk offset by a width before scaling the axis\n * rather than after, which is a different rounding order on every tap of the *point* path \u2014 so the\n * saving is paid for by perturbing eight scenes that currently gate at zero pixels, in a change\n * about area lights. `docs/IMPROVEMENTS.md` carries the row.\n *\n * **What would make it wrong** is a rectangle much wider than its distance to the caster, where\n * different points on the emitter genuinely see different silhouettes and no single map from the\n * centre stands in for all of them \u2014 a ceiling-wide panel a hand's width above a table. The honest\n * answer there is several maps across the emitter, which is several bakes.\n */\nfloat areaShadow(\n  highp sampler2DArray maps,\n  float layer,\n  vec3 toFrag,\n  float far,\n  float near,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize\n) {\n  float dist = length(toFrag);\n  /* The near plane says nothing this close to the emitter was rendered; see `pointShadow`. */\n  if (dist <= near) return 1.0;\n\n  float bias = 0.04 + dist * 0.015;\n\n  /*\n   * The blocker search, one tap along the centre ray, exactly as the round filter does it. Similar\n   * triangles turn the two distances into how much wider than the emitter the penumbra is.\n   *\n   * `textureLod(..., 0.0)` rather than `texture()`: the array carries one storage level and\n   * NEAREST both filters, so the two fetch the identical texel \u2014 and this sits inside the area\n   * light loop, which is not provably uniform control flow. See AGENTS.md, 2026-08-07.\n   */\n  float centreStored = textureLod(maps, vec3(octEncode(toFrag), layer), 0.0).r;\n  float occluderDistance = centreStored >= 0.9999 ? dist : centreStored * far;\n  float spread = max(dist - occluderDistance, 0.0) / max(occluderDistance, 0.05);\n\n  vec3 fwd = toFrag / dist;\n  /*\n   * Each axis with its along-the-ray component removed: the rectangle's outline flattened onto the\n   * plane the taps move in. The lengths that come back are the foreshortening \u2014 1 for a rectangle\n   * seen face-on, 0 for one seen exactly edge-on along that axis \u2014 so the two widths below carry\n   * both the emitter's size and how much of it this fragment can see.\n   */\n  vec3 acrossX = right - fwd * dot(right, fwd);\n  vec3 acrossY = up - fwd * dot(up, fwd);\n  float seenX = length(acrossX);\n  float seenY = length(acrossY);\n  /*\n   * A collapsed axis offsets nothing rather than offsetting along an arbitrary direction. Both\n   * cannot collapse at once: `right` and `up` are perpendicular, so a ray parallel to one of\n   * them is perpendicular to the other.\n   */\n  vec3 alongX = seenX > 1e-5 ? acrossX / seenX : vec3(0.0);\n  vec3 alongY = seenY > 1e-5 ? acrossY / seenY : vec3(0.0);\n\n  float halfX = halfSize.x * seenX;\n  float halfY = halfSize.y * seenY;\n  /* The same ceiling and the same floor the round filter uses, per axis. See MAX_FILTER_RADIUS. */\n  float widthX = min(halfX * spread, MAX_FILTER_RADIUS) + 0.012;\n  float widthY = min(halfY * spread, MAX_FILTER_RADIUS) + 0.012;\n\n  /*\n   * Turned inside the unit disk *before* the ellipse maps it, so the half-turn that separates\n   * the two halves of a pixel pair survives the anisotropy. The same two-pixel tile the round\n   * filter uses and for the same reasons \u2014 see `pointShadow`, which carries the measurement;\n   * a rectangle's shadow stippled exactly as a lamp's did, because it is the same twelve taps.\n   */\n  float angle = float(int(gl_FragCoord.x) & 1) * PCF_PAIR_TURN;\n  float ca = cos(angle);\n  float sa = sin(angle);\n\n  float lit = 0.0;\n  for (int i = 0; i < 12; i++) {\n    if (i >= uShadowFilterTaps) break;\n    vec2 disk = PCF_OFFSETS[i];\n    vec2 turned = vec2(disk.x * ca - disk.y * sa, disk.x * sa + disk.y * ca);\n    vec3 sampleDir = toFrag + alongX * (turned.x * widthX) + alongY * (turned.y * widthY);\n    float stored = textureLod(maps, vec3(octEncode(sampleDir), layer), 0.0).r;\n    if (stored >= 0.9999) {\n      /* Beyond the far plane nothing was rendered: treat as lit. */\n      lit += 1.0;\n      continue;\n    }\n    float storedDistance = stored * far;\n    if (dist - bias > storedDistance) {\n      /* An area light's occlusion cannot outlive the map that carries it either. */\n      float reach = shadowReach(max(dist - storedDistance, 0.0), far);\n      /* The narrower half extent, for the reason in the header: it is what keeps a strip's\n         umbra. Per tap, for the reason `tapStrength` gives. */\n      lit += 1.0 - reach * tapStrength(dist, storedDistance, min(halfX, halfY));\n    } else {\n      lit += 1.0;\n    }\n  }\n  return lit / float(max(uShadowFilterTaps, 1));\n}\n#endif\n\nout vec4 outColor;\n\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB. See renderQuality.ts. */\nuniform int uOutputTransform;\n/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */\nuniform float uOutputExposure;\n\n/*\n * ACES: the reference fit, not the cheap one.\n *\n * This was Narkowicz's single rational function, on the argument that the difference from\n * the reference curve is invisible next to the gain. That argument holds for a look and\n * fails for a *match*, which is what this option is for \u2014 aces exists so a world ported\n * from three.js reads the same, and three.js applies the full fit: into AP1 through\n * ACESInputMat, the RRT and ODT together, then back out through ACESOutputMat.\n *\n * The two curves are not a shade apart. Narkowicz is markedly brighter through the\n * midtones, which is exactly where an interior scene lives, and it is a large part of a\n * measured ~1.7x that survived correcting the colour space and the missing Lambert pi.\n * An approximation of a standard is the wrong thing to hold when the standard is the\n * specification.\n */\nvec3 rrtAndOdtFit(vec3 v) {\n  vec3 a = v * (v + 0.0245786) - 0.000090537;\n  vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081;\n  return a / b;\n}\n\nvec3 acesFilmic(vec3 x) {\n  /*\n   * Exposure first, because a tone curve is only defined relative to one.\n   *\n   * The reference RRT and ODT are graded for a dark cinema. Every renderer that ships ACES\n   * scales its input to suit whatever it is actually shown on, and the factor each one\n   * picks is a *look*, not a standard - so this engine takes no position and reads it from\n   * the caller. Neutral by default, which is the reference grade unmodified. three.js's own\n   * pick is 1 / 0.6, for a consumer matching one.\n   */\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: sRGB -> XYZ -> D65_2_D60 -> AP1 -> RRT_SAT.\n  const mat3 ACES_INPUT = mat3(\n    0.59719, 0.07600, 0.02840,\n    0.35458, 0.90834, 0.13383,\n    0.04823, 0.01566, 0.83777\n  );\n  // ODT_SAT -> XYZ -> D60_2_D65 -> sRGB.\n  const mat3 ACES_OUTPUT = mat3(\n     1.60475, -0.10208, -0.00327,\n    -0.53108,  1.10813, -0.07276,\n    -0.07367, -0.00605,  1.07602\n  );\n  return clamp(ACES_OUTPUT * rrtAndOdtFit(ACES_INPUT * x), 0.0, 1.0);\n}\n\n/*\n * Linear to sRGB. The piecewise form rather than a plain pow: the linear toe near black\n * is where banding lives in an 8-bit buffer, and the cheap approximation puts it in the\n * wrong place.\n */\nvec3 linearToSrgb(vec3 c) {\n  vec3 low = c * 12.92;\n  vec3 high = 1.055 * pow(max(c, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n  return mix(high, low, step(c, vec3(0.0031308)));\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  return linearToSrgb(c);\n}\n\n\n/**\n * A fixed Poisson disk avoids the grid-shaped edge left by square 3x3 PCF.\n * Directional and point shadows consume the same maximum filter-tap budget;\n * their texture sizes differ because one is a 2D projection of a frustum and one\n * is an octahedral projection of the whole sphere, not because one is a lower\n * quality tier.\n */\n#if DIRECTIONAL_SHADOWS\nconst vec2 DIRECTIONAL_PCF_OFFSETS[12] = vec2[12](\n  vec2(-0.326, -0.406), vec2( 0.519,  0.767), vec2( 0.962, -0.195), vec2(-0.696,  0.457),\n  vec2(-0.840, -0.074), vec2( 0.185, -0.893), vec2( 0.896,  0.412), vec2(-0.203,  0.621),\n  vec2( 0.473, -0.480), vec2( 0.507,  0.064), vec2(-0.322, -0.933), vec2(-0.792, -0.598)\n);\n\n/** Anything outside the light frustum or beyond its far plane counts as lit. */";
+export declare const POINTSHADOW_GLSL: string;

package/dist/render/shaders/flat/pointShadow.js

@@ -14,6 +14,7 @@
  */
 import { MAX_SHADOW_FILTER_TAPS } from '../../renderQuality.js';
 import { OUTPUT_TRANSFORM_GLSL } from '../outputTransform.js';
+import { LAMP_GLASS_GLSL } from './lampGlass.js';
 export const POINTSHADOW_GLSL = `/**
  * How much of one tap's occlusion survives its own penumbra.
  *
@@ -337,6 +338,7 @@ float areaShadow(
   }
   return lit / float(max(uShadowFilterTaps, 1));
 }
+${LAMP_GLASS_GLSL}
 #endif
 
 out vec4 outColor;

package/dist/render/shaders/flat/preamble.js

@@ -96,13 +96,20 @@ in float vThickness;
  * paid by every consumer whether or not they refract, against 19.8 KB for a branch -- which is the
  * price table Track D's three shipped rows measured.
  *
- * uRefractStrength at 0 is every draw that shipped before this existed, and it is the default, so
+ * uSeeThrough.x, the strength, at 0 is every draw that shipped before this existed, and it is the default, so
  * the sampler is bound to an empty texture and read nowhere on a frame that refracts nothing.
  */
 uniform sampler2D uRefractScene;
-uniform float uRefractStrength;
+/*
+ * **Four numbers in one vector: refraction's strength and path thickness, glass's transmission and
+ * frost** (x, y, z, w). One vector rather than four, and that is the whole reason: on a device at the
+ * WebGL2 floor of 256 fragment uniform vectors, every loose float is a vector the light budget
+ * gives up, and four separate floats cost half the shadowed lights such a device can have. The tints
+ * stay colours of their own. Zero transmission is not glass — see glass.ts.
+ */
+uniform vec4 uSeeThrough;
 uniform vec3 uRefractTint;
-uniform float uRefractThickness;
+uniform vec3 uGlassTint;
 flat in int vHasTangents;
 
 /**
@@ -256,9 +263,13 @@ uniform vec3 uEmissiveScale;
  * half of the file, because a test asserts that a profile without a probe mentions them
  * nowhere — a comment is source too, and it failed that test first.
  */
-uniform highp sampler2D uStaticShadowMap;  // wgsl:share shadow
-uniform highp sampler2D uPeeledShadowMap;  // wgsl:share shadow
-uniform highp sampler2D uDynamicShadowMap;  // wgsl:share shadow
+/* The sun's static, moving and peeled maps, as layers of one array: see shadowMap.ts. Where glass
+   has cast, the last two layers are the nearest pane's depth, static then moving. */
+uniform highp sampler2DArray uSunShadows;  // wgsl:share shadow
+/* What the sun keeps through glass, static then moving: colour times colour, and clarity (see
+   glassShadow.ts). A one-texel stand-in where no glass has cast, which the lookup reads as none.
+   Mipmapped and filtered, unlike the depths: frost reads the level its spread asks for. */
+uniform highp sampler2DArray uSunGlassTints;  // wgsl:share tint
 /** 0 disables directional shadows when their source is not emitting. */
 uniform float uShadowStrength;
 uniform float uShadowMapSize;
@@ -854,6 +865,10 @@ uniform float uPointShadowWeight[MAX_LIGHTS];
  * it exists.
  */
 uniform highp sampler2DArray uPointShadows;  // wgsl:share shadow
+/* What each light keeps through glass: one layer a light, colour times colour and clarity, beside
+   the array above — whose light L then keeps its depth at 2L and its nearest pane at 2L + 1 (see
+   pointShadowArray.ts). A one-texel stand-in where no lamp has met glass, read as none. */
+uniform highp sampler2DArray uPointGlassTints;  // wgsl:share tint
 
 /**
  * Moving casters are separate from persistent world maps. Two live maps exist