@forgeax/engine-runtime 0.1.20 → 0.1.23

package/src/__tests__/renderer-surface.unit.test.ts

@@ -164,7 +164,7 @@ function makeLights(): MockObj {
     shadowMapSize: 0,
     depthBias: 0,
     normalBias: 0,
-    pcfKernelSize: 0,
+    directionalShadowQuality: undefined,
     pointShadow: [],
   };
 }
@@ -174,13 +174,12 @@ function makeFrameState(): MockObj {
     frameNumber: 1,
     compiledFrameGraph: null,
     compiledFrameGraphTopologyKey: null,
+    compiledFrameGraphGeneration: 0,
     retiredCompiledFrameGraphs: new Set(),
     instanceBuffers: new Map(),
     transientInstanceBuffers: [],
     warnedZeroLightStandard: false,
     warnedMultiLightDirectional: false,
-    warnedMultiLightPoint: false,
-    warnedMultiLightSpot: false,
     warnedSkyboxTonemapNone: false,
     warnedMissingBaseColorTextureHandles: new Set<number>(),
     warnedNineSliceScaleEntities: new Set<number>(),
@@ -193,8 +192,7 @@ function makeFrameState(): MockObj {
     installedPipelineHandle: 0,
     activePipeline: { buildGraph: () => null, execute: () => undefined },
     installedPipelineConfig: undefined,
-    isHdrpActive: false,
-    hdrpOncePerFrameFired: new Set(),
+    standardOncePerFrameFired: new Set(),
     pointShadowAtlas: null,
     pointShadowSnapshots: [],
     lastFoldBucketCount: 0,
@@ -231,6 +229,232 @@ function callRecordFrame(
   acquireSwapChainTarget(internals, internals.getPipelineState());
 }
 
+type DirectionalShadowAdmission = {
+  readonly requested: 'off' | 'pcf1' | 'pcf3' | 'pcf5' | 'pcssMedium' | 'pcssHigh';
+  readonly effective:
+    | 'off'
+    | 'pcf1'
+    | 'pcf3'
+    | 'pcf5'
+    | 'pcssMedium'
+    | 'pcssHigh'
+    | 'rhi-null-structural';
+  readonly status: 'accepted' | 'fallback' | 'rejected';
+  readonly fallbackReason?: 'webgl2-unsupported' | 'rhi-null-structural' | 'candidate-failed';
+  readonly lastKnownGood: boolean;
+  readonly pixelEvidence: 'available' | 'not-available';
+};
+
+async function resolveDirectionalShadowAdmission(input: {
+  readonly backendKind: 'webgpu' | 'wgpu-webgl2' | 'null';
+  readonly requested: DirectionalShadowAdmission['requested'];
+  readonly candidate: 'accepted' | 'failed';
+  readonly lastKnownGood?: Exclude<
+    DirectionalShadowAdmission['effective'],
+    'off' | 'rhi-null-structural'
+  >;
+}): Promise<DirectionalShadowAdmission> {
+  const module = (await import('../../../render/src/render-pipeline')) as Record<string, unknown>;
+  const resolver = module.resolveDirectionalShadowBackendAdmission;
+  expect(typeof resolver).toBe('function');
+  return (resolver as (value: typeof input) => DirectionalShadowAdmission)(input);
+}
+
+describe('M3 backend admission and fallback truthfulness', () => {
+  it('keeps an explicitly disabled Directional shadow off without fabricating a candidate', async () => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'webgpu',
+        requested: 'off',
+        candidate: 'failed',
+      }),
+    ).resolves.toMatchObject({
+      requested: 'off',
+      effective: 'off',
+      status: 'accepted',
+      lastKnownGood: false,
+      pixelEvidence: 'not-available',
+    });
+  });
+
+  it('admits a production WebGPU/Dawn candidate without converting PCSS to PCF', async () => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'webgpu',
+        requested: 'pcssMedium',
+        candidate: 'accepted',
+      }),
+    ).resolves.toMatchObject({
+      requested: 'pcssMedium',
+      effective: 'pcssMedium',
+      status: 'accepted',
+      lastKnownGood: false,
+      pixelEvidence: 'available',
+    });
+  });
+
+  it.each([
+    ['pcssMedium', 'pcf3'],
+    ['pcssHigh', 'pcf5'],
+  ] as const)('maps WebGL2 %s to fixed effective %s', async (requested, effective) => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'wgpu-webgl2',
+        requested,
+        candidate: 'accepted',
+      }),
+    ).resolves.toMatchObject({
+      requested,
+      effective,
+      status: 'fallback',
+      fallbackReason: 'webgl2-unsupported',
+      pixelEvidence: 'available',
+    });
+  });
+
+  it('projects RhiNull as structural evidence and never as pixel evidence', async () => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'null',
+        requested: 'pcssHigh',
+        candidate: 'accepted',
+      }),
+    ).resolves.toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'rhi-null-structural',
+      status: 'fallback',
+      fallbackReason: 'rhi-null-structural',
+      pixelEvidence: 'not-available',
+    });
+  });
+
+  it('rejects a capable candidate failure while retaining compatible LKG', async () => {
+    const result = await resolveDirectionalShadowAdmission({
+      backendKind: 'webgpu',
+      requested: 'pcssHigh',
+      candidate: 'failed',
+      lastKnownGood: 'pcf3',
+    });
+    expect(result).toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'pcf3',
+      status: 'rejected',
+      fallbackReason: 'candidate-failed',
+      lastKnownGood: true,
+      pixelEvidence: 'available',
+    });
+    expect(result.effective).not.toBe('pcf5');
+  });
+
+  it('keeps falsifiers observable instead of allowing fake effective mappings', async () => {
+    const result = await resolveDirectionalShadowAdmission({
+      backendKind: 'wgpu-webgl2',
+      requested: 'pcssMedium',
+      candidate: 'accepted',
+    });
+    expect(result.fallbackReason).toBe('webgl2-unsupported');
+    expect(result.effective).toBe('pcf3');
+    expect(result).not.toMatchObject({ effective: 'pcssMedium' });
+  });
+});
+
+describe('M3 bounded Directional shadow inspection', () => {
+  it('requires one detached projection with bounded tap and generation facts', async () => {
+    const module = (await import(
+      '../../../render/src/assembly/directional-shadow-inspection'
+    )) as Record<string, unknown>;
+    const project = module.projectDirectionalShadowInspection;
+    expect(typeof project).toBe('function');
+    const result = (project as (input: Record<string, unknown>) => Record<string, unknown>)({
+      admission: {
+        requested: 'pcssHigh',
+        effective: 'pcssHigh',
+        status: 'accepted',
+        pixelEvidence: 'available',
+      },
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+      deviceGeneration: 2,
+      graphGeneration: 7,
+    });
+    expect(result).toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'pcssHigh',
+      cascadeCount: 4,
+      mapSize: 2048,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+      deviceGeneration: 2,
+      graphGeneration: 7,
+    });
+    expect(Object.keys(result)).not.toContain('perPixel');
+    expect(Object.isFrozen(result)).toBe(true);
+  });
+
+  it('projects production facts instead of fixed request, taps, or generations', async () => {
+    const module = (await import(
+      '../../../render/src/assembly/directional-shadow-inspection'
+    )) as Record<string, unknown>;
+    const projectSource = module.projectDirectionalShadowInspectionSource;
+    expect(typeof projectSource).toBe('function');
+    const project = projectSource as (input: Record<string, unknown>) => Record<string, unknown>;
+    const first = project({
+      requested: 'pcf3',
+      candidate: 'accepted',
+      cascadeCount: 3,
+      mapSize: 1024,
+      atlasBytes: 12_582_912,
+      writerPasses: 3,
+      deviceGeneration: 4,
+      graphGeneration: 11,
+      shadowReady: true,
+    });
+    const second = project({
+      requested: 'pcssHigh',
+      candidate: 'failed',
+      lastKnownGood: 'pcf3',
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      deviceGeneration: 5,
+      graphGeneration: 12,
+      shadowReady: false,
+    });
+    expect(first).toMatchObject({
+      requested: 'pcf3',
+      effective: 'pcf3',
+      status: 'accepted',
+      filterTapUpperBound: 9,
+      seamTapUpperBound: 9,
+      cascadeCount: 3,
+      mapSize: 1024,
+      deviceGeneration: 4,
+      graphGeneration: 11,
+    });
+    expect(second).toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'pcf3',
+      status: 'rejected',
+      lastKnownGood: true,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+      cascadeCount: 4,
+      mapSize: 2048,
+      deviceGeneration: 5,
+      graphGeneration: 12,
+    });
+    expect(second).not.toMatchObject({ requested: 'pcf3', status: 'accepted', atlasBytes: 0 });
+  });
+});
+
 // ── w5: surface retry — reconfigure + retry once (AC-03) ─────────────────────
 
 describe('Surface retry (w5)', () => {

package/src/__tests__/resolveName-unified-entry.test.ts

@@ -2,7 +2,7 @@
 //
 // resolveName is the one runtime name-truth function and it delegates to the
 // stateless deriveAssetName pure function (D-6). Every other name consumer reads
-// resolveName or that same deriveAssetName -- none re-implements the XOR rule.
+// resolveName or that same deriveAssetName -- none re-implements the display-name rule.
 //
 // This is a grep/fixture test, not a pure runtime assertion: it reads the source
 // trees and asserts structural unification.
@@ -27,11 +27,11 @@ const buildCatalogSrc = readFileSync(
 );
 
 describe('unified name resolution (AC-04)', () => {
-  it('deriveAssetName is the single XOR rule definition', () => {
+  it('deriveAssetName is the single display-name rule definition', () => {
     expect(deriveSrc).toContain('export function deriveAssetName');
   });
 
-  it('resolveName delegates to deriveAssetName (no inline XOR re-implementation)', () => {
+  it('resolveName delegates to deriveAssetName (no inline re-implementation)', () => {
     expect(registrySrc).toContain("import { deriveAssetName } from '@forgeax/engine-pack/name'");
     // resolveName returns the result of deriveAssetName, not a hand-rolled rule.
     const body = registrySrc.slice(
@@ -55,11 +55,11 @@ describe('unified name resolution (AC-04)', () => {
   });
 
   // M4 expansion (w22 landed): catalog-builder routes through deriveAssetName
-  it('catalog-builder imports and calls deriveAssetName (no inline XOR)', () => {
+  it('catalog-builder imports and calls deriveAssetName (no inline display-name rule)', () => {
     expect(buildCatalogSrc).toContain("import { deriveAssetName } from './deriveAssetName.js'");
     expect(buildCatalogSrc).toContain('deriveAssetName(');
-    // No inline re-implementation of the XOR rule (no hand-rolled basename)
-    // The single deriveAssetName pure function handles all branches.
+    // No inline re-implementation (no hand-rolled basename); the single
+    // deriveAssetName pure function handles the display-name rule.
     expect(buildCatalogSrc.match(/deriveAssetName\(/g)?.length ?? 0).toBeGreaterThanOrEqual(2);
   });
 });

package/src/__tests__/resolveName.test.ts

@@ -4,8 +4,8 @@
 // state directly through registerPackage (Risk-2: no pack-index fetch needed).
 //
 // Coverage:
-//   AC-01 — single-asset package: resolveName === basename(path); the stored
-//           Asset POD carries no `name` property (name is never on the payload).
+//   AC-01 — single-asset package: an explicit stored name wins; basename(path)
+//           remains the fallback. The Asset POD carries no `name` property.
 //   AC-02 — multi-asset package: resolveName returns each entry's stored name.
 
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
@@ -42,6 +42,18 @@ describe('resolveName single-asset package (AC-01)', () => {
     expect(stored).toBeDefined();
     expect(Object.hasOwn(stored as object, 'name')).toBe(false);
   });
+
+  it('preserves an explicit authored name for a single-member pack', () => {
+    const reg = makeRegistry();
+    reg.catalog(parseGuid(SINGLE_GUID), sampler);
+    reg._registerPackage(
+      'assets/Materials.pack.json',
+      [SINGLE_GUID],
+      new Map([[SINGLE_GUID, 'NewMaterial']]),
+    );
+
+    expect(reg.resolveName(SINGLE_GUID)).toBe('NewMaterial');
+  });
 });
 
 describe('resolveName multi-asset package (AC-02)', () => {

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

@@ -6,6 +6,8 @@
 // cascade tile: col = i % tilesPerSide, row = floor(i / tilesPerSide).
 
 import { describe, expect, it } from 'vitest';
+import { projectDirectionalShadowInspection } from '../../../render/src/assembly/directional-shadow-inspection';
+import { resolveDirectionalShadowBackendAdmission } from '../../../render/src/render-pipeline';
 
 /**
  * Pure helper mirroring urp-pipeline.ts atlas sizing logic.
@@ -176,3 +178,42 @@ describe('CSM atlas layout (w13)', () => {
     });
   });
 });
+
+describe('M3 inspection zero-delta structural budget', () => {
+  it('keeps PCF and PCSS on the same atlas and writer budget', () => {
+    const common = {
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      deviceGeneration: 1,
+      graphGeneration: 2,
+    } as const;
+    const pcf = projectDirectionalShadowInspection({
+      admission: resolveDirectionalShadowBackendAdmission({
+        backendKind: 'webgpu',
+        requested: 'pcf5',
+        candidate: 'accepted',
+      }),
+      ...common,
+      blockerTaps: 0,
+      filterTapUpperBound: 25,
+      seamTapUpperBound: 25,
+    });
+    const pcss = projectDirectionalShadowInspection({
+      admission: resolveDirectionalShadowBackendAdmission({
+        backendKind: 'webgpu',
+        requested: 'pcssHigh',
+        candidate: 'accepted',
+      }),
+      ...common,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+    });
+    expect(pcss).toMatchObject({ effective: 'pcssHigh', cascadeCount: 4, mapSize: 2048 });
+    expect(pcf.writerPasses).toBe(pcss.writerPasses);
+    expect(pcf.atlasBytes).toBe(pcss.atlasBytes);
+    expect(pcf.graphGeneration).toBe(pcss.graphGeneration);
+  });
+});

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

@@ -215,6 +215,7 @@ async function importEcs(): Promise<{ World: new () => unknown }> {
 
 async function importComponents(): Promise<{
   Transform: unknown;
+  GlobalTransform: unknown;
   MeshFilter: unknown;
   MeshRenderer: unknown;
   Camera: unknown;

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

@@ -83,7 +83,11 @@ describe('CSM component schema (w1)', () => {
       error: {
         code?: string;
         hint?: string;
-        detail?: { field?: string; value?: number; min?: number; max?: number };
+        detail?: {
+          field?: string;
+          actual?: number;
+          bound?: { kind?: string; min?: number; max?: number };
+        };
       };
     };
 
@@ -97,7 +101,7 @@ describe('CSM component schema (w1)', () => {
       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);
+      expect(r.error.detail?.actual).toBe(0);
     });
 
     it('cascadeCount=5 -> ShadowInvalidConfigError (max=4)', () => {
@@ -110,8 +114,8 @@ describe('CSM component schema (w1)', () => {
       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);
+      expect(r.error.detail?.actual).toBe(5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 1, max: 4 });
     });
 
     it('splitLambda=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
@@ -124,7 +128,8 @@ describe('CSM component schema (w1)', () => {
       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);
+      expect(r.error.detail?.actual).toBeCloseTo(-0.1, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 1 });
     });
 
     it('splitLambda=1.1 -> ShadowInvalidConfigError (max=1)', () => {
@@ -137,8 +142,8 @@ describe('CSM component schema (w1)', () => {
       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);
+      expect(r.error.detail?.actual).toBeCloseTo(1.1, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 1 });
     });
 
     it('cascadeBlend=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
@@ -151,7 +156,8 @@ describe('CSM component schema (w1)', () => {
       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);
+      expect(r.error.detail?.actual).toBeCloseTo(-0.1, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 0.5 });
     });
 
     it('cascadeBlend=0.6 -> ShadowInvalidConfigError (max=0.5)', () => {
@@ -164,8 +170,8 @@ describe('CSM component schema (w1)', () => {
       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);
+      expect(r.error.detail?.actual).toBeCloseTo(0.6, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 0.5 });
     });
 
     it('all three new fields within valid range spawn succeeds', () => {
@@ -180,29 +186,28 @@ describe('CSM component schema (w1)', () => {
 
   // ── w2: ShadowInvalidConfigDetail.max field constructor tests ──────────
 
-  describe('w2: ShadowInvalidConfigDetail.max constructor', () => {
-    it('cascadeCount=5 detail.max=4 via constructor', () => {
+  describe('w2: ShadowInvalidConfigDetail.bound constructor', () => {
+    it('cascadeCount=5 bound.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.detail.actual).toBe(5);
+      expect(err.detail.bound).toEqual({ kind: 'range', min: 1, max: 4 });
       expect(err.hint).toContain('[1, 4]');
     });
 
-    it('cascadeBlend=0.6 detail.max=0.5 via constructor', () => {
+    it('cascadeBlend=0.6 bound.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.detail.bound).toEqual({ kind: 'range', min: 0, max: 0.5 });
       expect(err.hint).toContain('[0, 0.5]');
     });
 
-    it('splitLambda=1.1 detail.max=1 via constructor', () => {
+    it('splitLambda=1.1 bound.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.detail.bound).toEqual({ kind: 'range', min: 0, max: 1 });
       expect(err.hint).toContain('[0, 1]');
     });
   });
@@ -260,15 +265,17 @@ describe('CSM component schema (w1)', () => {
         const err = r.error as {
           code?: string;
           hint?: string;
-          detail?: { field?: string; value?: number; min?: number; max?: number };
+          detail?: {
+            field?: string;
+            actual?: number;
+            bound?: { kind?: string; 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();
+        expect(err.detail?.actual).toBe(0);
+        expect(err.detail?.bound).toEqual({ kind: 'lower-bound', operator: '>=', value: 1 });
       }
     });