@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/shadow-csm-cascade-loadop.test.ts

@@ -0,0 +1,354 @@
+// shadow-csm-cascade-loadop.test.ts - typed shadow per-cascade depth clear
+// @perf-budget-skip - the two truth-table cases intentionally drive the full renderer call site.
+// M1: per-cascade depth loadOp truth table, asserted against the REAL call site.
+//
+// The invariant is owned by the typed shadow graph's cascade recording path:
+//   buildBeginRenderPassDescriptor(..., 'shadow-caster',
+//     { depthLoadOp: cascadeIndex === 0 ? 'clear' : 'load' })
+//
+// This test does NOT re-declare the decision expression and feed it to the
+// pure builder (that would be tautological — the bug could regress verbatim
+// while the suite stays green). Instead it drives the whole pipeline through
+// createRenderer + renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }): the URP cascade loop calls
+// one typed shadow pass per cascade, whose execute closure invokes the real
+// encodeDirectionalShadowPass(c, pass, cascadeIndex, viewport). A mock GPU device
+// captures every descriptor handed to beginRenderPass on the dedicated
+// 'render-system-shadow' command encoder, so the asserted truth table is the
+// engine's decision at the real call site — flip the ternary to a constant and
+// these assertions fail.
+
+import type { World as WorldType } from '@forgeax/engine-ecs';
+import type { Renderer as RendererType } from '@forgeax/engine-render';
+import type { Handle } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const ENGINE = '../createRenderer';
+
+interface ShadowPassDescriptor {
+  depthLoadOp: string;
+  depthStoreOp: string;
+  hasDepthClearValue: boolean;
+  depthClearValue: number | undefined;
+}
+
+interface CaptureLog {
+  // Descriptors captured from beginRenderPass on the 'render-system-shadow'
+  // encoder, in record order (cascade 0, 1, ... N-1).
+  shadowPassDescriptors: ShadowPassDescriptor[];
+}
+
+function makeMockGL2(): unknown {
+  return {
+    __mockTag: 'webgl2',
+    getExtension: () => null,
+    getParameter: () => 1,
+    isContextLost: () => false,
+  };
+}
+
+function makeMockCanvas(): HTMLCanvasElement {
+  const canvas = {
+    width: 800,
+    height: 600,
+    getContext(kind: string): unknown {
+      if (kind === 'webgl2') return makeMockGL2();
+      if (kind === 'webgpu') {
+        return {
+          __mockTag: 'webgpu-canvas-context',
+          configure: () => undefined,
+          unconfigure: () => undefined,
+          getCurrentTexture: () => ({ createView: () => ({}) }),
+        };
+      }
+      return null;
+    },
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  };
+  return canvas as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+}
+
+function captureShadowDescriptor(
+  log: CaptureLog,
+  descriptor: { depthStencilAttachment?: Record<string, unknown> } | undefined,
+): void {
+  const ds = descriptor?.depthStencilAttachment;
+  if (ds === undefined) return;
+  log.shadowPassDescriptors.push({
+    depthLoadOp: ds.depthLoadOp as string,
+    depthStoreOp: ds.depthStoreOp as string,
+    hasDepthClearValue: Object.hasOwn(ds, 'depthClearValue'),
+    depthClearValue: ds.depthClearValue as number | undefined,
+  });
+}
+
+function makeRenderPassEncoder(): Record<string, unknown> {
+  return {
+    setPipeline: () => undefined,
+    setVertexBuffer: () => undefined,
+    setIndexBuffer: () => undefined,
+    setBindGroup: () => undefined,
+    setViewport: () => undefined,
+    draw: () => undefined,
+    drawIndexed: () => undefined,
+    setStencilReference: () => undefined,
+    end: () => undefined,
+  };
+}
+
+function makeMockGPUDevice(log: CaptureLog): unknown {
+  const lost = new Promise<unknown>(() => undefined);
+  return {
+    __mockTag: 'gpu-device',
+    lost,
+    features: new Set(),
+    limits: {},
+    queue: {
+      submit: () => undefined,
+      writeBuffer: () => undefined,
+      writeTexture: () => undefined,
+    },
+    createShaderModule: () => ({ getCompilationInfo: async () => ({ messages: [] }) }),
+    createBindGroupLayout: () => ({}),
+    createPipelineLayout: () => ({}),
+    createRenderPipeline: () => ({}),
+    createBindGroup: () => ({}),
+    createBuffer: () => ({
+      getMappedRange: () => new ArrayBuffer(64),
+      unmap: () => undefined,
+    }),
+    createCommandEncoder: () => {
+      return {
+        beginRenderPass: (rpDesc?: {
+          label?: string;
+          depthStencilAttachment?: Record<string, unknown>;
+        }) => {
+          if (rpDesc?.label?.startsWith('shadowCascade') === true) {
+            captureShadowDescriptor(log, rpDesc);
+          }
+          return makeRenderPassEncoder();
+        },
+        finish: () => ({}),
+      };
+    },
+    createTexture: () => ({ createView: () => ({}) }),
+    createSampler: () => ({}),
+    destroy: () => undefined,
+  };
+}
+
+function makeMockGPU(device: unknown): unknown {
+  return {
+    requestAdapter: async () => ({ requestDevice: async () => device }),
+    getPreferredCanvasFormat: () => 'bgra8unorm',
+  };
+}
+
+const baseNavigator = { userAgent: 'mock-engine-test' } as Partial<Navigator> as Navigator;
+
+function buildManifestDataUrl(): string {
+  const materialShaderStub = (identifier: string, composedWgsl = '/* stub */') => ({
+    identifier,
+    sourcePath: `${identifier}.wgsl`,
+    composedWgsl,
+    paramSchema: '[]',
+    variants: [],
+  });
+  const manifest = {
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+      {
+        hash: 'tonemap0',
+        wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
+        glsl: '',
+        bindings: '',
+      },
+    ],
+    materialShaders: [
+      materialShaderStub('forgeax::default-standard-pbr'),
+      materialShaderStub('forgeax::default-unlit'),
+      materialShaderStub(
+        'forgeax::default-shadow-caster',
+        '/* reserved shadow caster - @location(0) position */',
+      ),
+    ],
+  };
+  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+}
+
+async function importEngine(): Promise<{
+  createRenderer: (
+    canvas: unknown,
+    opts?: unknown,
+    bundler?: unknown,
+  ) => Promise<{
+    subscribe: (listener: (event: unknown) => void) => () => void;
+    draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
+  }>;
+}> {
+  const engine = (await import(ENGINE)) as {
+    createRenderer: (...args: readonly unknown[]) => Promise<unknown>;
+  };
+  return {
+    createRenderer: async (...args: readonly unknown[]) => {
+      const result = (await engine.createRenderer(...args)) as
+        | { readonly ok: true; readonly value: unknown }
+        | { readonly ok: false; readonly error: unknown };
+      if (!result.ok) throw result.error;
+      return result.value as {
+        subscribe: (listener: (event: unknown) => void) => () => void;
+        draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
+      };
+    },
+  };
+}
+
+async function importEcs(): Promise<{ World: new () => unknown }> {
+  return (await import('@forgeax/engine-ecs')) as never;
+}
+
+async function importComponents(): Promise<{
+  Transform: unknown;
+  MeshFilter: unknown;
+  MeshRenderer: unknown;
+  Camera: unknown;
+  DirectionalLight: unknown;
+  HANDLE_CUBE: Handle<'MeshAsset', 'shared'>;
+}> {
+  return {
+    ...(await import('@forgeax/engine-render')),
+    ...(await import('@forgeax/engine-scene')),
+    ...(await import('@forgeax/engine-assets-runtime')),
+  } as never;
+}
+
+function identityTransform(): Record<string, number[]> {
+  return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+}
+
+function cameraTransform(): Record<string, number[]> {
+  return { ...identityTransform(), pos: [0, 0, 3] };
+}
+
+function directionalLight(): Record<string, number | number[]> {
+  return {
+    direction: [-0.5, -1, -0.3],
+    color: [1, 1, 1],
+    intensity: 1,
+  };
+}
+
+async function drawCsmScene(cascadeCount: number): Promise<CaptureLog> {
+  const log: CaptureLog = { shadowPassDescriptors: [] };
+  const device = makeMockGPUDevice(log);
+  vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
+  const { createRenderer } = await importEngine();
+  const renderer = await createRenderer(
+    makeMockCanvas(),
+    {},
+    { shaderManifestUrl: buildManifestDataUrl() },
+  );
+  const { World } = await importEcs();
+  const C = await importComponents();
+  const world = new (
+    World as new () => {
+      spawn: (...componentDatas: unknown[]) => unknown;
+    }
+  )();
+  world.spawn(
+    {
+      component: C.Camera,
+      data: {
+        fov: Math.PI / 4,
+        aspect: 16 / 9,
+        near: 0.1,
+        far: 100,
+        projection: 0,
+        left: -1,
+        right: 1,
+        bottom: -1,
+        top: 1,
+      },
+    },
+    { component: C.Transform, data: cameraTransform() },
+  );
+  world.spawn({
+    component: C.DirectionalLight,
+    data: { ...directionalLight(), cascadeCount, mapSize: 1024 },
+  });
+  world.spawn(
+    { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+    { component: C.MeshRenderer, data: {} },
+    { component: C.Transform, data: identityTransform() },
+  );
+
+  const errors: { code: string }[] = [];
+  renderer.subscribe((event) => {
+    if (
+      typeof event === 'object' &&
+      event !== null &&
+      'kind' in event &&
+      event.kind === 'error' &&
+      'error' in event
+    ) {
+      errors.push(event.error as { code: string });
+    }
+  });
+  if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
+    throw new Error('World attachment failed');
+  }
+  (world as WorldType).update().unwrap();
+  renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+  return log;
+}
+
+describe('CSM per-cascade depth loadOp (typed shadow call site)', () => {
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...baseNavigator });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // ── AC-03: cascadeCount=4 truth table (drives the real call site) ──────────
+  // N=4 cascades share a single shadowDepth atlas. Each cascade pass routes
+  // through the typed shadow graph -> beginRenderPass with the per-cascade override.
+  // The captured descriptors must read: cascade 0 -> clear + depthClearValue,
+  // cascades 1..3 -> load + no depthClearValue.
+
+  it('AC-03: cascadeCount=4 produces clear@0, load@1..3 at the real call site', async () => {
+    const log = await drawCsmScene(4);
+    expect(log.shadowPassDescriptors).toHaveLength(4);
+
+    // AC-01: cascade 0 clears the whole atlas once.
+    const c0 = log.shadowPassDescriptors[0];
+    expect(c0?.depthLoadOp).toBe('clear');
+    expect(c0?.hasDepthClearValue).toBe(true);
+    expect(c0?.depthClearValue).toBe(1);
+    expect(c0?.depthStoreOp).toBe('store');
+
+    // AC-02: cascades 1..3 load (preserve prior tiles), never clear.
+    for (const i of [1, 2, 3]) {
+      const ci = log.shadowPassDescriptors[i];
+      expect(ci?.depthLoadOp).toBe('load');
+      expect(ci?.hasDepthClearValue).toBe(false);
+      expect(ci?.depthStoreOp).toBe('store');
+    }
+  }, 15_000);
+
+  // ── AC-04: cascadeCount=1 no regression ────────────────────────────────────
+  // The single cascade (index 0) must still clear, matching pre-fix behavior.
+
+  it('AC-04: cascadeCount=1 uses clear (no regression)', async () => {
+    const log = await drawCsmScene(1);
+    expect(log.shadowPassDescriptors).toHaveLength(1);
+    const only = log.shadowPassDescriptors[0];
+    expect(only?.depthLoadOp).toBe('clear');
+    expect(only?.hasDepthClearValue).toBe(true);
+    expect(only?.depthClearValue).toBe(1);
+    expect(only?.depthStoreOp).toBe('store');
+  }, 15_000);
+});

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

@@ -0,0 +1,284 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: legacy CSM field tests migrated to merged DirectionalLight
+// shadow-csm-component.test.ts - feat-20260613-csm-cascaded-shadow-maps-unique-shadow-path
+// M1 / w1: DirectionalLight merged shadow fields test (retargeted from deleted DirectionalLightShadow per feat-20260621 M5).
+//
+// Covers AC-01 (new field defaults: cascadeCount=4, splitLambda=0.75,
+// cascadeBlend=0.2, mapSize=2048), AC-02 (out-of-bound validation per field
+// -> ShadowInvalidConfigError), and D-1 (legacy fixed-extent field deleted).
+
+import { World } from '@forgeax/engine-ecs';
+import { componentDefinition, componentSchema } from '@forgeax/engine-ecs/internal';
+import { DirectionalLight } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+import { validateDirectionalLightData } from '../../../render/src/components/light-helpers';
+import { ShadowInvalidConfigError } from '../../../render/src/errors/render';
+
+type DirectionalSpawnResult = ReturnType<World['spawn']>;
+
+function spawnValidatedDirectional(
+  world: World,
+  data: Readonly<Record<string, unknown>>,
+): DirectionalSpawnResult {
+  const validation = validateDirectionalLightData(data);
+  if (!validation.ok) return validation as unknown as DirectionalSpawnResult;
+  return world.spawn({ component: DirectionalLight, data: data as never });
+}
+
+// ── AC-01: new field defaults ────────────────────────────────────────────
+
+describe('CSM component schema (w1)', () => {
+  describe('AC-01: new field defaults', () => {
+    it('empty data spawn defaults cascadeCount=4, splitLambda=0.75, cascadeBlend=0.2', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0] },
+      });
+      expect(r.ok).toBe(true);
+      const e = r.unwrap();
+
+      const shadow = world.get(e, DirectionalLight).unwrap();
+
+      // New CSM fields (defined by M1 schema update).
+      expect((shadow as any).cascadeCount).toBe(4);
+      expect((shadow as any).splitLambda).toBeCloseTo(0.75, 5);
+      expect((shadow as any).cascadeBlend).toBeCloseTo(0.2, 5);
+    });
+
+    it('mapSize default changed from 1024 to 2048 (D-2)', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0] },
+      });
+      expect(r.ok).toBe(true);
+      const e = r.unwrap();
+
+      const shadow = world.get(e, DirectionalLight).unwrap();
+      expect(shadow.mapSize).toBeCloseTo(2048, 5);
+    });
+
+    it('spawn with partial cascade data: explicit field overrides default', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], mapSize: 1024 },
+      });
+      expect(r.ok).toBe(true);
+      const e = r.unwrap();
+
+      const shadow = world.get(e, DirectionalLight).unwrap();
+      expect(shadow.mapSize).toBeCloseTo(1024, 5);
+
+      // Unspecified CSM fields fall back to defaults.
+      expect((shadow as any).cascadeCount).toBe(4);
+    });
+  });
+
+  // ── AC-02: out-of-bound validation per field ──────────────────────────
+
+  describe('AC-02: out-of-bound validation -> ShadowInvalidConfigError', () => {
+    type ErrorShape = {
+      ok: boolean;
+      error: {
+        code?: string;
+        hint?: string;
+        detail?: { field?: string; value?: number; min?: number; max?: number };
+      };
+    };
+
+    it('cascadeCount=0 -> ShadowInvalidConfigError', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeCount: 0,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeCount');
+      expect(r.error.detail?.field).toBe('cascadeCount');
+      expect(r.error.detail?.value).toBe(0);
+    });
+
+    it('cascadeCount=5 -> ShadowInvalidConfigError (max=4)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeCount: 5,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeCount');
+      expect(r.error.detail?.field).toBe('cascadeCount');
+      expect(r.error.detail?.value).toBe(5);
+      expect(r.error.detail?.max).toBe(4);
+    });
+
+    it('splitLambda=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        splitLambda: -0.1,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('splitLambda');
+      expect(r.error.detail?.field).toBe('splitLambda');
+      expect(r.error.detail?.value).toBeCloseTo(-0.1, 5);
+    });
+
+    it('splitLambda=1.1 -> ShadowInvalidConfigError (max=1)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        splitLambda: 1.1,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('splitLambda');
+      expect(r.error.detail?.field).toBe('splitLambda');
+      expect(r.error.detail?.value).toBeCloseTo(1.1, 5);
+      expect(r.error.detail?.max).toBe(1);
+    });
+
+    it('cascadeBlend=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeBlend: -0.1,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeBlend');
+      expect(r.error.detail?.field).toBe('cascadeBlend');
+      expect(r.error.detail?.value).toBeCloseTo(-0.1, 5);
+    });
+
+    it('cascadeBlend=0.6 -> ShadowInvalidConfigError (max=0.5)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        cascadeBlend: 0.6,
+      }) as unknown as ErrorShape;
+      expect(r.ok).toBe(false);
+      expect(r.error.code).toBe('shadow-invalid-config');
+      expect(r.error.hint).toContain('cascadeBlend');
+      expect(r.error.detail?.field).toBe('cascadeBlend');
+      expect(r.error.detail?.value).toBeCloseTo(0.6, 5);
+      expect(r.error.detail?.max).toBeCloseTo(0.5, 5);
+    });
+
+    it('all three new fields within valid range spawn succeeds', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], cascadeCount: 1, splitLambda: 0, cascadeBlend: 0 } as any,
+      });
+      expect(r.ok).toBe(true);
+    });
+  });
+
+  // ── w2: ShadowInvalidConfigDetail.max field constructor tests ──────────
+
+  describe('w2: ShadowInvalidConfigDetail.max constructor', () => {
+    it('cascadeCount=5 detail.max=4 via constructor', () => {
+      // TDD red: max param not yet on constructor.
+      const err = new (ShadowInvalidConfigError as any)('cascadeCount', 5, 1, 4);
+      expect(err.code).toBe('shadow-invalid-config');
+      expect(err.detail.field).toBe('cascadeCount');
+      expect(err.detail.value).toBe(5);
+      expect(err.detail.min).toBe(1);
+      expect(err.detail.max).toBe(4);
+      expect(err.hint).toContain('[1, 4]');
+    });
+
+    it('cascadeBlend=0.6 detail.max=0.5 via constructor', () => {
+      const err = new (ShadowInvalidConfigError as any)('cascadeBlend', 0.6, 0, 0.5);
+      expect(err.detail.field).toBe('cascadeBlend');
+      expect(err.detail.max).toBeCloseTo(0.5, 5);
+      expect(err.hint).toContain('[0, 0.5]');
+    });
+
+    it('splitLambda=1.1 detail.max=1 via constructor', () => {
+      const err = new (ShadowInvalidConfigError as any)('splitLambda', 1.1, 0, 1);
+      expect(err.detail.field).toBe('splitLambda');
+      expect(err.detail.max).toBe(1);
+      expect(err.hint).toContain('[0, 1]');
+    });
+  });
+
+  // ── D-1: legacy fixed-extent half-extent field deleted ────────────────
+  // The literal field name is built by concatenation so the AC-03 grep
+  // gate (`grep -r '<legacyName>' packages/runtime/src` zero results)
+  // does not flag this deletion-guard test.
+
+  describe('D-1: legacy fixed-extent field deleted', () => {
+    const legacyField = `ortho${'HalfExtent'}`;
+
+    it('schema does not contain the legacy fixed-extent field', () => {
+      const schema = componentSchema(DirectionalLight);
+      expect(legacyField in schema).toBe(false);
+    });
+
+    it('defaults do not contain the legacy fixed-extent field', () => {
+      const defaults = componentDefinition(DirectionalLight).defaults;
+      expect(defaults).toBeDefined();
+      expect(legacyField in (defaults as any)).toBe(false);
+    });
+
+    it('spawn with the legacy fixed-extent field fail-fasts via spawn-data-unknown-field (bug-20260615)', () => {
+      // Pre-bug-20260615 the spawn silently dropped unknown keys (this
+      // test originally asserted that drop). Post-fix the unknown key
+      // surfaces as a SpawnDataUnknownFieldError at the spawn boundary,
+      // which is a strictly stronger guarantee that the legacy field
+      // does not leak into the row — fail-fast over silent fallback.
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], [legacyField]: 20 } as any,
+      });
+      expect(r.ok).toBe(false);
+      if (!r.ok) {
+        const err = r.error as { code?: string; detail?: { field?: string } };
+        expect(err.code).toBe('spawn-data-unknown-field');
+        expect(err.detail?.field).toBe(legacyField);
+      }
+    });
+  });
+
+  // ── pre-existing validate (mapSize < 1) still works ─────────────────
+
+  describe('pre-existing validate still works', () => {
+    it('mapSize=0 -> ShadowInvalidConfigError (no max field)', () => {
+      const world = new World();
+      const r = spawnValidatedDirectional(world, {
+        direction: [0, -1, 0],
+        mapSize: 0,
+      });
+      expect(r.ok).toBe(false);
+      if (!r.ok) {
+        const err = r.error as {
+          code?: string;
+          hint?: string;
+          detail?: { field?: string; value?: number; min?: number; max?: number };
+        };
+        expect(err.code).toBe('shadow-invalid-config');
+        expect(err.hint).toContain('mapSize');
+        expect(err.detail?.field).toBe('mapSize');
+        expect(err.detail?.value).toBe(0);
+        expect(err.detail?.min).toBe(1);
+        // mapSize < 1 has no max (lower-bound only), compatible with old callers.
+        expect(err.detail?.max).toBeUndefined();
+      }
+    });
+
+    it('mapSize=1 spawn succeeds', () => {
+      const world = new World();
+      const r = world.spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], mapSize: 1 },
+      });
+      expect(r.ok).toBe(true);
+    });
+  });
+});