@forgeax/engine-render 0.1.6 → 0.1.19

package/src/__tests__/detached-inspection.integration.test.ts

@@ -0,0 +1,177 @@
+import { World } from '@forgeax/engine-ecs';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../assembly/factory';
+import {
+  ANTIALIAS_FXAA,
+  ANTIALIAS_MSAA,
+  ANTIALIAS_NONE,
+  ANTIALIAS_TAA,
+  Camera,
+} from '../components/camera';
+import { DeviceScope } from '../device/device-scope';
+import { renderLifecycleManifestUrl } from './shader-manifest-fixture';
+
+function expectDetached(value: unknown, seen = new Set<unknown>()): void {
+  if (value === null || typeof value !== 'object' || seen.has(value)) return;
+  seen.add(value);
+  expect(value).not.toBeInstanceOf(Error);
+  expect(value).not.toBeInstanceOf(Map);
+  expect(value).not.toBeInstanceOf(Set);
+  expect(ArrayBuffer.isView(value)).toBe(false);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value)) {
+    throw new Error('detached inspection contains a live class instance');
+  }
+  for (const child of Object.values(value)) expectDetached(child, seen);
+}
+
+describe('detached renderer inspection', () => {
+  it('exposes JSON-safe exact-zero cold state', async () => {
+    const renderer = await createRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi },
+      {
+        shaderManifestUrl: `data:application/json,${encodeURIComponent(JSON.stringify({ entries: [] }))}`,
+      },
+    );
+    const inspection = renderer.inspect();
+    expect(inspection.environment.status).toBe('empty');
+    expect(inspection.temporal.mode).toBe('none');
+    expect(inspection.bloom).toMatchObject({
+      graphStatus: 'empty',
+      enabled: false,
+      targetCount: 0,
+      resourceCount: 0,
+      passCount: 0,
+      encodeCount: 0,
+      bindGroupCount: 0,
+      uploadCount: 0,
+      residentChildBytes: 0,
+    });
+    expect(() => JSON.parse(JSON.stringify(inspection))).not.toThrow();
+    expectDetached(inspection);
+    expect(Object.isFrozen(inspection.environment)).toBe(true);
+    expect(Object.isFrozen(inspection.temporal.coverage)).toBe(true);
+    expect(() => expectDetached(DeviceScope.create(401, 'live-scope'))).toThrow(
+      'live class instance',
+    );
+    expect((await renderer.dispose()).ok).toBe(true);
+  });
+
+  it('projects a successful TAA frame into detached PODs', async () => {
+    const renderer = await createRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    registerPropagateTransforms(world);
+    const camera = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 4] } },
+        {
+          component: Camera,
+          data: { fov: 1, aspect: 1, near: 0.1, far: 100, antialias: ANTIALIAS_TAA },
+        },
+      )
+      .unwrap();
+    expect(world.update().ok).toBe(true);
+    const frameInput = () => ({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    let frame = renderer.draw(frameInput());
+    if (!frame.ok) {
+      await Promise.resolve();
+      frame = renderer.draw(frameInput());
+    }
+    expect(frame.ok).toBe(true);
+    const inspection = renderer.inspect();
+    expect(inspection.environment.status).toBe('active');
+    expect(inspection.environment.activeSignature).toBeDefined();
+    expect(inspection.temporal.mode).toBe('taa');
+    expect(inspection.temporal.resources.active).toBeGreaterThan(0);
+    expect(inspection.temporal.resources.candidate).toBe(0);
+    expect(inspection.temporalTarget).toMatchObject({
+      identity: 'standard-scene-temporal',
+      producerId: 'forgeax::standard::scene-data',
+      schema: 'forgeax::scene-data::temporal-v1',
+      targetCount: 1,
+      descriptor: {
+        format: 'rgba16float',
+        width: 64,
+        height: 64,
+        sampleCount: 1,
+        bytes: 64 * 64 * 8,
+      },
+    });
+    const serialized = JSON.parse(JSON.stringify(inspection));
+    expect(serialized.temporal.viewIdentity).toBe(inspection.temporal.viewIdentity);
+    expectDetached(inspection);
+    const originalWidth = inspection.temporal.coverage.width;
+    try {
+      (inspection.temporal.coverage as { width: number }).width = originalWidth + 1;
+    } catch {
+      // Frozen detached snapshots reject mutation in strict callers.
+    }
+    expect(renderer.inspect().temporal.coverage.width).toBe(originalWidth);
+    const nestedBefore = renderer.inspect();
+    for (const subtree of [
+      nestedBefore.environment.active,
+      nestedBefore.environment.lkg,
+      nestedBefore.environment.lastCandidateFailure?.detail,
+      nestedBefore.temporal.resources,
+      nestedBefore.temporal.coverage,
+      nestedBefore.bloom,
+    ]) {
+      if (subtree !== undefined) expect(Object.isFrozen(subtree)).toBe(true);
+    }
+    const detachedBefore = JSON.parse(JSON.stringify(nestedBefore));
+    for (const subtree of [
+      nestedBefore.environment.active,
+      nestedBefore.environment.lkg,
+      nestedBefore.environment.lastCandidateFailure?.detail,
+      nestedBefore.temporal,
+      nestedBefore.temporal.resources,
+      nestedBefore.temporal.coverage,
+      nestedBefore.bloom,
+    ]) {
+      if (subtree === undefined) continue;
+      try {
+        (subtree as Record<string, unknown>).generation = -1;
+        (subtree as Record<string, unknown>).detail = { injected: true };
+      } catch {
+        // Frozen snapshots reject mutation; callers still get detached values.
+      }
+    }
+    expect(JSON.parse(JSON.stringify(renderer.inspect()))).toEqual(detachedBefore);
+    world.set(camera, Camera, { antialias: ANTIALIAS_NONE }).unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(renderer.draw(frameInput()).ok).toBe(true);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(renderer.inspect().temporal.mode).toBe('none');
+    for (const antialias of [ANTIALIAS_FXAA, ANTIALIAS_MSAA]) {
+      world.set(camera, Camera, { antialias }).unwrap();
+      expect(world.update().ok).toBe(true);
+      expect(renderer.draw(frameInput()).ok).toBe(true);
+      expect(renderer.inspect().temporal.mode).toBe(antialias === ANTIALIAS_FXAA ? 'fxaa' : 'msaa');
+      expect(renderer.inspect().temporal.resources).toEqual({
+        active: 0,
+        candidate: 0,
+        retiring: 0,
+        activeBytes: 0,
+        candidateBytes: 0,
+        retiringBytes: 0,
+      });
+    }
+    await renderer.dispose();
+  });
+});

package/src/__tests__/environment-fog-lanes.integration.test.ts

@@ -0,0 +1,219 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Atmosphere } from '../components/atmosphere';
+import { DirectionalLight } from '../components/directional-light';
+import { Fog } from '../components/fog';
+import { DeviceScope } from '../device/device-scope';
+import { selectEnvironment } from '../environment/frame';
+import { EnvironmentLifecycle } from '../environment/lifecycle';
+import { extractFrames } from '../render-system-extract';
+
+const frame = selectEnvironment({
+  environments: [
+    {
+      kind: 'atmosphere',
+      entityKey: 7,
+      sourceKey: 'sky-stable',
+      atmosphere: {
+        turbidity: 2,
+        rayleigh: 1,
+        mieCoefficient: 0.005,
+        mieDirectionalG: 0.8,
+        sunAngularRadius: 0.004675,
+      },
+    },
+  ],
+  fogs: [
+    {
+      entityKey: 8,
+      color: [0.2, 0.3, 0.4],
+      density: 0.03,
+      heightFalloff: 0.2,
+      maxOpacity: 0.9,
+    },
+  ],
+  suns: [{ entityKey: 9, direction: [0, -1, 0], color: [1, 1, 1], intensity: 2 }],
+  lane: 'direct',
+});
+
+describe('Environment and Fog lane graph contract', () => {
+  it('extracts all Atmosphere parameters and normalized Sun facts from ECS rows', () => {
+    const world = new World();
+    world
+      .spawn({
+        component: Atmosphere,
+        data: {
+          turbidity: 3,
+          rayleigh: 1.2,
+          mieCoefficient: 0.006,
+          mieDirectionalG: 0.7,
+          sunAngularRadius: 0.01,
+        },
+      })
+      .unwrap();
+    world
+      .spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -2, 0], intensity: 2 },
+      })
+      .unwrap();
+
+    const extracted = extractFrames([world], 0);
+    expect(extracted.environment).toBeDefined();
+    if (extracted.environment === undefined) throw new Error('expected extracted environment');
+    expect(extracted.environment.source.kind).toBe('atmosphere');
+    if (extracted.environment.source.kind !== 'atmosphere') {
+      throw new Error('expected atmosphere environment source');
+    }
+    expect(extracted.environment.source.atmosphere?.turbidity).toBeCloseTo(3);
+    expect(extracted.environment.source.atmosphere?.rayleigh).toBeCloseTo(1.2);
+    expect(extracted.environment.source.atmosphere?.mieCoefficient).toBeCloseTo(0.006);
+    expect(extracted.environment.source.atmosphere?.mieDirectionalG).toBeCloseTo(0.7);
+    expect(extracted.environment.source.atmosphere?.sunAngularRadius).toBeCloseTo(0.01);
+    const signature = JSON.parse(extracted.environment.signature) as {
+      environments: [{ atmosphere: Record<string, number> }];
+      suns: [{ direction: [number, number, number] }];
+    };
+    expect(signature.environments[0].atmosphere.turbidity).toBeCloseTo(3);
+    expect(signature.environments[0].atmosphere.rayleigh).toBeCloseTo(1.2);
+    expect(signature.environments[0].atmosphere.mieCoefficient).toBeCloseTo(0.006);
+    expect(signature.environments[0].atmosphere.mieDirectionalG).toBeCloseTo(0.7);
+    expect(signature.environments[0].atmosphere.sunAngularRadius).toBeCloseTo(0.01);
+    expect(signature.suns[0].direction).toEqual([0, 1, 0]);
+  });
+
+  it('extracts the resource-owner Fog into the frame projection', () => {
+    const world = new World();
+    const fogEntity = world
+      .spawn({
+        component: Fog,
+        data: {
+          color: [0.15, 0.25, 0.35],
+          density: 0.04,
+          heightFalloff: 0.3,
+          maxOpacity: 0.7,
+        },
+      })
+      .unwrap();
+
+    const first = extractFrames([world], 0);
+    expect(first.fog?.entityKey).toBe(fogEntity);
+    expect(first.fog?.color[0]).toBeCloseTo(0.15);
+    expect(first.fog?.color[1]).toBeCloseTo(0.25);
+    expect(first.fog?.color[2]).toBeCloseTo(0.35);
+    expect(first.fog?.density).toBeCloseTo(0.04);
+    expect(first.fog?.heightFalloff).toBeCloseTo(0.3);
+    expect(first.fog?.maxOpacity).toBeCloseTo(0.7);
+
+    world
+      .set(fogEntity, Fog, {
+        color: [0.6, 0.5, 0.4],
+        density: 0.01,
+        heightFalloff: 0,
+        maxOpacity: 0.2,
+      })
+      .unwrap();
+    const changed = extractFrames([world], 0);
+    expect(changed.fog?.density).toBeCloseTo(0.01);
+    expect(changed.fog?.color[0]).toBeCloseTo(0.6);
+    expect(changed.fog?.color[1]).toBeCloseTo(0.5);
+    expect(changed.fog?.color[2]).toBeCloseTo(0.4);
+  });
+
+  it('uses one signature and generation for direct and clustered consumers', async () => {
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(3, 'environment-lanes'));
+    const direct = await lifecycle.ensure(frame.value, 'direct');
+    const clustered = await lifecycle.ensure(frame.value, 'clustered');
+    expect(direct.ok).toBe(true);
+    expect(clustered.ok).toBe(true);
+    if (!direct.ok || !clustered.ok) return;
+    expect(clustered.value.generation).toBe(direct.value.generation);
+    expect(clustered.value.signature).toBe(direct.value.signature);
+    expect(clustered.value.liveHandle).toBe(direct.value.liveHandle);
+  });
+
+  it('keeps failed candidate receipts structured and active/LKG unchanged', async () => {
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(4, 'environment-recovery'));
+    const published = await lifecycle.ensure(frame.value, 'direct');
+    expect(published.ok).toBe(true);
+    if (!published.ok) return;
+    lifecycle.publish(published.value);
+    const before = lifecycle.inspect();
+    const failed = await lifecycle.ensure(frame.value, { failureAt: 'execute' });
+    expect(failed.ok).toBe(false);
+    if (failed.ok) return;
+    expect(failed.error.code).toBe('environment-generation-failed');
+    expect(failed.error.detail).toEqual({ sourceKey: 'sky-stable', stage: 'execute' });
+    expect(lifecycle.inspect()).toEqual(before);
+  });
+
+  it('rejects an invalid extracted candidate before lifecycle ensure, then publishes one correction', async () => {
+    const world = new World();
+    const atmosphereEntity = world
+      .spawn({
+        component: Atmosphere,
+        data: {
+          turbidity: 2,
+          rayleigh: 1,
+          mieCoefficient: 0.005,
+          mieDirectionalG: 0.8,
+          sunAngularRadius: 0.004675,
+        },
+      })
+      .unwrap();
+    world
+      .spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], intensity: 1 },
+      })
+      .unwrap();
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(5, 'environment-render-path'));
+
+    const initial = extractFrames([world], 0);
+    expect(initial.environmentReady).toBe(true);
+    expect(initial.environment).toBeDefined();
+    if (initial.environment === undefined) throw new Error('expected initial environment');
+    const first = await lifecycle.ensure(initial.environment);
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    lifecycle.publish(first.value);
+    const beforeInvalid = lifecycle.inspect();
+
+    world
+      .set(atmosphereEntity, Atmosphere, {
+        turbidity: -1,
+        rayleigh: 1,
+        mieCoefficient: 0.005,
+        mieDirectionalG: 0.8,
+        sunAngularRadius: 0.004675,
+      })
+      .unwrap();
+    const invalid = extractFrames([world], 0);
+    expect(invalid.environmentReady).toBe(false);
+    expect(lifecycle.inspect()).toEqual(beforeInvalid);
+
+    world
+      .set(atmosphereEntity, Atmosphere, {
+        turbidity: 3,
+        rayleigh: 1,
+        mieCoefficient: 0.006,
+        mieDirectionalG: 0.7,
+        sunAngularRadius: 0.01,
+      })
+      .unwrap();
+    const corrected = extractFrames([world], 0);
+    expect(corrected.environmentReady).toBe(true);
+    expect(corrected.environment).toBeDefined();
+    if (corrected.environment === undefined) throw new Error('expected corrected environment');
+    const second = await lifecycle.ensure(corrected.environment);
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+    expect(second.value.generation).toBeGreaterThan(first.value.generation);
+    lifecycle.publish(second.value);
+    expect(lifecycle.inspect().activeSignature).toBe(second.value.signature);
+  });
+});

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

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import { selectEnvironment } from '../environment/frame';
+import { EnvironmentLifecycle } from '../environment/lifecycle';
+import type { EnvironmentFrame } from '../extract/environment';
+
+function frame(sourceKey: string): EnvironmentFrame {
+  const result = selectEnvironment({
+    environments: [{ kind: 'image', entityKey: 1, sourceKey }],
+    fogs: [],
+    suns: [],
+    lane: 'direct',
+  });
+  if (!result.ok) throw result.error;
+  return Object.freeze({
+    ...result.value,
+    resourceDescriptor: Object.freeze({ width: 2, height: 2, bytesPerPixel: 4 }),
+  });
+}
+
+function emptyFrame(): EnvironmentFrame {
+  const result = selectEnvironment({
+    environments: [],
+    fogs: [],
+    suns: [],
+    lane: 'direct',
+  });
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('Environment generation candidate and LKG lifecycle (M2)', () => {
+  it.each([
+    'prepare',
+    'build',
+    'execute',
+    'finish',
+    'submit',
+  ] as const)('keeps active/LKG unchanged when %s aborts a candidate', async (failureAt) => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(11, 'environment-abort'));
+    const initial = await lifecycle.ensure(frame('sky-a'));
+    expect(initial.ok).toBe(true);
+    if (!initial.ok) return;
+    lifecycle.publish(initial.value);
+    const before = lifecycle.inspect();
+    const failed = await lifecycle.ensure(frame('sky-b'), { failureAt });
+    expect(failed.ok).toBe(false);
+    expect(lifecycle.inspect()).toEqual(before);
+  });
+
+  it('does not rebuild a stable signature and shares one generation across both lanes', async () => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(1, 'environment'));
+    const first = await lifecycle.ensure(frame('sky-a'));
+    const stable = await lifecycle.ensure(frame('sky-a'));
+    const clustered = await lifecycle.ensure(frame('sky-a'), 'clustered');
+
+    expect(first.ok).toBe(true);
+    expect(stable.ok).toBe(true);
+    expect(clustered.ok).toBe(true);
+    if (!first.ok || !stable.ok || !clustered.ok) return;
+    expect(stable.value).toBe(first.value);
+    expect(clustered.value.signature).toBe(first.value.signature);
+    expect(clustered.value.generation).toBe(first.value.generation);
+    expect(clustered.value.lane).toBe('clustered');
+  });
+
+  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());
+    expect(none.ok).toBe(true);
+    if (!none.ok) return;
+    expect(lifecycle.inspect().active).toBeUndefined();
+    lifecycle.publish(none.value);
+    expect(lifecycle.inspect()).toMatchObject({
+      bytes: 0,
+      resourceCount: 0,
+      residentBytes: 0,
+    });
+
+    const image = await lifecycle.ensure(frame('sky-bytes'));
+    expect(image.ok).toBe(true);
+    if (!image.ok) return;
+    expect(image.value.resourceCount).toBe(1);
+    expect(image.value.resourceBytes).toBe(16);
+    lifecycle.publish(image.value);
+    expect(lifecycle.inspect()).toMatchObject({
+      bytes: 16,
+      resourceCount: 1,
+      residentBytes: 16,
+    });
+  });
+
+  it('keeps active and LKG untouched when candidate generation fails, then recovers', async () => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(2, 'environment'));
+    const initial = await lifecycle.ensure(frame('sky-a'));
+    expect(initial.ok).toBe(true);
+    if (!initial.ok) return;
+    lifecycle.publish(initial.value);
+
+    const failed = await lifecycle.ensure(frame('sky-b'), { failureAt: 'build' });
+    expect(failed.ok).toBe(false);
+    expect(lifecycle.inspect()).toMatchObject({
+      activeSignature: initial.value.signature,
+      lkgSignature: initial.value.signature,
+    });
+
+    const recovered = await lifecycle.ensure(frame('sky-b'));
+    expect(recovered.ok).toBe(true);
+    if (!recovered.ok) return;
+    lifecycle.publish(recovered.value);
+    expect(recovered.value.generation).toBeGreaterThan(initial.value.generation);
+    expect(recovered.value.signature).not.toBe(initial.value.signature);
+  });
+
+  it('retires old generations only after leases release and never reuses lost handles', async () => {
+    const scope = DeviceScope.create(3, 'environment');
+    const lifecycle = new EnvironmentLifecycle(scope);
+    const old = await lifecycle.ensure(frame('sky-a'));
+    expect(old.ok).toBe(true);
+    if (!old.ok) return;
+    lifecycle.publish(old.value);
+    const lease = lifecycle.acquire();
+
+    const next = await lifecycle.ensure(frame('sky-b'));
+    expect(next.ok).toBe(true);
+    if (!next.ok) return;
+    lifecycle.publish(next.value);
+    expect(old.value.retired).toBe(false);
+    expect(lifecycle.inspect().retiringBytes).toBeGreaterThan(0);
+    lease.release();
+    lifecycle.collectRetired();
+    expect(old.value.retired).toBe(true);
+    expect(lifecycle.inspect().retiringBytes).toBe(0);
+
+    const recovered = await lifecycle.recover(DeviceScope.create(4, 'environment'));
+    expect(recovered.ok).toBe(true);
+    if (!recovered.ok) return;
+    expect(recovered.value.generation).not.toBe(old.value.generation);
+    expect(recovered.value.liveHandle).not.toBe(old.value.liveHandle);
+  });
+});