@forgeax/engine-render 0.1.20 → 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),
       };
     };
 
@@ -48,14 +48,70 @@ describe('one direct-light snapshot proof', () => {
       'utf8',
     );
     const shader = await readFile(
-      new URL('../../../shader/src/hdrp-cluster-forward.wgsl', import.meta.url),
+      new URL('../../../shader/src/standard-cluster.wgsl', import.meta.url),
       'utf8',
     );
 
     expect(extract.match(/const spotLightQuery =/g)).toHaveLength(1);
     expect(extract).toContain('direction: dirN');
-    expect(lighting).toContain('packLightSlot(pl');
-    expect(lighting).toContain('packLightSlot(sl)');
+    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__/docs-gate-green.unit.test.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+function read(relativePath: string): string {
+  return readFileSync(new URL(relativePath, import.meta.url), 'utf8');
+}
+
+const renderReadme = read('../../README.md');
+const assetsReadme = read('../../../assets-runtime/README.md');
+const instancesSource = read('../components/instances.ts');
+
+describe('M4 material and Instances documentation contract', () => {
+  it('keeps resident observation and derived-bounds recovery discoverable', () => {
+    for (const token of [
+      'renderer.inspect().meshMaterialBindings[]',
+      '`ready`, `pending`, `failed`, or `last-known-good`',
+      'nearest structured preparation',
+      'does not keep a second readiness ledger',
+      '`Instances` remains author data',
+      'renderer derives a CPU union bound',
+      'conservative no-cull result',
+      'GPU path keeps the mesh-local AABB',
+    ]) {
+      expect(renderReadme).toContain(token);
+    }
+    for (const token of [
+      'producer lifecycle observations',
+      '`inspect -> rebuild/recook or refresh LKG -> loadByGuid`',
+      'parallel readiness ledger',
+    ]) {
+      expect(assetsReadme).toContain(token);
+    }
+  });
+
+  it('keeps bounds out of the public Instances author schema', () => {
+    expect(instancesSource).not.toMatch(/\bbounds\s*:/);
+  });
+});

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,
+    });
+  });
+});