@driftengine/core 3.61.0

package/dist/render/shaders/line.js

@@ -0,0 +1,122 @@
+import { FOG_GLSL } from './fog.js';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.js';
+/**
+ * A polyline: a flat colour with a clean edge, a real width, and fog.
+ *
+ * **The plain sibling of `bolt.ts`, and they share a vertex expansion for a reason.** Both
+ * turn a segment into a quad that faces the viewer, because a filament has no thickness to
+ * see around and a world-fixed cross would make half the segments vanish edge-on. What they
+ * do not share is everything after that: an arc is light arriving, so it is additive,
+ * unlit, unfogged and allowed past white; a line is a thing in the world, so it is alpha
+ * blended, fogged, and its edge is a clean one.
+ *
+ * **This exists because there is no portable wide line.** WebGL2's `lineWidth` is clamped to
+ * one pixel by nearly every driver, and WebGPU has no line width at all. A one-pixel
+ * hairline is also the wrong answer on a high-density display, where it reads as a scratch
+ * rather than as a stroke. So the only line worth having is a triangle, which is what this
+ * draws.
+ */
+export const LINE_VERT = `#version 300 es
+layout(location = 0) in vec3 aFrom;
+layout(location = 1) in vec3 aTo;
+/** Along the segment (0 or 1), and which side of it (-1 or +1). */
+layout(location = 2) in vec2 aCorner;
+
+uniform mat4 uViewProj;
+uniform mat4 uModel;
+uniform vec3 uCameraPos;
+/** Half-width in metres, and how much of a pixel a far line must still cover. */
+uniform float uWidth;
+uniform float uMinWidthPerMetre;
+
+out float vSide;
+out vec3 vWorldPos;
+
+void main() {
+  /*
+   * Through the model matrix before anything else, unlike an arc, whose endpoints are
+   * world-space by nature. A line is usually attached to something that moves, and the
+   * alternative is making every caller transform its own points on the CPU each frame.
+   *
+   * The width is deliberately *not* scaled by the model. A stroke's weight is a property
+   * of how it is drawn rather than of the geometry it follows, so a card that shrinks
+   * keeps the same line weight, which is what a reader expects and what a designer means.
+   */
+  vec3 from = (uModel * vec4(aFrom, 1.0)).xyz;
+  vec3 to = (uModel * vec4(aTo, 1.0)).xyz;
+
+  vec3 mid = mix(from, to, aCorner.x);
+  vec3 dir = to - from;
+  float len = length(dir);
+  dir = len > 1e-6 ? dir / len : vec3(0.0, 1.0, 0.0);
+
+  vec3 view = mid - uCameraPos;
+  float dist = length(view);
+  view = dist > 1e-6 ? view / dist : vec3(0.0, 0.0, 1.0);
+
+  /*
+   * Across the segment and across the line of sight. Degenerate exactly when the segment
+   * points at the viewer, where any perpendicular is as good as another, and where the
+   * segment covers almost no screen anyway.
+   */
+  vec3 across = cross(dir, view);
+  float span = length(across);
+  across = span > 1e-4 ? across / span : normalize(cross(dir, vec3(0.0, 1.0, 0.0)) + vec3(1e-3));
+
+  /*
+   * A floor on the world-space width that grows with distance, so a stroke never thins
+   * below a pixel. Under a pixel a thin line does not get fainter, it *flickers*, because
+   * the rasteriser catches it on some frames and not others.
+   */
+  float halfWidth = max(uWidth, dist * uMinWidthPerMetre);
+  vec3 world = mid + across * aCorner.y * halfWidth;
+
+  vSide = aCorner.y;
+  vWorldPos = world;
+  gl_Position = uViewProj * vec4(world, 1.0);
+}
+`;
+export const LINE_FRAG = `#version 300 es
+precision highp float;
+
+in float vSide;
+in vec3 vWorldPos;
+
+uniform vec3 uColor;
+uniform float uOpacity;
+uniform vec3 uCameraPos;
+/**
+ * How far in from the edge the stroke fades, as a fraction of its half-width. Zero is a
+ * clean edge, one is a stroke that is soft all the way to its middle.
+ */
+uniform float uSoftness;
+
+${FOG_GLSL}
+
+out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
+
+void main() {
+  /*
+   * Coverage across the ribbon: one down the middle, falling to zero at both edges.
+   *
+   * The band is at least one pixel wide *in screen space*, which is what lets one shader
+   * draw a stroke of any width at any distance without either aliasing into a staircase or
+   * blurring into a smear. A constant band is tuned for one width and is wrong at the rest,
+   * which is the same argument \`SDF_TEXT_FRAG\` makes for the same reason.
+   */
+  float edge = 1.0 - abs(vSide);
+  float band = max(fwidth(vSide), uSoftness);
+  float coverage = smoothstep(0.0, band, edge);
+
+  /*
+   * Fogged like geometry, which is where this parts company with \`bolt.ts\`. That shader
+   * includes the same helpers and never calls them, because an arc is light arriving
+   * rather than a surface losing some of itself to the air on the way over. A drawn line
+   * is a thing in the world and recedes like one.
+   */
+  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+  vec3 color = mix(uColor, mediumColor(), fog);
+  outColor = vec4(applyOutputTransform(color), coverage * uOpacity);
+}
+`;

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

@@ -0,0 +1,26 @@
+/**
+ * The vertex-stage morph prelude: the delta texture, the weights, and their weighted sum.
+ *
+ * Included by `flat/index.ts` inside `#if MORPHED`, so `resolveConditionals` cuts every line out of
+ * the variants that do not morph. **The same mechanism the joint palette established**, and that
+ * is why this row was affordable: eleven attribute locations were already spoken for and glTF
+ * morph wants up to twenty-four more, so an attribute per target was never going to fit. A vertex
+ * data texture has no such budget.
+ *
+ * Measured, which is what §3.2 of the plan asks for: the second vertex flag takes the shader from
+ * two variants to four for **1,674 gzipped bytes**, against 246,925 for one more *fragment* flag.
+ * The worry that four diverging variants would dedupe far worse than two was wrong — they cost
+ * about half again as much, not an order of magnitude.
+ *
+ * **Both pre-build estimates came in low, and by a similar factor.** The first flag was estimated
+ * at 357 and cost 1,118; this one was estimated at 230 and cost 1,674. Both estimates were made by
+ * splicing hand-written WGSL into a duplicated variant, which does not model what naga emits — its
+ * temporaries, its entry-point parameters, and the uniform block that grows with the flag. Simulate
+ * a permutation to learn its *order of magnitude* and regenerate to learn its cost.
+ *
+ * **Positions only.** A morph target that also moved normals would need a second delta set and a
+ * second fetch per target; what this gives up is correct shading on a strongly morphed surface,
+ * which shows as lighting that lags the shape. What would make it wrong is a face rig, where it
+ * would be the whole point — the fix is a second texture, not a different mechanism.
+ */
+export declare const MORPH_GLSL = "\n/**\n * Every target's delta for every vertex, interleaved by vertex.\n *\n * A vertex's targets are adjacent because the shader reads all of them for one vertex and nothing\n * reads one target across many vertices \u2014 one cache line rather than `uMorphTargetCount` of them.\n * Wrapped onto rows, because a mesh times its targets passes WebGL2's guaranteed 2048 texels at\n * 256 vertices with eight targets, which is a small mesh.\n */\nuniform highp sampler2D uMorphDeltas;\nuniform float uMorphWeights[8];\nuniform int uMorphTargetCount;\n/** The texture's width, so the shader can turn a texel index into a row and a column. */\nuniform int uMorphTextureWidth;\n\n/**\n * The weighted sum of every active target's delta for this vertex.\n *\n * The loop bound is the compile-time maximum and the *break* is on the uniform, because GLSL ES\n * 3.00 requires a constant bound. A mesh with two targets still costs two iterations rather than\n * eight, which is the point of the break \u2014 and the branch is uniform across the draw, so nothing\n * here falls foul of the 2026-08-07 rule even before the observation that a vertex stage computes\n * no derivatives.\n */\nvec3 morphOffset() {\n  vec3 offset = vec3(0.0);\n  for (int t = 0; t < 8; t++) {\n    if (t >= uMorphTargetCount) break;\n    int texel = gl_VertexID * uMorphTargetCount + t;\n    ivec2 at = ivec2(texel % uMorphTextureWidth, texel / uMorphTextureWidth);\n    offset += texelFetch(uMorphDeltas, at, 0).xyz * uMorphWeights[t];\n  }\n  return offset;\n}\n";

package/dist/render/shaders/morph.js

@@ -0,0 +1,61 @@
+import { MAX_MORPH_TARGETS } from '../skinPalette.js';
+/**
+ * The vertex-stage morph prelude: the delta texture, the weights, and their weighted sum.
+ *
+ * Included by `flat/index.ts` inside `#if MORPHED`, so `resolveConditionals` cuts every line out of
+ * the variants that do not morph. **The same mechanism the joint palette established**, and that
+ * is why this row was affordable: eleven attribute locations were already spoken for and glTF
+ * morph wants up to twenty-four more, so an attribute per target was never going to fit. A vertex
+ * data texture has no such budget.
+ *
+ * Measured, which is what §3.2 of the plan asks for: the second vertex flag takes the shader from
+ * two variants to four for **1,674 gzipped bytes**, against 246,925 for one more *fragment* flag.
+ * The worry that four diverging variants would dedupe far worse than two was wrong — they cost
+ * about half again as much, not an order of magnitude.
+ *
+ * **Both pre-build estimates came in low, and by a similar factor.** The first flag was estimated
+ * at 357 and cost 1,118; this one was estimated at 230 and cost 1,674. Both estimates were made by
+ * splicing hand-written WGSL into a duplicated variant, which does not model what naga emits — its
+ * temporaries, its entry-point parameters, and the uniform block that grows with the flag. Simulate
+ * a permutation to learn its *order of magnitude* and regenerate to learn its cost.
+ *
+ * **Positions only.** A morph target that also moved normals would need a second delta set and a
+ * second fetch per target; what this gives up is correct shading on a strongly morphed surface,
+ * which shows as lighting that lags the shape. What would make it wrong is a face rig, where it
+ * would be the whole point — the fix is a second texture, not a different mechanism.
+ */
+export const MORPH_GLSL = `
+/**
+ * Every target's delta for every vertex, interleaved by vertex.
+ *
+ * A vertex's targets are adjacent because the shader reads all of them for one vertex and nothing
+ * reads one target across many vertices — one cache line rather than \`uMorphTargetCount\` of them.
+ * Wrapped onto rows, because a mesh times its targets passes WebGL2's guaranteed 2048 texels at
+ * 256 vertices with eight targets, which is a small mesh.
+ */
+uniform highp sampler2D uMorphDeltas;
+uniform float uMorphWeights[${MAX_MORPH_TARGETS}];
+uniform int uMorphTargetCount;
+/** The texture's width, so the shader can turn a texel index into a row and a column. */
+uniform int uMorphTextureWidth;
+
+/**
+ * The weighted sum of every active target's delta for this vertex.
+ *
+ * The loop bound is the compile-time maximum and the *break* is on the uniform, because GLSL ES
+ * 3.00 requires a constant bound. A mesh with two targets still costs two iterations rather than
+ * eight, which is the point of the break — and the branch is uniform across the draw, so nothing
+ * here falls foul of the 2026-08-07 rule even before the observation that a vertex stage computes
+ * no derivatives.
+ */
+vec3 morphOffset() {
+  vec3 offset = vec3(0.0);
+  for (int t = 0; t < ${MAX_MORPH_TARGETS}; t++) {
+    if (t >= uMorphTargetCount) break;
+    int texel = gl_VertexID * uMorphTargetCount + t;
+    ivec2 at = ivec2(texel % uMorphTextureWidth, texel / uMorphTextureWidth);
+    offset += texelFetch(uMorphDeltas, at, 0).xyz * uMorphWeights[t];
+  }
+  return offset;
+}
+`;

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

@@ -0,0 +1,76 @@
+import type { vec2, vec3 } from 'gl-matrix';
+/**
+ * Octahedral mapping: a direction to a point on the unit square, and back.
+ *
+ * **One projection over the whole sphere, which is the entire reason this exists.** A cube map
+ * stores six images rasterised under six separate 90 degree projections, and along a shared edge
+ * the two disagree by up to a texel of depth — so a filter tap that crosses the edge reads the
+ * other projection's answer, the comparison flips along that line, and the line draws as a
+ * straight ray from beneath the light. Seven separate reports pointed at those rays, and four
+ * attempts at widening the point-shadow filter failed against them. There is no second projection
+ * here for a tap to cross.
+ *
+ * **The algorithm is written twice, in two languages, and they must move together.** The GLSL is
+ * what runs, on both backends, since the WGSL is generated from it. The TypeScript exists so that
+ * a change to it has a test that needs no device, and `octahedral.test.ts` is that test. Nothing
+ * catches a divergence between the two, which is why they are in one file rather than one each.
+ */
+/**
+ * The chunk both the resolve pass and the lit pass include.
+ *
+ * **Not `sign()`, anywhere in here.** GLSL's `sign` returns 0 at 0, and a direction with an exact
+ * zero component is not a rarity in this engine — it is every axis-aligned wall in every scene it
+ * draws. `sign(0.0)` folds such a direction to the origin of the map, which reads as one light's
+ * shadow appearing on a surface it does not face. The ternaries below are that fix and are not
+ * style; a test asserts this text contains no `sign(` at all.
+ *
+ * **`octWrapUv` and the two inset helpers exist because a *filtered* octahedral map needs a
+ * gutter, and the point-shadow array never did.** That array is one storage level with `NEAREST`
+ * on both filters, so no tap ever crosses the map's outer border. A prefiltered environment is
+ * `LINEAR` with a mip chain, and there a tap does cross it — into whatever `CLAMP_TO_EDGE` last
+ * repeated, which is not the direction on the other side of the fold.
+ *
+ * The square's border is a fold rather than an edge: the point just past the right border at
+ * height `v` is the point just inside it at `1 - v`, and passing through a corner comes back in at
+ * the opposite corner, because all four corners are the same pole. Measured before it was written:
+ * a gutter texel filled by this rule matches the texel it is folded against to **3.3e-16**, and a
+ * border without one is wrong by **4.6e-2** in direction. The corner case is exact to 1.1e-16, and
+ * the direction gap across a corner falls linearly with the step, which is what a pole requires.
+ *
+ * `octInsetUv` and `octInsetDir` are the two ends of that: a sampler maps a direction into the
+ * inner `edge - 2` texels, and a generator asks which direction its own texel must hold — which in
+ * the gutter is a folded one. They are exact inverses on the interior.
+ */
+export declare const OCTAHEDRAL_GLSL = "vec2 octEncode(vec3 d) {\n  vec3 n = d / (abs(d.x) + abs(d.y) + abs(d.z));\n  vec2 p = n.z >= 0.0\n    ? n.xy\n    : (1.0 - abs(vec2(n.y, n.x))) * vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);\n  return p * 0.5 + 0.5;\n}\n\nvec3 octDecode(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  vec3 n = vec3(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));\n  float t = max(-n.z, 0.0);\n  n.x += n.x >= 0.0 ? -t : t;\n  n.y += n.y >= 0.0 ? -t : t;\n  return normalize(n);\n}\n\nvec2 octWrapUv(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  if (f.x < -1.0 || f.x > 1.0) {\n    f.x = (f.x > 0.0 ? 2.0 : -2.0) - f.x;\n    f.y = -f.y;\n  }\n  if (f.y < -1.0 || f.y > 1.0) {\n    f.y = (f.y > 0.0 ? 2.0 : -2.0) - f.y;\n    f.x = -f.x;\n  }\n  return f * 0.5 + 0.5;\n}\n\nvec2 octInsetUv(vec3 d, float edge) {\n  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;\n}\n\nvec3 octInsetDir(vec2 uv, float edge) {\n  return octDecode(octWrapUv((uv * edge - 1.0) / (edge - 2.0)));\n}";
+/**
+ * The GLSL above, in TypeScript, filling a target the caller owns.
+ *
+ * The direction need not be normalised: the L1 division below normalises it in the only sense this
+ * mapping cares about. Fills rather than returns a new vector because the callers that will exist
+ * are per-face rather than per-frame, and the rule is cheaper to keep than to reason about.
+ */
+export declare function octEncode(x: number, y: number, z: number, out: vec2): vec2;
+/**
+ * A point outside the unit square, folded back to the point of the sphere it names.
+ *
+ * The GLSL above, in TypeScript, and the identity inside the square — a texel that is not in the
+ * gutter must not move, or every map would be resampled by a function meant to touch its border.
+ */
+export declare function octWrapUv(u: number, v: number, out: vec2): vec2;
+/**
+ * Where to sample a direction in a map `edge` texels across whose outer ring is a gutter.
+ *
+ * The inner region is `edge - 2` texels, offset by one, so a direction at the very border of the
+ * octahedral square lands on the last real texel and the tap that interpolates past it reads the
+ * gutter — which `octInsetDir` filled with the folded direction.
+ */
+export declare function octInsetUv(x: number, y: number, z: number, edge: number, out: vec2): vec2;
+/**
+ * The direction one texel of such a map must hold, gutter included.
+ *
+ * The exact inverse of `octInsetUv` on the interior. In the gutter the un-inset coordinate falls
+ * outside the square and the fold answers it, which is the whole point.
+ */
+export declare function octInsetDir(u: number, v: number, edge: number, out: vec3): vec3;
+/** The exact inverse, filling a target the caller owns. Returns a unit vector. */
+export declare function octDecode(u: number, v: number, out: vec3): vec3;

package/dist/render/shaders/octahedral.js

@@ -0,0 +1,161 @@
+/**
+ * Octahedral mapping: a direction to a point on the unit square, and back.
+ *
+ * **One projection over the whole sphere, which is the entire reason this exists.** A cube map
+ * stores six images rasterised under six separate 90 degree projections, and along a shared edge
+ * the two disagree by up to a texel of depth — so a filter tap that crosses the edge reads the
+ * other projection's answer, the comparison flips along that line, and the line draws as a
+ * straight ray from beneath the light. Seven separate reports pointed at those rays, and four
+ * attempts at widening the point-shadow filter failed against them. There is no second projection
+ * here for a tap to cross.
+ *
+ * **The algorithm is written twice, in two languages, and they must move together.** The GLSL is
+ * what runs, on both backends, since the WGSL is generated from it. The TypeScript exists so that
+ * a change to it has a test that needs no device, and `octahedral.test.ts` is that test. Nothing
+ * catches a divergence between the two, which is why they are in one file rather than one each.
+ */
+/**
+ * The chunk both the resolve pass and the lit pass include.
+ *
+ * **Not `sign()`, anywhere in here.** GLSL's `sign` returns 0 at 0, and a direction with an exact
+ * zero component is not a rarity in this engine — it is every axis-aligned wall in every scene it
+ * draws. `sign(0.0)` folds such a direction to the origin of the map, which reads as one light's
+ * shadow appearing on a surface it does not face. The ternaries below are that fix and are not
+ * style; a test asserts this text contains no `sign(` at all.
+ *
+ * **`octWrapUv` and the two inset helpers exist because a *filtered* octahedral map needs a
+ * gutter, and the point-shadow array never did.** That array is one storage level with `NEAREST`
+ * on both filters, so no tap ever crosses the map's outer border. A prefiltered environment is
+ * `LINEAR` with a mip chain, and there a tap does cross it — into whatever `CLAMP_TO_EDGE` last
+ * repeated, which is not the direction on the other side of the fold.
+ *
+ * The square's border is a fold rather than an edge: the point just past the right border at
+ * height `v` is the point just inside it at `1 - v`, and passing through a corner comes back in at
+ * the opposite corner, because all four corners are the same pole. Measured before it was written:
+ * a gutter texel filled by this rule matches the texel it is folded against to **3.3e-16**, and a
+ * border without one is wrong by **4.6e-2** in direction. The corner case is exact to 1.1e-16, and
+ * the direction gap across a corner falls linearly with the step, which is what a pole requires.
+ *
+ * `octInsetUv` and `octInsetDir` are the two ends of that: a sampler maps a direction into the
+ * inner `edge - 2` texels, and a generator asks which direction its own texel must hold — which in
+ * the gutter is a folded one. They are exact inverses on the interior.
+ */
+export const OCTAHEDRAL_GLSL = `vec2 octEncode(vec3 d) {
+  vec3 n = d / (abs(d.x) + abs(d.y) + abs(d.z));
+  vec2 p = n.z >= 0.0
+    ? n.xy
+    : (1.0 - abs(vec2(n.y, n.x))) * vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);
+  return p * 0.5 + 0.5;
+}
+
+vec3 octDecode(vec2 uv) {
+  vec2 f = uv * 2.0 - 1.0;
+  vec3 n = vec3(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));
+  float t = max(-n.z, 0.0);
+  n.x += n.x >= 0.0 ? -t : t;
+  n.y += n.y >= 0.0 ? -t : t;
+  return normalize(n);
+}
+
+vec2 octWrapUv(vec2 uv) {
+  vec2 f = uv * 2.0 - 1.0;
+  if (f.x < -1.0 || f.x > 1.0) {
+    f.x = (f.x > 0.0 ? 2.0 : -2.0) - f.x;
+    f.y = -f.y;
+  }
+  if (f.y < -1.0 || f.y > 1.0) {
+    f.y = (f.y > 0.0 ? 2.0 : -2.0) - f.y;
+    f.x = -f.x;
+  }
+  return f * 0.5 + 0.5;
+}
+
+vec2 octInsetUv(vec3 d, float edge) {
+  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;
+}
+
+vec3 octInsetDir(vec2 uv, float edge) {
+  return octDecode(octWrapUv((uv * edge - 1.0) / (edge - 2.0)));
+}`;
+/**
+ * The GLSL above, in TypeScript, filling a target the caller owns.
+ *
+ * The direction need not be normalised: the L1 division below normalises it in the only sense this
+ * mapping cares about. Fills rather than returns a new vector because the callers that will exist
+ * are per-face rather than per-frame, and the rule is cheaper to keep than to reason about.
+ */
+export function octEncode(x, y, z, out) {
+    const l = Math.abs(x) + Math.abs(y) + Math.abs(z);
+    const nx = x / l;
+    const ny = y / l;
+    const nz = z / l;
+    let px = nx;
+    let py = ny;
+    if (nz < 0) {
+        px = (1 - Math.abs(ny)) * (nx >= 0 ? 1 : -1);
+        py = (1 - Math.abs(nx)) * (ny >= 0 ? 1 : -1);
+    }
+    out[0] = px * 0.5 + 0.5;
+    out[1] = py * 0.5 + 0.5;
+    return out;
+}
+/**
+ * A point outside the unit square, folded back to the point of the sphere it names.
+ *
+ * The GLSL above, in TypeScript, and the identity inside the square — a texel that is not in the
+ * gutter must not move, or every map would be resampled by a function meant to touch its border.
+ */
+export function octWrapUv(u, v, out) {
+    let fx = u * 2 - 1;
+    let fy = v * 2 - 1;
+    if (fx < -1 || fx > 1) {
+        fx = (fx > 0 ? 2 : -2) - fx;
+        fy = -fy;
+    }
+    if (fy < -1 || fy > 1) {
+        fy = (fy > 0 ? 2 : -2) - fy;
+        fx = -fx;
+    }
+    out[0] = fx * 0.5 + 0.5;
+    out[1] = fy * 0.5 + 0.5;
+    return out;
+}
+/**
+ * Where to sample a direction in a map `edge` texels across whose outer ring is a gutter.
+ *
+ * The inner region is `edge - 2` texels, offset by one, so a direction at the very border of the
+ * octahedral square lands on the last real texel and the tap that interpolates past it reads the
+ * gutter — which `octInsetDir` filled with the folded direction.
+ */
+export function octInsetUv(x, y, z, edge, out) {
+    octEncode(x, y, z, out);
+    out[0] = (out[0] * (edge - 2) + 1) / edge;
+    out[1] = (out[1] * (edge - 2) + 1) / edge;
+    return out;
+}
+/**
+ * The direction one texel of such a map must hold, gutter included.
+ *
+ * The exact inverse of `octInsetUv` on the interior. In the gutter the un-inset coordinate falls
+ * outside the square and the fold answers it, which is the whole point.
+ */
+export function octInsetDir(u, v, edge, out) {
+    const wrapped = octWrapUv((u * edge - 1) / (edge - 2), (v * edge - 1) / (edge - 2), insetScratch);
+    return octDecode(wrapped[0], wrapped[1], out);
+}
+/** Reused by `octInsetDir`, which the convolution calls once per texel of every level. */
+const insetScratch = [0, 0];
+/** The exact inverse, filling a target the caller owns. Returns a unit vector. */
+export function octDecode(u, v, out) {
+    const fx = u * 2 - 1;
+    const fy = v * 2 - 1;
+    const nz = 1 - Math.abs(fx) - Math.abs(fy);
+    const t = Math.max(-nz, 0);
+    const nx = fx + (fx >= 0 ? -t : t);
+    const ny = fy + (fy >= 0 ? -t : t);
+    const l = Math.hypot(nx, ny, nz);
+    out[0] = nx / l;
+    out[1] = ny / l;
+    out[2] = nz / l;
+    return out;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * A fullscreen triangle built from the vertex index, so the pass binds no buffer.
+ *
+ * Three vertices rather than a quad's six: a quad's diagonal is a seam every fragment on it is
+ * rasterised twice across, and this pass writes depth, so twice is not free.
+ */
+export declare const OCTAHEDRAL_RESOLVE_VERT = "#version 300 es\nvoid main() {\n  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}";
+/**
+ * One cube face into its region of an octahedral map, as linear radial distance.
+ *
+ * **Every octahedral texel has exactly one dominant axis, so the six regions are disjoint and
+ * together cover the map.** That is what makes one scratch texture enough for the whole engine
+ * rather than one cube per pool slot: a face is consumed the moment it is resolved, so a bake
+ * spread across frames — which is how bakes work here, a couple of faces at a time against
+ * `pointShadowBudget.ts` — never needs a second face to still exist.
+ *
+ * **The perspective decode happens here, once per texel, instead of twelve times per shaded
+ * fragment.** What lands in the layer is `radius / far`, linear, which at a far plane of 20 m
+ * quantises to about a micrometre in DEPTH_COMPONENT24 against a bias that starts at 4 cm. A cube
+ * spends most of its bits near the light instead, which is the wrong end for a shadow.
+ *
+ * The face index and the sampler are named apart on purpose: two uniforms called `uFace` is a
+ * redeclaration and GLSL rejects the whole shader.
+ */
+export declare const OCTAHEDRAL_RESOLVE_FRAG = "#version 300 es\nprecision highp float;\n\n/** The face the bake just rendered, as a depth texture. */\nuniform highp sampler2D uFace;\n/** That face's world-to-face rotation. See pointShadowFaceRotation. */\nuniform mat3 uFaceRotation;\n/** Which of the six this pass is resolving. Every other texel discards. */\nuniform int uFaceIndex;\nuniform float uFar;\nuniform float uNear;\n/** The octahedral map's edge, so this needs no viewport query. */\nuniform float uEdge;\n\nvec2 octEncode(vec3 d) {\n  vec3 n = d / (abs(d.x) + abs(d.y) + abs(d.z));\n  vec2 p = n.z >= 0.0\n    ? n.xy\n    : (1.0 - abs(vec2(n.y, n.x))) * vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);\n  return p * 0.5 + 0.5;\n}\n\nvec3 octDecode(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  vec3 n = vec3(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));\n  float t = max(-n.z, 0.0);\n  n.x += n.x >= 0.0 ? -t : t;\n  n.y += n.y >= 0.0 ? -t : t;\n  return normalize(n);\n}\n\nvec2 octWrapUv(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  if (f.x < -1.0 || f.x > 1.0) {\n    f.x = (f.x > 0.0 ? 2.0 : -2.0) - f.x;\n    f.y = -f.y;\n  }\n  if (f.y < -1.0 || f.y > 1.0) {\n    f.y = (f.y > 0.0 ? 2.0 : -2.0) - f.y;\n    f.x = -f.x;\n  }\n  return f * 0.5 + 0.5;\n}\n\nvec2 octInsetUv(vec3 d, float edge) {\n  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;\n}\n\nvec3 octInsetDir(vec2 uv, float edge) {\n  return octDecode(octWrapUv((uv * edge - 1.0) / (edge - 2.0)));\n}\n\nvoid main() {\n  vec3 d = octDecode(gl_FragCoord.xy / uEdge);\n\n  /*\n   * Which face owns this texel. The tie-breaking is x, then y, then z, and it has to match the\n   * CPU's exactly or a sliver of texels along a boundary belongs to two faces or to none.\n   */\n  vec3 a = abs(d);\n  int face;\n  if (a.x >= a.y && a.x >= a.z) face = d.x >= 0.0 ? 0 : 1;\n  else if (a.y >= a.z) face = d.y >= 0.0 ? 2 : 3;\n  else face = d.z >= 0.0 ? 4 : 5;\n  if (face != uFaceIndex) discard;\n\n  /* lookAt looks down -z, so a direction inside this face has a negative z here. */\n  vec3 v = uFaceRotation * d;\n  float forward = -v.z;\n  vec2 faceUv = (v.xy / forward) * 0.5 + 0.5;\n\n  /*\n   * textureLod at level zero rather than plain texture. The scratch carries one storage level and\n   * NEAREST filtering so the fetch is identical, and this call sits after a discard \u2014 which is\n   * non-uniform control flow, where an implicit derivative is undefined in GLSL and rejected\n   * outright in WGSL. AGENTS.md, 2026-08-07.\n   */\n  float stored = textureLod(uFace, faceUv, 0.0).r;\n  if (stored >= 0.9999) {\n    /* Nothing was rendered along this direction, so the stored radius is the far plane. */\n    gl_FragDepth = 1.0;\n    return;\n  }\n  float ndc = stored * 2.0 - 1.0;\n  float faceLocalZ = (2.0 * uFar * uNear) / (uFar + uNear - ndc * (uFar - uNear));\n  /* d is a unit vector, so forward is its cosine to the axis and this is the true radius. */\n  gl_FragDepth = clamp((faceLocalZ / forward) / uFar, 0.0, 1.0);\n}";

package/dist/render/shaders/octahedralResolve.js

@@ -0,0 +1,81 @@
+import { OCTAHEDRAL_GLSL } from './octahedral.js';
+/**
+ * A fullscreen triangle built from the vertex index, so the pass binds no buffer.
+ *
+ * Three vertices rather than a quad's six: a quad's diagonal is a seam every fragment on it is
+ * rasterised twice across, and this pass writes depth, so twice is not free.
+ */
+export const OCTAHEDRAL_RESOLVE_VERT = `#version 300 es
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}`;
+/**
+ * One cube face into its region of an octahedral map, as linear radial distance.
+ *
+ * **Every octahedral texel has exactly one dominant axis, so the six regions are disjoint and
+ * together cover the map.** That is what makes one scratch texture enough for the whole engine
+ * rather than one cube per pool slot: a face is consumed the moment it is resolved, so a bake
+ * spread across frames — which is how bakes work here, a couple of faces at a time against
+ * `pointShadowBudget.ts` — never needs a second face to still exist.
+ *
+ * **The perspective decode happens here, once per texel, instead of twelve times per shaded
+ * fragment.** What lands in the layer is `radius / far`, linear, which at a far plane of 20 m
+ * quantises to about a micrometre in DEPTH_COMPONENT24 against a bias that starts at 4 cm. A cube
+ * spends most of its bits near the light instead, which is the wrong end for a shadow.
+ *
+ * The face index and the sampler are named apart on purpose: two uniforms called `uFace` is a
+ * redeclaration and GLSL rejects the whole shader.
+ */
+export const OCTAHEDRAL_RESOLVE_FRAG = `#version 300 es
+precision highp float;
+
+/** The face the bake just rendered, as a depth texture. */
+uniform highp sampler2D uFace;
+/** That face's world-to-face rotation. See pointShadowFaceRotation. */
+uniform mat3 uFaceRotation;
+/** Which of the six this pass is resolving. Every other texel discards. */
+uniform int uFaceIndex;
+uniform float uFar;
+uniform float uNear;
+/** The octahedral map's edge, so this needs no viewport query. */
+uniform float uEdge;
+
+${OCTAHEDRAL_GLSL}
+
+void main() {
+  vec3 d = octDecode(gl_FragCoord.xy / uEdge);
+
+  /*
+   * Which face owns this texel. The tie-breaking is x, then y, then z, and it has to match the
+   * CPU's exactly or a sliver of texels along a boundary belongs to two faces or to none.
+   */
+  vec3 a = abs(d);
+  int face;
+  if (a.x >= a.y && a.x >= a.z) face = d.x >= 0.0 ? 0 : 1;
+  else if (a.y >= a.z) face = d.y >= 0.0 ? 2 : 3;
+  else face = d.z >= 0.0 ? 4 : 5;
+  if (face != uFaceIndex) discard;
+
+  /* lookAt looks down -z, so a direction inside this face has a negative z here. */
+  vec3 v = uFaceRotation * d;
+  float forward = -v.z;
+  vec2 faceUv = (v.xy / forward) * 0.5 + 0.5;
+
+  /*
+   * textureLod at level zero rather than plain texture. The scratch carries one storage level and
+   * NEAREST filtering so the fetch is identical, and this call sits after a discard — which is
+   * non-uniform control flow, where an implicit derivative is undefined in GLSL and rejected
+   * outright in WGSL. AGENTS.md, 2026-08-07.
+   */
+  float stored = textureLod(uFace, faceUv, 0.0).r;
+  if (stored >= 0.9999) {
+    /* Nothing was rendered along this direction, so the stored radius is the far plane. */
+    gl_FragDepth = 1.0;
+    return;
+  }
+  float ndc = stored * 2.0 - 1.0;
+  float faceLocalZ = (2.0 * uFar * uNear) / (uFar + uNear - ndc * (uFar - uNear));
+  /* d is a unit vector, so forward is its cosine to the axis and this is the true radius. */
+  gl_FragDepth = clamp((faceLocalZ / forward) / uFar, 0.0, 1.0);
+}`;

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

@@ -0,0 +1,17 @@
+/**
+ * The order-independent transparency resolve: two buffers composited over the finished scene.
+ *
+ * **The accumulation holds a weighted sum and the revealage a product.** Dividing the summed
+ * premultiplied colour by the summed weighted alpha gives the average colour the translucent
+ * layers make; the revealage says how much of what is behind them still shows through. For a
+ * single layer that reduces exactly to ordinary alpha blending, which is the anchor
+ * "orderIndependent.ts" asserts against numbers.
+ *
+ * **The composite is done by the blend state rather than by reading the scene.** Drawn with
+ * (ONE_MINUS_SRC_ALPHA, SRC_ALPHA) over the scene target, the hardware computes
+ * average * (1 - reveal) + scene * reveal, which is the resolve — so this pass never samples the
+ * colour it is compositing onto and cannot be caught reading a target it is also writing.
+ *
+ * The vertex stage is FULLSCREEN_VERT, shared with the occlusion pass, its blur and the rush.
+ */
+export declare const OIT_RESOLVE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\n\n/** Weighted premultiplied colour in rgb, weighted alpha in a. Cleared to zero. */\nuniform sampler2D uOitAccum;\n/** What every layer let through, as a product. Cleared to one, so an untouched pixel is all scene. */\nuniform sampler2D uOitReveal;\n\nout vec4 fragColor;\n\nvoid main() {\n  vec4 accum = textureLod(uOitAccum, vUv, 0.0);\n  float reveal = textureLod(uOitReveal, vUv, 0.0).r;\n\n  /*\n   * Guarded because a pixel no fragment touched has a weighted alpha of zero. Its revealage is\n   * then one, so the blend discards whatever this produced anyway \u2014 but a division by zero would\n   * put a NaN into the target first, and a NaN blended against anything stays a NaN.\n   */\n  vec3 average = accum.rgb / max(accum.a, 1e-5);\n\n  fragColor = vec4(average, reveal);\n}\n";

package/dist/render/shaders/oitResolve.js

@@ -0,0 +1,42 @@
+/**
+ * The order-independent transparency resolve: two buffers composited over the finished scene.
+ *
+ * **The accumulation holds a weighted sum and the revealage a product.** Dividing the summed
+ * premultiplied colour by the summed weighted alpha gives the average colour the translucent
+ * layers make; the revealage says how much of what is behind them still shows through. For a
+ * single layer that reduces exactly to ordinary alpha blending, which is the anchor
+ * "orderIndependent.ts" asserts against numbers.
+ *
+ * **The composite is done by the blend state rather than by reading the scene.** Drawn with
+ * (ONE_MINUS_SRC_ALPHA, SRC_ALPHA) over the scene target, the hardware computes
+ * average * (1 - reveal) + scene * reveal, which is the resolve — so this pass never samples the
+ * colour it is compositing onto and cannot be caught reading a target it is also writing.
+ *
+ * The vertex stage is FULLSCREEN_VERT, shared with the occlusion pass, its blur and the rush.
+ */
+export const OIT_RESOLVE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** Weighted premultiplied colour in rgb, weighted alpha in a. Cleared to zero. */
+uniform sampler2D uOitAccum;
+/** What every layer let through, as a product. Cleared to one, so an untouched pixel is all scene. */
+uniform sampler2D uOitReveal;
+
+out vec4 fragColor;
+
+void main() {
+  vec4 accum = textureLod(uOitAccum, vUv, 0.0);
+  float reveal = textureLod(uOitReveal, vUv, 0.0).r;
+
+  /*
+   * Guarded because a pixel no fragment touched has a weighted alpha of zero. Its revealage is
+   * then one, so the blend discards whatever this produced anyway — but a division by zero would
+   * put a NaN into the target first, and a NaN blended against anything stays a NaN.
+   */
+  vec3 average = accum.rgb / max(accum.a, 1e-5);
+
+  fragColor = vec4(average, reveal);
+}
+`;