@forgeax/engine-render 0.1.2

package/src/ssao-data.ts

@@ -0,0 +1,106 @@
+// @forgeax/engine-runtime — SSAO kernel + noise data generation.
+//
+// feat-20260612-hdrp-ssao M1 / w2.
+//
+// Implements the LO 5.9 host-side algorithm (research F1 + F2):
+//  - generateSsaoKernel: 64 vec3 hemisphere samples with quadratic falloff
+//    bias (lerp(0.1, 1.0, (i/64)^2)), deterministic given a seed.
+//  - generateSsaoNoise: 4x4 vec3 rotation vectors (z=0 tangent-plane),
+//    deterministic given a seed.
+//
+// Both are one-shot, host-side generated (requirements OOS-7: no runtime
+// regeneration). Output fits directly into Float32Array for writeBuffer upload.
+//
+// The mulberry32 PRNG is used for deterministic reproducibility across
+// runs — same seed always yields same kernel/noise (AC-03 snapshot).
+
+export const SSAO_KERNEL_SAMPLE_COUNT = 64;
+const NOISE_SIZE = 16; // 4 x 4
+
+/**
+ * Mulberry32 PRNG — fast 32-bit deterministic generator.
+ * Returns a float in [0, 1).
+ */
+function mulberry32(seed: number): () => number {
+  let state = seed | 0;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + t * (b - a);
+}
+
+/**
+ * Generate 64 SSAO hemisphere sample vectors (tangent-space, z >= 0).
+ *
+ * Algorithm (LO 5.9, research F1):
+ *  1. Random direction on unit sphere with z >= 0.
+ *  2. Normalize.
+ *  3. Scale by random [0,1].
+ *  4. Scale by lerp(0.1, 1.0, (i/64)^2) for quadratic falloff.
+ *
+ * Each sample is returned as a `[x, y, z]` tuple in a `Float32Array`
+ * slice — 64 slices of 3 floats each, packed contiguously for upload.
+ *
+ * @param seed Optional PRNG seed (default 0). Same seed always produces
+ *   the same kernel.
+ * @returns Array of 64 `[x, y, z]` arrays (each Float32Array length 3).
+ */
+export function generateSsaoKernel(seed: number = 0): readonly Float32Array[] {
+  const rand = mulberry32(seed);
+  const kernel: Float32Array[] = [];
+  for (let i = 0; i < SSAO_KERNEL_SAMPLE_COUNT; i++) {
+    // Step 1: random direction on unit hemisphere (z >= 0)
+    let x = rand() * 2 - 1;
+    let y = rand() * 2 - 1;
+    let z = rand(); // [0, 1] => z >= 0 hemisphere
+    // Step 1b: normalize
+    const len = Math.sqrt(x * x + y * y + z * z);
+    x /= len;
+    y /= len;
+    z /= len;
+    // Step 2: random length [0, 1]
+    const r = rand();
+    x *= r;
+    y *= r;
+    z *= r;
+    // Step 3: quadratic falloff — more samples near origin
+    const scale = lerp(0.1, 1.0, (i / SSAO_KERNEL_SAMPLE_COUNT) * (i / SSAO_KERNEL_SAMPLE_COUNT));
+    const sample = new Float32Array(3);
+    sample[0] = x * scale;
+    sample[1] = y * scale;
+    sample[2] = z * scale;
+    kernel.push(sample);
+  }
+  return kernel;
+}
+
+/**
+ * Generate 4x4 noise rotation vectors (tangent-space, z = 0).
+ *
+ * Algorithm (LO 5.9, research F2):
+ *  16 vec3 vectors with random xy directions and z = 0.
+ *  Used by shader to rotate the 64-sample kernel per-pixel via
+ *  tiled sampling (REPEAT addressing).
+ *
+ * Returns a flat Float32Array of 48 floats (16 vectors x 3
+ * components each), suitable for upload as a 4x4 rgba32float texture.
+ *
+ * @param seed Optional PRNG seed (default 0).
+ * @returns Float32Array of length 48.
+ */
+export function generateSsaoNoise(seed: number = 0): Float32Array {
+  const rand = mulberry32(seed);
+  const noise = new Float32Array(NOISE_SIZE * 3); // 16 * 3 = 48
+  for (let i = 0; i < NOISE_SIZE; i++) {
+    noise[i * 3 + 0] = rand() * 2 - 1;
+    noise[i * 3 + 1] = rand() * 2 - 1;
+    noise[i * 3 + 2] = 0; // tangent-plane rotation (z = 0)
+  }
+  return noise;
+}

package/src/surface-format.ts

@@ -0,0 +1,37 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+
+export interface SwapChainFormatPair {
+  readonly storage: GPUTextureFormat;
+  readonly view: GPUTextureFormat;
+  readonly fallbackReason?: 'preferred-canvas-format-missing';
+}
+
+export type SurfaceBackendKind = RhiDevice['caps']['backendKind'];
+
+export function resolveSurfaceFormatPair(
+  backendKind: SurfaceBackendKind,
+  storage: GPUTextureFormat,
+  view: GPUTextureFormat,
+): SwapChainFormatPair {
+  return backendKind === 'wgpu-webgl2' ? { storage: view, view } : { storage, view };
+}
+
+export function selectSwapChainFormat(storageBufferCapable: boolean): SwapChainFormatPair {
+  if (!storageBufferCapable) {
+    return { storage: 'rgba8unorm', view: 'rgba8unorm-srgb' };
+  }
+  const nav = (
+    globalThis as { navigator?: { gpu?: { getPreferredCanvasFormat?: () => GPUTextureFormat } } }
+  ).navigator;
+  const gpu = nav?.gpu;
+  const getPreferred = gpu?.getPreferredCanvasFormat;
+  if (gpu !== undefined && typeof getPreferred === 'function') {
+    const storage = getPreferred.call(gpu);
+    return { storage, view: `${storage}-srgb` as unknown as GPUTextureFormat };
+  }
+  return {
+    storage: 'rgba8unorm',
+    view: 'rgba8unorm-srgb',
+    fallbackReason: 'preferred-canvas-format-missing',
+  };
+}

package/src/systems/active-camera.ts

@@ -0,0 +1,116 @@
+// @forgeax/engine-runtime - ActiveCamera KV resource + selection helper.
+//
+// feat-20260630-viewport-2x2-run-x-display-redesign M2 w12 / plan-strategy D-2.
+//
+// PROBLEM (research Finding 4): the render extract stage selects the camera by
+// archetype-query FIRST-HIT (`cameras[0]`) and fires `render-system-multi-camera`
+// when more than one [Camera, Transform, Entity] entity exists. A single engine
+// world that carries BOTH an editor orbit camera AND a game camera therefore
+// cannot pick which one renders. This module adds the minimum neutral mechanism:
+// an `ActiveCamera { entity }` resource naming the entity to render through.
+//
+// ENGINE-NEUTRAL (requirements OOS-4 / AC-16): the engine knows only entity IDs.
+// It does NOT know which entity is "editor" or "game" -- the caller (editor side)
+// decides what `ActiveCamera.entity` points at. No editor concept enters this
+// file or the engine layer.
+//
+// BACKWARD COMPATIBLE (plan-strategy D-2): when the resource is ABSENT, or the
+// named entity is not among the queried cameras, selection falls back to the
+// existing first-hit behavior unchanged. Single-camera scenes are unaffected.
+//
+// Surface:
+//   - interface  ActiveCamera { entity: number }
+//   - constant   ACTIVE_CAMERA_KEY = 'ActiveCamera'
+//   - helper     getActiveCamera(world): ActiveCamera | undefined
+//   - helper     setActiveCamera(world, entity): void
+//   - pure       selectActiveCameraIndex(cameraEntities, activeEntity): number
+//
+// @new-surface KV resource: ECS has no defineResource factory; the TS POD
+//   interface + string KV key form is the minimum-new-surface route, mirroring
+//   TransparentSortConfig. The world resource store
+//   (insertResource / getResource / hasResource) is reused unchanged.
+// @derives world.hasResource / world.insertResource / world.getResource KV API.
+// @fallback getActiveCamera KV missing returns undefined; no warn; no throw
+//   (absent ActiveCamera is a legal state -> first-hit fallback in extract).
+//
+// charter mapping: F1 (single-import barrel + single entity pointer, smallest
+// concept face vs a multi-field priority/enabled scheme) + P4 (consistent
+// abstraction -- same world.{has,get,insert}Resource KV API as every other
+// engine resource consumer).
+
+import type { World } from '@forgeax/engine-ecs';
+
+// ────────────────────────────────────────────────────────────────────────────
+// POD interface + KV key
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Active-camera pointer (plain-data POD). Lives as a world-level resource keyed
+ * by `ACTIVE_CAMERA_KEY`. `entity` is the packed entity id (engine `EntityHandle`
+ * is a branded number) of the camera the renderer should use.
+ *
+ * The engine treats `entity` as an opaque id; whether it names an editor camera
+ * or a game camera is a caller-side decision (OOS-4 — engine stays neutral).
+ */
+export interface ActiveCamera {
+  readonly entity: number;
+}
+
+/** World resource key for the `ActiveCamera` KV entry. */
+export const ACTIVE_CAMERA_KEY = 'ActiveCamera' as const;
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read the world's `ActiveCamera` resource.
+ *
+ * @fallback KV missing returns `undefined` — absent ActiveCamera is a legal
+ * state (the renderer falls back to archetype first-hit). NO warn, NO throw.
+ * The `hasResource` guard precedes the read so this helper never trips
+ * `ResourceNotFoundError` from `world.getResource`.
+ *
+ * @example
+ *   const a = getActiveCamera(world);   // undefined when not set
+ *   if (a) { ... a.entity ... }
+ */
+export function getActiveCamera(world: World): ActiveCamera | undefined {
+  if (!world.hasResource(ACTIVE_CAMERA_KEY)) return undefined;
+  return world.getResource<ActiveCamera>(ACTIVE_CAMERA_KEY);
+}
+
+/**
+ * Write the world's `ActiveCamera` resource (idempotent last-write-wins via
+ * `world.insertResource`). The renderer will use the camera whose entity id
+ * equals `entity`, or fall back to first-hit if that id is not a queried camera.
+ *
+ * @example
+ *   setActiveCamera(world, gameCameraEntity);  // render through the game camera
+ */
+export function setActiveCamera(world: World, entity: number): void {
+  world.insertResource<ActiveCamera>(ACTIVE_CAMERA_KEY, { entity });
+}
+
+/**
+ * Pure selection: given the entity ids of every camera surfaced by the extract
+ * archetype query (in query order) and the optional active-camera entity id,
+ * return the index of the active camera in `cameraEntities`, or `-1` to signal
+ * "no selection — use first-hit fallback".
+ *
+ * `-1` is returned when `activeEntity` is `undefined` (resource absent) OR when
+ * the id is not present among `cameraEntities` (stale / non-camera entity).
+ * Both cases preserve the existing first-hit behavior (plan-strategy D-2).
+ *
+ * @example
+ *   selectActiveCameraIndex([10, 20, 30], 20) === 1   // pick the 2nd camera
+ *   selectActiveCameraIndex([10, 20, 30], undefined) === -1  // first-hit
+ *   selectActiveCameraIndex([10, 20, 30], 999) === -1        // first-hit
+ */
+export function selectActiveCameraIndex(
+  cameraEntities: readonly number[],
+  activeEntity: number | undefined,
+): number {
+  if (activeEntity === undefined) return -1;
+  return cameraEntities.indexOf(activeEntity);
+}

package/src/systems/pass-selector.ts

@@ -0,0 +1,49 @@
+// M3 / w19: PassSelector matching logic
+// (feat-20260526-material-asset-multipass-renderstate)
+//
+// Pure-function helpers for matching MaterialPass tags against
+// a PassSelector. Plan-strategy D-4: Tags free Record + PassSelector
+// Record<string, string[]>. Requirements AC-05.
+
+import type { MaterialPass, PassSelector } from '@forgeax/engine-types';
+
+/**
+ * Test whether a pass's tags match a {@link PassSelector}.
+ *
+ * Matching rule (AC-05): every key in the selector must exist in the pass's
+ * `tags` and the pass's tag value must be in the selector's value list for
+ * that key. An empty selector matches every pass.
+ *
+ * @param tags The pass-level tags (free key-value pairs)
+ * @param selector The selector to match against
+ */
+export function matchPass(tags: Record<string, string>, selector: PassSelector): boolean {
+  if (Object.keys(selector).length === 0) return true;
+  for (const [key, allowedValues] of Object.entries(selector)) {
+    const passValue = tags[key];
+    if (passValue === undefined) return false;
+    if ((allowedValues as readonly string[]).length === 0) return false;
+    if (!(allowedValues as readonly string[]).includes(passValue)) return false;
+  }
+  return true;
+}
+
+/**
+ * Filter passes whose tags match the given {@link PassSelector}.
+ *
+ * An empty selector matches all passes (returns the input array reference).
+ * Otherwise each pass is checked via {@link matchPass}.
+ *
+ * @param passes The material's pass descriptors
+ * @param selector The pass selector
+ * @returns Filtered array of matching passes
+ */
+export function selectPasses(
+  passes: readonly MaterialPass[],
+  selector: PassSelector,
+): readonly MaterialPass[] {
+  if (Object.keys(selector).length === 0) return passes;
+  return passes.filter((p) =>
+    matchPass((p.renderState?.tags as Record<string, string> | undefined) ?? {}, selector),
+  );
+}

package/src/systems/skin-palette-allocator.ts

@@ -0,0 +1,294 @@
+// @forgeax/engine-runtime - Skin palette buffer allocator (M2 / T-24).
+//
+// Per-renderer mutable state: vertex-stage palette buffer(s) holding
+// pre-multiplied joint matrices (M_i = joint_world * IBM_i) for every
+// skinned entity in a frame. Two backends (split at construction by
+// `useStorageBuffer`):
+//
+//   STORAGE PATH  (`useStorageBuffer = true`, `maxStorageBuffersPerShaderStage
+//                  >= 8` — i.e. WebGPU spec default device).
+//     One shared GPU buffer grows at 1.5x (Bevy skin.rs alignment,
+//     plan-strategy D-4). Every entity's slice is `{ buffer: shared,
+//     byteOffset: cursor }`. Record-stage builds ONE BG against the
+//     shared buffer + `bindingWindowBytes` entry size; per-draw
+//     `setBindGroup(_, bg, [_, dynOffset = slice.byteOffset])` slides
+//     the static window across the buffer. WebGPU rule
+//     `dynOffset + entry.size <= buffer.size` is satisfied because the
+//     allocator extends `buffer.size` to `cursor + bindingWindowBytes`
+//     after every slice.
+//
+//   UNIFORM PATH  (`useStorageBuffer = false`, browser uniform fallback —
+//                  `maxStorageBuffersPerShaderStage = 0`).
+//     `maxUniformBufferBindingSize` floor is 16 KiB; the static binding
+//     window alone is 16320 B, leaving room for ZERO additional
+//     entities behind a shared dynOffset. The shared-BG model collapses,
+//     so each entity gets its OWN small UBO of size = `bindingWindowBytes`
+//     (= MAX_JOINTS * 64 = 16320, which is `<= maxUniformBufferBindingSize`).
+//     Slice returns `{ buffer: per-entity, byteOffset: 0 }`. Record-stage
+//     BG cache key includes `slice.buffer` so each entity gets its own
+//     BG (cached per-buffer pointer; pool reuse keeps createBuffer
+//     amortized across frames).
+//
+//   Concept that does NOT branch by path: `bindingWindowBytes`. It is
+//   the static `pbr-skin-mesh-array-bgl @binding(1/2)` BG entry size,
+//   identical on both paths (WGSL declares the same layout). Record-
+//   stage uses it verbatim for both palettes when constructing the BG.
+//   dynOffset[1/2] on the uniform path is always 0 (entry size already
+//   equals buffer size); on the storage path both walk 0, 1536, 3072, ... .
+//
+// CPU pre-multiply (path-agnostic): writeJointPalette(slice, ibm, jointWorld)
+//   -> mat4 per joint: M_i = joint_world_i * IBM_i
+//   -> queue.writeBuffer(slice.buffer, slice.byteOffset, payload).
+//
+// feat-20260523-skin-skeleton-animation M2 / T-24;
+// feat-20260612-skin-palette-per-frame-upload M6 (uniform fallback split).
+
+import type { Mat4 } from '@forgeax/engine-math';
+import { mat4 } from '@forgeax/engine-math';
+import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
+import { SkinPaletteOverflowError } from '../errors';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import type { SkinPaletteSlice } from '../render-system-extract';
+
+const MAT4_BYTES = 64; // 16 f32 * 4 bytes
+// MAX_JOINTS = 255 matches `pbr-skin-mesh-array-bgl @binding(1/2)` static BG
+// entry size: 255 * 64 = 16320 B. The number is the MAX joints any single
+// skinned entity may have. On the storage path the shared buffer holds
+// many entities back-to-back; on the uniform path each entity owns one
+// 16320 B buffer.
+const MAX_JOINTS = 255;
+const BINDING_WINDOW_BYTES = MAX_JOINTS * MAT4_BYTES; // 16320
+// WebGPU `minStorageBufferOffsetAlignment` default (spec floor) — every
+// dynamic offset passed to setBindGroup must be a multiple of this. The shared
+// storage path packs many entities back-to-back, so each slice's start must be
+// rounded up to this boundary; otherwise a slice whose predecessor's joint
+// footprint (jointCount * 64) is not a multiple of 256 (e.g. 33 joints -> 2112)
+// lands on an unaligned offset and trips `Dynamic Offset[1] is not 256 byte
+// aligned` at draw time.
+const PALETTE_OFFSET_ALIGN = 256;
+
+export interface SkinPaletteAllocator {
+  /**
+   * Static BG entry size for `pbr-skin-mesh-array-bgl @binding(1/2)`. Always
+   * `MAX_JOINTS * 64 = 16320`; consumers (record stage) bind this size
+   * when building the BG. Path-independent.
+   */
+  readonly bindingWindowBytes: number;
+  /**
+   * True when this allocator is in storage-path mode (single shared
+   * buffer + dynOffset). False on the uniform fallback (per-entity
+   * buffer + dynOffset always 0). Record-stage reads this only for
+   * shape assertions in tests; production code branches via
+   * `slice.buffer` identity (shared vs per-entity), not this flag.
+   */
+  readonly useStorageBuffer: boolean;
+  /**
+   * Allocate a slice for `jointCount` joints. Returns the buffer + byte
+   * offset the record stage should bind. Storage path returns the same
+   * shared buffer for every call; uniform path mints (or pool-reuses) a
+   * per-entity buffer and returns it with `byteOffset: 0`. Both paths
+   * guarantee BG validation: storage extends the shared buffer's size,
+   * uniform sizes the per-entity buffer to exactly `bindingWindowBytes`.
+   *
+   * @throws if storage path buffer would exceed
+   *         `device.limits.maxStorageBufferBindingSize`
+   */
+  allocateSlice(jointCount: number): SkinPaletteSlice;
+  /**
+   * Write joint matrices into the slice's buffer at the slice's offset.
+   * Computes M_i = jointWorldTransforms[i] * ibm[i] per joint.
+   *
+   * `jointWorlds[i]` is taken straight from `Skin.joints[i]` entity's
+   * `Transform.world` view (a 16-float column-major Float32Array
+   * written by propagateTransforms); zero recompose, premultiplies
+   * directly against the IBM.
+   */
+  writeJointPalette(
+    slice: SkinPaletteSlice,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Mat4[],
+  ): void;
+  /** Upload the renderer projection's previous successful-submit palette. */
+  writePreviousJointPalette(slice: SkinPaletteSlice, jointMatrices: Float32Array): void;
+  /**
+   * Reset for next frame. Storage path: cursor rewinds, shared buffer
+   * stays. Uniform path: per-entity buffer cursor rewinds (pool entries
+   * stay allocated and round-robin to the next frame's first entity).
+   */
+  resetForFrame(): void;
+}
+
+export function createSkinPaletteAllocator(
+  device: RhiDevice,
+  maxBindingSize: number,
+  useStorageBuffer = true,
+): SkinPaletteAllocator {
+  // Storage path: shared buffer state.
+  let storageBuffer: Buffer | null = null;
+  let previousStorageBuffer: Buffer | null = null;
+  let storageCapacity = 0;
+  let storageCursor = 0;
+
+  // Uniform path: per-entity buffer pool. `pool` is the pre-allocated
+  // 16320 B UBO ring; `poolCursor` advances per allocateSlice within a
+  // frame and rewinds in resetForFrame, so a 3-entity scene reuses 3
+  // entries across frames (createBuffer fires only when the per-frame
+  // entity count grows past the historical max). 16320 B / entry
+  // bounded by maxUniformBufferBindingSize (>= 16384 by spec floor).
+  const pool: Buffer[] = [];
+  const previousPool: Buffer[] = [];
+  let poolCursor = 0;
+
+  function ensureStorageCapacity(needed: number): void {
+    if (storageBuffer !== null && previousStorageBuffer !== null && needed <= storageCapacity)
+      return;
+    let newCapacity = storageCapacity === 0 ? BINDING_WINDOW_BYTES : storageCapacity;
+    while (newCapacity < needed) {
+      // 1.5x grow, then next multiple of 256 for alignment (plan-strategy D-4).
+      newCapacity = (newCapacity + (newCapacity >> 1) + 255) & ~255;
+    }
+    if (newCapacity > maxBindingSize) {
+      throw new SkinPaletteOverflowError(newCapacity, maxBindingSize);
+    }
+    const bufRes = device.createBuffer({
+      label: 'skin-palette',
+      size: newCapacity,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!bufRes.ok) throw bufRes.error;
+    const previousBufRes = device.createBuffer({
+      label: 'skin-palette-previous',
+      size: newCapacity,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!previousBufRes.ok) throw previousBufRes.error;
+    storageBuffer = bufRes.value;
+    previousStorageBuffer = previousBufRes.value;
+    storageCapacity = newCapacity;
+  }
+
+  function acquirePoolBuffer(buffers: Buffer[], label: string): Buffer {
+    if (poolCursor < buffers.length) {
+      const reused = buffers[poolCursor];
+      // biome-ignore lint/style/noNonNullAssertion: poolCursor < buffers.length guarantees the slot is set
+      return reused!;
+    }
+    if (BINDING_WINDOW_BYTES > maxBindingSize) {
+      throw new SkinPaletteOverflowError(BINDING_WINDOW_BYTES, maxBindingSize);
+    }
+    const bufRes = device.createBuffer({
+      label,
+      size: BINDING_WINDOW_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!bufRes.ok) throw bufRes.error;
+    buffers.push(bufRes.value);
+    return bufRes.value;
+  }
+
+  function allocateSlice(jointCount: number): SkinPaletteSlice {
+    if (useStorageBuffer) {
+      // Storage path: shared buffer + dynOffset window.
+      // WebGPU validates `dynOffset + entry.size <= buffer.size` per
+      // setBindGroup, so the buffer must extend a full BINDING_WINDOW_BYTES
+      // past `byteOffset` -- not just `jointCount * 64`. Pre-M6 used the
+      // latter and tripped `Dynamic Offset[1] out of bounds` on entity 2+.
+      const offset = storageCursor;
+      const needed = offset + BINDING_WINDOW_BYTES;
+      ensureStorageCapacity(needed);
+      // biome-ignore lint/style/noNonNullAssertion: ensureStorageCapacity throws if buffer cannot be created
+      const buffer = storageBuffer!;
+      // biome-ignore lint/style/noNonNullAssertion: ensureStorageCapacity creates the pair atomically or throws
+      const previousBuffer = previousStorageBuffer!;
+      // Cursor advances by the actual joint footprint, then rounds up to
+      // PALETTE_OFFSET_ALIGN so the NEXT slice's byteOffset stays a valid
+      // dynamic offset (WebGPU requires 256-byte alignment). Slices still pack
+      // near-tightly (at most 255 B slack between them). Only the last slice's
+      // window may overhang into uninitialized buffer space, which is benign
+      // (shader reads only `jointCount` matrices).
+      storageCursor =
+        (offset + jointCount * MAT4_BYTES + (PALETTE_OFFSET_ALIGN - 1)) &
+        ~(PALETTE_OFFSET_ALIGN - 1);
+      return {
+        jointCount,
+        jointMatrices: new Float32Array(jointCount * 16),
+        byteOffset: offset,
+        buffer,
+        previousBuffer,
+      };
+    }
+    // Uniform fallback: each slice gets its own 16320 B UBO.
+    const buffer = acquirePoolBuffer(pool, 'skin-palette');
+    const previousBuffer = acquirePoolBuffer(previousPool, 'skin-palette-previous');
+    poolCursor += 1;
+    return {
+      jointCount,
+      jointMatrices: new Float32Array(jointCount * 16),
+      byteOffset: 0,
+      buffer,
+      previousBuffer,
+    };
+  }
+
+  function writeJointPalette(
+    slice: SkinPaletteSlice,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Mat4[],
+  ): void {
+    const count = Math.min(slice.jointCount, ibms.length, jointWorlds.length);
+    if (count === 0) return;
+    const payload = new Float32Array(count * 16);
+    const temp = mat4.create();
+    const ibm = mat4.create();
+    const ibmNums = ibm as unknown as number[];
+    for (let i = 0; i < count; i++) {
+      const ibmFlat = ibms[i];
+      const jw = jointWorlds[i];
+      if (ibmFlat === undefined || jw === undefined) continue;
+      for (let k = 0; k < 16; k++) {
+        ibmNums[k] = ibmFlat[k] ?? 0;
+      }
+      mat4.multiply(temp, jw, ibm);
+      const base = i * 16;
+      for (let j = 0; j < 16; j++) {
+        payload[base + j] = (temp as unknown as number[])[j] ?? 0;
+      }
+    }
+    slice.jointMatrices.set(payload);
+    const res = device.queue.writeBuffer(slice.buffer, slice.byteOffset, payload);
+    if (!res.ok) throw res.error;
+  }
+
+  function writePreviousJointPalette(slice: SkinPaletteSlice, jointMatrices: Float32Array): void {
+    const count = Math.min(slice.jointCount * 16, jointMatrices.length);
+    if (count === 0) return;
+    const payload = jointMatrices.subarray(0, count);
+    const result = device.queue.writeBuffer(
+      slice.previousBuffer ?? slice.buffer,
+      slice.byteOffset,
+      payload,
+    );
+    if (!result.ok) throw result.error;
+  }
+
+  function resetForFrame(): void {
+    storageCursor = 0;
+    poolCursor = 0;
+  }
+
+  return {
+    bindingWindowBytes: BINDING_WINDOW_BYTES,
+    useStorageBuffer,
+    allocateSlice,
+    writeJointPalette,
+    writePreviousJointPalette,
+    resetForFrame,
+  };
+}