@forgeax/engine-render 0.1.4 → 0.1.6

package/src/__tests__/cluster-grid-default-surface.unit.test.ts

@@ -1,17 +1,20 @@
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
-import { DEFAULT_CLUSTER_GRID } from '../hdrp-pipeline';
+import { DEFAULT_CLUSTER_GRID } from '../pipeline/standard-profile';
 
-const ownerSource = readFileSync(new URL('../hdrp-pipeline.ts', import.meta.url), 'utf8');
+const ownerSource = readFileSync(
+  new URL('../pipeline/standard-profile.ts', import.meta.url),
+  'utf8',
+);
 const recordSource = readFileSync(new URL('../record/frame-lighting.ts', import.meta.url), 'utf8');
 
 describe('cluster grid default owner', () => {
-  it('keeps both record-stage fallbacks on the pipeline owner', () => {
+  it('keeps all record-stage fallbacks on the pipeline owner', () => {
     expect(DEFAULT_CLUSTER_GRID).toEqual({ x: 16, y: 9, z: 24 });
     expect(
       ownerSource.match(/export const DEFAULT_CLUSTER_GRID\s*=\s*\{ x: 16, y: 9, z: 24 \}/g),
     ).toHaveLength(1);
-    expect(recordSource.match(/clusterGrid \?\? DEFAULT_CLUSTER_GRID/g)).toHaveLength(2);
+    expect(recordSource.match(/clusterGrid \?\? DEFAULT_CLUSTER_GRID/g)).toHaveLength(3);
     expect(recordSource).not.toMatch(/clusterGrid \?\? \{\s*x: 16,\s*y: 9,\s*z: 24,\s*\}/);
   });
 });

package/src/__tests__/construct-renderer-identity.unit.test.ts

@@ -1,10 +1,23 @@
 import * as render from '@forgeax/engine-render';
-import { constructRenderer as internalConstructRenderer } from '@forgeax/engine-render/internal/construct-renderer';
+import {
+  constructRendererHost as internalConstructRendererHost,
+  type RendererHostAssembly,
+} from '@forgeax/engine-render/internal/construct-renderer';
 import { describe, expect, it } from 'vitest';
+import type { RenderError } from '../errors/render';
+import type { RenderResult } from '../render-contract';
 
 describe('construct-renderer internal entry', () => {
   it('keeps construction out of the public barrel', () => {
     expect('constructRenderer' in render).toBe(false);
-    expect(internalConstructRenderer).toEqual(expect.any(Function));
+    expect(internalConstructRendererHost).toEqual(expect.any(Function));
+  });
+
+  it('freezes the only construct seam as a structured Result factory', () => {
+    type Return = ReturnType<typeof internalConstructRendererHost>;
+    type Expected = Promise<RenderResult<RendererHostAssembly, RenderError>>;
+    // This assertion is intentionally red until construction stops rejecting
+    // and returns the narrow Result contract.
+    expect(null as unknown as Return satisfies Expected).toBeNull();
   });
 });

package/src/__tests__/device-scope-lifecycle.unit.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DeviceScope,
+  type LifecycleResourceSpec,
+  LifecycleTransaction,
+} from '../device/device-scope';
+
+function spec(
+  kind: LifecycleResourceSpec<unknown>['kind'],
+  order: string[],
+  index: number,
+  failAt?: number,
+): LifecycleResourceSpec<unknown> {
+  return {
+    kind,
+    create: () => {
+      if (failAt === index) throw new Error(`create-${kind}`);
+      order.push(`create:${kind}`);
+      return { kind };
+    },
+    cleanup: () => {
+      order.push(`cleanup:${kind}`);
+    },
+  };
+}
+
+describe('DeviceScope lifecycle transaction', () => {
+  it('rolls back the first N-1 resources in reverse order and keeps the primary error', async () => {
+    const scope = DeviceScope.create(7, 'renderer');
+    const order: string[] = [];
+    const transaction = new LifecycleTransaction(scope, { failureAt: 4 });
+    transaction.add(spec('listener', order, 1));
+    transaction.add(spec('surface', order, 2));
+    transaction.add(spec('shader', order, 3));
+    transaction.add(spec('pipeline', order, 4, 4));
+
+    const result = await transaction.commit();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.primary.code).toBe('lifecycle-construction-failed');
+      expect(result.error.primary.detail.owner).toBe('renderer');
+      expect(result.error.cleanupFailures).toEqual([]);
+      expect(result.error.receipt.generation).toBe(7);
+    }
+    expect(order).toEqual([
+      'create:listener',
+      'create:surface',
+      'create:shader',
+      'cleanup:shader',
+      'cleanup:surface',
+      'cleanup:listener',
+    ]);
+    expect(scope.resourceDelta()).toBe(0);
+    expect(scope.state).toBe('active');
+  });
+
+  it('collects cleanup failures without changing the primary error or resource delta', async () => {
+    const scope = DeviceScope.create(8, 'renderer');
+    const transaction = new LifecycleTransaction(scope, { failureAt: 3 });
+    transaction.add({
+      kind: 'buffer',
+      create: () => ({ id: 'buffer' }),
+      cleanup: () => {
+        throw new Error('buffer-cleanup');
+      },
+    });
+    transaction.add({
+      kind: 'texture',
+      create: () => ({ id: 'texture' }),
+      cleanup: () => undefined,
+    });
+    transaction.add({
+      kind: 'binding',
+      create: () => {
+        throw new Error('binding-create');
+      },
+      cleanup: () => undefined,
+    });
+
+    const result = await transaction.commit();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.primary.detail.operation).toBe('create');
+      expect(result.error.primary.detail.resourceKind).toBe('binding');
+      expect(result.error.cleanupFailures).toHaveLength(1);
+      expect(result.error.cleanupFailures[0]?.resourceKind).toBe('buffer');
+    }
+    expect(scope.resourceDelta()).toBe(0);
+  });
+
+  it('publishes a replacement only after complete success and retires the old scope', async () => {
+    const current = DeviceScope.create(10, 'renderer');
+    const oldRef = current.ref('shader', { id: 'old' });
+
+    const replacementResult = await current.replace(11, [
+      {
+        kind: 'shader',
+        create: () => ({ id: 'new' }),
+        cleanup: () => undefined,
+      },
+    ]);
+
+    expect(replacementResult.ok).toBe(true);
+    if (replacementResult.ok) {
+      expect(current.state).toBe('retired');
+      expect(replacementResult.value.state).toBe('active');
+      expect(replacementResult.value.parent).toBe(current);
+      expect(oldRef.isStale(replacementResult.value)).toBe(true);
+    }
+  });
+
+  it('keeps the current scope active when replacement construction is lost', async () => {
+    const current = DeviceScope.create(20, 'renderer');
+    const result = await current.replace(21, [
+      {
+        kind: 'surface',
+        create: () => {
+          throw new Error('replacement-loss');
+        },
+        cleanup: () => undefined,
+      },
+    ]);
+
+    expect(result.ok).toBe(false);
+    expect(current.state).toBe('active');
+    expect(current.generation).toBe(20);
+    expect(current.resourceDelta()).toBe(0);
+  });
+
+  it('makes dispose win over an in-flight construction and terminalizes pending work', async () => {
+    const scope = DeviceScope.create(30, 'renderer');
+    let resolveCreate: ((value: { id: string }) => void) | undefined;
+    const transaction = new LifecycleTransaction(scope);
+    transaction.add({
+      kind: 'post-effect',
+      create: () => new Promise<{ id: string }>((resolve) => (resolveCreate = resolve)),
+      cleanup: () => undefined,
+    });
+
+    const pending = transaction.commit();
+    scope.dispose();
+    resolveCreate?.({ id: 'late' });
+    const result = await pending;
+
+    expect(result.ok).toBe(false);
+    expect(scope.state).toBe('disposed');
+    expect(scope.resourceDelta()).toBe(0);
+  });
+});

package/src/__tests__/device-scope-stale-matrix.unit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { DEVICE_RESOURCE_KINDS, DeviceScope } from '../device/device-scope';
+
+describe('DeviceScope stale resource matrix', () => {
+  it('covers every device-bound resource family through one generation fence', () => {
+    const current = DeviceScope.create(40, 'renderer');
+    const replacement = DeviceScope.create(41, 'renderer');
+
+    for (const kind of DEVICE_RESOURCE_KINDS) {
+      const ref = current.ref(kind, { kind });
+      expect(ref.kind).toBe(kind);
+      expect(ref.isCurrent(current)).toBe(true);
+      expect(ref.isStale(replacement)).toBe(true);
+      expect(replacement.accepts(ref)).toBe(false);
+    }
+
+    expect(DEVICE_RESOURCE_KINDS).toEqual([
+      'listener',
+      'surface',
+      'shader',
+      'pipeline',
+      'buffer',
+      'texture',
+      'binding',
+      'scene-table',
+      'feature',
+      'post-effect',
+    ]);
+  });
+
+  it('does not publish stale alive state after retire or abandon', () => {
+    const retired = DeviceScope.create(50, 'renderer');
+    retired.retire();
+    const abandoned = DeviceScope.create(51, 'renderer');
+    abandoned.abandon();
+
+    expect(retired.state).toBe('retired');
+    expect(abandoned.state).toBe('abandoned');
+    expect(retired.isAlive()).toBe(false);
+    expect(abandoned.isAlive()).toBe(false);
+  });
+});

package/src/__tests__/direct-extract-consumer-contract.test-d.ts

@@ -1,17 +1,14 @@
 import type { World } from '@forgeax/engine-ecs';
-import {
-  extractFrame,
-  extractFrames,
-  type PreparedExtractContext,
-} from '@forgeax/engine-render/internal';
+import type { CatalogDelta } from '@forgeax/engine-types';
 import { expectTypeOf } from 'vitest';
-import type {
-  DerivedMaterialSlotProjection,
-  DerivedMaterialSlotProjectionInput,
-} from '../extract/material-interface.js';
+import type { PreparedExtractContext } from '../render-system-extract';
+import { extractFrame, extractFrames } from '../render-system-extract';
+
+declare const delta: CatalogDelta;
+
+expectTypeOf(delta.scopeId).toEqualTypeOf<string | undefined>();
+expectTypeOf(delta.generation).toEqualTypeOf<number | undefined>();
 
-declare const input: DerivedMaterialSlotProjectionInput;
-declare const projection: DerivedMaterialSlotProjection;
 declare const world: World;
 declare const prepared: PreparedExtractContext;
 
@@ -24,11 +21,3 @@ extractFrame(world, prepared);
 extractFrame(world);
 // @ts-expect-error null is not a prepared context
 extractFrame(world, null);
-
-expectTypeOf(input.schema).toMatchTypeOf<
-  readonly { readonly name: string; readonly type: string }[]
->();
-expectTypeOf(projection.derivedInterface.layoutIdentity).toBeString();
-expectTypeOf(projection.coordinates).toMatchTypeOf<
-  ReadonlyMap<string, { readonly physicalUvScale: readonly [number, number] }>
->();

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

@@ -6,7 +6,6 @@ import type { SpotLightSnapshot } from '../render-system-extract';
 
 const snapshot: SpotLightSnapshot = {
   kind: 'spot',
-  entity: 7,
   position: new Float32Array([0, 2, 0]) as Vec3,
   direction: new Float32Array([0, 1, 0]) as Vec3,
   color: new Float32Array([2, 1, 0.5]) as Vec3,
@@ -14,12 +13,12 @@ const snapshot: SpotLightSnapshot = {
   invRangeSquared: 0.01,
   cosInner: 0.98,
   cosOuter: 0.7,
-  castShadow: true,
-  lightViewProj: new Float32Array(16),
+  castShadow: false,
+  lightViewProj: undefined,
   mapSize: 2048,
   nearPlane: 0.1,
   farPlane: 50,
-  shadowAtlasTile: 0,
+  shadowAtlasTile: -1,
 };
 
 describe('one direct-light snapshot proof', () => {
@@ -40,15 +39,6 @@ describe('one direct-light snapshot proof', () => {
     expect(packed.urp[9]).toBe(1);
     expect(packed.hdrp[8]).toBe(0);
     expect(packed.hdrp[9]).toBe(1);
-    expect(new Int32Array(packed.hdrp.buffer)[13]).toBe(0);
-  });
-
-  it('uses identical LightSlot bytes for storage and uniform transport', () => {
-    const storage = packLightSlot(snapshot);
-    const uniform = packLightSlot(snapshot);
-
-    expect(new Uint8Array(storage.buffer)).toEqual(new Uint8Array(uniform.buffer));
-    expect(new Int32Array(storage.buffer)[13]).toBe(snapshot.shadowAtlasTile);
   });
 
   it('keeps extract and shader owners single-source', async () => {