@forgeax/engine-render 0.1.20 → 0.1.21

package/src/__tests__/render-target-public-schema.unit.test.ts

@@ -0,0 +1,91 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import * as Render from '../index';
+
+const schema = JSON.parse(
+  readFileSync(new URL('./render-target-public-schema.json', import.meta.url), 'utf8'),
+) as {
+  readonly $id: string;
+  readonly title: string;
+  readonly schemaVersion?: never;
+  readonly additionalProperties: boolean;
+  readonly properties: {
+    readonly schemaVersion: { readonly const: string };
+    readonly runtimeExports: { readonly items: { readonly enum: readonly string[] } };
+    readonly typeExports: { readonly items: { readonly enum: readonly string[] } };
+    readonly operations: {
+      readonly items: {
+        readonly properties: { readonly name: { readonly enum: readonly string[] } };
+      };
+    };
+    readonly errorCodes: { readonly items: { readonly enum: readonly string[] } };
+    readonly stableTargetIds: { readonly const: readonly string[] };
+  } & Record<string, unknown>;
+};
+
+const manifest = JSON.parse(
+  readFileSync(
+    new URL(
+      '../../../../apps/learn-render/6.pbr/4.render-target-reflection/src/feature-manifest.json',
+      import.meta.url,
+    ),
+    'utf8',
+  ),
+) as {
+  readonly stableTargetIds: readonly string[];
+  readonly evidenceCommands: readonly string[];
+  readonly operations: readonly string[];
+};
+
+describe('public render-target schema and stable consumer manifest', () => {
+  it('describes the public surface without a runtime registry', () => {
+    expect(schema.properties.schemaVersion.const).toBe('render-target-public/1');
+    expect(schema.additionalProperties).toBe(false);
+    expect(Object.keys(schema.properties)).toEqual([
+      'schemaVersion',
+      'runtimeExports',
+      'typeExports',
+      'operations',
+      'errorCodes',
+      'stableTargetIds',
+    ]);
+    for (const name of schema.properties.runtimeExports.items.enum)
+      expect(name in Render).toBe(true);
+    expect(schema.properties.typeExports.items.enum).toContain('ReflectionProbeInspection');
+    expect(schema.properties.typeExports.items.enum).toContain(
+      'ReflectionProbeSelectionInspection',
+    );
+    expect(schema.properties.typeExports.items.enum).toContain('RenderIntentInvalidDetail');
+    expect(schema.properties.operations.items.properties.name.enum).toEqual([
+      'Renderer.createRenderTarget',
+      'Renderer.resizeRenderTarget',
+      'Renderer.createRenderTargetTextureSource',
+      'Renderer.requestTargetReadback',
+      'Renderer.observe',
+      'Renderer.inspect',
+      'Renderer.recover',
+      'Renderer.destroyRenderTarget',
+    ]);
+    expect(schema.properties.errorCodes.items.enum).toEqual([
+      'render-target-descriptor-invalid',
+      'render-target-capability-missing',
+      'render-target-state-invalid',
+      'render-target-operation-failed',
+      'reflection-probe-budget-exceeded',
+      'render-intent-invalid',
+    ]);
+    expect(JSON.stringify(schema)).not.toMatch(/device|queue|encoder|handle|registry/i);
+  });
+
+  it('keeps the five stable target IDs and evidence commands aligned', () => {
+    expect(manifest.operations).toEqual(schema.properties.operations.items.properties.name.enum);
+    expect(manifest.stableTargetIds).toEqual(schema.properties.stableTargetIds.const);
+    expect(manifest.evidenceCommands).toEqual([
+      'node scripts/smoke-cube-camera-browser.mjs',
+      'node scripts/smoke-cube-camera-dawn.mjs',
+      'node scripts/smoke-reflection-probe-browser.mjs',
+      'node scripts/smoke-reflection-probe-dawn.mjs',
+    ]);
+    expect(JSON.stringify(manifest)).not.toMatch(/device|queue|encoder|handle|registry/i);
+  });
+});

package/src/__tests__/render-target-public-surface.test-d.ts

@@ -0,0 +1,83 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  RenderError,
+  RenderErrorCode,
+  Renderer,
+  RenderTarget,
+  RenderTargetDescriptor,
+  RenderTargetFormat,
+  RenderTargetReadbackTicket,
+  RenderTargetShape,
+  RenderTargetTextureSource,
+} from '../index';
+
+const formats = [
+  'rgba16float',
+  'rgba8unorm',
+  'rgba8unorm-srgb',
+] as const satisfies readonly RenderTargetFormat[];
+const shapes = ['2d', 'cube'] as const satisfies readonly RenderTargetShape[];
+
+const descriptor: RenderTargetDescriptor = {
+  shape: '2d',
+  width: 512,
+  height: 256,
+  format: 'rgba8unorm-srgb',
+  mipLevels: 'full',
+  sampleCount: 1,
+  depth: 'depth24plus-stencil8',
+  sampled: true,
+  readback: true,
+};
+
+describe('RenderTarget public surface', () => {
+  it('keeps the descriptor vocabulary closed and color-domain based', () => {
+    expectTypeOf<RenderTargetDescriptor['format']>().toEqualTypeOf<RenderTargetFormat>();
+    expectTypeOf<RenderTargetDescriptor['shape']>().toEqualTypeOf<RenderTargetShape>();
+    expectTypeOf(formats).toMatchTypeOf<readonly RenderTargetFormat[]>();
+    expectTypeOf(shapes).toMatchTypeOf<readonly RenderTargetShape[]>();
+    // @ts-expect-error target descriptors do not carry a second color-space fact.
+    const withColorSpace: RenderTargetDescriptor = { ...descriptor, colorSpace: 'srgb' };
+    void withColorSpace;
+    // @ts-expect-error array targets are outside the first public target vocabulary.
+    const arrayTarget: RenderTargetDescriptor = { ...descriptor, shape: 'array' };
+    void arrayTarget;
+  });
+
+  it('exposes opaque target values and typed Renderer operations', () => {
+    const renderer = undefined as unknown as Renderer;
+    const target = undefined as unknown as RenderTarget;
+    const source = undefined as unknown as RenderTargetTextureSource;
+    const ticket = undefined as unknown as RenderTargetReadbackTicket;
+
+    expectTypeOf(renderer.createRenderTarget(descriptor)).toMatchTypeOf<
+      | { readonly ok: true; readonly value: RenderTarget }
+      | { readonly ok: false; readonly error: RenderError }
+    >();
+    expectTypeOf(renderer.resizeRenderTarget).parameter(0).toEqualTypeOf<RenderTarget>();
+    expectTypeOf(renderer.createRenderTargetTextureSource)
+      .parameter(0)
+      .toEqualTypeOf<RenderTarget>();
+    expectTypeOf(renderer.requestTargetReadback).parameter(0).toEqualTypeOf<RenderTarget>();
+    expectTypeOf(renderer.destroyRenderTarget).parameter(0).toEqualTypeOf<RenderTarget>();
+    expectTypeOf(source).not.toEqualTypeOf(target);
+    expectTypeOf(ticket).not.toEqualTypeOf(target);
+    // @ts-expect-error opaque target values are not numeric handles.
+    const numericIdentity: number = target;
+    void numericIdentity;
+    void source;
+    void ticket;
+  });
+
+  it('keeps target failures in the closed RenderError family', () => {
+    const targetCodes = [
+      'render-target-descriptor-invalid',
+      'render-target-capability-missing',
+      'render-target-state-invalid',
+      'render-target-operation-failed',
+    ] as const satisfies readonly RenderErrorCode[];
+    expectTypeOf<(typeof targetCodes)[number]>().toEqualTypeOf<
+      Extract<RenderErrorCode, `${string}target${string}`>
+    >();
+  });
+});

package/src/__tests__/render-target-readback.integration.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderTargetDescriptor } from '../targets/contracts';
+import { createRenderTargetOwner } from '../targets/owner';
+import {
+  completeRenderTargetReadback,
+  createRenderTargetReadbackTicket,
+  type RenderTargetReadbackReceipt,
+} from '../targets/readback';
+
+const descriptor: RenderTargetDescriptor = {
+  shape: '2d',
+  width: 17,
+  height: 9,
+  format: 'rgba8unorm',
+  mipLevels: 1,
+  sampleCount: 1,
+  sampled: false,
+  readback: true,
+};
+
+function target() {
+  const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 2 });
+  const result = owner.create(descriptor);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('RenderTarget receipt-bound readback', () => {
+  it('admits a square cube target as six independently addressable faces', () => {
+    const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 3 });
+    const result = owner.create({ ...descriptor, shape: 'cube', width: 9, height: 9 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const staged = owner.stage(result.value);
+    expect(staged.ok).toBe(true);
+    if (!staged.ok) return;
+    expect(staged.value.descriptor.shape).toBe('cube');
+    expect(staged.value.descriptor.width).toBe(staged.value.descriptor.height);
+  });
+
+  it('uses 256-byte row alignment and completes exactly once for a matching receipt', () => {
+    const ticket = createRenderTargetReadbackTicket(target(), {
+      frameId: 11,
+      deviceGeneration: 2,
+      mipLevel: 0,
+      width: 17,
+      height: 9,
+      bytesPerPixel: 4,
+    });
+    expect(ticket.ok).toBe(true);
+    if (!ticket.ok) return;
+    expect(ticket.value.bytesPerRow).toBe(256);
+    expect(ticket.value.byteLength).toBe(256 * 9);
+
+    const receipt: RenderTargetReadbackReceipt = {
+      frameId: 11,
+      deviceGeneration: 2,
+    };
+    const bytes = new Uint8Array(ticket.value.byteLength);
+    const completed = completeRenderTargetReadback(ticket.value, receipt, bytes);
+    expect(completed.ok).toBe(true);
+    if (!completed.ok) return;
+    expect(completed.value.bytes).toBe(bytes);
+    expect(completeRenderTargetReadback(ticket.value, receipt, bytes).ok).toBe(false);
+  });
+
+  it('rejects mismatched frame or generation before consuming the one-shot ticket', () => {
+    const ticket = createRenderTargetReadbackTicket(target(), {
+      frameId: 4,
+      deviceGeneration: 8,
+      mipLevel: 0,
+      width: 1,
+      height: 1,
+      bytesPerPixel: 8,
+    });
+    expect(ticket.ok).toBe(true);
+    if (!ticket.ok) return;
+    const bytes = new Uint8Array(ticket.value.byteLength);
+    const stale = completeRenderTargetReadback(
+      ticket.value,
+      { frameId: 5, deviceGeneration: 8 },
+      bytes,
+    );
+    expect(stale.ok).toBe(false);
+    if (!stale.ok) expect(stale.error.code).toBe('render-target-state-invalid');
+    expect(
+      completeRenderTargetReadback(ticket.value, { frameId: 4, deviceGeneration: 8 }, bytes).ok,
+    ).toBe(true);
+  });
+});

package/src/__tests__/render-target-recovery.integration.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderTargetDescriptor } from '../targets/contracts';
+import { createRenderTargetOwner } from '../targets/owner';
+import {
+  bindRenderTargetReadbackTicket,
+  completeRenderTargetReadback,
+  createRenderTargetReadbackTicket,
+} from '../targets/readback';
+
+const descriptor: RenderTargetDescriptor = {
+  shape: 'cube',
+  width: 4,
+  height: 4,
+  format: 'rgba8unorm-srgb',
+  mipLevels: 1,
+  sampleCount: 4,
+  sampled: true,
+  readback: true,
+};
+
+describe('RenderTarget recovery integration', () => {
+  it('keeps the logical token and LKG while a candidate aborts', () => {
+    const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 3 });
+    const target = owner.create(descriptor);
+    expect(target.ok).toBe(true);
+    if (!target.ok) return;
+    const candidate = owner.stage(target.value);
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+    expect(owner.promote(target.value, candidate.value.generation).ok).toBe(true);
+    const resized = owner.stage(target.value, { ...descriptor, width: 8, height: 8 });
+    expect(resized.ok).toBe(true);
+    if (!resized.ok) return;
+    expect(owner.rejectCandidate(target.value, resized.value.generation, 'submit').ok).toBe(false);
+    const inspection = owner.inspect(target.value);
+    expect(inspection.ok).toBe(true);
+    if (inspection.ok) {
+      expect(inspection.value.token).toBe(target.value);
+      expect(inspection.value.state).toBe('active');
+      expect(inspection.value.generation).toBe(3);
+      expect(inspection.value.descriptor.width).toBe(4);
+    }
+  });
+
+  it('retires the old generation before rebuilding readback state', () => {
+    const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 1 });
+    const target = owner.create(descriptor);
+    expect(target.ok).toBe(true);
+    if (!target.ok) return;
+    const staged = owner.stage(target.value);
+    expect(staged.ok).toBe(true);
+    if (!staged.ok) return;
+    expect(owner.promote(target.value, 1).ok).toBe(true);
+    const ticket = createRenderTargetReadbackTicket(target.value, {
+      deviceGeneration: 1,
+      mipLevel: 0,
+      face: 2,
+      width: 4,
+      height: 4,
+      bytesPerPixel: 4,
+    });
+    expect(ticket.ok).toBe(true);
+    if (!ticket.ok) return;
+    expect(
+      bindRenderTargetReadbackTicket(ticket.value, { frameId: 7, deviceGeneration: 1 }).ok,
+    ).toBe(true);
+    expect(owner.beginRecovery(target.value, 2).ok).toBe(true);
+    expect(owner.finishRecovery(target.value).ok).toBe(true);
+    const stale = completeRenderTargetReadback(
+      ticket.value,
+      { frameId: 8, deviceGeneration: 2 },
+      new Uint8Array(ticket.value.byteLength),
+    );
+    expect(stale.ok).toBe(false);
+    if (!stale.ok) expect(stale.error.code).toBe('render-target-state-invalid');
+    const recovered = owner.inspect(target.value);
+    expect(recovered.ok).toBe(true);
+    if (recovered.ok)
+      expect(recovered.value).toMatchObject({
+        token: target.value,
+        state: 'uninitialized',
+        generation: 2,
+      });
+  });
+});

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -99,6 +99,54 @@ describe('material shader variant identity', () => {
     ).toBe('urp');
   });
 
+  it('rewrites directional PCSS to the backend-owned WebGL2 shader variant', () => {
+    const variants = [
+      {
+        defines: {
+          STORAGE_BUFFER_AVAILABLE: false,
+          DIRECTIONAL_PCSS_AVAILABLE: false,
+        },
+      },
+      {
+        defines: {
+          STORAGE_BUFFER_AVAILABLE: true,
+          DIRECTIONAL_PCSS_AVAILABLE: true,
+        },
+      },
+    ];
+
+    expect(
+      resolveMaterialShaderVariantSet(
+        'DIRECTIONAL_PCSS_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true',
+        variants,
+        'wgpu-webgl2',
+        false,
+      ),
+    ).toBe('DIRECTIONAL_PCSS_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false');
+    expect(
+      resolveMaterialShaderVariantSet(
+        'DIRECTIONAL_PCSS_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+        variants,
+        'webgpu',
+        true,
+      ),
+    ).toBe('');
+  });
+
+  it('fails closed when a clustered layout is unavailable', () => {
+    expect(
+      selectPipelineLayoutForVariant(
+        {
+          pbrPipelineLayout: 'urp' as never,
+          hdrpPbrPipelineLayout: null,
+          pbrSkinPipelineLayout: null,
+        },
+        '',
+        'hdrp-pbr',
+      ),
+    ).toBeNull();
+  });
+
   it('does not promote an omitted semantic axis to true', () => {
     const resolved = resolveMaterialShaderVariantSet(
       'VERTEX_COLOR_AVAILABLE=true',

package/src/__tests__/renderer-lifecycle.integration.test.ts

@@ -6,6 +6,20 @@ import { RenderRecoveryError } from '../errors/recover';
 import { LifecycleConstructionError, type RenderError } from '../errors/render';
 
 describe('renderer lifecycle', () => {
+  it('keeps cube capture in the existing renderer lifecycle boundary', () => {
+    const calls: string[] = [];
+    const frame = () => {
+      calls.push('extract');
+      calls.push('encode');
+      calls.push('finish');
+      calls.push('submit');
+    };
+    frame();
+    expect(calls).toEqual(['extract', 'encode', 'finish', 'submit']);
+    expect(calls.filter((call) => call === 'extract')).toHaveLength(1);
+    expect(calls.filter((call) => call === 'submit')).toHaveLength(1);
+  });
+
   it('rejects missing construction input', async () => {
     await expect(constructRenderer(undefined, { rhi })).rejects.toBeDefined();
   });

package/src/__tests__/shader-stage-surface.unit.test.ts

@@ -5,14 +5,20 @@ import {
   GPU_SHADER_STAGE_FRAGMENT,
   GPU_SHADER_STAGE_VERTEX,
 } from '../gpu-stage';
+import { createHdrpBindGroupLayoutDescriptor } from '../pbr-pipeline';
 
 const ownerSource = readFileSync(new URL('../gpu-stage.ts', import.meta.url), 'utf8');
 const computeConsumerSources = [
   readFileSync(new URL('../hdrp-buffers.ts', import.meta.url), 'utf8'),
 ];
+const pbrPipelineSource = readFileSync(new URL('../pbr-pipeline.ts', import.meta.url), 'utf8');
+const iblPipelineCacheSource = readFileSync(
+  new URL('../ibl/IblPipelineCache.ts', import.meta.url),
+  'utf8',
+);
 const fragmentConsumerSources = [
-  readFileSync(new URL('../pbr-pipeline.ts', import.meta.url), 'utf8'),
-  readFileSync(new URL('../ibl/IblPipelineCache.ts', import.meta.url), 'utf8'),
+  pbrPipelineSource,
+  iblPipelineCacheSource,
   readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8'),
   readFileSync(new URL('../assembly/factory.ts', import.meta.url), 'utf8'),
 ];
@@ -37,7 +43,16 @@ describe('shader stage owner', () => {
     for (const source of computeConsumerSources) {
       expect(source).toContain('GPU_SHADER_STAGE_COMPUTE');
     }
-    expect(fragmentConsumerSources[0]).toContain('GPU_SHADER_STAGE_VERTEX');
-    expect(fragmentConsumerSources[1]).toContain('GPU_SHADER_STAGE_VERTEX');
+    expect(pbrPipelineSource).toContain('GPU_SHADER_STAGE_VERTEX');
+    expect(iblPipelineCacheSource).toContain('GPU_SHADER_STAGE_VERTEX');
+  });
+
+  it('keeps HDRP mesh storage visible to both mesh consumers', () => {
+    const group2 = createHdrpBindGroupLayoutDescriptor().entries?.find(
+      (entry) => entry.binding === 0,
+    );
+
+    expect(group2?.visibility).toBe(GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT);
+    expect(group2?.buffer?.type).toBe('read-only-storage');
   });
 });

package/src/__tests__/skin-motion-regression.unit.test.ts

@@ -0,0 +1,132 @@
+import type { Mat4 } from '@forgeax/engine-math';
+import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  selectHdrpPbrPrewarmVariants,
+  selectPipelineLayoutForVariant,
+  selectSkinPrewarmVariants,
+} from '../assembly/factory';
+import { resolvePipelineGroup2Contract } from '../pbr-pipeline';
+import { createSkinPaletteAllocator } from '../systems/skin-palette-allocator';
+
+describe('custom skinned mesh motion consumer contract', () => {
+  it('keeps two animated palette payloads observable at the skin consumer', () => {
+    const writes: Array<{ buffer: Buffer; offset: number; data: Float32Array }> = [];
+    const device = {
+      limits: { maxStorageBufferBindingSize: 65536 },
+      createBuffer: () => ok({} as Buffer),
+      queue: {
+        writeBuffer(buffer: Buffer, offset: number, data: Float32Array) {
+          writes.push({ buffer, offset, data: new Float32Array(data) });
+          return ok(undefined);
+        },
+      },
+    } as unknown as RhiDevice;
+    const allocator = createSkinPaletteAllocator(device, 65536, true);
+    const ibm = new Float32Array(16);
+    ibm[0] = 1;
+    ibm[5] = 1;
+    ibm[10] = 1;
+    ibm[15] = 1;
+    const poseA = new Float32Array(ibm) as unknown as Mat4;
+    const poseB = new Float32Array(ibm) as unknown as Mat4;
+    poseB[12] = 0.5;
+    const first = allocator.allocateSlice(1);
+    allocator.writeJointPalette(first, [ibm], [poseA]);
+    allocator.resetForFrame();
+    const second = allocator.allocateSlice(1);
+    allocator.writeJointPalette(second, [ibm], [poseB]);
+
+    expect(writes).toHaveLength(2);
+    expect(writes[0]?.buffer).toBe(writes[1]?.buffer);
+    expect(writes[0]?.offset).toBe(writes[1]?.offset);
+    expect(writes[0]?.data).not.toEqual(writes[1]?.data);
+    expect(writes[1]?.data[12]).toBe(0.5);
+  });
+
+  it('prepares both URP and HDRP pbr-skin consumers with the skin-cluster contract', () => {
+    const variants = selectSkinPrewarmVariants(
+      {
+        identifier: 'forgeax::pbr-skin',
+        sourcePath: 'default-standard-pbr-skin.wgsl',
+        composedWgsl: '@group(2) @binding(1) var<storage> palette: array<u32>;',
+        paramSchema: '[]',
+        variants: [
+          {
+            definesKey:
+              'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+            defines: {
+              CLUSTER_FORWARD_AVAILABLE: false,
+              STORAGE_BUFFER_AVAILABLE: true,
+              VERTEX_COLOR_AVAILABLE: false,
+            },
+            composedWgsl: '@group(2) @binding(1) var<storage> palette: array<u32>;',
+          },
+          {
+            definesKey:
+              'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+            defines: {
+              CLUSTER_FORWARD_AVAILABLE: true,
+              STORAGE_BUFFER_AVAILABLE: true,
+              VERTEX_COLOR_AVAILABLE: false,
+            },
+            composedWgsl:
+              '@group(2) @binding(1) var<storage> palette: array<u32>; @group(2) @binding(4) var<storage> lights: array<u32>;',
+          },
+        ],
+      },
+      true,
+    );
+    expect(variants.map((variant) => variant.definesKey)).toEqual([
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+    ]);
+    expect(resolvePipelineGroup2Contract(variants[1]?.composedWgsl ?? '')).toBe('skin-cluster');
+    expect(
+      selectPipelineLayoutForVariant(
+        {
+          pbrPipelineLayout: 'urp' as never,
+          hdrpPbrPipelineLayout: 'hdrp' as never,
+          pbrSkinPipelineLayout: 'skin-urp' as never,
+          hdrpSkinPipelineLayout: 'skin-hdrp' as never,
+        },
+        variants[1]?.definesKey,
+        'hdrp-skin',
+      ),
+    ).toBe('skin-hdrp');
+  });
+
+  it('does not expose clustered skin or HDRP PBR prewarm variants on WebGL2', () => {
+    const variants = [
+      {
+        definesKey: 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false',
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: false,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+        composedWgsl: 'urp-uniform',
+      },
+      {
+        definesKey: 'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=false',
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: true,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+        composedWgsl: 'hdrp-uniform',
+      },
+    ];
+    const entry = {
+      identifier: 'forgeax::default-standard-pbr-skin',
+      sourcePath: 'default-standard-pbr-skin.wgsl',
+      composedWgsl: 'default',
+      paramSchema: '[]',
+      variants,
+    };
+
+    expect(selectSkinPrewarmVariants(entry, false).map((variant) => variant.definesKey)).toEqual([
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false',
+    ]);
+    expect(selectHdrpPbrPrewarmVariants(entry, false, true)).toEqual([]);
+  });
+});

package/src/__tests__/skinned-shadow-caster.test.ts

@@ -3,7 +3,9 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 import { resolveMaterialShaderVariantSet } from '../assembly/factory';
 import {
+  createPbrSkinMeshBindGroupEntries,
   isSkinnedShadowCasterVariant,
+  pbrSkinMeshDynamicOffsets,
   SHADOW_CASTER_SHADER_ID,
   shadowCasterVariantSet,
 } from '../pbr-pipeline.js';
@@ -96,8 +98,15 @@ describe('skinned shadow caster', () => {
     expect(recordSource).toContain(
       "'shadow-caster',\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      'pbr'",
     );
-    expect(recordSource).toContain('shadowPass.setBindGroup(2, skinMeshBindGroup, [');
-    expect(recordSource).toContain('entry.source.skin.byteOffset');
+    expect(recordSource).toContain('createPbrSkinMeshBindGroupEntries(');
+    expect(recordSource).toContain('pbrSkinMeshDynamicOffsets(');
+
+    const meshBuffer = {} as never;
+    const paletteBuffer = {} as never;
+    const entries = createPbrSkinMeshBindGroupEntries(meshBuffer, 64, paletteBuffer, 128);
+    expect(entries.map((entry) => entry.binding)).toEqual([0, 1, 2]);
+    expect(entries[1]?.resource).toEqual(entries[2]?.resource);
+    expect(pbrSkinMeshDynamicOffsets(256, 512)).toEqual([256, 512, 512]);
   });
 
   it('keeps low-limit shadow view bindings paired with the optional projector layout', () => {