@driftengine/core 4.8.7 → 4.10.0

package/dist/render/shaders/vertexChannel.js

@@ -37,6 +37,32 @@ uniform float uWindTime;
 /* Spatial frequency of the travelling gust, per metre. */
 uniform vec2 uWindSpatialPhase;
 `;
+/**
+ * The same, for the lit stage, whose wind lives in its view block: the frame's and not the draw's,
+ * so a draw's own block does not change when the wind does. See `hoistUniformBlock` in
+ * `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs the same program it always
+ * has; the depth stage keeps the unmarked chunk, having no view block.
+ */
+export const LIT_CHANNEL_ATTRIBUTE = `
+layout(location = 13) in vec4 aChannel;
+
+/*
+ * The frame's wind, already converted by \`resolveScatterDeform\` — a normalised direction, metres
+ * of bend, a gust amplitude and a scaled clock.
+ *
+ * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A
+ * second conversion here would be a second wind however identical its inputs, and the failure is
+ * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the
+ * grass beneath it leans another, with no single element looking wrong. See "One wind, sampled
+ * once" in AGENTS.md.
+ */
+uniform vec2 uWindDirection; // wgsl:view
+uniform float uWindSpeed; // wgsl:view
+uniform float uWindGust; // wgsl:view
+uniform float uWindTime; // wgsl:view
+/* Spatial frequency of the travelling gust, per metre. */
+uniform vec2 uWindSpatialPhase; // wgsl:view
+`;
 /**
  * Where the wind puts a vertex, given how much of it that vertex takes.
  *

package/dist/render/shaders/water.d.ts

@@ -15,4 +15,4 @@
  * ocean from a fixed vertex budget without the surface sliding underfoot.
  */
 export declare const WATER_VERT = "#version 300 es\nlayout(location = 0) in vec2 aGrid;\n\nuniform mat4 uViewProj;\nuniform mat4 uReflectionViewProj;\nuniform vec3 uCameraPos;\nuniform float uTime;\n/**\n * Where the sheet is laid, in world XZ.\n *\n * The ocean passes its own camera position snapped to whole cells, which is what\n * gives an endless sea from a fixed vertex budget without the surface sliding\n * underfoot. A *bounded* sheet \u2014 a pool in a courtyard \u2014 passes the middle of the\n * thing it is filling instead, and is world-fixed by construction.\n *\n * Snapped on the CPU rather than here so that one number is the only difference\n * between an ocean and a basin, and the shader has no idea which it is drawing.\n */\nuniform vec2 uGridOrigin;\n/**\n * Metres per unit of the sheet's own grid, along each of the body's own axes.\n *\n * One and one for the ocean, whose grid is authored in metres and is two meshes wide.\n * A bounded body \u2014 a pool, a tank, a puddle, a channel \u2014 is drawn from a unit sheet\n * and scaled by its own half-extents, which is what lets one mesh and one material\n * serve every body of water in the world.\n *\n * **Two numbers and not one since 2026-08-28.** A single span makes every bounded\n * body square, and a square that contains a channel floods the ground either side\n * of it. The ocean passes the same number twice and is bit-identical to what it was.\n */\nuniform vec2 uGridSpan;\nuniform vec2 uGridHalf;\nuniform vec2 uNearHalf;\n/**\n * The body's own +z, in world XZ, unit length. (0, 1) leaves the sheet unturned.\n *\n * A direction rather than an angle, so nothing here needs a trig call and a consumer\n * bounding a channel can hand over the direction its run already takes. The across\n * axis is world up crossed with this, `(fz, -fx)`, which is the basis\n * `MeshBuilder.addOrientedBox` builds from a forward vector \u2014 one convention for an\n * oriented thing, so a reader who has met one has met both.\n */\nuniform vec2 uGridForward;\n/** Prevailing wind bearing, normalised. Waves are steered toward it. */\nuniform vec2 uWindDir;\n/** Multiplier on authored steepness \u2014 how built-up the sea is. */\nuniform float uWaveGain;\nuniform float uWaterLevel;\n\nout vec3 vWorldPos;\nout vec3 vNormal;\nout float vCrest;\nout vec4 vReflectionClip;\n/** Grid-local offset, so the sheet can fade out its own boundary. */\nout vec2 vGrid;\n\n\nconst int GERSTNER_COUNT = 4;\n/*\n * direction.xy, steepness, wavelength. Amplitude is steepness/k, so these sum to\n * roughly a 1m swell \u2014 enough to read as a living surface, low enough that crests\n * never wash over an island whose deck sits ~1.8m above sea level.\n */\nconst vec4 GERSTNER_WAVES[4] = vec4[4](\n  vec4( 1.0,  0.0,  0.115, 34.0),\n  vec4( 0.6,  0.8,  0.100, 18.0),\n  vec4(-0.7,  0.7,  0.080,  9.0),\n  vec4( 0.2, -0.98, 0.060,  5.0)\n);\n\n/*\n * Steer each wave toward the wind, but only partway. A real sea is a dominant\n * swell plus cross-chop; rotating all four onto one bearing gives corduroy,\n * which reads as a material rather than as water.\n */\nvec2 gerstnerDirection(int i, vec2 windDir) {\n  return normalize(mix(normalize(GERSTNER_WAVES[i].xy), windDir, 0.62));\n}\n\nfloat gerstnerWavenumber(int i) {\n  return 6.28318530718 / GERSTNER_WAVES[i].w;\n}\n\n/** Deep-water phase in radians at a point on the resting plane. */\nfloat gerstnerPhase(float k, vec2 dir, vec2 p, float time) {\n  float c = sqrt(9.81 / k);              // deep-water phase speed\n  return k * (dot(dir, p) - c * time);\n}\n\nstruct GerstnerSurface {\n  /** Displacement from the resting plane \u2014 horizontal as well as vertical. */\n  vec3 offset;\n  vec3 normal;\n  /** Height in units of steepness; positive near a crest. */\n  float crest;\n};\n\nGerstnerSurface gerstnerSurface(vec2 p, float time, vec2 windDir, float gain) {\n  GerstnerSurface s;\n  s.offset = vec3(0.0);\n  s.normal = vec3(0.0, 1.0, 0.0);\n  s.crest = 0.0;\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    float a = steepness / k;             // amplitude from steepness\n\n    s.offset.x += dir.x * a * cos(f);\n    s.offset.y += a * sin(f);\n    s.offset.z += dir.y * a * cos(f);\n\n    // Analytic normal: the partial derivatives of the displacement above.\n    s.normal.x -= dir.x * steepness * cos(f);\n    s.normal.z -= dir.y * steepness * cos(f);\n    s.normal.y -= steepness * sin(f);\n\n    s.crest += sin(f) * steepness;\n  }\n  return s;\n}\n\n/**\n * Second derivatives of the height field: (d2h/dx2, d2h/dz2, d2h/dxdz).\n *\n * How the surface *bends*, which is what decides where reflected light\n * converges. Analytic from the same sum, so it cannot disagree with the shape\n * the vertex stage displaced.\n */\nvec3 gerstnerCurvature(vec2 p, float time, vec2 windDir, float gain) {\n  vec3 h = vec3(0.0);\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    // Second derivative of (steepness/k)*sin(f) along the wave's own bearing.\n    float second = -steepness * k * sin(f);\n    h.x += second * dir.x * dir.x;\n    h.y += second * dir.y * dir.y;\n    h.z += second * dir.x * dir.y;\n  }\n  return h;\n}\n\n\nvoid main() {\n  /*\n   * Waves must reach nothing by the near sheet's edge, because beyond it lies\n   * the flat skirt. A displaced rim meeting an undisplaced skirt would tear the\n   * surface open along a visible seam; fading first makes the two meshes agree\n   * exactly where they meet. Chebyshev distance, so the fade band follows the\n   * rectangular boundary rather than cutting an ellipse inside it.\n   *\n   * **Measured as a fraction of each axis' own extent**, which is what lets a\n   * channel three metres across and twenty-one long fade evenly at both its ends\n   * and both its sides. Against one shared extent the narrow axis would be inside\n   * the fade band along its whole length and the water would never reach its own\n   * bank. For the ocean, whose two extents are equal, this is the same arithmetic\n   * with the division moved one step earlier.\n   *\n   * It is also the honest thing to draw. At a few hundred metres a 1 m swell is\n   * well under a pixel, and out on the skirt a float32 phase argument has lost\n   * most of its meaningful bits \u2014 a calm horizon is what an ocean actually looks\n   * like from that far away.\n   */\n  vec2 grid = aGrid * uGridSpan;\n  /* The same offset the fragment stage fades the rim on, so the two cannot disagree. */\n  vGrid = grid;\n  vec2 rimFraction = abs(grid) / max(uNearHalf, vec2(1e-4));\n  float rimDistance = max(rimFraction.x, rimFraction.y);\n  float waveFade = 1.0 - smoothstep(0.35, 0.97, rimDistance);\n\n  /*\n   * Into the world: across the body, then along it. `right = up x forward` is\n   * `(fz, -fx)`, and getting that pair the wrong way round is a sheet mirrored\n   * about its own axis, which on a square is invisible and on a channel is a\n   * channel across the road instead of along it.\n   */\n  vec2 laid = vec2(uGridForward.y, -uGridForward.x) * grid.x + uGridForward * grid.y;\n\n  vec3 base = vec3(uGridOrigin.x + laid.x, uWaterLevel, uGridOrigin.y + laid.y);\n\n  GerstnerSurface sea = gerstnerSurface(base.xz, uTime, uWindDir, waveFade * uWaveGain);\n  vec3 pos = base + sea.offset;\n\n  vWorldPos = pos;\n  vNormal = normalize(sea.normal);\n  vCrest = sea.crest;\n  vReflectionClip = uReflectionViewProj * vec4(pos, 1.0);\n  gl_Position = uViewProj * vec4(pos, 1.0);\n}\n";
-export declare const WATER_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorldPos;\nin vec3 vNormal;\nin float vCrest;\nin vec4 vReflectionClip;\nin vec2 vGrid;\n\nuniform vec2 uGridHalf;\nuniform float uFoamGain;\n/**\n * How much of what is beneath it a body of water hides, looked straight down.\n *\n * The *density* of the water rather than a rendering trick: a sea hides its own\n * floor, a fountain shows the tiles at the bottom of it, and a puddle is nearly\n * clear. Only the nadir end is configurable \u2014 at a grazing angle every water\n * surface goes reflective, which is Fresnel and not a property of the liquid.\n */\nuniform float uNadirOpacity;\n/** The whole surface's visibility, 0 to 1. Zero draws nothing at all. */\nuniform float uVisibility;\n/**\n * How much this body mirrors regardless of the angle it is seen at, 0 to 1.\n *\n * Zero is physics: reflection is Fresnel alone, which is right for an ocean seen\n * across its own surface and which means *almost nothing* when you stand over a\n * basin and look down into it \u2014 the angle is steep, the Fresnel term is a few\n * percent, and a reflection nobody can see is the same as no reflection: the\n * character's reflection is technically present and far too faint to perceive.\n *\n * So a body may declare itself more mirror than water. It is a lie about optics\n * and an honest one about what a small pool is *for*: you look into it to see\n * something. The sea keeps zero and behaves exactly as it always has.\n */\nuniform float uMirror;\nuniform vec3 uDeepColor;\nuniform vec3 uShallowColor;\nuniform vec3 uDirectionalDir;\nuniform vec3 uDirectionalColor;\nuniform vec3 uAmbient;\n/**\n * The scene's point lights, which water is entitled to as much as stone is.\n *\n * The surface used to answer to the sun alone, on the reasonable assumption that water\n * is a thing that sits under the sky. It is not: a flooded corridor, a cistern, an\n * indoor pool and a harbour at night are all water lit entirely by lamps, and under\n * those this shaded to flat ambient \u2014 a coloured plane, with the specular glitter that\n * is the single strongest cue that a surface *is* water switched off because no\n * directional source existed to make it. A lantern on a jetty threw nothing.\n *\n * Same slots, same weights and the surface shader's falloffs, a light's own exponent among\n * them, so a lamp reaches as far over water as over the ground beside it. **What it gives up**:\n * a spot's cone, which water does not read, so a spot lights the water around it as a lamp\n * would; and the smooth falloff's square, which the surface applies and this has never, so under\n * that falloff a lamp's pool on water is the wider of the two.\n */\n#define MAX_LIGHTS 16\nuniform int uLightCount;\nuniform vec3 uLightPos[MAX_LIGHTS];\nuniform vec3 uLightColor[MAX_LIGHTS];\nuniform float uLightRadius[MAX_LIGHTS];\nuniform float uLightWeight[MAX_LIGHTS];\nuniform int uLightFalloff;\n/* The surface shader's cone record, of which water reads z alone: a light's own falloff exponent. */\nuniform vec4 uLightCone[MAX_LIGHTS];\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform vec3 uCameraPos;\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform vec2 uReflectionTexelSize;\nuniform int uReflectionFilterTaps;\n\nconst vec2 REFLECTION_FILTER[9] = vec2[9](\n  vec2( 0.00,  0.00), vec2(-0.62, -0.31), vec2( 0.54,  0.43),\n  vec2(-0.34,  0.76), vec2( 0.78, -0.57), vec2(-0.88,  0.28),\n  vec2( 0.22, -0.91), vec2( 0.91,  0.08), vec2(-0.18,  0.94)\n);\n// Preserve small moving silhouettes such as a character while still spreading\n// the surrounding taps enough to make the target read as rough water.\nconst float REFLECTION_FILTER_WEIGHT[9] = float[9](\n  0.28, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09\n);\n\nout vec4 outColor;\n\nvoid main() {\n  vec3 n = normalize(vNormal);\n  vec3 view = normalize(uCameraPos - vWorldPos);\n\n  // Fresnel: water is nearly a mirror at grazing angles and clear straight down.\n  // abs keeps the underside physically continuous with the top instead of\n  // turning the entire surface into an opaque mirror below the waterline.\n  float facing = clamp(abs(dot(n, view)), 0.0, 1.0);\n  float fresnel = 0.02 + 0.98 * pow(1.0 - facing, 5.0);\n\n  vec3 atmosphereColor = mediumColor();\n\n  vec3 col = mix(uDeepColor, uShallowColor, clamp(vCrest * 1.4 + 0.4, 0.0, 1.0));\n  vec3 incident = uAmbient +\n    uDirectionalColor * max(dot(n, uDirectionalDir), 0.0) * 0.6;\n\n  // Specular glitter along the crests \u2014 the strongest single cue that a surface\n  // is water rather than a coloured plane.\n  vec3 halfVec = normalize(uDirectionalDir + view);\n  float spec = pow(max(dot(n, halfVec), 0.0), 220.0);\n  vec3 highlight = uDirectionalColor * spec * 1.6;\n\n  /*\n   * And the same from every lamp in range: a light over water lights it, and glitters\n   * on it. Indoors this is the whole of the surface's lighting.\n   *\n   * The exponent is the sun's, so a crest picks a lamp out as tightly as it picks out\n   * the sky \u2014 which is what makes a strip light read as a *streak* across a pool rather\n   * than a broad sheen. Weighted by presence like every other consumer of these slots,\n   * so a light entering the set fades in instead of appearing.\n   */\n  for (int i = 0; i < MAX_LIGHTS; i++) {\n    if (i >= uLightCount) break;\n    vec3 toLight = uLightPos[i] - vWorldPos;\n    float lightDist = length(toLight);\n    float falloff;\n    float exponent = uLightCone[i].z;\n    if (exponent > 0.0) {\n      float reach = lightDist / max(uLightRadius[i], 1e-4);\n      falloff = pow(clamp(1.0 - reach * reach, 0.0, 1.0), exponent);\n    } else if (uLightFalloff == 1) {\n      float window = clamp(1.0 - pow(lightDist / max(uLightRadius[i], 1e-4), 4.0), 0.0, 1.0);\n      falloff = window * window / max(lightDist * lightDist, 0.01);\n    } else {\n      falloff = clamp(1.0 - lightDist / max(uLightRadius[i], 1e-4), 0.0, 1.0);\n    }\n    if (falloff <= 0.0) continue;\n    vec3 lightDir = toLight / max(lightDist, 1e-4);\n    float shaped = falloff * uLightWeight[i];\n    incident += uLightColor[i] * max(dot(n, lightDir), 0.0) * shaped * 0.6;\n    vec3 lampHalf = normalize(lightDir + view);\n    highlight += uLightColor[i] * pow(max(dot(n, lampHalf), 0.0), 220.0) * shaped * 1.6;\n  }\n\n  col *= incident;\n  col += highlight;\n\n  // Foam where crests peak \u2014 and only when the wind is actually breaking them.\n  float foam = smoothstep(0.55, 0.85, vCrest) * uFoamGain;\n  col = mix(col, vec3(0.92, 0.96, 1.0), foam * 0.5);\n\n  float dist = distance(vWorldPos, uCameraPos);\n  float fog = mediumFog(dist, vWorldPos.y);\n  col = mix(col, atmosphereColor, fog);\n\n  // Transparency is angle-dependent, like real water: looking down you see\n  // straight through to the seabed, at grazing angles it turns reflective.\n  // This is computed before reflection because straight-alpha compositing must\n  // not attenuate reflected radiance a second time below.\n  float airOpacity = mix(uNadirOpacity, 0.96, fresnel);\n  float underwaterOpacity = mix(uNadirOpacity * 0.55, 0.88, fresnel);\n  float opacity = mix(airOpacity, underwaterOpacity, uUnderwaterFactor);\n  opacity = mix(opacity, 0.96, foam * 0.7);\n\n  // Project the displaced surface into the mirrored camera. The Gerstner\n  // displacement supplies broad distortion; the analytic normal adds the\n  // smaller ripples that make reflected silhouettes move with each crest.\n  vec3 reflected = atmosphereColor;\n  float reflectionValid = 0.0;\n  if (uReflectionEnabled != 0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    reflectionUv += n.xz * mix(0.008, 0.022, fresnel);\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    reflectionValid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    // A planar target is optically sharp, which is correct for a mirror but\n    // wrong for a moving water surface. Broaden it over a Poisson footprint\n    // that grows gently with viewing distance; normal displacement above\n    // still makes every crest steer that softened image independently.\n    float blurPixels = 1.35 + min(dist * 0.022, 3.5);\n    vec3 sceneReflection = vec3(0.0);\n    float filterWeight = 0.0;\n    for (int i = 0; i < 9; i++) {\n      if (i >= uReflectionFilterTaps) break;\n      vec2 sampleUv = reflectionUv +\n        REFLECTION_FILTER[i] * uReflectionTexelSize * blurPixels;\n      float weight = REFLECTION_FILTER_WEIGHT[i];\n      /*\n       * `textureLod` rather than `texture`, by the rule `AGENTS.md` records on 2026-08-07:\n       * this loop is reached through a branch on `vReflectionClip`, which is not uniform, and\n       * an implicit derivative there is undefined. **WGSL does not merely leave it undefined,\n       * it refuses to compile the module**: *\"'textureSample' must only be called from uniform\n       * control flow\"*, with the note that reading `vReflectionClip` may be non-uniform.\n       *\n       * Bit-identical on WebGL2: `planarReflection.ts` allocates one level and filters\n       * `LINEAR`, so there is no mip to select and level zero is the only thing `texture`\n       * could have read.\n       */\n      sceneReflection +=\n        textureLod(uReflectionMap, clamp(sampleUv, 0.0, 1.0), 0.0).rgb * weight;\n      filterWeight += weight;\n    }\n    sceneReflection /= max(filterWeight, 0.001);\n    reflected = mix(atmosphereColor, sceneReflection, reflectionValid);\n  }\n  // The atmosphere-colour fallback preserves the old sky reflection when a\n  // quality profile disables the extra scene pass. Foam scatters rather than\n  // mirroring, so it masks the reflection at breaking crests.\n  float sceneWeight = float(uReflectionEnabled) * reflectionValid;\n  float reflectionGain = mix(0.75, 0.94, sceneWeight);\n  // Angle-honest by default, and a mirror where a body says so. See uMirror above.\n  float reflectivity = mix(fresnel, 1.0, uMirror);\n  float reflectedRadiance = min(\n    reflectivity * reflectionGain * (1.0 - foam * 0.8),\n    opacity\n  );\n  // With SRC_ALPHA blending, mixing by Fresnel directly would multiply the\n  // reflection by opacity again. Divide it out here so the framebuffer gets\n  // the intended reflected fraction while the remainder stays transmissive.\n  float reflectionWeight = reflectedRadiance / max(opacity, 0.001);\n  col = mix(col, reflected, reflectionWeight);\n\n  /*\n   * Dissolve the sheet at its own boundary.\n   *\n   * Fading on fog alone made the horizon a function of the daily palette: a\n   * clear day never reached the threshold, so the grid's rim \u2014 corner and all \u2014\n   * became the skyline. Fading on the grid coordinate cannot fail that way,\n   * because alpha reaches zero at the last row of vertices by construction.\n   * Chebyshev distance because the sheet is a rectangle, so the fade band\n   * follows its four edges instead of cutting an ellipse out of it \u2014 and it is\n   * measured per axis, or a channel's narrow sides would be one continuous fade\n   * and it would have no visible edge at all.\n   */\n  vec2 rimFraction = abs(vGrid) / max(uGridHalf, vec2(0.001));\n  float rimT = max(rimFraction.x, rimFraction.y);\n  float rim = 1.0 - smoothstep(0.9, 1.0, rimT);\n  // Fog still helps where it is thick, it just is no longer load-bearing.\n  float edge = 1.0 - smoothstep(0.82, 1.0, fog);\n  outColor = vec4(col, opacity * edge * rim * uVisibility);\n}\n";
+export declare const WATER_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorldPos;\nin vec3 vNormal;\nin float vCrest;\nin vec4 vReflectionClip;\nin vec2 vGrid;\n\nuniform vec2 uGridHalf;\nuniform float uFoamGain;\n/**\n * How much of what is beneath it a body of water hides, looked straight down.\n *\n * The *density* of the water rather than a rendering trick: a sea hides its own\n * floor, a fountain shows the tiles at the bottom of it, and a puddle is nearly\n * clear. Only the nadir end is configurable \u2014 at a grazing angle every water\n * surface goes reflective, which is Fresnel and not a property of the liquid.\n */\nuniform float uNadirOpacity;\n/** The whole surface's visibility, 0 to 1. Zero draws nothing at all. */\nuniform float uVisibility;\n/**\n * How much this body mirrors regardless of the angle it is seen at, 0 to 1.\n *\n * Zero is physics: reflection is Fresnel alone, which is right for an ocean seen\n * across its own surface and which means *almost nothing* when you stand over a\n * basin and look down into it \u2014 the angle is steep, the Fresnel term is a few\n * percent, and a reflection nobody can see is the same as no reflection: the\n * character's reflection is technically present and far too faint to perceive.\n *\n * So a body may declare itself more mirror than water. It is a lie about optics\n * and an honest one about what a small pool is *for*: you look into it to see\n * something. The sea keeps zero and behaves exactly as it always has.\n */\nuniform float uMirror;\nuniform vec3 uDeepColor;\nuniform vec3 uShallowColor;\nuniform vec3 uDirectionalDir;\nuniform vec3 uDirectionalColor;\nuniform vec3 uAmbient;\n/**\n * The scene's point lights, which water is entitled to as much as stone is.\n *\n * The surface used to answer to the sun alone, on the reasonable assumption that water\n * is a thing that sits under the sky. It is not: a flooded corridor, a cistern, an\n * indoor pool and a harbour at night are all water lit entirely by lamps, and under\n * those this shaded to flat ambient \u2014 a coloured plane, with the specular glitter that\n * is the single strongest cue that a surface *is* water switched off because no\n * directional source existed to make it. A lantern on a jetty threw nothing.\n *\n * Same slots, same weights and the surface shader's falloffs, a light's own exponent among\n * them, so a lamp reaches as far over water as over the ground beside it. **What it gives up**:\n * a spot's cone, which water does not read, so a spot lights the water around it as a lamp\n * would; and the smooth falloff's square, which the surface applies and this has never, so under\n * that falloff a lamp's pool on water is the wider of the two.\n */\n#define MAX_LIGHTS 16\nuniform int uLightCount;\nuniform vec3 uLightPos[MAX_LIGHTS];\nuniform vec3 uLightColor[MAX_LIGHTS];\nuniform float uLightRadius[MAX_LIGHTS];\nuniform float uLightWeight[MAX_LIGHTS];\nuniform int uLightFalloff;\n/* The surface shader's cone record, of which water reads z alone: a light's own falloff exponent. */\nuniform vec4 uLightCone[MAX_LIGHTS];\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform vec3 uCameraPos;\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform vec2 uReflectionTexelSize;\nuniform int uReflectionFilterTaps;\n\nconst vec2 REFLECTION_FILTER[9] = vec2[9](\n  vec2( 0.00,  0.00), vec2(-0.62, -0.31), vec2( 0.54,  0.43),\n  vec2(-0.34,  0.76), vec2( 0.78, -0.57), vec2(-0.88,  0.28),\n  vec2( 0.22, -0.91), vec2( 0.91,  0.08), vec2(-0.18,  0.94)\n);\n// Preserve small moving silhouettes such as a character while still spreading\n// the surrounding taps enough to make the target read as rough water.\nconst float REFLECTION_FILTER_WEIGHT[9] = float[9](\n  0.28, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09\n);\n\nout vec4 outColor;\n\nvoid main() {\n  vec3 n = normalize(vNormal);\n  vec3 view = normalize(uCameraPos - vWorldPos);\n\n  // Fresnel: water is nearly a mirror at grazing angles and clear straight down.\n  // abs keeps the underside physically continuous with the top instead of\n  // turning the entire surface into an opaque mirror below the waterline.\n  float facing = clamp(abs(dot(n, view)), 0.0, 1.0);\n  float fresnel = 0.02 + 0.98 * pow(1.0 - facing, 5.0);\n\n  vec3 atmosphereColor = mediumColor();\n\n  vec3 col = mix(uDeepColor, uShallowColor, clamp(vCrest * 1.4 + 0.4, 0.0, 1.0));\n  vec3 incident = uAmbient +\n    uDirectionalColor * max(dot(n, uDirectionalDir), 0.0) * 0.6;\n\n  // Specular glitter along the crests \u2014 the strongest single cue that a surface\n  // is water rather than a coloured plane.\n  vec3 halfVec = normalize(uDirectionalDir + view);\n  float spec = pow(max(dot(n, halfVec), 0.0), 220.0);\n  vec3 highlight = uDirectionalColor * spec * 1.6;\n\n  /*\n   * And the same from every lamp in range: a light over water lights it, and glitters\n   * on it. Indoors this is the whole of the surface's lighting.\n   *\n   * The exponent is the sun's, so a crest picks a lamp out as tightly as it picks out\n   * the sky \u2014 which is what makes a strip light read as a *streak* across a pool rather\n   * than a broad sheen. Weighted by presence like every other consumer of these slots,\n   * so a light entering the set fades in instead of appearing.\n   */\n  for (int i = 0; i < MAX_LIGHTS; i++) {\n    if (i >= uLightCount) break;\n    vec3 toLight = uLightPos[i] - vWorldPos;\n    float lightDist = length(toLight);\n    float falloff;\n    float exponent = uLightCone[i].z;\n    if (exponent > 0.0) {\n      float reach = lightDist / max(uLightRadius[i], 1e-4);\n      falloff = pow(clamp(1.0 - reach * reach, 0.0, 1.0), exponent);\n    } else if (uLightFalloff == 1) {\n      float window = clamp(1.0 - pow(lightDist / max(uLightRadius[i], 1e-4), 4.0), 0.0, 1.0);\n      falloff = window * window / max(lightDist * lightDist, 0.01);\n    } else {\n      falloff = clamp(1.0 - lightDist / max(uLightRadius[i], 1e-4), 0.0, 1.0);\n    }\n    if (falloff <= 0.0) continue;\n    vec3 lightDir = toLight / max(lightDist, 1e-4);\n    float shaped = falloff * uLightWeight[i];\n    incident += uLightColor[i] * max(dot(n, lightDir), 0.0) * shaped * 0.6;\n    vec3 lampHalf = normalize(lightDir + view);\n    highlight += uLightColor[i] * pow(max(dot(n, lampHalf), 0.0), 220.0) * shaped * 1.6;\n  }\n\n  col *= incident;\n  col += highlight;\n\n  // Foam where crests peak \u2014 and only when the wind is actually breaking them.\n  float foam = smoothstep(0.55, 0.85, vCrest) * uFoamGain;\n  col = mix(col, vec3(0.92, 0.96, 1.0), foam * 0.5);\n\n  float dist = distance(vWorldPos, uCameraPos);\n  float fog = mediumFog(dist, vWorldPos.y);\n  col = mix(col, atmosphereColor, fog);\n\n  // Transparency is angle-dependent, like real water: looking down you see\n  // straight through to the seabed, at grazing angles it turns reflective.\n  // This is computed before reflection because straight-alpha compositing must\n  // not attenuate reflected radiance a second time below.\n  float airOpacity = mix(uNadirOpacity, 0.96, fresnel);\n  float underwaterOpacity = mix(uNadirOpacity * 0.55, 0.88, fresnel);\n  float opacity = mix(airOpacity, underwaterOpacity, uUnderwaterFactor);\n  opacity = mix(opacity, 0.96, foam * 0.7);\n\n  // Project the displaced surface into the mirrored camera. The Gerstner\n  // displacement supplies broad distortion; the analytic normal adds the\n  // smaller ripples that make reflected silhouettes move with each crest.\n  vec3 reflected = atmosphereColor;\n  float reflectionValid = 0.0;\n  if (uReflectionEnabled != 0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    reflectionUv += n.xz * mix(0.008, 0.022, fresnel);\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    reflectionValid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    // A planar target is optically sharp, which is correct for a mirror but\n    // wrong for a moving water surface. Broaden it over a Poisson footprint\n    // that grows gently with viewing distance; normal displacement above\n    // still makes every crest steer that softened image independently.\n    float blurPixels = 1.35 + min(dist * 0.022, 3.5);\n    vec3 sceneReflection = vec3(0.0);\n    float filterWeight = 0.0;\n    for (int i = 0; i < 9; i++) {\n      if (i >= uReflectionFilterTaps) break;\n      vec2 sampleUv = reflectionUv +\n        REFLECTION_FILTER[i] * uReflectionTexelSize * blurPixels;\n      float weight = REFLECTION_FILTER_WEIGHT[i];\n      /*\n       * `textureLod` rather than `texture`, by the rule `AGENTS.md` records on 2026-08-07:\n       * this loop is reached through a branch on `vReflectionClip`, which is not uniform, and\n       * an implicit derivative there is undefined. **WGSL does not merely leave it undefined,\n       * it refuses to compile the module**: *\"'textureSample' must only be called from uniform\n       * control flow\"*, with the note that reading `vReflectionClip` may be non-uniform.\n       *\n       * Bit-identical on WebGL2: `planarReflection.ts` allocates one level and filters\n       * `LINEAR`, so there is no mip to select and level zero is the only thing `texture`\n       * could have read.\n       */\n      sceneReflection +=\n        textureLod(uReflectionMap, clamp(sampleUv, 0.0, 1.0), 0.0).rgb * weight;\n      filterWeight += weight;\n    }\n    sceneReflection /= max(filterWeight, 0.001);\n    reflected = mix(atmosphereColor, sceneReflection, reflectionValid);\n  }\n  // The atmosphere-colour fallback preserves the old sky reflection when a\n  // quality profile disables the extra scene pass. Foam scatters rather than\n  // mirroring, so it masks the reflection at breaking crests.\n  float sceneWeight = float(uReflectionEnabled) * reflectionValid;\n  float reflectionGain = mix(0.75, 0.94, sceneWeight);\n  // Angle-honest by default, and a mirror where a body says so. See uMirror above.\n  float reflectivity = mix(fresnel, 1.0, uMirror);\n  float reflectedRadiance = min(\n    reflectivity * reflectionGain * (1.0 - foam * 0.8),\n    opacity\n  );\n  // With SRC_ALPHA blending, mixing by Fresnel directly would multiply the\n  // reflection by opacity again. Divide it out here so the framebuffer gets\n  // the intended reflected fraction while the remainder stays transmissive.\n  float reflectionWeight = reflectedRadiance / max(opacity, 0.001);\n  col = mix(col, reflected, reflectionWeight);\n\n  /*\n   * Dissolve the sheet at its own boundary.\n   *\n   * Fading on fog alone made the horizon a function of the daily palette: a\n   * clear day never reached the threshold, so the grid's rim \u2014 corner and all \u2014\n   * became the skyline. Fading on the grid coordinate cannot fail that way,\n   * because alpha reaches zero at the last row of vertices by construction.\n   * Chebyshev distance because the sheet is a rectangle, so the fade band\n   * follows its four edges instead of cutting an ellipse out of it \u2014 and it is\n   * measured per axis, or a channel's narrow sides would be one continuous fade\n   * and it would have no visible edge at all.\n   */\n  vec2 rimFraction = abs(vGrid) / max(uGridHalf, vec2(0.001));\n  float rimT = max(rimFraction.x, rimFraction.y);\n  float rim = 1.0 - smoothstep(0.9, 1.0, rimT);\n  // Fog still helps where it is thick, it just is no longer load-bearing.\n  float edge = 1.0 - smoothstep(0.82, 1.0, fog);\n  outColor = vec4(col, opacity * edge * rim * uVisibility);\n}\n";

package/dist/render/ssrPass.d.ts

@@ -1,5 +1,6 @@
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { ReflectionQueue } from './screenSpaceReflection.ts';
+import type { ResolvedFrameReflections } from './frameReflections.ts';
 /**
  * Screen-space reflection on WebGL2: a scissored trace per surface, then one composite.
  *
@@ -33,6 +34,9 @@ export declare class SsrPass {
     private width;
     private height;
     /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per surface. */
+    /** The frame's materials' resolve, compiled the first time a frame traces them. */
+    private materialResolve;
+    private materialUniforms;
     private readonly depthToWorld;
     private readonly scissor;
     constructor(gl: WebGL2RenderingContext, 
@@ -54,6 +58,18 @@ export declare class SsrPass {
      */
     traceReflections(queue: ReflectionQueue, scene: WebGLTexture, depth: WebGLTexture, viewProjection: ReadonlyMat4, eye: ArrayLike<number>, width: number, height: number, edgeFade: number): void;
     /** Composite what the trace found over whatever framebuffer is bound. */
+    /**
+     * Every pixel the lit stage left a reflection for, marched against the frame's depth by the
+     * trace's material mode, into this pass's own target; `resolveMaterials` then swaps the probe's
+     * share for it. See `frameReflections.ts`. Ends on the default framebuffer, as the surfaces' does.
+     */
+    traceMaterials(scene: WebGLTexture, depth: WebGLTexture, probe: WebGLTexture, tint: WebGLTexture, viewProjection: ReadonlyMat4, eye: ArrayLike<number>, width: number, height: number, edgeFade: number, reflections: ResolvedFrameReflections): void;
+    /**
+     * The probe's share of each pixel swapped for what `traceMaterials` found, blurred by the
+     * surface's roughness, added onto whatever framebuffer is bound — the scene's, with the two maps
+     * already detached from it. See `SSR_MATERIAL_RESOLVE_FRAG`.
+     */
+    resolveMaterials(probe: WebGLTexture, tint: WebGLTexture, width: number, height: number, reflections: ResolvedFrameReflections): void;
     resolveReflections(): void;
     dispose(): void;
 }

package/dist/render/ssrPass.js

@@ -3,7 +3,7 @@ import { decalScissor } from './decalProjector.js';
 import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
-import { SSR_RESOLVE_FRAG } from './shaders/ssrResolve.js';
+import { SSR_MATERIAL_RESOLVE_FRAG, SSR_RESOLVE_FRAG } from './shaders/ssrResolve.js';
 import { SSR_TRACE_FRAG } from './shaders/ssrTrace.js';
 import { blendKeeping } from './sceneCoverage.js';
 /**
@@ -32,6 +32,9 @@ export class SsrPass {
     width = 0;
     height = 0;
     /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per surface. */
+    /** The frame's materials' resolve, compiled the first time a frame traces them. */
+    materialResolve = null;
+    materialUniforms = {};
     depthToWorld = new Float32Array(16);
     scissor = new Int32Array(4);
     constructor(gl, 
@@ -118,6 +121,11 @@ export class SsrPass {
         gl.activeTexture(gl.TEXTURE1);
         gl.bindTexture(gl.TEXTURE_2D, scene);
         gl.uniform1i(u['uSsrScene'] ?? null, 1);
+        /* The materials' maps unread in this mode, and pointed at a bound texture all the same: a
+           driver may fetch a sampler's descriptor before the branch that skips it. */
+        gl.uniform1i(u['uSsrProbeMap'] ?? null, 0);
+        gl.uniform1i(u['uSsrTintMap'] ?? null, 0);
+        gl.uniform1f(u['uSsrMaterial'] ?? null, 0);
         gl.uniformMatrix4fv(u['uSsrDepthToWorld'] ?? null, false, this.depthToWorld);
         /* No Y flip on this backend: `gl.scissor` and the framebuffer both count rows from the bottom,
            which is the space the raw matrix already emits. See `CLIP_Y_FLIP`. */
@@ -153,6 +161,100 @@ export class SsrPass {
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     }
     /** Composite what the trace found over whatever framebuffer is bound. */
+    /**
+     * Every pixel the lit stage left a reflection for, marched against the frame's depth by the
+     * trace's material mode, into this pass's own target; `resolveMaterials` then swaps the probe's
+     * share for it. See `frameReflections.ts`. Ends on the default framebuffer, as the surfaces' does.
+     */
+    traceMaterials(scene, depth, probe, tint, viewProjection, eye, width, height, edgeFade, reflections) {
+        const { gl } = this;
+        const u = this.traceUniforms;
+        this.ensureSize(width, height);
+        mat4.invert(this.depthToWorld, viewProjection);
+        mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.viewport(0, 0, width, height);
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.disable(gl.SCISSOR_TEST);
+        gl.disable(gl.BLEND);
+        gl.clearBufferfv(gl.COLOR, 0, [0, 0, 0, 0]);
+        gl.useProgram(this.trace);
+        gl.bindVertexArray(this.vao);
+        const textures = [depth, scene, probe, tint];
+        const names = ['uSsrDepth', 'uSsrScene', 'uSsrProbeMap', 'uSsrTintMap'];
+        for (let unit = 0; unit < 4; unit++) {
+            gl.activeTexture(gl.TEXTURE0 + unit);
+            gl.bindTexture(gl.TEXTURE_2D, textures[unit] ?? null);
+            gl.uniform1i(u[names[unit] ?? ''] ?? null, unit);
+        }
+        gl.uniformMatrix4fv(u['uSsrDepthToWorld'] ?? null, false, this.depthToWorld);
+        gl.uniformMatrix4fv(u['uSsrViewProj'] ?? null, false, viewProjection);
+        gl.uniform3f(u['uSsrEye'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
+        gl.uniform1f(u['uSsrEdgeFade'] ?? null, edgeFade);
+        gl.uniform3f(u['uSsrAxis'] ?? null, 0, 0, 0);
+        gl.uniform3f(u['uSsrTint'] ?? null, 1, 1, 1);
+        gl.uniform1f(u['uSsrStrength'] ?? null, 1);
+        gl.uniform2f(u['uSsrFresnel'] ?? null, 0, 0);
+        gl.uniform1f(u['uSsrFacingCos'] ?? null, -1);
+        gl.uniform1f(u['uSsrReach'] ?? null, reflections.reachM);
+        gl.uniform1f(u['uSsrThickness'] ?? null, reflections.thicknessM);
+        gl.uniform1f(u['uSsrSteps'] ?? null, reflections.steps);
+        gl.uniform1f(u['uSsrMaterial'] ?? null, 1);
+        gl.uniform1f(u['uSsrMaxRoughness'] ?? null, reflections.maxRoughness);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        /* Back to the surfaces' mode, which every other trace in the frame is. */
+        gl.uniform1f(u['uSsrMaterial'] ?? null, 0);
+        gl.bindVertexArray(null);
+        for (let unit = 3; unit >= 0; unit--) {
+            gl.activeTexture(gl.TEXTURE0 + unit);
+            gl.bindTexture(gl.TEXTURE_2D, null);
+        }
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    }
+    /**
+     * The probe's share of each pixel swapped for what `traceMaterials` found, blurred by the
+     * surface's roughness, added onto whatever framebuffer is bound — the scene's, with the two maps
+     * already detached from it. See `SSR_MATERIAL_RESOLVE_FRAG`.
+     */
+    resolveMaterials(probe, tint, width, height, reflections) {
+        const { gl } = this;
+        if (this.reflection === null)
+            return;
+        if (this.materialResolve === null) {
+            this.materialResolve = compileProgram(gl, FULLSCREEN_VERT, SSR_MATERIAL_RESOLVE_FRAG, 'ssrMaterialResolve');
+            this.materialUniforms = uniformLocations(gl, this.materialResolve, 'ssrMaterialResolve');
+        }
+        const u = this.materialUniforms;
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.enable(gl.BLEND);
+        /* Added, a negative addend subtracting, and the scene's alpha kept. */
+        blendKeeping(gl, gl.ONE, gl.ONE);
+        gl.useProgram(this.materialResolve);
+        const textures = [this.reflection, probe, tint];
+        const names = ['uSsrReflection', 'uSsrProbeMap', 'uSsrTintMap'];
+        for (let unit = 0; unit < 3; unit++) {
+            gl.activeTexture(gl.TEXTURE0 + unit);
+            gl.bindTexture(gl.TEXTURE_2D, textures[unit] ?? null);
+            gl.uniform1i(u[names[unit] ?? ''] ?? null, unit);
+        }
+        gl.uniform3f(u['uSsrBlur'] ?? null, 1 / Math.max(width, 1), 1 / Math.max(height, 1), reflections.blur * height);
+        gl.bindVertexArray(this.vao);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.bindVertexArray(null);
+        for (let unit = 2; unit >= 0; unit--) {
+            gl.activeTexture(gl.TEXTURE0 + unit);
+            gl.bindTexture(gl.TEXTURE_2D, null);
+        }
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+    }
     resolveReflections() {
         const { gl } = this;
         if (this.reflection === null)
@@ -189,6 +291,9 @@ export class SsrPass {
             gl.deleteFramebuffer(this.framebuffer);
         gl.deleteProgram(this.trace);
         gl.deleteProgram(this.resolve);
+        if (this.materialResolve !== null)
+            gl.deleteProgram(this.materialResolve);
+        this.materialResolve = null;
         gl.deleteVertexArray(this.vao);
         this.reflection = null;
         this.framebuffer = null;

package/dist/render/staticDraws.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Draws that do not change between frames, captured once from an enumeration and replayed into any
+ * colour pass: what `createStaticDraws` keeps, and the one rule both backends replay it by.
+ *
+ * **Captured, not referenced.** An enumeration is a closure over the caller's state, written to
+ * allocate nothing, so it hands a sink its scratch: the matrix it fills for every entry and the
+ * count it rewrites for the next batch. A list kept across frames copies both when it is made, so
+ * what it draws is what the enumeration said then. Meshes, batches and materials are held by
+ * reference: they are the caller's, and disposing one a list still holds is the caller's error.
+ *
+ * **Rigid meshes and instanced batches only.** A skinned mesh is posed every frame and a scatter
+ * batch bends with every frame's wind, so neither can be kept, and both are refused by name rather
+ * than captured in the pose they happened to have. A caller draws them each frame as it always has.
+ *
+ * What a backend does with the list is its own: WebGL2 replays the entries every frame through
+ * the scene-caster path, and WebGPU records them once into a render bundle per view. See
+ * `RendererApi.createStaticDraws` for what a caller is promised, which is the same on both.
+ */
+import type { InstancedHandle, MeshHandle } from './backend/api.ts';
+import type { MeshInstances } from './instances.ts';
+import type { SceneCasterMaterial, ShadowCasterSink, ShadowCasters } from './shadowCasters.ts';
+/** A list from `createStaticDraws`. Opaque but for its size. */
+export interface StaticDrawsHandle {
+    /** How many entries it holds: meshes and batches, a batch counting once. */
+    readonly draws: number;
+}
+/** One captured entry. */
+export type StaticEntry = {
+    readonly kind: 'mesh';
+    readonly mesh: MeshHandle;
+    readonly model: Float32Array;
+    readonly material: SceneCasterMaterial;
+} | {
+    readonly kind: 'instanced';
+    readonly batch: InstancedHandle;
+    readonly data: MeshInstances;
+    readonly material: SceneCasterMaterial;
+};
+/** What both backends hold: the entries, and whether the list has been disposed. */
+export interface StaticDrawsList extends StaticDrawsHandle {
+    readonly entries: readonly StaticEntry[];
+    disposed: boolean;
+}
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export declare function captureStaticDraws(casters: ShadowCasters): StaticDrawsList;
+/** Hand every entry to `sink`, in the order it was captured. */
+export declare function replayStaticDraws(list: StaticDrawsList, sink: ShadowCasterSink): void;

package/dist/render/staticDraws.js

@@ -0,0 +1,43 @@
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export function captureStaticDraws(casters) {
+    const entries = [];
+    const sink = {
+        mesh: (mesh, model, material) => {
+            entries.push({
+                kind: 'mesh',
+                mesh,
+                model: new Float32Array(model),
+                material: material ?? null,
+            });
+        },
+        instanced: (batch, data, material) => {
+            /* The batch's placements are on the device already; the count is the caller's scratch. */
+            entries.push({ kind: 'instanced', batch, data: { ...data }, material: material ?? null });
+        },
+        skinnedMesh: () => {
+            throw new Error('createStaticDraws: a skinned mesh is posed every frame, so a list kept across frames ' +
+                'cannot hold one. Draw it each frame, with drawMesh or drawSceneCasters.');
+        },
+        scatter: () => {
+            throw new Error('createStaticDraws: a scatter batch bends with every frame’s wind, so a list kept across ' +
+                'frames cannot hold one. Draw it each frame with drawScatter.');
+        },
+    };
+    casters(sink);
+    return {
+        entries,
+        get draws() {
+            return entries.length;
+        },
+        disposed: false,
+    };
+}
+/** Hand every entry to `sink`, in the order it was captured. */
+export function replayStaticDraws(list, sink) {
+    for (const entry of list.entries) {
+        if (entry.kind === 'mesh')
+            sink.mesh(entry.mesh, entry.model, entry.material);
+        else
+            sink.instanced?.(entry.batch, entry.data, entry.material);
+    }
+}

package/dist/render/surfaceOverlay.d.ts

@@ -0,0 +1,132 @@
+/**
+ * What a draw lays over its surface beyond its material: a rim of light, an emissive overlay that
+ * dissolves the surface away, and a second normal map blended in by region. Set per draw with
+ * `RendererApi.setSurfaceOverlay`, so one character's whole set of materials changes together
+ * while another's does not.
+ *
+ * **Per draw and held, like `setEnvironmentGain`**: set before a character's draws, cleared after,
+ * and every draw between them wears it. **Images come from one atlas** (`maps`), each named by the
+ * rectangle it occupies — a scale and an offset in the atlas's uv — because the lit stage binds every
+ * sampler a device is guaranteed and has none left for a texture of its own: the atlas is bound in
+ * the slot the frame's refraction copy takes, which an opaque surface never reads. A draw that both
+ * refracts and wears an overlay's images keeps its refraction and loses the images, said once.
+ *
+ * **Fifteen vectors of numbers**, in the material's uniform block. WebGPU has the room; WebGL2 has
+ * room where its device reports more than the lit stage's 254 vectors, and refuses the overlay in
+ * words where it does not. See `packSurfaceOverlay` for the layout.
+ */
+import type { Vec3 } from '../math/color.ts';
+import type { SurfaceTextureHandle } from './backend/api.ts';
+/** Where an image sits in the atlas: its size and its corner, each in the atlas's uv. */
+export interface OverlayRegion {
+    readonly scale: readonly [number, number];
+    readonly offset: readonly [number, number];
+}
+/**
+ * Light along the silhouette: the edge `(1 - N·V)^falloff`, leaning toward normals that face up,
+ * raised to a contrast, times a noise laid in screen space, a slow pulse and a mask, in a colour.
+ * Added to what the surface emits, and not gated on the night as emission is: it is a glow the
+ * surface wears, not light it gives off.
+ */
+export interface SurfaceRim {
+    readonly colour: Vec3;
+    /** How bright, 0 for none. Multiplied with `alpha`. */
+    readonly intensity: number;
+    readonly alpha?: number;
+    /** The edge's exponent: larger keeps the rim nearer the silhouette. 1.5 unless given. */
+    readonly falloff?: number;
+    /**
+     * How far the rim leans toward normals that face up: the weight is `(N·up · ½ + ½)^upward`, so
+     * 0 is no lean. 0.4 unless given.
+     */
+    readonly upward?: number;
+    /** The exponent the whole edge is raised to. 1 unless given. */
+    readonly contrast?: number;
+    /** A noise image laid in screen space and scrolled, the rim taken times it, clamped to 1. */
+    readonly noise?: {
+        readonly region: OverlayRegion;
+        /** Screens a second, along x and y. */
+        readonly scroll?: readonly [number, number];
+        /** Repeats across the screen's height. 1 unless given. */
+        readonly tiling?: number;
+    };
+    /** A pulse `½ + ½ sin(rate · t)`, held between `low` and `high`, on `Environment.surfaceTime`. */
+    readonly pulse?: {
+        readonly rate: number;
+        readonly low: number;
+        readonly high: number;
+    };
+    /** A mask in the mesh's uv where the rim is erased: the rim times `1 - weight · mask`. */
+    readonly mask?: {
+        readonly region: OverlayRegion;
+        readonly weight: number;
+    };
+}
+/**
+ * The surface cut away where a noise in its uv falls under `threshold`, with a glowing band just
+ * above it, and a colour laid over the surface through the same noise.
+ */
+export interface SurfaceDissolve {
+    readonly noise: {
+        readonly region: OverlayRegion;
+        readonly tiling?: readonly [number, number];
+    };
+    /** 0 keeps everything; 1 cuts everything. */
+    readonly threshold: number;
+    /** The band's width, in the noise's own units. 0.05 unless given. */
+    readonly edge?: number;
+    /** The band's light. */
+    readonly edgeColour?: Vec3;
+    readonly edgeIntensity?: number;
+    /** A colour laid over the surface through the noise, as light, and how much of it. */
+    readonly overlay?: {
+        readonly colour: Vec3;
+        readonly amount: number;
+    };
+}
+/**
+ * A second normal map blended into the surface's by six region weights, read through two masks:
+ * the first mask's red, green and blue carry regions 1 to 3, the second's regions 4 to 6. A face's
+ * expressions, or veins brought up all over.
+ */
+export interface SurfaceWrinkle {
+    readonly normal: OverlayRegion;
+    readonly masks: readonly [OverlayRegion, OverlayRegion];
+    readonly weights: readonly [number, number, number, number, number, number];
+}
+/**
+ * What a draw lays over its surface beyond its material, for `setSurfaceOverlay`: a rim, a dissolve
+ * and wrinkles, each optional, and the atlas their images are regions of.
+ */
+export interface SurfaceOverlay {
+    /**
+     * The atlas every image above is a region of. Absent: no image is read whatever regions are
+     * named — rims are smooth, nothing dissolves and nothing wrinkles — because the slot then holds a
+     * stand-in whose colour would read as a noise and a mask.
+     */
+    readonly maps?: SurfaceTextureHandle;
+    readonly rim?: SurfaceRim;
+    readonly dissolve?: SurfaceDissolve;
+    readonly wrinkle?: SurfaceWrinkle;
+}
+/** Vectors the overlay takes in the material's block: `uOverlay[OVERLAY_VECTORS]`. */
+export declare const OVERLAY_VECTORS = 15;
+/** Floats `packSurfaceOverlay` fills. */
+export declare const OVERLAY_FLOATS: number;
+/**
+ * An overlay as the shader reads it, into `out` (`OVERLAY_FLOATS`); all zeros for `null`, which is
+ * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
+ * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
+ *
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 1: falloff, upward lean, contrast, mask weight
+ * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
+ * - 4: the pulse's low and high (1 and 1 where none)
+ * - 5: the rim's mask region
+ * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
+ * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
+ * - 10: the wrinkle normal's region; 11 and 12: the two masks'; 13 and 14: the six weights
+ */
+export declare function packSurfaceOverlay(overlay: SurfaceOverlay | null, out: Float32Array): void;
+/** Whether an overlay lays anything at all, so a renderer can leave the lit switch off. */
+export declare function overlayLays(overlay: SurfaceOverlay | null): boolean;

package/dist/render/surfaceOverlay.js

@@ -0,0 +1,85 @@
+/** Vectors the overlay takes in the material's block: `uOverlay[OVERLAY_VECTORS]`. */
+export const OVERLAY_VECTORS = 15;
+/** Floats `packSurfaceOverlay` fills. */
+export const OVERLAY_FLOATS = OVERLAY_VECTORS * 4;
+const finite = (value, fallback) => value !== undefined && Number.isFinite(value) ? value : fallback;
+function region(out, at, r) {
+    out[at] = finite(r?.scale[0], 0);
+    out[at + 1] = finite(r?.scale[1], 0);
+    out[at + 2] = finite(r?.offset[0], 0);
+    out[at + 3] = finite(r?.offset[1], 0);
+}
+/**
+ * An overlay as the shader reads it, into `out` (`OVERLAY_FLOATS`); all zeros for `null`, which is
+ * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
+ * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
+ *
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 1: falloff, upward lean, contrast, mask weight
+ * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
+ * - 4: the pulse's low and high (1 and 1 where none)
+ * - 5: the rim's mask region
+ * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
+ * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
+ * - 10: the wrinkle normal's region; 11 and 12: the two masks'; 13 and 14: the six weights
+ */
+export function packSurfaceOverlay(overlay, out) {
+    out.fill(0);
+    if (overlay === null)
+        return;
+    /* No atlas, no region: see `SurfaceOverlay.maps`. */
+    const images = overlay.maps !== undefined;
+    const rim = overlay.rim;
+    if (rim !== undefined) {
+        out[0] = finite(rim.colour[0], 0);
+        out[1] = finite(rim.colour[1], 0);
+        out[2] = finite(rim.colour[2], 0);
+        out[3] = Math.max(0, finite(rim.intensity, 0) * finite(rim.alpha, 1));
+        out[4] = Math.max(0, finite(rim.falloff, 1.5));
+        out[5] = Math.max(0, finite(rim.upward, 0.4));
+        out[6] = Math.max(0, finite(rim.contrast, 1));
+        out[7] = rim.mask === undefined ? 0 : Math.min(Math.max(finite(rim.mask.weight, 0), 0), 1);
+        region(out, 8, images ? rim.noise?.region : null);
+        out[12] = finite(rim.noise?.scroll?.[0], 0);
+        out[13] = finite(rim.noise?.scroll?.[1], 0);
+        out[14] = Math.max(0, finite(rim.noise?.tiling, 1));
+        out[15] = finite(rim.pulse?.rate, 0);
+        out[16] = rim.pulse === undefined ? 1 : finite(rim.pulse.low, 1);
+        out[17] = rim.pulse === undefined ? 1 : finite(rim.pulse.high, 1);
+        region(out, 20, images ? rim.mask?.region : null);
+    }
+    const dissolve = overlay.dissolve;
+    if (dissolve !== undefined) {
+        region(out, 24, images ? dissolve.noise.region : null);
+        out[28] = finite(dissolve.noise.tiling?.[0], 1);
+        out[29] = finite(dissolve.noise.tiling?.[1], 1);
+        out[30] = Math.min(Math.max(finite(dissolve.threshold, 0), 0), 1);
+        out[31] = Math.max(1e-4, finite(dissolve.edge, 0.05));
+        const edge = dissolve.edgeColour ?? [0, 0, 0];
+        out[32] = finite(edge[0], 0);
+        out[33] = finite(edge[1], 0);
+        out[34] = finite(edge[2], 0);
+        out[35] = Math.max(0, finite(dissolve.edgeIntensity, 1));
+        const laid = dissolve.overlay;
+        if (laid !== undefined) {
+            out[36] = finite(laid.colour[0], 0);
+            out[37] = finite(laid.colour[1], 0);
+            out[38] = finite(laid.colour[2], 0);
+            out[39] = Math.max(0, finite(laid.amount, 0));
+        }
+    }
+    const wrinkle = overlay.wrinkle;
+    if (wrinkle !== undefined) {
+        region(out, 40, images ? wrinkle.normal : null);
+        region(out, 44, images ? wrinkle.masks[0] : null);
+        region(out, 48, images ? wrinkle.masks[1] : null);
+        for (let i = 0; i < 6; i++) {
+            out[52 + i] = Math.min(Math.max(finite(wrinkle.weights[i], 0), 0), 1);
+        }
+    }
+}
+/** Whether an overlay lays anything at all, so a renderer can leave the lit switch off. */
+export function overlayLays(overlay) {
+    return (overlay !== null &&
+        (overlay.rim !== undefined || overlay.dissolve !== undefined || overlay.wrinkle !== undefined));
+}