@driftengine/core 4.9.0 → 4.11.0

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

@@ -6,6 +6,17 @@ export const MAIN_GLSL = `void main() {
    * turns a float into an array index. A plain texture is an array of one, so layer 0.
    */
   vec3 surfaceAt = vec3(vUv.xy, floor(vUv.z + 0.5));
+  /*
+   * The coordinates a map's frame and its cutout's level are measured along: the mesh's, or the
+   * world's where the material projects its maps (worldUv.ts) — in which case the mesh's tangents
+   * no longer run along them either. Triplanar reads its own three planes below; every other
+   * reader of surfaceAt takes the horizontal plane.
+   */
+  vec2 frameAt = vUv.xy;
+  int frameTangents = vHasTangents;
+  projectSurface(surfaceAt, frameAt, frameTangents);
+  /* A layered material's mask, read once for every layer's share below: layered.ts. */
+  if (LAYERED && layered()) layeredBegin();
   if (dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;
   /*
    * The layer's surface effects, zeros where the albedo array carries no table — see
@@ -25,6 +36,8 @@ export const MAIN_GLSL = `void main() {
   vec2 fxDx = dFdx(surfaceAt.xy);
   vec2 fxDy = dFdy(surfaceAt.xy);
   if (uWriteMode.y != 0.0 && !ditherKeeps(uWriteMode.y)) discard;
+  /* An opacity spent on the screen door instead of the blend: preamble.ts. 0 keeps nothing. */
+  if (uWriteMode.z != 0.0 && ditherThreshold() >= vAlpha) discard;
   /* A draw's dissolve cuts the surface away before anything is shaded: overlay.ts. */
   if (SURFACE_OVERLAY) {
     if (overlayCuts(surfaceAt.xy)) discard;
@@ -62,14 +75,14 @@ export const MAIN_GLSL = `void main() {
    */
   float coverage = 1.0;
   if (uMaterialFlags.x != 0) {
-    vec4 texel = texture(uAlbedo, surfaceAt);
+    vec4 texel = albedoTexel(surfaceAt);
     // Discarded before anything else is computed: a thrown-away fragment should not pay
     // for the lighting it will never contribute to. The test credits alpha for the mip level
     // it samples, so a needle averaged thin down the chain is not lost; see cutoutCoverage.ts.
     // Behind a branch on a uniform, so a material with no cutoff pays nothing for it.
     float kept = texel.a;
     if (uCutout.x > 0.0) {
-      float tested = cutoutAlpha(texel.a, vUv.xy * vec2(textureSize(uAlbedo, 0).xy));
+      float tested = cutoutAlpha(texel.a, frameAt * vec2(textureSize(uAlbedo, 0).xy));
       if (uCutout.y == 0.0) {
         if (tested < uCutout.x) discard;
       } else {
@@ -81,7 +94,7 @@ export const MAIN_GLSL = `void main() {
          */
         float share = cutoutShare(tested, uCutout.x);
         if (uCutout.y == 1.0) {
-          if (!cutoutKeeps(share, gl_FragCoord.xy, uCutout.z)) discard;
+          if (!cutoutKeeps(share, gl_FragCoord.xy, uHighlightMin.w)) discard;
           kept = 1.0;
         } else {
           kept = share;
@@ -114,7 +127,7 @@ export const MAIN_GLSL = `void main() {
   float ormRoughness = vRoughness;
   float metal = 0.0;
   if (uMaterialFlags.y != 0) {
-    vec3 t = texture(uOrmMap, surfaceAt).rgb;
+    vec3 t = ormTexel(surfaceAt);
     ormOcclusion = mix(1.0, t.r, uOrmScale.r);
     ormRoughness = clamp(t.g * uOrmScale.g, 0.0, 1.0);
     metal = clamp(t.b * uOrmScale.b, 0.0, 1.0);
@@ -155,6 +168,14 @@ export const MAIN_GLSL = `void main() {
   vec3 glassGlow = vec3(0.0);
   float glassTransmission = uSeeThrough.z;
   float glassFrost = uSeeThrough.w;
+  /*
+   * **A thin surface lets light from behind through, coloured by itself**: a banner, a leaf, a
+   * lampshade, an opaque material's \`diffuseTransmission\`, in the glass tint's spare lane. It
+   * gathers the light behind it in glassGlow, as a pane does, and adds it through its own colour.
+   * None on glass, which has its own way through.
+   */
+  float thin = glassTransmission > 0.0 ? 0.0 : uGlassTint.w;
+  bool seesBehind = glassTransmission > 0.0 || thin > 0.0;
 
   /*
    * The normal a refracting draw bends by: the shading normal, a normal map's tilt and every relief
@@ -196,7 +217,7 @@ export const MAIN_GLSL = `void main() {
      * below. The rule is about non-uniform branches, and this branch is on a uniform.
      */
     vec3 unmapped = n;
-    if (uNormalStrength > 0.0) n = normalMapped(n, surfaceAt);
+    if (uNormalStrength > 0.0) n = normalMapped(n, surfaceAt, frameAt, frameTangents);
     /* A draw's wrinkles, by region, over whatever the map made: overlay.ts. */
     if (SURFACE_OVERLAY) n = overlayWrinkle(n, unmapped, surfaceAt.xy);
 
@@ -367,6 +388,8 @@ export const MAIN_GLSL = `void main() {
      */
     shadingNormal = n;
     if (backFace) n = -n;
+    /* A blending rim, on the base colour every light below reads: overlay.ts. */
+    if (SURFACE_OVERLAY) albedo = overlayRimBase(albedo, surfaceAt.xy, n);
     /*
      * A model's surface, gathered once, on a branch on the switches alone (models.ts) — and whether
      * there is one, asked once: every site below is a branch on these two, which a pipeline with no
@@ -449,7 +472,7 @@ 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;
+    if (seesBehind) glassGlow += sunColor * max(-surfaceNdl, 0.0) * sunShade;
 
     /*
      * Hemispheric: sky above, ground below, mixed by which way the surface looks. An
@@ -1280,7 +1303,7 @@ export const MAIN_GLSL = `void main() {
        */
       float falloff;
       /*
-       * **A light may name its own falloff, and then it is Unreal's for a light without
+       * **A light may name its own falloff, and then it is the usual one for a light without
        * inverse-square falloff**: \`(1 - (d/R)^2)^n\` with no distance term, so a fill authored to
        * light a whole hall across a hundred metres does, where the inverse square would have it
        * gone a few metres out. Zero is the frame's own rule below, which every light was before.
@@ -1301,8 +1324,7 @@ export const MAIN_GLSL = `void main() {
        * 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;
+      float backNdl = seesBehind ? max(-dot(n, toLight / max(dist, 1e-4)), 0.0) : 0.0;
       /* A model that sees light from behind keeps the lamps behind the surface. See models.ts. */
       if (ndl <= 0.0 && backNdl <= 0.0 && !modelledBehind) continue;
 
@@ -1322,7 +1344,9 @@ export const MAIN_GLSL = `void main() {
 #if POINT_SHADOWS
       float grazing = 1.0 - ndl;
       float normalOffset = (0.06 + dist * 0.05) * grazing * grazing + 0.02;
-      vec3 receiverPoint = vWorldPos + n * normalOffset;
+      /* Toward a lamp behind a thin surface, which is in the map itself: away from it, the surface
+         would stand in its own shadow. A pane is in no map, so glass keeps the usual side. */
+      vec3 receiverPoint = vWorldPos + (thin > 0.0 && ndl <= 0.0 ? -n : n) * normalOffset;
 
       /*
        * uPointShadowWeight is how present the cubemap is, and it is the difference
@@ -1698,7 +1722,7 @@ export const MAIN_GLSL = `void main() {
       float signedForm = areaSignedForm(n, seenCentre, right, up, seenHalf);
       float form = mix(max(0.0, signedForm), abs(signedForm), uAreaLightTwoSided[a]);
       /* The form factor is linear in the normal, so the one seen from behind is its negation. */
-      float backForm = glassTransmission > 0.0
+      float backForm = seesBehind
         ? mix(max(0.0, -signedForm), abs(signedForm), uAreaLightTwoSided[a])
         : 0.0;
       if (form <= 0.0 && backForm <= 0.0) continue;
@@ -1872,7 +1896,7 @@ export const MAIN_GLSL = `void main() {
      * \`driftLight.ts\`.
      */
     if (driftShare > 0.0) {
-      if (glassTransmission > 0.0) {
+      if (seesBehind) {
         glassGlow += driftLightIrradiance(vWorldPos, -n) * (driftShare * uDriftLight.w);
       }
       /* The standard expression in its own order — albedo times the field, then the share — so a
@@ -1932,6 +1956,8 @@ export const MAIN_GLSL = `void main() {
      * underneath: a ceiling emitting a dull warm haze over a pale panel cannot be expressed
      * by scaling the panel, and scaling it gets the brightness right and the hue wrong.
      */
+    /* What a thin surface lets through from behind, through its own colour; a metal lets none. */
+    if (thin > 0.0) lit += albedo * glassGlow * (thin * (1.0 - metal));
     diffuseAlone = lit;
     vec3 emissiveTint = vEmissiveColor.r < 0.0 ? albedo : vEmissiveColor;
     /*
@@ -1952,7 +1978,7 @@ export const MAIN_GLSL = `void main() {
      */
     vec3 emissiveMapped = vec3(1.0);
     if (uMaterialFlags.z != 0) {
-      emissiveMapped = texture(uEmissiveMap, surfaceAt).rgb * uEmissiveScale;
+      emissiveMapped = emissiveTexel(surfaceAt) * uEmissiveScale;
     }
     /* Pulse, flicker and fade from the layer's effects; exactly 1 where it names none. */
     float fxGlow = fx4.z + fx5.x + fx5.w > 0.0 ? fxEmission(surfaceAt.z) : 1.0;
@@ -1996,7 +2022,7 @@ export const MAIN_GLSL = `void main() {
     // finishing a run reads the same at noon and at midnight. Costs one compare
     // per fragment and no extra draw call — the box is a uniform, not geometry.
     if (uHighlightMax.w > 0.0) {
-      vec3 inside = step(uHighlightMin, vWorldPos) * step(vWorldPos, uHighlightMax.xyz);
+      vec3 inside = step(uHighlightMin.xyz, vWorldPos) * step(vWorldPos, uHighlightMax.xyz);
       lit += albedo * uHighlightMax.w * inside.x * inside.y * inside.z;
     }
   }
@@ -2096,11 +2122,21 @@ export const MAIN_GLSL = `void main() {
      * map here, on a branch on uniforms alone, which keeps its derivatives legal.
      */
     vec3 refractN = shadingNormal;
-    if (uLightingEnabled == 0 && uNormalStrength > 0.0) refractN = normalMapped(refractN, surfaceAt);
+    if (uLightingEnabled == 0 && uNormalStrength > 0.0) refractN = normalMapped(refractN, surfaceAt, frameAt, frameTangents);
     vec3 refractV = normalize(uCameraPos - vWorldPos);
     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));
+    /*
+     * **The normal's sideways part as the eye sees it**: the shading normal in view space, its x
+     * and y across the screen, y turned to the way this frame's rows run (w of the tint). It was the
+     * normal's world x and y until 4.10.0, which on a quad facing the camera is the quad's own lean
+     * against the world's axes: one offset over the whole quad, a lens, with a normal map's tilt a
+     * small change on top. In view space a quad facing the eye bends by nothing but its map, which
+     * is a shimmer, and a pane bends by how it leans toward the eye wherever the eye stands.
+     */
+    vec3 seenN = mat3(uView) * refractN;
+    vec2 bend = vec2(seenN.x, seenN.y * uRefractTint.w);
+    vec2 bent = clamp(screenUv + bend * 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,
@@ -2114,7 +2150,7 @@ export const MAIN_GLSL = `void main() {
     /* 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));
+    vec3 seen = behind * pow(uRefractTint.rgb, vec3(pathLength));
     if (glassTransmission > 0.0) {
       /*
        * **Glass keeps its own surface and shows what is behind over it**, by how much it lets
@@ -2123,8 +2159,8 @@ export const MAIN_GLSL = `void main() {
        * 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));
+      shaded = mix(shaded, seen * uGlassTint.rgb, glassTransmission * (1.0 - fresnel)) +
+        applyOutputTransform(glassGlow * uGlassTint.rgb * (glassFrost * glassTransmission) * (1.0 - fog));
     } else {
       shaded = seen;
     }
@@ -2136,9 +2172,10 @@ export const MAIN_GLSL = `void main() {
    * **It did not need MeshData.colors widened to four floats**, which is how the consumer who
    * asked for it had costed the change -- widening colors moves every mesh producer, the
    * container layout and every baked asset. Alpha is a factor on the draw's opacity, not a
-   * component of its albedo, so it rides a lane instead and nothing existing moves.
+   * component of its albedo, so it rides a lane instead and nothing existing moves. Where the draw
+   * spends it on the screen door instead (\`uWriteMode.z\`), it was spent at the top and is 1 here.
    */
-  float alpha = uOpacity * coverage * vAlpha;
+  float alpha = uOpacity * coverage * (uWriteMode.z != 0.0 ? 1.0 : vAlpha);
 
   /*
    * **Order-independent transparency, when this draw is accumulating into it.**

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

@@ -0,0 +1,10 @@
+/**
+ * Where each of a material's maps is read: a layered material's blend (`layered.ts`), the three
+ * planes of a triplanar projection (`worldUv.ts`), or the map itself at the surface's coordinates.
+ *
+ * **Functions rather than branches in `main`, for the bundle's sake.** The generated WGSL stores an
+ * item once however many of the sixteen permutations share it, and `main` differs in every one, so
+ * a line there is paid sixteen times and a line here once. Called from the same uniform branches the
+ * reads stood in, so their implicit levels are as legal as they were: AGENTS.md 2026-08-07.
+ */
+export declare const MAP_READS_GLSL = "\n/* The surface's coordinates moved onto the world's horizontal plane where a material projects them,\n   with the frame's coordinates and the mesh's tangents, which no longer run along them, set aside. */\nvoid projectSurface(inout vec3 at, inout vec2 frameAt, inout int frameTangents) {\n  if (WORLD_UVS && projected()) {\n    at.xy = planarAt();\n    frameAt = at.xy;\n    frameTangents = 0;\n  }\n}\n\nvec4 albedoTexel(vec3 at) {\n  if (LAYERED && layered()) return layeredAlbedo();\n  if (WORLD_UVS && triplanar()) return triplanarAlbedo(at.z);\n  return texture(uAlbedo, at);\n}\n\nvec3 ormTexel(vec3 at) {\n  if (LAYERED && layered()) return layeredOrm();\n  if (WORLD_UVS && triplanar()) return triplanarOrm(at.z);\n  return texture(uOrmMap, at).rgb;\n}\n\nvec3 emissiveTexel(vec3 at) {\n  if (LAYERED && layered() && layeredGlows()) return layeredEmissive();\n  if (WORLD_UVS && triplanar()) return triplanarEmissive(at.z);\n  return texture(uEmissiveMap, at).rgb;\n}\n";

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

@@ -0,0 +1,38 @@
+/**
+ * Where each of a material's maps is read: a layered material's blend (`layered.ts`), the three
+ * planes of a triplanar projection (`worldUv.ts`), or the map itself at the surface's coordinates.
+ *
+ * **Functions rather than branches in `main`, for the bundle's sake.** The generated WGSL stores an
+ * item once however many of the sixteen permutations share it, and `main` differs in every one, so
+ * a line there is paid sixteen times and a line here once. Called from the same uniform branches the
+ * reads stood in, so their implicit levels are as legal as they were: AGENTS.md 2026-08-07.
+ */
+export const MAP_READS_GLSL = /* glsl */ `
+/* The surface's coordinates moved onto the world's horizontal plane where a material projects them,
+   with the frame's coordinates and the mesh's tangents, which no longer run along them, set aside. */
+void projectSurface(inout vec3 at, inout vec2 frameAt, inout int frameTangents) {
+  if (WORLD_UVS && projected()) {
+    at.xy = planarAt();
+    frameAt = at.xy;
+    frameTangents = 0;
+  }
+}
+
+vec4 albedoTexel(vec3 at) {
+  if (LAYERED && layered()) return layeredAlbedo();
+  if (WORLD_UVS && triplanar()) return triplanarAlbedo(at.z);
+  return texture(uAlbedo, at);
+}
+
+vec3 ormTexel(vec3 at) {
+  if (LAYERED && layered()) return layeredOrm();
+  if (WORLD_UVS && triplanar()) return triplanarOrm(at.z);
+  return texture(uOrmMap, at).rgb;
+}
+
+vec3 emissiveTexel(vec3 at) {
+  if (LAYERED && layered() && layeredGlows()) return layeredEmissive();
+  if (WORLD_UVS && triplanar()) return triplanarEmissive(at.z);
+  return texture(uEmissiveMap, at).rgb;
+}
+`;

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

@@ -57,7 +57,7 @@ const bool PHYSICAL_SPECULAR = PHYSICAL_SPECULAR_ON;  // wgsl:override
  * A model's numbers, two vectors a material — the lit stage's uniform budget has no more room
  * (surfaceModel.ts) — and whether a model map is bound, in the last component.
  */
-uniform vec4 uModelParams[2];
+uniform vec4 uModelParams[2]; // wgsl:material
 /* The model's own channels, in the albedo's layout: what each means is each model's to say. */
 uniform highp sampler2DArray uModelMap;
 

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

@@ -0,0 +1,21 @@
+/**
+ * The sun's moving layer read through a matrix of its own: the one the frame's dynamic shadow pass
+ * was drawn with, where that is not the static layer's.
+ *
+ * **Why a matrix of its own.** The static layer wants a square over the whole of what stands still,
+ * so distant roofs keep their shadows; what moves wants a tight one, so a character's shadow is
+ * sharp. One matrix for both is one of the two given up. A caller fits each as it likes and draws
+ * each pass with its own (`beginShadowPass(matrix, 'dynamic')`); the renderer keeps the dynamic
+ * pass's and the lit stage reads that layer through it, the receiver's position projected from the
+ * world here rather than carried in a second varying.
+ *
+ * **A lit switch, `MOVING_SUN`**, off until a frame's dynamic pass is drawn with a matrix the static
+ * layer does not share, then on for good. Declared beside the other lit switches, ahead of the
+ * shadow lookup that calls it; compiled out, the moving layer is read at the static layer's place,
+ * exactly as it always was, and its matrix and depth span are not declared at all.
+ *
+ * **What it gives up**: a receiver outside the static layer's square takes no sun shadow at all,
+ * moving casters included, since everything is faded by that square first; so the tight square
+ * belongs inside the wide one.
+ */
+export declare function movingSunGlsl(on: boolean): string;

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

@@ -0,0 +1,46 @@
+/**
+ * The sun's moving layer read through a matrix of its own: the one the frame's dynamic shadow pass
+ * was drawn with, where that is not the static layer's.
+ *
+ * **Why a matrix of its own.** The static layer wants a square over the whole of what stands still,
+ * so distant roofs keep their shadows; what moves wants a tight one, so a character's shadow is
+ * sharp. One matrix for both is one of the two given up. A caller fits each as it likes and draws
+ * each pass with its own (`beginShadowPass(matrix, 'dynamic')`); the renderer keeps the dynamic
+ * pass's and the lit stage reads that layer through it, the receiver's position projected from the
+ * world here rather than carried in a second varying.
+ *
+ * **A lit switch, `MOVING_SUN`**, off until a frame's dynamic pass is drawn with a matrix the static
+ * layer does not share, then on for good. Declared beside the other lit switches, ahead of the
+ * shadow lookup that calls it; compiled out, the moving layer is read at the static layer's place,
+ * exactly as it always was, and its matrix and depth span are not declared at all.
+ *
+ * **What it gives up**: a receiver outside the static layer's square takes no sun shadow at all,
+ * moving casters included, since everything is faded by that square first; so the tight square
+ * belongs inside the wide one.
+ */
+export function movingSunGlsl(on) {
+    if (!on) {
+        return /* glsl */ `
+const bool MOVING_SUN = false;  // wgsl:override
+vec3 movingSunAt() { return vec3(0.0); }
+float movingSunSpan() { return 1.0; }
+`;
+    }
+    return /* glsl */ `
+/* Whether the moving layer has a matrix of its own. Off until a frame draws it with one: movingSun.ts. */
+const bool MOVING_SUN = true;  // wgsl:override
+/* The dynamic shadow pass's world-to-light matrix, and the depth it spans in metres. */
+uniform mat4 uMovingLightViewProj;
+uniform float uMovingShadowDepthSpan;
+
+/* The receiver in the moving layer's map: x and y across it, z its depth, all 0 to 1. */
+vec3 movingSunAt() {
+  vec4 l = uMovingLightViewProj * vec4(vWorldPos, 1.0);
+  return l.xyz / l.w * 0.5 + 0.5;
+}
+
+float movingSunSpan() {
+  return uMovingShadowDepthSpan;
+}
+`;
+}

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

@@ -3,8 +3,12 @@
  * lit block for every light and by an unlit refracting draw for the direction it bends, so a lit
  * pane and an unlit distortion bend by one tilt rather than two transcriptions of it.
  *
- * Depth zero, after the tangent frame it calls; see `flatFrag`. **Only ever called under a branch
+ * The frame is built from `frameAt`, the coordinates the map was laid by — the mesh's, or the
+ * world's where a material projects them (`worldUv.ts`), with the mesh's tangents then set aside
+ * by `hasTangents`, since they run along coordinates the map no longer follows.
+ *
+ * Depth zero, after the tangent frame and the world's projection it calls; see `flatFrag`. **Only ever called under a branch
  * on a uniform** — `uNormalStrength` and whatever gates its caller — which is what makes the
  * derivatives inside `tangentFrame` and the implicit level of the read legal: AGENTS.md 2026-08-07.
  */
-export declare const NORMAL_MAP_GLSL = "\nvec3 normalMapped(vec3 n, vec3 at) {\n  vec3 mapped = texture(uNormalMap, at).xyz * 2.0 - 1.0;\n  /*\n   * z rebuilt where none is stored. A tangent-space normal points out of its surface, so a\n   * stored z at or below zero is never a real one: it is a two-channel map, BC5, whose blue a\n   * device samples as zero and which arrives here as -1. Every map baked from BC5 to PNG before\n   * 4.8.4 carried the same zero. A select rather than a flag: no uniform to bind, no material\n   * that has to say what format it holds, and continuous at the boundary, since a unit texel\n   * lying flat has its z near zero either way. A texel with z above zero is left as it was.\n   */\n  mapped.z = mapped.z > 0.0 ? mapped.z : sqrt(max(0.0, 1.0 - dot(mapped.xy, mapped.xy)));\n  mat3 tbn = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);\n  return normalize(mix(n, normalize(tbn * mapped), uNormalStrength));\n}\n";
+export declare const NORMAL_MAP_GLSL = "\nvec3 normalMapped(vec3 n, vec3 at, vec2 frameAt, int hasTangents) {\n  /* On three planes where the material projects them so: worldUv.ts. */\n  if (WORLD_UVS && triplanar()) return triplanarNormal(n, at.z);\n  /* A layered material's texels, blended by its mask before the frame turns them: layered.ts. */\n  if (LAYERED && layered()) {\n    mat3 layeredFrame = tangentFrame(n, vWorldPos, frameAt, vTangent, hasTangents);\n    return normalize(mix(n, normalize(layeredFrame * layeredTexel()), uNormalStrength));\n  }\n  vec3 mapped = texture(uNormalMap, at).xyz * 2.0 - 1.0;\n  /*\n   * z rebuilt where none is stored. A tangent-space normal points out of its surface, so a\n   * stored z at or below zero is never a real one: it is a two-channel map, BC5, whose blue a\n   * device samples as zero and which arrives here as -1. Every map baked from BC5 to PNG before\n   * 4.8.4 carried the same zero. A select rather than a flag: no uniform to bind, no material\n   * that has to say what format it holds, and continuous at the boundary, since a unit texel\n   * lying flat has its z near zero either way. A texel with z above zero is left as it was.\n   */\n  mapped.z = mapped.z > 0.0 ? mapped.z : sqrt(max(0.0, 1.0 - dot(mapped.xy, mapped.xy)));\n  mat3 tbn = tangentFrame(n, vWorldPos, frameAt, vTangent, hasTangents);\n  return normalize(mix(n, normalize(tbn * mapped), uNormalStrength));\n}\n";

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

@@ -3,12 +3,23 @@
  * lit block for every light and by an unlit refracting draw for the direction it bends, so a lit
  * pane and an unlit distortion bend by one tilt rather than two transcriptions of it.
  *
- * Depth zero, after the tangent frame it calls; see `flatFrag`. **Only ever called under a branch
+ * The frame is built from `frameAt`, the coordinates the map was laid by — the mesh's, or the
+ * world's where a material projects them (`worldUv.ts`), with the mesh's tangents then set aside
+ * by `hasTangents`, since they run along coordinates the map no longer follows.
+ *
+ * Depth zero, after the tangent frame and the world's projection it calls; see `flatFrag`. **Only ever called under a branch
  * on a uniform** — `uNormalStrength` and whatever gates its caller — which is what makes the
  * derivatives inside `tangentFrame` and the implicit level of the read legal: AGENTS.md 2026-08-07.
  */
 export const NORMAL_MAP_GLSL = /* glsl */ `
-vec3 normalMapped(vec3 n, vec3 at) {
+vec3 normalMapped(vec3 n, vec3 at, vec2 frameAt, int hasTangents) {
+  /* On three planes where the material projects them so: worldUv.ts. */
+  if (WORLD_UVS && triplanar()) return triplanarNormal(n, at.z);
+  /* A layered material's texels, blended by its mask before the frame turns them: layered.ts. */
+  if (LAYERED && layered()) {
+    mat3 layeredFrame = tangentFrame(n, vWorldPos, frameAt, vTangent, hasTangents);
+    return normalize(mix(n, normalize(layeredFrame * layeredTexel()), uNormalStrength));
+  }
   vec3 mapped = texture(uNormalMap, at).xyz * 2.0 - 1.0;
   /*
    * z rebuilt where none is stored. A tangent-space normal points out of its surface, so a
@@ -19,7 +30,7 @@ vec3 normalMapped(vec3 n, vec3 at) {
    * lying flat has its z near zero either way. A texel with z above zero is left as it was.
    */
   mapped.z = mapped.z > 0.0 ? mapped.z : sqrt(max(0.0, 1.0 - dot(mapped.xy, mapped.xy)));
-  mat3 tbn = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);
+  mat3 tbn = tangentFrame(n, vWorldPos, frameAt, vTangent, hasTangents);
   return normalize(mix(n, normalize(tbn * mapped), uNormalStrength));
 }
 `;

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

@@ -1,7 +1,8 @@
 /**
  * A draw's surface overlay in the lit stage: the rim, the dissolve and the wrinkles
- * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at three places — the dissolve's cut
- * before anything is shaded, the wrinkles after the normal map, and the glow beside emission.
+ * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at four places — the dissolve's cut
+ * before anything is shaded, the wrinkles after the normal map, a blending rim on the base colour
+ * once the normal is final and before any light reads the colour, and the glow beside emission.
  *
  * **A lit switch, `SURFACE_OVERLAY`**, off until a draw first sets an overlay and then on for good,
  * as `litSwitchesGlsl`'s are; declared after the models so every switch before it keeps its id.

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

@@ -1,7 +1,8 @@
 /**
  * A draw's surface overlay in the lit stage: the rim, the dissolve and the wrinkles
- * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at three places — the dissolve's cut
- * before anything is shaded, the wrinkles after the normal map, and the glow beside emission.
+ * `surfaceOverlay.ts` packs into `uOverlay`. Called from `main` at four places — the dissolve's cut
+ * before anything is shaded, the wrinkles after the normal map, a blending rim on the base colour
+ * once the normal is final and before any light reads the colour, and the glow beside emission.
  *
  * **A lit switch, `SURFACE_OVERLAY`**, off until a draw first sets an overlay and then on for good,
  * as `litSwitchesGlsl`'s are; declared after the models so every switch before it keeps its id.
@@ -19,6 +20,7 @@ export function overlayGlsl(on) {
 const bool SURFACE_OVERLAY = false;  // wgsl:override
 bool overlayCuts(vec2 uv) { return false; }
 vec3 overlayWrinkle(vec3 mapped, vec3 unmapped, vec2 uv) { return mapped; }
+vec3 overlayRimBase(vec3 base, vec2 uv, vec3 n) { return base; }
 vec3 overlayGlow(vec2 uv, vec3 n) { return vec3(0.0); }
 `;
     }
@@ -26,7 +28,7 @@ vec3 overlayGlow(vec2 uv, vec3 n) { return vec3(0.0); }
 /* Whether this program carries a draw's overlay. Off but where one has been set: overlay.ts. */
 const bool SURFACE_OVERLAY = true;  // wgsl:override
 /* The overlay's fifteen vectors; packSurfaceOverlay in surfaceOverlay.ts says what each holds. */
-uniform vec4 uOverlay[15];
+uniform vec4 uOverlay[15]; // wgsl:material
 
 /* Whether the atlas is what the refraction slot holds: not where this draw refracts or is glass. */
 bool overlayImagesBound() {
@@ -84,8 +86,42 @@ vec2 overlayScreen() {
   return vec2(eye.x / depth + uClusterFrustum.w, eye.y / depth + 1.0) * 0.5;
 }
 
+/*
+ * The rim's weight here, 0 to 1 before the pulse and the mask: the edge leaning toward normals that
+ * face up, raised to the contrast, times the noise laid in screen space. Its strength is the
+ * caller's: an added rim takes it times its light, a blending one times its colour.
+ */
+float overlayRimWeight(vec2 uv, vec3 n) {
+  vec3 toEye = normalize(uCameraPos - vWorldPos);
+  float edge = pow(1.0 - clamp(dot(n, toEye), 0.0, 1.0), max(uOverlay[1].x, 1e-4));
+  float up = pow(clamp(n.y * 0.5 + 0.5, 0.0, 1.0), max(uOverlay[1].y, 1e-4));
+  float rim = pow(edge * up, max(uOverlay[1].z, 1e-4));
+  float time = uSurfaceScene.x;
+  if (uOverlay[2].x > 0.0 && overlayImagesBound()) {
+    vec2 at = overlayScreen() * uOverlay[3].z + uOverlay[3].xy * time;
+    rim *= overlayImage(uOverlay[2], at).r;
+  }
+  rim = min(rim, 1.0);
+  rim *= mix(uOverlay[4].x, uOverlay[4].y, 0.5 + 0.5 * sin(uOverlay[3].w * time));
+  if (uOverlay[5].x > 0.0 && overlayImagesBound()) {
+    rim *= 1.0 - uOverlay[1].w * overlayImage(uOverlay[5], uv).r;
+  }
+  return rim;
+}
+
+/*
+ * A blending rim: the base colour pulled toward the rim's by the weight times the alpha, held at
+ * one, before any light reads it, so the edge is lit as the surface is. The colour arrives already
+ * held at one a channel. Nothing where the rim adds instead, or where there is none.
+ */
+vec3 overlayRimBase(vec3 base, vec2 uv, vec3 n) {
+  if (uOverlay[0].w <= 0.0 || uOverlay[4].z < 0.5) return base;
+  float weight = clamp(uOverlay[0].w * overlayRimWeight(uv, n), 0.0, 1.0);
+  return mix(base, uOverlay[0].rgb, weight);
+}
+
 /* What the overlay adds to the light the surface gives off: the dissolve's band, the colour laid
-   over through its noise, and the rim. Zero where the draw sets none of them. */
+   over through its noise, and an adding rim. Zero where the draw sets none of them. */
 vec3 overlayGlow(vec2 uv, vec3 n) {
   vec3 glow = vec3(0.0);
   float noise = overlayDissolveNoise(uv);
@@ -94,22 +130,8 @@ vec3 overlayGlow(vec2 uv, vec3 n) {
     glow += uOverlay[8].rgb * uOverlay[8].w * band + uOverlay[9].rgb * uOverlay[9].w * noise;
   }
   float strength = uOverlay[0].w;
-  if (strength > 0.0) {
-    vec3 toEye = normalize(uCameraPos - vWorldPos);
-    float edge = pow(1.0 - clamp(dot(n, toEye), 0.0, 1.0), max(uOverlay[1].x, 1e-4));
-    float up = pow(clamp(n.y * 0.5 + 0.5, 0.0, 1.0), max(uOverlay[1].y, 1e-4));
-    float rim = pow(edge * up, max(uOverlay[1].z, 1e-4));
-    float time = uSurfaceScene.x;
-    if (uOverlay[2].x > 0.0 && overlayImagesBound()) {
-      vec2 at = overlayScreen() * uOverlay[3].z + uOverlay[3].xy * time;
-      rim *= overlayImage(uOverlay[2], at).r;
-    }
-    rim = min(rim, 1.0);
-    rim *= mix(uOverlay[4].x, uOverlay[4].y, 0.5 + 0.5 * sin(uOverlay[3].w * time));
-    if (uOverlay[5].x > 0.0 && overlayImagesBound()) {
-      rim *= 1.0 - uOverlay[1].w * overlayImage(uOverlay[5], uv).r;
-    }
-    glow += uOverlay[0].rgb * strength * rim;
+  if (strength > 0.0 && uOverlay[4].z < 0.5) {
+    glow += uOverlay[0].rgb * strength * overlayRimWeight(uv, n);
   }
   return glow;
 }

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

@@ -13,7 +13,7 @@
  * picture and is its own change.
  */
 import { MAX_SHADOW_FILTER_TAPS } from '../../renderQuality.js';
-import { OUTPUT_TRANSFORM_GLSL } from '../outputTransform.js';
+import { LIT_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.
@@ -343,7 +343,7 @@ ${LAMP_GLASS_GLSL}
 
 layout(location = 0) out vec4 outColor;
 
-${OUTPUT_TRANSFORM_GLSL}
+${LIT_OUTPUT_TRANSFORM_GLSL}
 
 /**
  * A fixed Poisson disk avoids the grid-shaped edge left by square 3x3 PCF.