@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/shadow-csm-caster-membership.test.ts

@@ -1,232 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  Camera,
-  DirectionalLight,
-  extractFrames,
-  MeshFilter,
-  MeshRenderer,
-} from '@forgeax/engine-render/internal';
-import { Transform } from '@forgeax/engine-scene';
-import { describe, expect, it } from 'vitest';
-import { executeCpuMultiViewVisibility } from '../../../render/src/gpu-driven/view-gpu';
-
-interface CascadePlanObservation {
-  readonly casterRenderableIndices: readonly number[];
-  readonly unboundedFallbackCount: number;
-}
-
-interface CsmObservation {
-  readonly cascades?: readonly CascadePlanObservation[];
-}
-
-const shadowPassSource = readFileSync(
-  fileURLToPath(new URL('../../../render/src/record/shadow-pass.ts', import.meta.url)),
-  'utf8',
-);
-
-function spawnRenderable(world: World, position: [number, number, number]): void {
-  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
-  world
-    .spawn(
-      { component: Transform, data: { pos: position } },
-      { component: MeshFilter, data: { assetHandle: cubeHandle } },
-      { component: MeshRenderer, data: {} },
-    )
-    .unwrap();
-}
-
-function makeWorld(shadowFields: { depthBias?: number; normalBias?: number } = {}): World {
-  const world = new World();
-  spawnRenderable(world, [0, 0, -8]);
-  spawnRenderable(world, [9, 0, -8]);
-  world.spawn({
-    component: DirectionalLight,
-    data: {
-      direction: [0.4, -0.8, 0.2],
-      cascadeCount: 2,
-      cascadeBlend: 0.25,
-      shadowDistance: 40,
-      mapSize: 1024,
-      ...(shadowFields.depthBias === undefined ? {} : { depthBias: shadowFields.depthBias }),
-      ...(shadowFields.normalBias === undefined ? {} : { normalBias: shadowFields.normalBias }),
-    },
-  });
-  world.spawn(
-    { component: Transform, data: {} },
-    { component: Camera, data: { fov: Math.PI / 3, aspect: 1, near: 0.1, far: 100 } },
-  );
-  return world;
-}
-
-describe('directional CSM caster membership', () => {
-  it('keeps an off-main-view caster in the cascade plan and excludes lateral misses', () => {
-    const frame = extractFrames([makeWorld()], 0, undefined, undefined, undefined, undefined, {
-      cull: 'none',
-    });
-    const csm = frame.lights as unknown as CsmObservation;
-    expect(csm.cascades).toBeDefined();
-    if (csm.cascades === undefined) return;
-
-    const first = csm.cascades[0];
-    expect(first).toBeDefined();
-    if (first === undefined) return;
-    expect(first.casterRenderableIndices.length).toBeGreaterThan(0);
-    expect(first.casterRenderableIndices).toContain(0);
-    expect(first.casterRenderableIndices).not.toContain(1);
-    expect(first.unboundedFallbackCount).toBe(0);
-  });
-
-  it('keeps bias changes out of CSM membership and clip fitting', () => {
-    const baseline = extractFrames(
-      [makeWorld({ depthBias: 0, normalBias: 0 })],
-      0,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      { cull: 'none' },
-    );
-    const extreme = extractFrames(
-      [makeWorld({ depthBias: 0.5, normalBias: 2 })],
-      0,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      { cull: 'none' },
-    );
-    const baselineLights = baseline.lights as unknown as CsmObservation & {
-      readonly lightViewProj?: readonly Float32Array[];
-    };
-    const extremeLights = extreme.lights as unknown as CsmObservation & {
-      readonly lightViewProj?: readonly Float32Array[];
-    };
-    expect(baselineLights.lightViewProj?.[0]).toBeDefined();
-    expect(extremeLights.lightViewProj?.[0]).toBeDefined();
-    expect(Array.from(extremeLights.lightViewProj?.[0] ?? [])).toEqual(
-      Array.from(baselineLights.lightViewProj?.[0] ?? []),
-    );
-    expect(Array.from(extremeLights.cascades?.[0]?.casterRenderableIndices ?? [])).toEqual(
-      Array.from(baselineLights.cascades?.[0]?.casterRenderableIndices ?? []),
-    );
-  });
-
-  it('makes the multi-view indirect submission the directional record owner', () => {
-    const start = shadowPassSource.indexOf('function recordShadowCasterDraws(');
-    expect(start).toBeGreaterThanOrEqual(0);
-    const directionalSource = shadowPassSource.slice(start);
-    expect(shadowPassSource).toContain("multiViewSubmission(c, 'cascade', cascadeIndex)");
-    expect(directionalSource).toContain('submissionCandidateIndices(productionSubmission)');
-    expect(directionalSource).toContain('if (productionCandidateIndices !== undefined)');
-    expect(directionalSource).toContain("reason: 'outside-multi-view-submission'");
-    expect(directionalSource).toContain("source: 'multi-view-indirect'");
-    expect(shadowPassSource).not.toContain('function directionalCasterMembership(');
-    expect(shadowPassSource).not.toContain('mainVisibleRenderableIndices');
-    expect(shadowPassSource).not.toContain('buildGpuDrivenBatchKey');
-    expect(directionalSource).toContain('productionSubmission?: MultiViewProductionSubmission');
-    expect(directionalSource).toContain('validatedIndexByCandidateIndex');
-    expect(directionalSource).not.toContain('new Map<ValidatedRenderable, number>()');
-  });
-
-  it('matches a brute-force view oracle for false-positive and false-negative cases', () => {
-    const planes = new Float32Array([
-      1, 0, 0, 1, -1, 0, 0, 1, 0, 1, 0, 1, 0, -1, 0, 1, 0, 0, 1, 1, 0, 0, -1, 1,
-    ]);
-    const evidence = executeCpuMultiViewVisibility({
-      views: [
-        {
-          viewId: 'main',
-          kind: 'main',
-          cascadeIndex: undefined,
-          planes,
-          casterCandidateIndices: new Set<number>(),
-          volumeRevision: undefined,
-          spatialIndexRevision: 7,
-        },
-        {
-          viewId: 'cascade-0',
-          kind: 'cascade',
-          cascadeIndex: 0,
-          planes: new Float32Array(0),
-          casterCandidateIndices: new Set([1]),
-          volumeRevision: 11,
-          spatialIndexRevision: 7,
-        },
-      ],
-      candidates: [
-        {
-          stableId: 10,
-          generation: 2,
-          candidateIndex: 0,
-          worldAabb: new Float32Array([-0.25, -0.25, -0.25, 0.25, 0.25, 0.25]),
-          casterEligible: false,
-          batchId: undefined,
-          instanceOrdinal: undefined,
-        },
-        {
-          stableId: 20,
-          generation: 4,
-          candidateIndex: 1,
-          worldAabb: new Float32Array([4.75, -0.25, -0.25, 5.25, 0.25, 0.25]),
-          casterEligible: true,
-          batchId: undefined,
-          instanceOrdinal: undefined,
-        },
-      ],
-    });
-    expect(evidence.views[0]?.stableIds).toEqual([10]);
-    expect(evidence.views[1]?.stableIds).toEqual([20]);
-    expect(evidence.cascadeMasks).toEqual([
-      { stableId: 10, generation: 2, cascadeMask: 0 },
-      { stableId: 20, generation: 4, cascadeMask: 1 },
-    ]);
-    expect(evidence.spatialIndexRevision).toBe(7);
-    expect(evidence.views[1]?.volumeRevision).toBe(11);
-  });
-
-  it('keeps stable IDs while exposing a new generation after slot reuse', () => {
-    const view = {
-      viewId: 'cascade-0',
-      kind: 'cascade' as const,
-      cascadeIndex: 0,
-      planes: new Float32Array(0),
-      casterCandidateIndices: new Set([3]),
-      volumeRevision: 1,
-      spatialIndexRevision: 1,
-    };
-    const first = executeCpuMultiViewVisibility({
-      views: [view],
-      candidates: [
-        {
-          stableId: 3,
-          generation: 5,
-          candidateIndex: 3,
-          worldAabb: undefined,
-          casterEligible: true,
-          batchId: 2,
-          instanceOrdinal: 0,
-        },
-      ],
-    });
-    const recreated = executeCpuMultiViewVisibility({
-      views: [view],
-      candidates: [
-        {
-          stableId: 3,
-          generation: 6,
-          candidateIndex: 3,
-          worldAabb: undefined,
-          casterEligible: true,
-          batchId: 2,
-          instanceOrdinal: 0,
-        },
-      ],
-    });
-    expect(first.views[0]?.compactVisible[0]).toMatchObject({ stableId: 3, generation: 5 });
-    expect(recreated.views[0]?.compactVisible[0]).toMatchObject({ stableId: 3, generation: 6 });
-    expect(recreated.cascadeMasks[0]).toEqual({ stableId: 3, generation: 6, cascadeMask: 1 });
-  });
-});

package/src/__tests__/shadow-csm-pssm.test.ts

@@ -1,142 +0,0 @@
-// shadow-csm-pssm.test.ts - feat-20260613-csm-cascaded-shadow-maps-unique-shadow-path
-// M2 / w6: PSSM split function unit test (RED, test-first).
-//
-// PSSM formula (plan-strategy section 2 decision D-8):
-//   C_i = λ · n · (f/n)^(i/m) + (1-λ) · (n + i/m · (f-n))
-//   where i = 1..m, m = cascadeCount, n = nearPlane, f = farPlane
-//
-// Covers AC-04: split numerical correctness / monotonicity / λ degeneration /
-// near≈far error / N=1..4 end-to-end.
-
-import { pssmSplit } from '@forgeax/engine-render/internal';
-import { describe, expect, it } from 'vitest';
-
-// ── Hand-calculated anchors ────────────────────────────────────────────────
-//
-// λ=0.75, n=0.1, f=100, m=4:
-//   log  term: n·(f/n)^(i/4) = 0.1 · (1000)^(i/4)
-//   uniform term: n + i/4·(f-n) = 0.1 + i·24.975
-//
-//   i=1: log = 0.1·1000^0.25 = 0.1·5.6234 ≈ 0.5623
-//         uni = 0.1 + 1·24.975 = 25.075
-//         C1  = 0.75·0.5623 + 0.25·25.075 = 0.4217 + 6.2688 = 6.6905
-//
-//   i=2: log = 0.1·1000^0.5 = 0.1·31.6228 ≈ 3.1623
-//         uni = 0.1 + 2·24.975 = 50.05
-//         C2  = 0.75·3.1623 + 0.25·50.05 = 2.3717 + 12.5125 = 14.8842
-//
-//   i=3: log = 0.1·1000^0.75 = 0.1·177.8279 ≈ 17.7828
-//         uni = 0.1 + 3·24.975 = 75.025
-//         C3  = 0.75·17.7828 + 0.25·75.025 = 13.3371 + 18.7563 = 32.0934
-//
-//   i=4: log = 0.1·1000^1.0 = 100.0
-//         uni = 0.1 + 4·24.975 = 100.0
-//         C4  = 0.75·100 + 0.25·100 = 100.0
-//
-// Monotonicity: C1 < C2 < C3 < C4 = 100.0
-
-describe('PSSM split function (w6)', () => {
-  const EPS = 0.01;
-
-  // biome-ignore lint/style/noNonNullAssertion: Float32Array indexed access in test assertions
-  const at = (a: Float32Array, i: number): number => a[i]!;
-
-  // biome-ignore lint/style/noNonNullAssertion: Float32Array indexed access in test assertions
-  const prev = (a: Float32Array, i: number): number => a[i - 1]!;
-
-  describe('λ=1 (pure logarithmic)', () => {
-    it('produces exponentially spaced splits', () => {
-      const result = pssmSplit(0.1, 100, 4, 1.0);
-      expect(result.length).toBe(4);
-      expect(at(result, 0)).toBeCloseTo(0.5623, 2);
-      expect(at(result, 3)).toBeCloseTo(100.0, 4);
-      for (let i = 1; i < 4; i++) {
-        expect(at(result, i)).toBeGreaterThan(prev(result, i));
-      }
-    });
-  });
-
-  describe('λ=0 (pure uniform)', () => {
-    it('produces linearly spaced splits', () => {
-      const result = pssmSplit(0.1, 100, 4, 0);
-      expect(result.length).toBe(4);
-      expect(at(result, 0)).toBeCloseTo(25.075, 2);
-      expect(at(result, 1)).toBeCloseTo(50.05, 2);
-      expect(at(result, 2)).toBeCloseTo(75.025, 2);
-      expect(at(result, 3)).toBeCloseTo(100.0, 4);
-      for (let i = 1; i < 4; i++) {
-        expect(at(result, i)).toBeGreaterThan(prev(result, i));
-      }
-    });
-  });
-
-  describe('λ=0.75 (default PSSM blend)', () => {
-    it('produce monotonically increasing values between log and uniform', () => {
-      const result = pssmSplit(0.1, 100, 4, 0.75);
-      expect(result.length).toBe(4);
-      expect(at(result, 0)).toBeCloseTo(6.6905, 2);
-      expect(at(result, 1)).toBeCloseTo(14.8842, 2);
-      expect(at(result, 2)).toBeCloseTo(32.0934, 2);
-      expect(at(result, 3)).toBeCloseTo(100.0, 3);
-      for (let i = 1; i < 4; i++) {
-        expect(at(result, i)).toBeGreaterThan(prev(result, i));
-      }
-    });
-
-    it('split values lie between pure uniform and pure log', () => {
-      const blend = pssmSplit(0.1, 100, 4, 0.75);
-      const uniform = pssmSplit(0.1, 100, 4, 0);
-      const log = pssmSplit(0.1, 100, 4, 1.0);
-      for (let i = 0; i < 3; i++) {
-        const b = at(blend, i);
-        const u = at(uniform, i);
-        const l = at(log, i);
-        expect(b).toBeGreaterThan(Math.min(l, u) - EPS);
-        expect(b).toBeLessThan(Math.max(l, u) + EPS);
-      }
-    });
-  });
-
-  describe('N=1 (single cascade)', () => {
-    it('returns array with far plane only', () => {
-      const result = pssmSplit(0.1, 100, 1, 0.75);
-      expect(result.length).toBe(1);
-      expect(at(result, 0)).toBeCloseTo(100.0, 4);
-    });
-  });
-
-  describe('N=2..4 end-to-end', () => {
-    it('N=2 produces monotonic 2-element array', () => {
-      const result = pssmSplit(0.1, 100, 2, 0.75);
-      expect(result.length).toBe(2);
-      expect(at(result, 0)).toBeGreaterThan(0);
-      expect(at(result, 0)).toBeLessThan(at(result, 1));
-      expect(at(result, 1)).toBeCloseTo(100.0, 4);
-    });
-
-    it('N=3 produces monotonic 3-element array', () => {
-      const result = pssmSplit(0.1, 100, 3, 0.75);
-      expect(result.length).toBe(3);
-      for (let i = 1; i < 3; i++) {
-        expect(at(result, i)).toBeGreaterThan(prev(result, i));
-      }
-      expect(at(result, 2)).toBeCloseTo(100.0, 4);
-    });
-
-    it('N=4 produces monotonic 4-element array', () => {
-      const result = pssmSplit(0.1, 100, 4, 0.75);
-      expect(result.length).toBe(4);
-      for (let i = 1; i < 4; i++) {
-        expect(at(result, i)).toBeGreaterThan(prev(result, i));
-      }
-      expect(at(result, 3)).toBeCloseTo(100.0, 4);
-    });
-  });
-
-  describe('nearPlane ≈ farPlane degenerate', () => {
-    it('throws ShadowInvalidConfigError when farPlane <= nearPlane + epsilon', () => {
-      expect(() => pssmSplit(10, 10, 4, 0.75)).toThrow();
-      expect(() => pssmSplit(10, 10.0000001, 4, 0.75)).toThrow();
-    });
-  });
-});

package/src/__tests__/shadow-csm-temporal.browser.test.ts

@@ -1,145 +0,0 @@
-import { type EntityHandle, World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  Camera,
-  DirectionalLight,
-  extractFrames,
-  MeshFilter,
-  MeshRenderer,
-} from '@forgeax/engine-render/internal';
-import { propagateTransforms, Transform } from '@forgeax/engine-scene';
-import { describe, expect, it } from 'vitest';
-import { executeCpuMultiViewVisibility } from '../../../render/src/gpu-driven/view-gpu';
-import { buildRenderVisibilityViewDescriptors } from '../../../render/src/render-system-extract';
-
-function makeWorld(): World {
-  const world = new World();
-  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
-  world.spawn({
-    component: DirectionalLight,
-    data: {
-      direction: [0.37, -0.86, 0.21],
-      cascadeCount: 2,
-      cascadeBlend: 0.25,
-      mapSize: 1024,
-      shadowDistance: 50,
-    },
-  });
-  world.spawn(
-    { component: Transform, data: {} },
-    { component: Camera, data: { fov: Math.PI / 3, aspect: 1, near: 0.1, far: 100 } },
-  );
-  world.spawn(
-    { component: Transform, data: { pos: [0, 0, -8] } },
-    { component: MeshFilter, data: { assetHandle: cubeHandle } },
-    { component: MeshRenderer, data: {} },
-  );
-  propagateTransforms(world).unwrap();
-  return world;
-}
-
-function moveCamera(world: World, x: number): void {
-  const query = world.query({ read: [Camera], with: [Transform] }).unwrap();
-  let cameraEntity: EntityHandle | undefined;
-  for (const row of query) {
-    cameraEntity = row.entity;
-    break;
-  }
-  if (cameraEntity === undefined) throw new Error('camera fixture is missing');
-  world.set(cameraEntity, Transform, { pos: [x, 0, 0] }).unwrap();
-  propagateTransforms(world).unwrap();
-}
-
-function moveDoor(world: World, x: number): void {
-  const query = world.query({ read: [Transform], with: [MeshFilter] }).unwrap();
-  let doorEntity: EntityHandle | undefined;
-  for (const row of query) {
-    doorEntity = row.entity;
-    break;
-  }
-  if (doorEntity === undefined) throw new Error('door fixture is missing');
-  world.set(doorEntity, Transform, { pos: [x, 0, -8] }).unwrap();
-  propagateTransforms(world).unwrap();
-}
-
-function matrix(frame: ReturnType<typeof extractFrames>): Float32Array {
-  const value = frame.lights.lightViewProj?.[0];
-  if (!(value instanceof Float32Array)) throw new Error('cascade matrix is unavailable');
-  return value;
-}
-
-function visibilityEvidence(frame: ReturnType<typeof extractFrames>) {
-  const source = frame.candidateRenderables ?? frame.renderables;
-  const views = buildRenderVisibilityViewDescriptors({
-    camera: frame.cameras[0],
-    directionalCsm: frame.lights.directionalCsm,
-  });
-  return executeCpuMultiViewVisibility({
-    views,
-    candidates: source.map((snapshot, candidateIndex) => ({
-      stableId: snapshot.entityKey,
-      generation: 0,
-      candidateIndex,
-      worldAabb: undefined,
-      casterEligible: true,
-      batchId: undefined,
-      instanceOrdinal: undefined,
-    })),
-  });
-}
-
-describe('directional CSM temporal stability in the browser', () => {
-  it('does not churn the door cascade matrix for sub-texel camera motion', () => {
-    const world = makeWorld();
-    const baseline = matrix(extractFrames([world], 0));
-    moveCamera(world, 0.001);
-    const subTexel = matrix(extractFrames([world], 0));
-    expect(Array.from(subTexel)).toEqual(Array.from(baseline));
-  });
-
-  it('changes only by whole texel steps after crossing the stable-fit grid', () => {
-    const world = makeWorld();
-    const baseline = matrix(extractFrames([world], 0));
-    moveCamera(world, 0.1);
-    const moved = matrix(extractFrames([world], 0));
-    const dx = (moved[12] ?? 0) - (baseline[12] ?? 0);
-    const dy = (moved[13] ?? 0) - (baseline[13] ?? 0);
-    // Matrix translation is in NDC; one shadow-map texel is 2 / mapSize in
-    // that space. `2 / abs(m[0]) / mapSize` is world-units-per-texel and must
-    // not be compared with the NDC translation delta.
-    const ndcTexel = 2 / 1024;
-    expect(dx / ndcTexel).toBeCloseTo(Math.round(dx / ndcTexel), 3);
-    expect(dy / ndcTexel).toBeCloseTo(Math.round(dy / ndcTexel), 3);
-  });
-
-  it('keeps the door caster in adjacent CPU frames while the camera crosses a boundary', () => {
-    const world = makeWorld();
-    const baseline = visibilityEvidence(extractFrames([world], 0));
-    moveCamera(world, 0.001);
-    const adjacent = visibilityEvidence(extractFrames([world], 0));
-    expect(adjacent.views).toHaveLength(4);
-    const baselineMasks = baseline.cascadeMasks.filter((entry) => entry.cascadeMask !== 0);
-    const adjacentMasks = adjacent.cascadeMasks.filter((entry) => entry.cascadeMask !== 0);
-    expect(adjacentMasks).toEqual(baselineMasks);
-    expect(
-      adjacent.views.filter((view) => view.kind === 'cascade').every((view) => !view.overflow),
-    ).toBe(true);
-  });
-
-  it('retains stable caster identity after a dynamic transform mutation', () => {
-    const world = makeWorld();
-    const before = visibilityEvidence(extractFrames([world], 0));
-    moveDoor(world, 0.25);
-    const after = visibilityEvidence(extractFrames([world], 0));
-    const beforeIds = new Set(before.cascadeMasks.map((entry) => entry.stableId));
-    const afterIds = new Set(after.cascadeMasks.map((entry) => entry.stableId));
-    expect(afterIds).toEqual(beforeIds);
-    expect(after.cascadeMasks.every((entry) => entry.generation === 0)).toBe(true);
-    expect(after.views.map((view) => view.viewId)).toEqual([
-      'main',
-      'cascade-0',
-      'cascade-1',
-      'cascade-2',
-    ]);
-  });
-});

package/src/__tests__/shadow-csm-viewport.test.ts

@@ -1,74 +0,0 @@
-// shadow-csm-viewport.test.ts - feat-20260613-csm-cascaded-shadow-maps-unique-shadow-path
-// M3 / w10: addShadowPass viewport extension test (RED).
-//
-// Covers D-4 (addShadowPass signature extended with optional viewport):
-// - AddShadowPassOptions accepts optional viewport: { x, y, w, h }
-// - Undefined viewport preserves backward compat (existing callers unchanged)
-// - addShadowPass accepts viewport parameter without error
-
-import {
-  type AddShadowPassOptions,
-  directionalCascadeRasterViewport,
-} from '@forgeax/engine-render/internal';
-import { describe, expect, it } from 'vitest';
-
-describe('CSM viewport (w10)', () => {
-  it('derives every atlas viewport from the cascade volume producer', () => {
-    expect(
-      Array.from({ length: 4 }, (_, cascade) => directionalCascadeRasterViewport(cascade, 4, 1024)),
-    ).toEqual([
-      { x: 0, y: 0, w: 1024, h: 1024 },
-      { x: 1024, y: 0, w: 1024, h: 1024 },
-      { x: 0, y: 1024, w: 1024, h: 1024 },
-      { x: 1024, y: 1024, w: 1024, h: 1024 },
-    ]);
-  });
-
-  describe('AddShadowPassOptions viewport field', () => {
-    it('accepts optional viewport with { x, y, w, h }', () => {
-      // Type-level test: the opts type must accept viewport.
-      const opts: AddShadowPassOptions = {
-        depth: 'shadowDepth',
-        selector: { LightMode: ['ShadowCaster'] },
-        viewport: { x: 0, y: 0, w: 1024, h: 1024 },
-      };
-      expect(opts.viewport).toEqual({ x: 0, y: 0, w: 1024, h: 1024 });
-    });
-
-    it('undefined viewport preserves backward compat (existing callers unchanged)', () => {
-      // Existing callers do not pass viewport -- must still typecheck.
-      const opts: AddShadowPassOptions = {
-        depth: 'shadowDepth',
-        selector: { LightMode: ['ShadowCaster'] },
-      };
-      expect(opts.viewport).toBeUndefined();
-    });
-
-    it('addShadowPass accepts viewport parameter', () => {
-      // The function must accept the extended options without error.
-      // We import addShadowPass and verify its parameter type accepts viewport
-      // through the type-level contract above; this is a compile-time assertion
-      // that the signature is correct.
-      const optsWithViewport: AddShadowPassOptions = {
-        depth: 'shadowDepth',
-        selector: { LightMode: ['ShadowCaster'] },
-        viewport: { x: 1024, y: 0, w: 1024, h: 1024 },
-      };
-      // Verify opts are structurally sound.
-      expect(optsWithViewport.viewport).not.toBeUndefined();
-      expect(optsWithViewport.viewport?.x).toBe(1024);
-      expect(optsWithViewport.viewport?.w).toBe(1024);
-    });
-
-    it('addShadowPass without viewport still compiles (backward compat)', () => {
-      // The function must still accept the old signature shape.
-      const optsWithoutViewport: AddShadowPassOptions = {
-        depth: 'shadowDepth',
-        selector: { LightMode: ['ShadowCaster'] },
-      };
-      expect(optsWithoutViewport.viewport).toBeUndefined();
-      // Verify we can call addShadowPass with both shapes (type-level gate).
-      // Runtime verification via dawn smoke and browser test (w12, w30).
-    });
-  });
-});