@forgeax/engine-render 0.1.21 → 0.1.23

package/src/__tests__/direct-light-snapshot.unit.test.ts

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import type { Vec3 } from '@forgeax/engine-math';
 import { describe, expect, it } from 'vitest';
-import { packLightSlot, packSpotLight } from '../light-buffer-layout';
+import { packDirectLightSlot } from '../light-buffer-layout';
 import type { SpotLightSnapshot } from '../render-system-extract';
 
 const snapshot: SpotLightSnapshot = {
@@ -27,8 +27,8 @@ describe('one direct-light snapshot proof', () => {
     const consume = (value: SpotLightSnapshot) => {
       consumed.push(value);
       return {
-        urp: packSpotLight(value),
-        hdrp: packLightSlot(value),
+        urp: packDirectLightSlot(value),
+        hdrp: packDirectLightSlot(value),
       };
     };
 
@@ -54,8 +54,64 @@ describe('one direct-light snapshot proof', () => {
 
     expect(extract.match(/const spotLightQuery =/g)).toHaveLength(1);
     expect(extract).toContain('direction: dirN');
+    expect(lighting).toMatch(/packDirectLightSlot\(/);
     expect(lighting).toContain('prepareStandardLighting');
     expect(lighting).toContain('source');
     expect(shader).not.toContain('normalize(light.direction.xyz)');
   });
 });
+
+const snapshots = [
+  {
+    kind: 'point',
+    sortKey: 20,
+    position: [0, 1, 0],
+    color: [1, 1, 1],
+    invRangeSquared: 0.01,
+    shadowAtlasLayer: -1,
+  },
+  {
+    kind: 'spot',
+    sortKey: 10,
+    position: [0, 2, 0],
+    color: [1, 1, 1],
+    direction: [0, -1, 0],
+    invRangeSquared: 0.01,
+    cosInner: 0.9,
+    cosOuter: 0.7,
+    shadowAtlasTile: -1,
+  },
+  {
+    kind: 'rect-area',
+    sortKey: 30,
+    position: [0, 3, 0],
+    color: [1, 1, 1],
+    invRangeSquared: 0.01,
+    halfWidth: 1,
+    halfHeight: 1,
+    axisX: [1, 0, 0],
+    axisY: [0, 1, 0],
+  },
+] as const;
+
+describe('direct light snapshot consumers', () => {
+  it('keeps one deterministic order for non-cluster and clustered paths', () => {
+    const ordered = [...snapshots].sort((left, right) => left.sortKey - right.sortKey);
+    expect(ordered.map((value) => value.kind)).toEqual(['spot', 'point', 'rect-area']);
+
+    const packed = ordered.map((value) => packDirectLightSlot(value as never));
+    expect(packed).toHaveLength(3);
+    expect(packed.every((slot) => slot.byteLength === 80)).toBe(true);
+  });
+
+  it('requires both direct and cluster consumers to name the same packer', async () => {
+    const frameLighting = await readFile(
+      new URL('../record/frame-lighting.ts', import.meta.url),
+      'utf8',
+    );
+    const clusterBinner = await readFile(new URL('../cluster-binner.ts', import.meta.url), 'utf8');
+
+    expect(frameLighting).toContain('packDirectLightSlot');
+    expect(clusterBinner).toContain('deriveCullingRadius');
+  });
+});

package/src/__tests__/environment-generation.integration.test.ts

@@ -64,6 +64,22 @@ describe('Environment generation candidate and LKG lifecycle (M2)', () => {
     expect(clustered.value.lane).toBe('clustered');
   });
 
+  it('reuses the published active generation when the environment signature stays stable', async () => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(13, 'environment-active-stable'));
+    const first = await lifecycle.ensure(frame('sky-stable'));
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    lifecycle.publish(first.value);
+
+    const nextFrame = await lifecycle.ensure(frame('sky-stable'));
+    expect(nextFrame.ok).toBe(true);
+    if (!nextFrame.ok) return;
+
+    expect(nextFrame.value).toBe(first.value);
+    expect(lifecycle.isActive(nextFrame.value)).toBe(true);
+    expect(lifecycle.inspect().generation).toBe(first.value.generation);
+  });
+
   it('projects descriptor-derived bytes separately from resource count', async () => {
     const lifecycle = new EnvironmentLifecycle(DeviceScope.create(12, 'environment-bytes'));
     const none = await lifecycle.ensure(emptyFrame());

package/src/__tests__/evidence-identity.ts

@@ -0,0 +1,13 @@
+export interface EvidenceImportMetaEnv {
+  readonly VITE_FORGEAX_COMMIT?: string;
+  readonly VITE_GITHUB_SHA?: string;
+}
+
+const viteEnv = (import.meta as ImportMeta & { readonly env?: EvidenceImportMetaEnv }).env;
+
+export function resolveEvidenceCommitIdentity(
+  env: EvidenceImportMetaEnv | undefined = viteEnv,
+): string {
+  const commit = env?.VITE_FORGEAX_COMMIT ?? env?.VITE_GITHUB_SHA;
+  return typeof commit === 'string' && commit.trim().length > 0 ? commit : 'working-tree';
+}

package/src/__tests__/evidence-identity.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { resolveEvidenceCommitIdentity } from './evidence-identity';
+
+describe('evidence commit identity', () => {
+  it('prefers the ForgeaX Vite commit injection', () => {
+    expect(
+      resolveEvidenceCommitIdentity({
+        VITE_FORGEAX_COMMIT: 'forgeax-commit',
+        VITE_GITHUB_SHA: 'github-commit',
+      }),
+    ).toBe('forgeax-commit');
+  });
+
+  it('accepts the GitHub Vite injection when the ForgeaX value is absent', () => {
+    expect(resolveEvidenceCommitIdentity({ VITE_GITHUB_SHA: 'github-commit' })).toBe(
+      'github-commit',
+    );
+  });
+
+  it('uses a stable local identity when no build identity is injected', () => {
+    expect(resolveEvidenceCommitIdentity(undefined)).toBe('working-tree');
+    expect(resolveEvidenceCommitIdentity({ VITE_FORGEAX_COMMIT: '  ' })).toBe('working-tree');
+  });
+});

package/src/__tests__/extended-lighting-recovery.browser.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+describe('extended-lighting browser recovery evidence', () => {
+  it('records an honest bounded status when the real carrier is unavailable', () => {
+    const evidence = {
+      status: 'not-run' as const,
+      reason: 'Browser carrier requires a real extendedLighting adapter and readback owner',
+      generation: 0,
+      recordByteLength: 160,
+    };
+    expect(evidence.status).toBe('not-run');
+    expect(evidence.recordByteLength).toBe(160);
+  });
+});

package/src/__tests__/extended-lighting-recovery.dawn.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+describe('extended-lighting Dawn recovery evidence', () => {
+  it('records an honest bounded status when the real carrier is unavailable', () => {
+    const evidence = {
+      status: 'not-run' as const,
+      reason: 'Dawn carrier requires a real extendedLighting adapter and readback owner',
+      generation: 0,
+      recordByteLength: 160,
+    };
+    expect(evidence.status).toBe('not-run');
+    expect(evidence.recordByteLength).toBe(160);
+  });
+});

package/src/__tests__/extended-lighting-recovery.integration.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { createLightResourceUnavailable } from '../errors/render';
+import type { ExtendedLightingResourceCandidate } from '../prepare/extended-lighting/resources';
+import {
+  createExtendedLightingState,
+  projectExtendedLightingInspection,
+  promoteExtendedLightingCandidate,
+  recordExtendedLightingFailure,
+} from '../prepare/extended-lighting/state';
+
+function candidate(generation: number, descriptorBytes: number): ExtendedLightingResourceCandidate {
+  return {
+    topology: 'extendedLighting',
+    generation,
+    scope: undefined as never,
+    iesSliceCount: 1,
+    cookieSliceCount: 1,
+    cookieMatrices: 1,
+    sampler: undefined as never,
+    iesTexture: undefined,
+    cookieTexture: undefined,
+    cookieMatrixBuffer: undefined,
+    descriptorBytes,
+    uploadCount: 1,
+  };
+}
+
+function failure(generation: number) {
+  return createLightResourceUnavailable({
+    entity: 3,
+    feature: 'cookie',
+    generation,
+    sourceKey: 'parity/extended-lighting/recovery',
+    reason: 'format',
+    expected: 'rgba8unorm',
+    actual: 'rgba16float',
+    hint: 'retry the same source after renderer recovery',
+  });
+}
+
+describe('extended-lighting recovery owner', () => {
+  it('retains the accepted LKG while a replacement candidate fails', () => {
+    const ready = promoteExtendedLightingCandidate(
+      createExtendedLightingState(1),
+      candidate(1, 128),
+    );
+    const degraded = recordExtendedLightingFailure(ready, failure(2));
+    const inspection = projectExtendedLightingInspection(degraded);
+
+    expect(inspection.generation).toBe(1);
+    expect(inspection.accepted).toBe('extendedLighting:generation-1');
+    expect(inspection.lastKnownGood).toBe('extendedLighting:generation-1');
+    expect(inspection.failure).toBe('light-resource-unavailable');
+  });
+
+  it('publishes a replacement only after the new generation is complete', () => {
+    const ready = promoteExtendedLightingCandidate(
+      createExtendedLightingState(1),
+      candidate(1, 128),
+    );
+    const replaced = promoteExtendedLightingCandidate(ready, candidate(2, 256));
+
+    expect(replaced.generation).toBe(2);
+    expect(replaced.accepted?.generation).toBe(2);
+    expect(replaced.lastKnownGood?.generation).toBe(2);
+    expect(replaced.descriptorBytes).toBe(256);
+  });
+
+  it('keeps resize-sized descriptor evidence bounded to the current accepted candidate', () => {
+    const initial = promoteExtendedLightingCandidate(
+      createExtendedLightingState(4),
+      candidate(4, 160),
+    );
+    const resized = promoteExtendedLightingCandidate(initial, candidate(5, 320));
+
+    expect(resized.generation).toBe(5);
+    expect(resized.descriptorBytes).toBe(320);
+    expect(resized.uploadCount).toBe(1);
+    expect(resized.lastKnownGood?.generation).toBe(resized.generation);
+  });
+});

package/src/__tests__/extended-lighting-resources.unit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import {
+  COOKIE_SLICE_CAPACITY,
+  createExtendedLightingResourceCandidate,
+  EXTENDED_LIGHTING_TOPOLOGY,
+  IES_SLICE_CAPACITY,
+  inspectExtendedLightingResources,
+} from '../prepare/extended-lighting/resources';
+import { createExtendedLightingState } from '../prepare/extended-lighting/state';
+
+describe('extended lighting resource topology', () => {
+  it('uses one closed topology and exact-zero state without authored extensions', () => {
+    const state = createExtendedLightingState(3);
+
+    expect(EXTENDED_LIGHTING_TOPOLOGY).toBe('extendedLighting');
+    expect(state).toMatchObject({
+      enabled: false,
+      generation: 3,
+      status: 'empty',
+      resourceCount: 0,
+      descriptorBytes: 0,
+      uploadCount: 0,
+      passCount: 0,
+      bindGroupCount: 0,
+    });
+  });
+
+  it('reserves the fixed 32-slice IES and Cookie capacities', () => {
+    expect(IES_SLICE_CAPACITY).toBe(32);
+    expect(COOKIE_SLICE_CAPACITY).toBe(32);
+  });
+
+  it('does not publish a candidate until every resource and upload succeeds', async () => {
+    const scope = DeviceScope.create(4, 'renderer');
+    const candidate = await createExtendedLightingResourceCandidate({
+      device: undefined,
+      scope,
+      iesSliceCount: 1,
+      cookieSliceCount: 1,
+      cookieMatrices: 1,
+    });
+
+    expect(candidate.ok).toBe(false);
+    expect(inspectExtendedLightingResources(scope)).toMatchObject({
+      status: 'empty',
+      accepted: false,
+      resourceCount: 0,
+    });
+  });
+});

package/src/__tests__/extended-lighting-zero-feature.integration.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import {
+  createExtendedLightingResourceCandidate,
+  inspectExtendedLightingResources,
+} from '../prepare/extended-lighting/resources';
+import {
+  createExtendedLightingState,
+  promoteExtendedLightingCandidate,
+} from '../prepare/extended-lighting/state';
+
+describe('extended lighting zero-feature integration', () => {
+  it('keeps all extension allocations and graph work at exact zero', () => {
+    const scope = DeviceScope.create(1, 'renderer');
+    const state = createExtendedLightingState(1);
+    const inspection = inspectExtendedLightingResources(scope);
+
+    expect(state.enabled).toBe(false);
+    expect(inspection).toEqual({
+      topology: 'extendedLighting',
+      generation: 1,
+      status: 'empty',
+      accepted: false,
+      resourceCount: 0,
+      descriptorBytes: 0,
+      uploadCount: 0,
+      blendInvalidations: 0,
+      passCount: 0,
+    });
+    expect(promoteExtendedLightingCandidate(state, undefined)).toEqual(state);
+  });
+
+  it('retains accepted resources when a later candidate is rejected', async () => {
+    const scope = DeviceScope.create(2, 'renderer');
+    const state = createExtendedLightingState(2);
+    const rejected = await createExtendedLightingResourceCandidate({
+      device: undefined,
+      scope,
+      iesSliceCount: 33,
+      cookieSliceCount: 0,
+      cookieMatrices: 0,
+    });
+
+    expect(rejected.ok).toBe(false);
+    expect(
+      promoteExtendedLightingCandidate(state, rejected.ok ? rejected.value : undefined),
+    ).toMatchObject({
+      status: 'empty',
+      accepted: undefined,
+    });
+  });
+});

package/src/__tests__/factory-contract.integration.test.ts

@@ -126,6 +126,11 @@ describe('factory contract', () => {
     expect(source).not.toContain('tone-output');
   });
 
+  it('forwards the bundler build identity into RenderSystem inspections', () => {
+    const source = readFileSync(factorySourcePath, 'utf8');
+    expect(source).toContain('get build() {\n      return internals.bundler?.build;\n    },');
+  });
+
   it('releases its profiler catalog contribution on dispose', async () => {
     const profiler = createProfiler();
     const renderer = await constructRenderer(
@@ -138,6 +143,34 @@ describe('factory contract', () => {
     expect(profiler.phaseCatalog.render).toEqual([]);
   });
 
+  it('forwards timing admission to the backend device request', async () => {
+    const adapter = new RhiNullAdapter();
+    const device = (await adapter.requestDevice()).unwrap();
+    let requested: unknown;
+    const timingRhi = {
+      ...rhi,
+      requestAdapter: async () =>
+        ok({
+          features: new Set(['timestamp-query']),
+          limits: adapter.limits,
+          requestDevice: async (descriptor?: unknown) => {
+            requested = descriptor;
+            return ok(device);
+          },
+        }),
+    } as never;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      {
+        rhi: timingRhi,
+        gpuPassTiming: { maxPassesPerFrame: 4, maxFramesInFlight: 1, retentionFrames: 2 },
+      },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    expect(requested).toMatchObject({ requiredFeatures: ['timestamp-query'] });
+    renderer.dispose();
+  });
+
   it('completes the receipt-bound create, attach, draw, observe, recover chain', async () => {
     const renderer = await constructRenderer(
       { getContext: () => null },

package/src/__tests__/frame-observation.contract.test.ts

@@ -6,6 +6,7 @@ import {
   type FrameObservationSource,
   observeCurrentFrame,
 } from '../record/frame.js';
+import { validateGraphTargetCaptureReadback } from '../record/frame-snapshot';
 import type { FrameObservationRequest, FrameReceipt } from '../render-contract';
 
 const texture = {} as Texture;
@@ -109,4 +110,18 @@ describe('render current-frame observation producer contract', () => {
     expect(result.ok).toBe(false);
     expect(readback).not.toHaveBeenCalled();
   });
+
+  it('rejects empty fallback bytes unless the selected rows are neutral', () => {
+    const bytes = new Uint8Array(256);
+    expect(
+      validateGraphTargetCaptureReadback({ bytes, expectedByteLength: bytes.byteLength }),
+    ).toEqual({ ok: false, code: 'capture-readback-empty' });
+    expect(
+      validateGraphTargetCaptureReadback({
+        bytes,
+        expectedByteLength: bytes.byteLength,
+        allowZero: true,
+      }),
+    ).toEqual({ ok: true });
+  });
 });

package/src/__tests__/gpu-driven-batch-topology-pbr.unit.test.ts

@@ -0,0 +1,146 @@
+import { vec3 } from '@forgeax/engine-math';
+import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { BatchTopology } from '../gpu-driven/batch-topology';
+import type { PreparedGpuDrivenDraw } from '../gpu-driven/prepared-draw';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const receipt = createStandardPbrArtifactReceipt();
+const resourceClass = JSON.stringify({ textures: 8, samplers: 8, video: 0 });
+
+function prepared(overrides: Partial<PreparedGpuDrivenDraw> = {}): PreparedGpuDrivenDraw {
+  return {
+    identity: { material: 'forgeax::default-standard-pbr', geometry: 'cube', deformation: 'rigid' },
+    receiptGeneration: receipt.generation,
+    directEntry: receipt.directEntry,
+    sceneIndexEntry: receipt.sceneIndexEntry,
+    materialRow: receipt.materialRow,
+    resourceSlots: receipt.resourceSlots,
+    uvSets: receipt.uvSets,
+    vertexInputs: receipt.vertexInputs,
+    alphaMask: receipt.alphaMask,
+    skinPaletteAddress: receipt.skinPaletteAddress,
+    topology: 'triangle-list',
+    indexed: true,
+    first: 0,
+    count: 36,
+    baseVertex: 0,
+    ...overrides,
+  };
+}
+
+function snapshot(
+  entityKey: number,
+  drawPrepared: PreparedGpuDrivenDraw,
+  material: Partial<MaterialSnapshot> = {},
+): RenderableSnapshot {
+  const value = {
+    baseColor: vec3.create(1, 1, 1),
+    metallic: 0,
+    roughness: 0.5,
+    materialShaderId: 'forgeax::default-standard-pbr',
+    textureHandles: new Map(
+      receipt.resourceSlots
+        .filter((slot) => slot.kind === 'texture')
+        .map((slot, index) => [slot.parameter, index + 1]),
+    ) as never,
+    samplerHandles: new Map(
+      receipt.resourceSlots
+        .filter((slot) => slot.kind === 'sampler')
+        .map((slot, index) => [slot.parameter, index + 101]),
+    ) as never,
+    ...material,
+  } as MaterialSnapshot;
+  return {
+    assetHandle: 7,
+    transform: { world: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]) },
+    localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    material: value,
+    materials: [value],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: drawPrepared.first,
+        count: drawPrepared.count,
+        baseVertex: drawPrepared.baseVertex,
+        materialSlot: 0,
+        topology: drawPrepared.topology,
+        pipelineClass: 'prepared-standard-pbr',
+        materialResourceClass: JSON.stringify({
+          textures: drawPrepared.resourceSlots.filter((slot) => slot.kind === 'texture').length,
+          samplers: drawPrepared.resourceSlots.filter((slot) => slot.kind === 'sampler').length,
+          video: 0,
+        }),
+        prepared: drawPrepared,
+      },
+    ],
+  };
+}
+
+function topologyFor(...snapshots: readonly RenderableSnapshot[]): BatchTopology {
+  const projection = new RenderScene();
+  projection.apply(snapshots.map((snapshot) => ({ kind: 'create' as const, snapshot })));
+  const topology = new BatchTopology();
+  topology.rebuild(projection.slotsSnapshot());
+  return topology;
+}
+
+describe('PBR prepared GPU-driven batch topology', () => {
+  it('groups only by prepared identity and admits opaque plus Alpha Mask', () => {
+    const mask = snapshot(2, prepared(), { paramSnapshot: { alphaCutoff: 0.5 } });
+    const topology = topologyFor(snapshot(1, prepared()), mask);
+    const plan = topology.plan();
+
+    expect(plan.candidateCount).toBe(2);
+    expect(plan.batches).toHaveLength(2);
+    expect(plan.batches[0]?.key).toMatchObject({
+      preparedIdentity: 'forgeax::default-standard-pbr|cube|rigid',
+      resourceIdentity: resourceClass,
+    });
+  });
+
+  it('keeps numeric edits in place and patches only resource identity changes', () => {
+    const projection = new RenderScene();
+    projection.apply([{ kind: 'create', snapshot: snapshot(1, prepared()) }]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    const stableRevision = topology.inspect().revision;
+    const numeric = projection.apply([
+      {
+        kind: 'update-transform',
+        worldId: 0,
+        entityKey: 1,
+        world: snapshot(1, prepared()).transform.world,
+      },
+    ]);
+    expect(topology.apply(numeric)).toBe(false);
+    expect(topology.inspect().revision).toBe(stableRevision);
+
+    const resourceChanged = projection.apply([
+      {
+        kind: 'create',
+        snapshot: snapshot(1, prepared({ resourceSlots: receipt.resourceSlots.slice(0, 2) })),
+      },
+    ]);
+    expect(topology.apply(resourceChanged)).toBe(true);
+    expect(topology.inspect().patches).toBe(1);
+    expect(topology.inspect().candidateCount).toBe(1);
+  });
+
+  it('routes Alpha Blend, morph and unsupported authoring out of the GPU lane', () => {
+    const blend = snapshot(2, prepared(), {
+      transparent: true,
+      renderState: { blend: { color: {}, alpha: {} } } as never,
+    });
+    const morph = { ...snapshot(3, prepared()), morph: {} as never } as RenderableSnapshot;
+    const custom = snapshot(4, prepared(), { materialShaderId: 'game::custom-shader' });
+    const topology = topologyFor(snapshot(1, prepared()), blend, morph, custom);
+
+    expect(topology.plan().candidateCount).toBe(1);
+    expect(topology.inspect().ineligible).toBe(3);
+  });
+});

package/src/__tests__/gpu-driven-indirect-raster-evidence.ts

@@ -251,6 +251,7 @@ export async function runGpuDrivenIndirectRasterEvidence(): Promise<GpuDrivenInd
       ]),
       viewBindGroupLayout: viewLayout,
       meshResidencyEpoch: 1,
+      hdrp: false,
     })
     .unwrap();
   if (prepared === undefined) throw new Error('GPU-driven production lane inactive');

package/src/__tests__/gpu-driven-indirect-raster.dawn.test.ts

@@ -25,6 +25,7 @@ describe('GPU-driven indirect raster Dawn', () => {
       'gpu-driven.view-reset',
       'gpu-driven.frustum-compact',
       'gpu-driven.finalize-indirect',
+      'gpu-driven.lod-selection-readback',
       'gpu-driven.opaque-indirect',
       'gpu-driven.raster-readback',
     ]);