@forgeax/engine-runtime 0.1.2

package/src/__tests__/name.unit.test.ts

@@ -0,0 +1,123 @@
+// Name component (built-in, runtime-owned) — schema literal + identity +
+// AC-13 invariant + spawn/set fallback. Migrated from
+// packages/ecs/src/__tests__/hierarchy.unit.test.ts (name-component +
+// name-mutation paragraphs) by tweak-20260612-ecs-concept-compression: Name's
+// authoritative location is now @forgeax/engine-runtime, not the ECS framework.
+
+import { type SchemaOf, World } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { Name } from '@forgeax/engine-scene';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('Name component --- schema literal (w2, AC-03 a/d)', () => {
+  it('componentSchema(Name) deep-equals { value: "string" } (KD-4 single field)', () => {
+    expect(componentSchema(Name)).toEqual({ value: 'string' });
+    expect(Object.keys(componentSchema(Name))).toEqual(['value']);
+  });
+
+  it('componentSchema(Name).value preserved as literal "string", not widened', () => {
+    type ValueField = SchemaOf<typeof Name>['value'];
+    expectTypeOf<ValueField>().toEqualTypeOf<'string'>();
+  });
+});
+
+describe('Name component --- identity (w2, AC-03 b)', () => {
+  it('Name.name === "Name" (no Component suffix per AGENTS.md naming)', () => {
+    expect(Name.name).toBe('Name');
+  });
+});
+
+describe('Name component --- single-import surface (w2, AC-03 c / AC-11)', () => {
+  it('Name resolves through the runtime barrel re-export', () => {
+    expect(Name).toBeDefined();
+    expect(typeof Name).toBe('object');
+  });
+});
+
+describe('Name component --- AC-13 schema invariant (w20)', () => {
+  it("componentSchema(Name)['value'] is the literal 'string'", () => {
+    expect(componentSchema(Name).value).toBe('string');
+    type ValueField = SchemaOf<typeof Name>['value'];
+    expectTypeOf<ValueField>().toEqualTypeOf<'string'>();
+  });
+
+  it('world.get(e, Name).unwrap().value returns a native JS string at runtime', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'Hero' } }).unwrap();
+    const value = w.get(e, Name).unwrap().value;
+    expect(typeof value).toBe('string');
+    expect(value).toBe('Hero');
+  });
+
+  it('world.get(e, Name).unwrap().value infers as string at the type level', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'X' } }).unwrap();
+    const value = w.get(e, Name).unwrap().value;
+    expectTypeOf(value).toEqualTypeOf<string>();
+  });
+});
+
+describe('w10 --- Name spawn + read (AC-04 a)', () => {
+  it('spawn with { value: "Player" } -> get returns native string "Player"', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'Player' } }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('Player');
+    expect(typeof got.value.value).toBe('string');
+  });
+});
+
+describe('w10 --- Name rename via world.set (AC-04 b)', () => {
+  it('world.set overwrites value; subsequent get returns the new string', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'Player' } }).unwrap();
+    w.set(e, Name, { value: 'Boss' }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('Boss');
+    expect(typeof got.value.value).toBe('string');
+  });
+
+  it('successive sets each show through to the next read', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: { value: 'a' } }).unwrap();
+    w.set(e, Name, { value: 'bb' }).unwrap();
+    expect(w.get(e, Name).unwrap().value).toBe('bb');
+    w.set(e, Name, { value: 'ccc' }).unwrap();
+    expect(w.get(e, Name).unwrap().value).toBe('ccc');
+  });
+});
+
+describe('w10 --- AC-06 spawn fallback (raw=undefined / null / number -> "")', () => {
+  it('spawn with no data field reads as empty string', () => {
+    const w = new World();
+    const e = w.spawn({ component: Name, data: {} }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('');
+    expect(typeof got.value.value).toBe('string');
+  });
+
+  it('spawn with data.value=null reads as empty string', () => {
+    const w = new World();
+    // @ts-expect-error AC-09 strict signature rejects null; runtime
+    // fallback (AC-06) coerces null to '' — testing that runtime path.
+    const e = w.spawn({ component: Name, data: { value: null } }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('');
+    expect(typeof got.value.value).toBe('string');
+  });
+
+  it('spawn with data.value=<number> reads as empty string', () => {
+    const w = new World();
+    // @ts-expect-error AC-09 strict signature rejects number for `string` field;
+    // runtime fallback (AC-06) coerces non-string to '' — testing that runtime path.
+    const e = w.spawn({ component: Name, data: { value: 42 } }).unwrap();
+    const got = w.get(e, Name);
+    if (!got.ok) throw new Error('expected ok');
+    expect(got.value.value).toBe('');
+    expect(typeof got.value.value).toBe('string');
+  });
+});

package/src/__tests__/node-shims.d.ts

@@ -0,0 +1,33 @@
+// Ambient declarations for node:* modules used by dawn tests that read the
+// hello-triangle compiled shader manifest at runtime. The runtime package's
+// tsconfig does not enable @types/node (production target is browser); these
+// minimal shims keep tsc green for the 3 shadow dawn test files only.
+//
+// Used by:
+// - shadow-m2.dawn.test.ts
+// - shadow-m3.dawn.test.ts
+// - shadow-m3-calibrate-run.dawn.test.ts
+// - tilemap-chunk-y-sort-bench.unit.test.ts (perf_hooks + process.env)
+// - render-system-fold-scene-instances.unit.test.ts (readdirSync + dirname)
+// - basis-catalog-dispatch.integration.test.ts (existsSync pkg-built gate)
+
+declare module 'node:fs' {
+  export function readFileSync(path: string, encoding: string): string;
+  export function readdirSync(path: string): string[];
+  export function existsSync(path: string): boolean;
+}
+
+declare module 'node:path' {
+  export function resolve(...paths: string[]): string;
+  export function dirname(p: string): string;
+}
+
+declare module 'node:url' {
+  export function fileURLToPath(url: string | URL): string;
+}
+
+declare module 'node:perf_hooks' {
+  export const performance: { now(): number };
+}
+
+declare const process: { env: Record<string, string | undefined> };

package/src/__tests__/pass-selector.unit.test.ts

@@ -0,0 +1,102 @@
+import { matchPass, selectPasses } from '@forgeax/engine-render/internal';
+import type { MaterialPass, PassSelector } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+/*
+ * feat-20260609 M1 / T-003: AddScenePass/AddShadowPass selector required.
+ *
+ * These tests verify the PassSelector matching semantics:
+ *   - selector: {} matches every pass (AC-02)
+ *   - selector with a key filters passes that have that tag key + value in the
+ *     allowed list
+ *   - selector with multiple keys requires all keys to match (AND logic)
+ */
+
+function makePass(name: string, tags?: Record<string, string>): MaterialPass {
+  if (tags !== undefined) {
+    return { name, program: { module: 'forgeax_material::unlit' }, renderState: { tags } };
+  }
+  return { name, program: { module: 'forgeax_material::unlit' } };
+}
+
+describe('pass-selector semantics', () => {
+  describe('selector: {} = match all', () => {
+    it('returns the input array reference (no filtering) for empty selector', () => {
+      const passes = [
+        makePass('Forward', { LightMode: 'Forward' }),
+        makePass('ShadowCaster', { LightMode: 'ShadowCaster' }),
+        makePass('Untagged'),
+      ];
+      const result = selectPasses(passes, {});
+      // AC-02: empty selector returns the input reference unchanged (no array copy)
+      expect(result).toBe(passes);
+      expect(result.length).toBe(3);
+    });
+
+    it('returns empty array reference when input is empty and selector is empty', () => {
+      const passes: MaterialPass[] = [];
+      const result = selectPasses(passes, {});
+      expect(result).toBe(passes);
+      expect(result.length).toBe(0);
+    });
+  });
+
+  describe('selector filtering', () => {
+    it('filters passes by single tag key', () => {
+      const passes = [
+        makePass('Forward', { LightMode: 'Forward' }),
+        makePass('ShadowCaster', { LightMode: 'ShadowCaster' }),
+        makePass('Untagged'),
+      ];
+      const selector: PassSelector = { LightMode: ['Forward'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(1);
+      expect(result[0]?.name).toBe('Forward');
+    });
+
+    it('filters passes by multiple allowed values for one key', () => {
+      const passes = [
+        makePass('Forward', { LightMode: 'Forward' }),
+        makePass('ShadowCaster', { LightMode: 'ShadowCaster' }),
+        makePass('Untagged'),
+      ];
+      const selector: PassSelector = { LightMode: ['Forward', 'ShadowCaster'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(2);
+      expect(result.map((p) => p.name).sort()).toEqual(['Forward', 'ShadowCaster']);
+    });
+
+    it('returns empty array when no pass matches', () => {
+      const passes = [makePass('Forward', { LightMode: 'Forward' })];
+      const selector: PassSelector = { LightMode: ['ShadowCaster'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(0);
+    });
+
+    it('requires all selector keys to match (AND logic)', () => {
+      const passes = [
+        makePass('A', { Kind: 'Opaque', RenderType: 'Main' }),
+        makePass('B', { Kind: 'Transparent', RenderType: 'Main' }),
+        makePass('C', { Kind: 'Opaque', RenderType: 'Shadow' }),
+      ];
+      const selector: PassSelector = { Kind: ['Opaque'], RenderType: ['Main'] };
+      const result = selectPasses(passes, selector);
+      expect(result.length).toBe(1);
+      expect(result[0]?.name).toBe('A');
+    });
+  });
+
+  describe('matchPass edge cases', () => {
+    it('tags with no matching key -> false', () => {
+      expect(matchPass({ LightMode: 'Forward' }, { LightMode: ['ShadowCaster'] })).toBe(false);
+    });
+
+    it('missing key in tags -> false', () => {
+      expect(matchPass({}, { LightMode: ['Forward'] })).toBe(false);
+    });
+
+    it('empty allowed values array -> false', () => {
+      expect(matchPass({ LightMode: 'Forward' }, { LightMode: [] })).toBe(false);
+    });
+  });
+});

package/src/__tests__/pbr-pipeline.unit.test.ts

@@ -0,0 +1,204 @@
+// pbr-pipeline.unit.test.ts -- M3-T1-TEST: byte-equiv guard for D-13 dispatcher.
+//
+// For each of the 6 createBindGroupLayout sites in pbr-pipeline.ts
+// (view / material-merged / mesh-array / instances / skin-mesh-array /
+// unlit-material), assert that the descriptor passed to
+// device.createBindGroupLayout(...) deep-equals
+// buildBindGroupLayoutDescriptor(spec, { kind, caps }).
+//
+// This pins M3-T1's byte-equiv refactor: the 6 hand-written entries[] arrays
+// must be replaced by buildBindGroupLayoutDescriptor calls without changing
+// what the device sees.
+
+import type { PipelineSpec } from '@forgeax/engine-render/internal';
+import {
+  appendInjection,
+  buildBindGroupLayoutDescriptor,
+  buildPbrMaterialUserRegionEntries,
+  buildPbrViewBglEntries,
+} from '@forgeax/engine-render/internal';
+import { DEFAULT_UNLIT_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+// Stable spec stub — the dispatcher uses spec.shader for reflection only when
+// a registry is supplied; without registry the BGL shape comes purely from
+// the kind + caps inputs.
+function makeSpec(): PipelineSpec {
+  return {
+    shader: {
+      id: 'forgeax::default-standard-pbr',
+      passKind: 'forward',
+      variantSet: undefined,
+    },
+    attachments: {
+      colorFormats: ['rgba8unorm-srgb'],
+      depthFormat: 'depth24plus-stencil8',
+      sampleCount: 1,
+    },
+    geometry: {
+      topology: 'triangle-list',
+      vertexLayout: {},
+    },
+    renderState: undefined,
+  };
+}
+
+describe('buildBindGroupLayoutDescriptor — pbr-pipeline 6 sites byte-equiv', () => {
+  describe('pbr-view', () => {
+    it('storageBuffer=true: 9 entries with read-only-storage on bindings 1+2', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-view',
+        caps: { storageBuffer: true },
+      });
+      const expected = {
+        label: 'pbr-view-bgl',
+        entries: buildPbrViewBglEntries({ storageBuffer: true }),
+      };
+      expect(out).toEqual(expected);
+      // feat-20260625-spot-light-shadow-mapping: binding 8 (spot shadow atlas,
+      // w14) raised the view BGL to 9 entries (always-on, D-5). w25 (scope-amend
+      // webkit-fallback) folded the former binding 9 spotLightViewProj matrices
+      // UBO into the View UBO (`view.spotLightViewProj`), so the BGL stays at 9
+      // entries (bindings 0..8) — keeping the WebGL2 fallback fragment uniform-
+      // buffer count <= 11 (GLES 3.0).
+      expect(out.entries.length).toBe(9);
+    });
+
+    it('storageBuffer=false: bindings 1+2 fall back to uniform', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-view',
+        caps: { storageBuffer: false },
+      });
+      const expected = {
+        label: 'pbr-view-bgl',
+        entries: buildPbrViewBglEntries({ storageBuffer: false }),
+      };
+      expect(out).toEqual(expected);
+    });
+  });
+
+  describe('pbr-material-merged', () => {
+    it('20 entries: user-region 13 (derived) + ibl 7', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-material-merged',
+      });
+      // Post-M2 (D-1): user-region comes from derive(paramSchema).bglEntries
+      // (built-in standard-PBR 6-texture fallback), then IBL is appended at
+      // start = userRegion.length.
+      const userRegion = buildPbrMaterialUserRegionEntries();
+      const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
+      const expected = {
+        label: 'pbr-material-skylight-bgl',
+        entries: afterIbl,
+      };
+      expect(out).toEqual(expected);
+      expect(out.entries.length).toBe(20);
+    });
+  });
+
+  describe('pbr-mesh-array', () => {
+    it('storageBuffer=true: 1 entry with read-only-storage + dynamic offset + VERTEX|FRAGMENT visibility', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-mesh-array',
+        caps: { storageBuffer: true },
+      });
+      expect(out).toEqual({
+        label: 'pbr-mesh-array-bgl',
+        entries: [
+          {
+            binding: 0,
+            visibility: 0x1 | 0x2,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: true },
+          },
+        ],
+      });
+    });
+
+    it('storageBuffer=false: falls back to uniform', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-mesh-array',
+        caps: { storageBuffer: false },
+      });
+      expect(out.entries[0]?.buffer?.type).toBe('uniform');
+    });
+  });
+
+  describe('pbr-instances', () => {
+    it('storageBuffer=true: 1 entry with read-only-storage, no dynamic offset', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-instances',
+        caps: { storageBuffer: true },
+      });
+      expect(out).toEqual({
+        label: 'pbr-instances-bgl',
+        entries: [
+          {
+            binding: 0,
+            visibility: 0x1,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+          },
+        ],
+      });
+    });
+
+    it('storageBuffer=false: falls back to uniform', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-instances',
+        caps: { storageBuffer: false },
+      });
+      expect(out.entries[0]?.buffer?.type).toBe('uniform');
+    });
+  });
+
+  describe('pbr-skin-mesh-array', () => {
+    it('storageBuffer=true: mesh plus current/previous palettes use dynamic offsets', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'pbr-skin-mesh-array',
+        caps: { storageBuffer: true },
+      });
+      expect(out).toEqual({
+        label: 'pbr-skin-mesh-array-bgl',
+        entries: [
+          {
+            binding: 0,
+            visibility: 0x3,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: true },
+          },
+          {
+            binding: 1,
+            visibility: 0x1,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: true },
+          },
+          {
+            binding: 2,
+            visibility: 0x1,
+            buffer: { type: 'read-only-storage', hasDynamicOffset: true },
+          },
+        ],
+      });
+    });
+  });
+
+  describe('unlit-material', () => {
+    it('3 entries: reflected unlit material only (no skylight injection)', () => {
+      const spec = makeSpec();
+      const out = buildBindGroupLayoutDescriptor(spec, {
+        kind: 'unlit-material',
+      });
+      expect(out).toEqual({
+        label: 'unlit-material-bgl',
+        entries: buildPbrMaterialUserRegionEntries(derive(DEFAULT_UNLIT_PARAM_SCHEMA)),
+      });
+      expect(out.entries.length).toBe(3);
+    });
+  });
+});

package/src/__tests__/pipeline-builder-msaa.unit.test.ts

@@ -0,0 +1,224 @@
+/*
+ * bug-20260615-msaa-silently-disables-custom-material-shaders M2 / m2-1:
+ * buildPipelineForMaterialShader multisample descriptor shape.
+ *
+ * Asserts that the `sampleCount` parameter drives the `multisample` field in
+ * the descriptor handed to `device.createRenderPipeline`:
+ *   - sampleCount=1 (default) → multisample === undefined
+ *   - sampleCount=4 → multisample === { count: 4 }
+ *
+ * The mock device captures the descriptor via `vi.fn()`. The shader-module
+ * factory stub returns a dummy ShaderModule so the pipeline build reaches
+ * the descriptor stage without a real GPU.
+ */
+
+import {
+  buildPipelineForMaterialShader,
+  type PipelineBuilderContext,
+} from '@forgeax/engine-render/internal';
+import {
+  ok,
+  type RenderPipeline,
+  type Result,
+  type RhiDevice,
+  type RhiError,
+  type ShaderModule,
+} from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+
+function fakeShaderModule(): ShaderModule {
+  return { label: 'fake-module' } as unknown as ShaderModule;
+}
+
+function fakeRenderPipeline(): RenderPipeline {
+  return { label: 'fake-pipeline' } as unknown as RenderPipeline;
+}
+
+function fakeEntry() {
+  return {
+    source:
+      'fn vs_main() -> @builtin(position) vec4f { return vec4f(0.0); } fn fs_main() -> @location(0) vec4f { return vec4f(1.0); }',
+    paramSchema: [],
+  };
+}
+
+function buildCtx(
+  overrides: Partial<PipelineBuilderContext> & {
+    createPipelineSpy: ReturnType<typeof vi.fn>;
+  },
+): PipelineBuilderContext {
+  return {
+    device: {
+      createRenderPipeline: overrides.createPipelineSpy,
+    } as unknown as RhiDevice,
+    shaderModuleFactory: {
+      createShaderModule: vi.fn(() => ok(fakeShaderModule())),
+    },
+    pipelineLayout: undefined as unknown as PipelineBuilderContext['pipelineLayout'],
+    colorFormat: 'bgra8unorm' as unknown as GPUTextureFormat,
+    depthFormat: 'depth24plus-stencil8' as unknown as GPUTextureFormat,
+    vertexBuffers: [],
+    ...overrides,
+  };
+}
+
+describe('buildPipelineForMaterialShader multisample descriptor (M2)', () => {
+  it('sampleCount=1 (default) produces multisample: undefined', () => {
+    const spy = vi.fn<(desc: unknown) => Result<RenderPipeline, RhiError>>(
+      () => ok(fakeRenderPipeline()) as unknown as Result<RenderPipeline, RhiError>,
+    );
+    const ctx = buildCtx({ createPipelineSpy: spy });
+
+    buildPipelineForMaterialShader(
+      'test::shader',
+      fakeEntry(),
+      ctx,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'forward',
+      1,
+    );
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    const desc = spy.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(desc.multisample).toBeUndefined();
+  });
+
+  it('default sampleCount (omitted) produces multisample: undefined', () => {
+    const spy = vi.fn<(desc: unknown) => Result<RenderPipeline, RhiError>>(
+      () => ok(fakeRenderPipeline()) as unknown as Result<RenderPipeline, RhiError>,
+    );
+    const ctx = buildCtx({ createPipelineSpy: spy });
+
+    buildPipelineForMaterialShader('test::shader', fakeEntry(), ctx);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    const desc = spy.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(desc.multisample).toBeUndefined();
+  });
+
+  it('sampleCount=4 produces multisample: { count: 4 }', () => {
+    const spy = vi.fn<(desc: unknown) => Result<RenderPipeline, RhiError>>(
+      () => ok(fakeRenderPipeline()) as unknown as Result<RenderPipeline, RhiError>,
+    );
+    const ctx = buildCtx({ createPipelineSpy: spy });
+
+    buildPipelineForMaterialShader(
+      'test::shader',
+      fakeEntry(),
+      ctx,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'forward',
+      4,
+    );
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    const desc = spy.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(desc.multisample).toEqual({ count: 4 });
+  });
+
+  it('sampleCount=4 carries alpha-to-coverage into the multisample descriptor', () => {
+    const spy = vi.fn<(desc: unknown) => Result<RenderPipeline, RhiError>>(
+      () => ok(fakeRenderPipeline()) as unknown as Result<RenderPipeline, RhiError>,
+    );
+    const ctx = buildCtx({ createPipelineSpy: spy });
+
+    buildPipelineForMaterialShader(
+      'test::shader',
+      fakeEntry(),
+      ctx,
+      { alphaToCoverageEnabled: true },
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'forward',
+      4,
+    );
+
+    const desc = spy.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(desc.multisample).toEqual({ count: 4, alphaToCoverageEnabled: true });
+  });
+
+  it('sampleCount=2 narrowed to 1 per PipelineSpec contract (1 | 4 only)', () => {
+    // M2-T4: PipelineSpec.sampleCount is 1 | 4 (closed set). sampleCount=2
+    // is narrowed to 1 by the pipeline-builder, producing undefined multisample.
+    // When sampleCount=2 is added to the union, this test must be reverted.
+    const spy = vi.fn<(desc: unknown) => Result<RenderPipeline, RhiError>>(
+      () => ok(fakeRenderPipeline()) as unknown as Result<RenderPipeline, RhiError>,
+    );
+    const ctx = buildCtx({ createPipelineSpy: spy });
+
+    buildPipelineForMaterialShader(
+      'test::shader',
+      fakeEntry(),
+      ctx,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'forward',
+      2,
+    );
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    const desc = spy.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(desc.multisample).toBeUndefined();
+  });
+
+  it('shadow-caster pass with sampleCount=1 produces multisample: undefined', () => {
+    const spy = vi.fn<(desc: unknown) => Result<RenderPipeline, RhiError>>(
+      () => ok(fakeRenderPipeline()) as unknown as Result<RenderPipeline, RhiError>,
+    );
+    const ctx = buildCtx({ createPipelineSpy: spy });
+
+    buildPipelineForMaterialShader(
+      'test::shadow',
+      fakeEntry(),
+      ctx,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'shadow-caster',
+      1,
+    );
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    const desc = spy.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(desc.multisample).toBeUndefined();
+  });
+
+  it('shadow-caster pass with sampleCount=4 produces multisample: { count: 4 }', () => {
+    const spy = vi.fn<(desc: unknown) => Result<RenderPipeline, RhiError>>(
+      () => ok(fakeRenderPipeline()) as unknown as Result<RenderPipeline, RhiError>,
+    );
+    const ctx = buildCtx({ createPipelineSpy: spy });
+
+    buildPipelineForMaterialShader(
+      'test::shadow',
+      fakeEntry(),
+      ctx,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'shadow-caster',
+      4,
+    );
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    const desc = spy.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(desc.multisample).toEqual({ count: 4 });
+  });
+});