@driftengine/core 3.61.0

package/dist/render/backend/webgpu/shaderModules.js

@@ -0,0 +1,45 @@
+/**
+ * Shader modules, built once per source per device.
+ *
+ * **A module used to be created inside every pipeline descriptor**, which reads as free and is
+ * not: `createShaderModule` parses and validates the WGSL, and a descriptor is built on every
+ * `PipelineCache` miss. The flat shader is the worst case and the common one. A consumer that
+ * creates two dozen meshes gets a pipeline per distinct vertex layout, times a blended twin,
+ * times every target the mesh can land on, and each of those parsed the same large source
+ * again. On a workstation that is invisible. On a phone it is seconds of the main thread,
+ * before a single frame, which is a black and unresponsive page rather than a slow one.
+ *
+ * Keyed by the source text rather than by the label, because the source is what decides what a
+ * module *is* — two passes that compile the same WGSL under different labels want one module,
+ * and a label is a debugging string that must never change the object graph. Modules are
+ * immutable once created and safe to share between pipelines, which is the whole reason this
+ * can be a cache rather than a pool.
+ *
+ * `WeakMap` on the device, so nothing here outlives the device it belongs to: a lost context
+ * builds a new device, which starts empty and cannot be handed a module belonging to the dead
+ * one. That also means this needs no `dispose` and no wiring into anybody's teardown.
+ */
+const byDevice = new WeakMap();
+/**
+ * The module for this source, compiling it on the first ask only.
+ *
+ * A drop-in for `device.createShaderModule(descriptor)`, and deliberately the same shape so a
+ * call site reads the same after the change as before it.
+ */
+export function shaderModule(device, descriptor) {
+    let modules = byDevice.get(device);
+    if (modules === undefined) {
+        modules = new Map();
+        byDevice.set(device, modules);
+    }
+    const existing = modules.get(descriptor.code);
+    if (existing !== undefined)
+        return existing;
+    const built = device.createShaderModule(descriptor);
+    modules.set(descriptor.code, built);
+    return built;
+}
+/** How many distinct sources this device has compiled. Read by tests and diagnostics. */
+export function shaderModuleCount(device) {
+    return byDevice.get(device)?.size ?? 0;
+}

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The froxel binner, in WGSL, hand-authored.
+ *
+ * **`npm run wgsl` does not produce this file and `npm run wgsl:check` does not police it.** That
+ * is an exception to the standing rule that GLSL is the source of truth, it is written down in
+ * `AGENTS.md` under the 2026-08-12 rule, and the argument is in
+ * the compute-seam design. In one line: the rule exists so
+ * no shader is maintained twice and so a generator defect can only reach the backend that has a
+ * fallback, and a compute shader has no twin and no fallback — generating it would invert the very
+ * property the rule protects.
+ *
+ * **Every layout constant is interpolated from `clusteredLights.ts` rather than written here.**
+ * Two files agreeing about a stride by both containing the number 8 is the shape of defect this
+ * whole feature is gated against; there is one definition and this reads it.
+ *
+ * **It must produce the same bytes as `buildLightClusters`.** Where the two could have differed
+ * they were made to agree deliberately: lights are visited in increasing index so a cluster's list
+ * is sorted without sorting, unused slots are written as zero on both sides, and the overflow rule
+ * is the same eviction of the farthest from the cluster centre followed by the same ascending
+ * sort. `scripts/cluster-check.mjs` is what holds that, and the 2026-08-17 rule about two
+ * implementations of one decision is why it exists at all.
+ */
+export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 5u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 16u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/** Three vec4s a light, in exactly the record order `buildLightClusters` writes. */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = lights[light * LIGHT_TEXELS];\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    let radius = lights[light * LIGHT_TEXELS].w;\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.js

@@ -0,0 +1,208 @@
+import { CLUSTER_COUNT, CLUSTER_TEXELS, CLUSTER_X, CLUSTER_Y, CLUSTER_Z, LIGHT_REGION_TEXELS, LIGHT_TEXELS, MAX_LIGHTS_PER_CLUSTER, TABLE_WIDTH, } from '../../../clusteredLights.js';
+/**
+ * The froxel binner, in WGSL, hand-authored.
+ *
+ * **`npm run wgsl` does not produce this file and `npm run wgsl:check` does not police it.** That
+ * is an exception to the standing rule that GLSL is the source of truth, it is written down in
+ * `AGENTS.md` under the 2026-08-12 rule, and the argument is in
+ * the compute-seam design. In one line: the rule exists so
+ * no shader is maintained twice and so a generator defect can only reach the backend that has a
+ * fallback, and a compute shader has no twin and no fallback — generating it would invert the very
+ * property the rule protects.
+ *
+ * **Every layout constant is interpolated from `clusteredLights.ts` rather than written here.**
+ * Two files agreeing about a stride by both containing the number 8 is the shape of defect this
+ * whole feature is gated against; there is one definition and this reads it.
+ *
+ * **It must produce the same bytes as `buildLightClusters`.** Where the two could have differed
+ * they were made to agree deliberately: lights are visited in increasing index so a cluster's list
+ * is sorted without sorting, unused slots are written as zero on both sides, and the overflow rule
+ * is the same eviction of the farthest from the cluster centre followed by the same ascending
+ * sort. `scripts/cluster-check.mjs` is what holds that, and the 2026-08-17 rule about two
+ * implementations of one decision is why it exists at all.
+ */
+export const CLUSTER_BIN_WGSL = `
+const CLUSTER_X: u32 = ${CLUSTER_X}u;
+const CLUSTER_Y: u32 = ${CLUSTER_Y}u;
+const CLUSTER_Z: u32 = ${CLUSTER_Z}u;
+const CLUSTER_COUNT: u32 = ${CLUSTER_COUNT}u;
+const CLUSTER_TEXELS: u32 = ${CLUSTER_TEXELS}u;
+const MAX_LIGHTS_PER_CLUSTER: u32 = ${MAX_LIGHTS_PER_CLUSTER}u;
+const LIGHT_TEXELS: u32 = ${LIGHT_TEXELS}u;
+const LIGHT_REGION_TEXELS: u32 = ${LIGHT_REGION_TEXELS}u;
+const TABLE_WIDTH: u32 = ${TABLE_WIDTH}u;
+
+struct Params {
+  view: mat4x4<f32>,
+  /** near, far, tan(fovY/2), aspect. */
+  frustum: vec4<f32>,
+  lightCount: u32,
+  pad0: u32,
+  pad1: u32,
+  pad2: u32,
+}
+
+@group(0) @binding(0) var<uniform> params: Params;
+/** Three vec4s a light, in exactly the record order \`buildLightClusters\` writes. */
+@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;
+/**
+ * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.
+ *
+ * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason
+ * a cluster owns a fixed run rather than appending into a shared one.
+ */
+@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;
+
+/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */
+fn texelAt(texel: u32) -> vec2<i32> {
+  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));
+}
+
+fn sliceNearDepth(slice: f32) -> f32 {
+  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));
+}
+
+/** Squared distance from a point to an axis-aligned box, zero inside it. */
+fn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {
+  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));
+  return dot(d, d);
+}
+
+/** A light's view-space centre, with depth positive along the view direction. */
+fn viewOf(light: u32) -> vec3<f32> {
+  let world = lights[light * LIGHT_TEXELS];
+  let v = params.view * vec4<f32>(world.xyz, 1.0);
+  return vec3<f32>(v.x, v.y, -v.z);
+}
+
+/**
+ * Squared distance from a light's view-space centre to a point.
+ *
+ * **Squared, matching \`centreDistanceSq\` in \`clusteredLights.ts\` rather than taking a root.** The
+ * ranking is identical either way, and a square root is one more operation for the two
+ * implementations to round differently.
+ */
+fn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {
+  let d = viewOf(light) - centre;
+  return dot(d, d);
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let id = gid.x;
+
+  /*
+   * The light records, written by the first invocations that have one.
+   *
+   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture
+   * the clusters do, because the lit pass reads both through one texture unit; writing them from
+   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.
+   * There are always more clusters than lights, so every record has an invocation.
+   */
+  if (id < params.lightCount) {
+    let record = id * LIGHT_TEXELS;
+    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {
+      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));
+    }
+  }
+
+  if (id >= CLUSTER_COUNT) {
+    return;
+  }
+
+  let k = id / (CLUSTER_X * CLUSTER_Y);
+  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;
+  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;
+
+  /* The AABB of the froxel's eight corners, exactly as \`clusterViewBounds\` derives it. */
+  let zNear = sliceNearDepth(f32(k));
+  let zFar = sliceNearDepth(f32(k + 1u));
+  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);
+  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);
+  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);
+  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);
+  let halfHNear = zNear * params.frustum.z;
+  let halfHFar = zFar * params.frustum.z;
+  let halfWNear = halfHNear * params.frustum.w;
+  let halfWFar = halfHFar * params.frustum.w;
+
+  let lo = vec3<f32>(
+    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),
+    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),
+    zNear,
+  );
+  let hi = vec3<f32>(
+    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),
+    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),
+    zFar,
+  );
+  let centre = (lo + hi) * 0.5;
+
+  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;
+  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {
+    indices[n] = 0u;
+  }
+  var count: u32 = 0u;
+
+  /* Increasing light index, which is what makes the list sorted without a sort. */
+  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {
+    let radius = lights[light * LIGHT_TEXELS].w;
+    let v = viewOf(light);
+    if (v.z + radius <= 0.0) {
+      continue;
+    }
+    if (distanceSqToBounds(v, lo, hi) > radius * radius) {
+      continue;
+    }
+
+    if (count < MAX_LIGHTS_PER_CLUSTER) {
+      indices[count] = light;
+      count = count + 1u;
+      continue;
+    }
+
+    /*
+     * Full. Drop the farthest from the cluster's centre if this one is nearer.
+     *
+     * **The only float comparison that decides anything here**, and the reason the *order* is an
+     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,
+     * so it is confined to membership, where the conformance script forgives a light sitting
+     * within epsilon of a boundary.
+     */
+    var worstSlot: i32 = -1;
+    var worst = centreDistanceSq(light, centre);
+    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {
+      let d = centreDistanceSq(indices[n], centre);
+      if (d > worst) {
+        worst = d;
+        worstSlot = i32(n);
+      }
+    }
+    if (worstSlot < 0) {
+      continue;
+    }
+    indices[u32(worstSlot)] = light;
+
+    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */
+    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {
+      let value = indices[n];
+      var m: i32 = i32(n) - 1;
+      while (m >= 0 && indices[u32(m)] > value) {
+        indices[u32(m) + 1u] = indices[u32(m)];
+        m = m - 1;
+      }
+      indices[u32(m + 1)] = value;
+    }
+  }
+
+  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;
+  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));
+  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {
+    textureStore(
+      table,
+      texelAt(base + 1u + t),
+      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),
+    );
+  }
+}
+`;

package/dist/render/backend/webgpu/skinPaletteRing.d.ts

@@ -0,0 +1,67 @@
+/**
+ * How many palettes one frame may set before the ring is full.
+ *
+ * The arithmetic rather than a round number: a character's palette is uploaded once per *pass*
+ * that draws it, and a full profile draws the same character five times — the main pass, a planar
+ * reflection, and the static, peel and dynamic shadow layers. So this is twenty-five characters at
+ * once, which is a crowd rather than a cast.
+ *
+ * **What it costs is nothing until it is used.** A slot allocates its texture on the first frame
+ * that reaches it and keeps it, so a scene with two characters holds two: a 24-joint rig is 96
+ * texels of `rgba32float`, which is 1.5 KB, and a 96-joint humanoid is 6 KB.
+ *
+ * **What would make it wrong** is a genuine crowd — a stadium, a swarm of rigged birds — and the
+ * fix is then the one `skinPalette.ts` names: one texture holding every palette with a per-draw
+ * row offset, which spends a uniform and a shader change to stop spending textures.
+ */
+export declare const MAX_SKIN_PALETTES = 128;
+/**
+ * Every joint palette a frame sets, each in its own texture, reused frame after frame.
+ *
+ * **This exists for the reason `UniformRing` exists, and the fact is the same one.**
+ * `queue.writeTexture` does not interleave with draw commands: writes are ordered on the queue
+ * timeline and the frame's encoder is submitted *after* all of them, so two palettes uploaded into
+ * one texture between two draws give **both** draws the last palette written. Not the first, not a
+ * blend — the last, for every skinned draw in the frame.
+ *
+ * What that looks like is not a skinning bug. Every character in the frame stands in the pose, and
+ * at the position, of whichever was drawn last, because a rig carries its placement in its palette
+ * rather than in `uModel`. Measured in the product: a game drawing a ghost of an earlier run and
+ * then the live character drew the ghost with the *character's* palette, so a translucent second body sat
+ * exactly on top of the player and read as a transparency fault.
+ *
+ * **The other backend needs none of this and that is not an asymmetry of decision.** WebGL2's
+ * `texSubImage2D` is a command in the same stream as the draws around it, so an upload between two
+ * draws separates them there by construction. The decision — a palette belongs to a draw — is one;
+ * only what it takes to honour it differs, which is what `skinPalette.ts` says a binder is for.
+ *
+ * **A slot is written at most once per frame**, since every `setSkinPalette` takes a fresh one.
+ * That is what makes the reallocation inside `SkinPaletteTexture` safe: a joint count can only
+ * change a slot's texture between frames, never while a recorded draw is still pointing at it.
+ */
+export declare class SkinPaletteRing {
+    private readonly slots;
+    private used;
+    private warnedFull;
+    /** How many slots this frame has taken. */
+    get count(): number;
+    /**
+     * Start a frame: every slot is free again.
+     *
+     * **Called where the frame's encoder is replaced and not a line earlier.** A slot may only be
+     * re-let once the draws pointing at it have been submitted, which is exactly what `beginFrame`
+     * has just done — including for anything drawn after the previous `endFrame`.
+     */
+    reset(): void;
+    /**
+     * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
+     *
+     * **Null rather than reusing a slot**, because reusing one is the defect this class is named
+     * after: the caller's character would silently take another character's pose. A caller that runs
+     * out declines the draw and says so once.
+     */
+    take(device: GPUDevice, palette: Float32Array): number | null;
+    /** The view a draw binds for a slot, or null for a slot nothing has uploaded into. */
+    view(slot: number): GPUTextureView | null;
+    dispose(): void;
+}

package/dist/render/backend/webgpu/skinPaletteRing.js

@@ -0,0 +1,97 @@
+import { SkinPaletteTexture } from './skinPaletteTexture.js';
+/**
+ * How many palettes one frame may set before the ring is full.
+ *
+ * The arithmetic rather than a round number: a character's palette is uploaded once per *pass*
+ * that draws it, and a full profile draws the same character five times — the main pass, a planar
+ * reflection, and the static, peel and dynamic shadow layers. So this is twenty-five characters at
+ * once, which is a crowd rather than a cast.
+ *
+ * **What it costs is nothing until it is used.** A slot allocates its texture on the first frame
+ * that reaches it and keeps it, so a scene with two characters holds two: a 24-joint rig is 96
+ * texels of `rgba32float`, which is 1.5 KB, and a 96-joint humanoid is 6 KB.
+ *
+ * **What would make it wrong** is a genuine crowd — a stadium, a swarm of rigged birds — and the
+ * fix is then the one `skinPalette.ts` names: one texture holding every palette with a per-draw
+ * row offset, which spends a uniform and a shader change to stop spending textures.
+ */
+export const MAX_SKIN_PALETTES = 128;
+/**
+ * Every joint palette a frame sets, each in its own texture, reused frame after frame.
+ *
+ * **This exists for the reason `UniformRing` exists, and the fact is the same one.**
+ * `queue.writeTexture` does not interleave with draw commands: writes are ordered on the queue
+ * timeline and the frame's encoder is submitted *after* all of them, so two palettes uploaded into
+ * one texture between two draws give **both** draws the last palette written. Not the first, not a
+ * blend — the last, for every skinned draw in the frame.
+ *
+ * What that looks like is not a skinning bug. Every character in the frame stands in the pose, and
+ * at the position, of whichever was drawn last, because a rig carries its placement in its palette
+ * rather than in `uModel`. Measured in the product: a game drawing a ghost of an earlier run and
+ * then the live character drew the ghost with the *character's* palette, so a translucent second body sat
+ * exactly on top of the player and read as a transparency fault.
+ *
+ * **The other backend needs none of this and that is not an asymmetry of decision.** WebGL2's
+ * `texSubImage2D` is a command in the same stream as the draws around it, so an upload between two
+ * draws separates them there by construction. The decision — a palette belongs to a draw — is one;
+ * only what it takes to honour it differs, which is what `skinPalette.ts` says a binder is for.
+ *
+ * **A slot is written at most once per frame**, since every `setSkinPalette` takes a fresh one.
+ * That is what makes the reallocation inside `SkinPaletteTexture` safe: a joint count can only
+ * change a slot's texture between frames, never while a recorded draw is still pointing at it.
+ */
+export class SkinPaletteRing {
+    slots = [];
+    used = 0;
+    warnedFull = false;
+    /** How many slots this frame has taken. */
+    get count() {
+        return this.used;
+    }
+    /**
+     * Start a frame: every slot is free again.
+     *
+     * **Called where the frame's encoder is replaced and not a line earlier.** A slot may only be
+     * re-let once the draws pointing at it have been submitted, which is exactly what `beginFrame`
+     * has just done — including for anything drawn after the previous `endFrame`.
+     */
+    reset() {
+        this.used = 0;
+    }
+    /**
+     * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
+     *
+     * **Null rather than reusing a slot**, because reusing one is the defect this class is named
+     * after: the caller's character would silently take another character's pose. A caller that runs
+     * out declines the draw and says so once.
+     */
+    take(device, palette) {
+        if (this.used >= MAX_SKIN_PALETTES) {
+            if (!this.warnedFull) {
+                this.warnedFull = true;
+                console.warn(`WebGPU: more than ${MAX_SKIN_PALETTES} skin palettes in one frame; the rest of the ` +
+                    'skinned draws are declined this frame rather than drawn in another rig’s pose. ' +
+                    'See MAX_SKIN_PALETTES.');
+            }
+            return null;
+        }
+        const at = this.used++;
+        let slot = this.slots[at];
+        if (slot === undefined) {
+            slot = new SkinPaletteTexture();
+            this.slots[at] = slot;
+        }
+        slot.update(device, palette);
+        return at;
+    }
+    /** The view a draw binds for a slot, or null for a slot nothing has uploaded into. */
+    view(slot) {
+        return this.slots[slot]?.view() ?? null;
+    }
+    dispose() {
+        for (const slot of this.slots)
+            slot.dispose();
+        this.slots.length = 0;
+        this.used = 0;
+    }
+}

package/dist/render/backend/webgpu/skinPaletteTexture.d.ts

@@ -0,0 +1,17 @@
+export declare class SkinPaletteTexture {
+    private texture;
+    private joints;
+    /**
+     * The view, cached rather than created per call.
+     *
+     * `createView` allocates, and a bind group is rebuilt against this per draw — so a fresh view
+     * each time is both an allocation in the frame loop and a value that never compares equal,
+     * which would defeat any cache keyed on it. Invalidated only when the texture is replaced.
+     */
+    private cachedView;
+    /** Upload a palette, reallocating only when the joint count changes. */
+    update(device: GPUDevice, palette: Float32Array): void;
+    view(): GPUTextureView | null;
+    get ready(): boolean;
+    dispose(): void;
+}

package/dist/render/backend/webgpu/skinPaletteTexture.js

@@ -0,0 +1,68 @@
+import { paletteTextureWidth, validateSkinPalette } from '../../skinPalette.js';
+/**
+ * The joint palette as a one-row `rgba32float` texture, on WebGPU.
+ *
+ * The twin of the WebGL2 module of this name, and deliberately symmetric with it: one decision in
+ * `skinPalette.ts`, two thin binders, per the 2026-08-13 rule.
+ *
+ * **`rgba32float` is `unfilterable-float` to a bind group layout**, which costs nothing because
+ * the shader reads it with `textureLoad` — an integer coordinate and no sampler at all. A layout
+ * declaring it filterable would fail validation at pipeline creation, which is the loud failure
+ * rather than the quiet one.
+ */
+/*
+ * Spelled out rather than read from the global `GPUTextureUsage`, which is not in the TypeScript
+ * lib this package compiles against — `clusterBinner.ts` does the same and for the same reason.
+ */
+const TEXTURE_USAGE = {
+    COPY_DST: 0x02,
+    TEXTURE_BINDING: 0x04,
+};
+export class SkinPaletteTexture {
+    texture = null;
+    joints = 0;
+    /**
+     * The view, cached rather than created per call.
+     *
+     * `createView` allocates, and a bind group is rebuilt against this per draw — so a fresh view
+     * each time is both an allocation in the frame loop and a value that never compares equal,
+     * which would defeat any cache keyed on it. Invalidated only when the texture is replaced.
+     */
+    cachedView = null;
+    /** Upload a palette, reallocating only when the joint count changes. */
+    update(device, palette) {
+        validateSkinPalette(palette);
+        const joints = palette.length / 16;
+        const width = paletteTextureWidth(joints);
+        if (this.texture === null || this.joints !== joints) {
+            this.texture?.destroy();
+            this.cachedView = null;
+            this.texture = device.createTexture({
+                /* Labelled, because `createGpuSurface`'s uncaptured-error lines are only legible when
+                   every resource carries one. See the 2026-08-14 rule. */
+                label: `skin.palette:${joints}`,
+                size: { width, height: 1 },
+                format: 'rgba32float',
+                usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST,
+            });
+            this.joints = joints;
+        }
+        device.queue.writeTexture({ texture: this.texture }, palette, { bytesPerRow: width * 16 }, { width, height: 1 });
+    }
+    view() {
+        if (this.texture === null)
+            return null;
+        if (this.cachedView === null)
+            this.cachedView = this.texture.createView();
+        return this.cachedView;
+    }
+    get ready() {
+        return this.texture !== null;
+    }
+    dispose() {
+        this.texture?.destroy();
+        this.texture = null;
+        this.cachedView = null;
+        this.joints = 0;
+    }
+}

package/dist/render/backend/webgpu/skyPass.d.ts

@@ -0,0 +1,102 @@
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The sky: one triangle covering the screen, with the world reconstructed per fragment.
+ *
+ * **No vertex buffers at all.** The vertex shader builds its three corners from
+ * `gl_VertexIndex` — `gl_VertexID` in the GLSL, which the transform renames — so there is
+ * nothing to upload and nothing to bind. That makes this the simplest pass in the engine to
+ * port and a good second one after `flat`.
+ */
+export declare const SKY_FIELDS: {
+    readonly uInvViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uCameraPos: {
+        readonly offset: 64;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uTopColor: {
+        readonly offset: 80;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uHorizonColor: {
+        readonly offset: 96;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uDeepColor: {
+        readonly offset: 112;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uSunDir: {
+        readonly offset: 128;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uSunColor: {
+        readonly offset: 144;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uSunDiscExponent: {
+        readonly offset: 156;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uMoonDir: {
+        readonly offset: 160;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uMoonColor: {
+        readonly offset: 176;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uMoonAngularRadius: {
+        readonly offset: 188;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uMoonPhase: {
+        readonly offset: 192;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uNightFactor: {
+        readonly offset: 196;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uCloudOffset: {
+        readonly offset: 200;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uUnderwaterColor: {
+        readonly offset: 208;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uUnderwaterFactor: {
+        readonly offset: 220;
+        readonly size: 4;
+        readonly type: "float";
+    };
+};
+export declare const SKY_UNIFORM_SIZE: 224;
+export declare function createSkyBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createSkyBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, uniforms: GPUBuffer): GPUBindGroup;
+/**
+ * The sky pipeline.
+ *
+ * **Depth is tested but not written**, which is what `gl.depthMask(false)` does on the
+ * WebGL2 path. The sky sits at the far plane, so writing its depth would push every later
+ * pass behind it; not testing at all would paint it over geometry already drawn.
+ */
+export declare function skyPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;