@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,331 @@
+import { World } from '@forgeax/engine-ecs';
+import { createProfiler } from '@forgeax/engine-profiler';
+import { RhiNullAdapter, rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { Camera } from '../components';
+import { constructRenderer } from '../construct-renderer';
+
+function manifestUrl(): string {
+  return `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+}
+
+describe('factory contract', () => {
+  it('releases its profiler catalog contribution on dispose', async () => {
+    const profiler = createProfiler();
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { profiler, rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+
+    expect(profiler.phaseCatalog.render.length).toBeGreaterThan(0);
+    renderer.dispose();
+    expect(profiler.phaseCatalog.render).toEqual([]);
+  });
+
+  it('rolls back a post-process params buffer when its initial write fails', async () => {
+    const adapter = new RhiNullAdapter();
+    const deviceResult = await adapter.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok) return;
+    const device = deviceResult.value;
+    device.queue.writeBuffer = () =>
+      ({
+        ok: false,
+        error: new Error('write failed'),
+      }) as never;
+    const failingRhi = {
+      requestAdapter: () =>
+        Promise.resolve({
+          ok: true as const,
+          value: { ...adapter, requestDevice: () => Promise.resolve(deviceResult) },
+        }),
+      acquireCanvasContext: rhi.acquireCanvasContext,
+      createShaderModule: rhi.createShaderModule,
+    };
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi: failingRhi as never },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    expect(() =>
+      renderer.postProcess.register('test::write-failure', {
+        source: 'fn main() {}',
+        params: { byteSize: 16, defaultValue: new Uint8Array(16) },
+      }),
+    ).toThrow('write failed');
+    const buffers = (device as import('@forgeax/engine-rhi-null').RhiNullDevice).bookkeeper
+      .allRecords()
+      .filter((record) => record.kind === 'Buffer');
+    expect(buffers.at(-1)?.destroyed).toBe(true);
+    renderer.dispose();
+  });
+
+  it('attaches derived-state systems once without putting writes in draw', async () => {
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const world = new World();
+
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    expect(world.inspect().schedules.flatMap((schedule) => schedule.systems)).not.toEqual(
+      expect.arrayContaining([expect.objectContaining({ name: 'renderDerivedEntities' })]),
+    );
+    renderer.dispose();
+  });
+
+  it('leases one World transform schedule across independent renderer owners', async () => {
+    const first = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const second = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const world = new World();
+
+    expect(first.attachWorld(world).ok).toBe(true);
+    expect(second.attachWorld(world).ok).toBe(true);
+    first.dispose();
+    expect(second.attachWorld(world).ok).toBe(true);
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 5] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    expect(world.update().ok).toBe(true);
+    second.dispose();
+  });
+
+  it('releases one World without disposing the shared Renderer', async () => {
+    const first = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const second = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const world = new World();
+
+    expect(first.attachWorld(world).ok).toBe(true);
+    first.detachWorld(world);
+    first.detachWorld(world);
+    expect(second.attachWorld(world).ok).toBe(true);
+    second.dispose();
+    first.dispose();
+  });
+
+  it('keeps the last published frame after rejecting an invalid update delta', async () => {
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    expect((await renderer.ready).ok).toBe(true);
+    const world = new World();
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 5] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+
+    expect(world.update(Number.NaN).ok).toBe(false);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    renderer.dispose();
+  });
+
+  it('resolves a renderer for a host canvas and rejects missing input', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+    await expect(
+      constructRenderer({ getContext: () => null }, { rhi }, { shaderManifestUrl: manifest }),
+    ).resolves.toMatchObject({
+      backend: 'webgpu',
+    });
+    await expect(constructRenderer(undefined, { rhi })).rejects.toBeInstanceOf(Error);
+  });
+
+  it('temporarily releases presentation while preserving the Renderer identity', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifest },
+    );
+    expect(renderer.releaseSurface().ok).toBe(true);
+    expect(renderer.releaseSurface().ok).toBe(true);
+    expect(renderer.draw([], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(false);
+    expect(renderer.restoreSurface().ok).toBe(true);
+    expect(renderer.restoreSurface().ok).toBe(true);
+    expect(renderer.draw([], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+  });
+
+  it('does not unconfigure a surface after its ownership was released', async () => {
+    let unconfigureCalls = 0;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      {
+        rhi: {
+          ...rhi,
+          acquireCanvasContext: () => ({
+            ok: true as const,
+            value: {
+              configure: () => ({ ok: true as const, value: undefined }),
+              unconfigure: () => {
+                unconfigureCalls += 1;
+              },
+              getConfiguration: () => undefined,
+              getCurrentTexture: () => ({
+                ok: true as const,
+                value: { __brand: 'TextureView' },
+              }),
+            },
+          }),
+        },
+      } as never,
+      { shaderManifestUrl: manifestUrl() },
+    );
+
+    expect(renderer.releaseSurface().ok).toBe(true);
+    expect(unconfigureCalls).toBe(1);
+    renderer.dispose();
+    expect(unconfigureCalls).toBe(1);
+  });
+
+  it('keeps the real factory-owned GPU refusal structured on the null carrier', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi, membershipTiming: { mode: 'gpu' } },
+      { shaderManifestUrl: manifest },
+    );
+    try {
+      const ready = await renderer.ready;
+      expect(ready.ok).toBe(true);
+      expect(renderer.membershipTiming).toBeDefined();
+      const started = renderer.membershipTiming?.start();
+      expect(started?.ok).toBe(false);
+      if (started !== undefined && !started.ok) {
+        expect(started.error.code).toBe('timestamp-query-unsupported');
+        expect(started.error.expected).toContain('timestampQuery');
+        expect(started.error.hint).toEqual(expect.any(String));
+        expect(started.error.detail).toEqual(expect.any(String));
+      }
+    } finally {
+      renderer.dispose();
+    }
+  });
+
+  it('reports one capture identity through the real Render submit path for CPU control', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi, membershipTiming: { mode: 'cpu-control' } },
+      { shaderManifestUrl: manifest },
+    );
+    try {
+      const ready = await renderer.ready;
+      expect(ready.ok).toBe(true);
+      const timing = renderer.membershipTiming;
+      expect(timing?.start().ok).toBe(true);
+      const world = new World();
+      expect(renderer.attachWorld(world).ok).toBe(true);
+      expect(world.update().ok).toBe(true);
+      expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+      const report = await timing?.finish();
+      expect(report?.ok).toBe(true);
+      if (report?.ok) {
+        expect(report.value.captureId).toMatch(/^membership-\d+$/);
+        expect(report.value.submissionToken).toBe(`${report.value.captureId}:submission`);
+        expect(report.value.actualProducer).toBe('cpu');
+        expect(report.value.gpu).toBeNull();
+      }
+    } finally {
+      renderer.dispose();
+    }
+  });
+
+  it('publishes frame completion only after a successful draw', async () => {
+    const manifest = manifestUrl();
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifest },
+    );
+    expect((await renderer.ready).ok).toBe(true);
+
+    let completions = 0;
+    const unsubscribe = renderer.subscribeFrameEnd(() => {
+      completions += 1;
+    });
+    const world = new World();
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    world.update().unwrap();
+
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(completions).toBe(1);
+
+    expect(renderer.releaseSurface().ok).toBe(true);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(false);
+    expect(completions).toBe(1);
+
+    expect(renderer.restoreSurface().ok).toBe(true);
+    unsubscribe();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(completions).toBe(1);
+  });
+
+  it('does not publish completion when the render stage cannot submit', async () => {
+    const adapterResult = await rhi.requestAdapter();
+    expect(adapterResult.ok).toBe(true);
+    if (!adapterResult.ok) return;
+    const deviceResult = await adapterResult.value.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok) return;
+    const failingPack = {
+      rhi: {
+        requestAdapter: () => Promise.resolve(adapterResult),
+        acquireCanvasContext: () => ({
+          ok: true as const,
+          value: {
+            configure: () => ({ ok: true as const, value: undefined }),
+            unconfigure: () => undefined,
+            getConfiguration: () => undefined,
+            getCurrentTexture: () => ({
+              ok: false as const,
+              error: new Error('surface unavailable'),
+            }),
+          },
+        }),
+      },
+    };
+    const renderer = await constructRenderer({ getContext: () => null }, failingPack as never, {
+      shaderManifestUrl: manifestUrl(),
+    });
+    expect((await renderer.ready).ok).toBe(true);
+
+    let completions = 0;
+    renderer.subscribeFrameEnd(() => {
+      completions += 1;
+    });
+    const world = new World();
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    world.update().unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(completions).toBe(0);
+  });
+});

package/src/__tests__/fallback-row-stride-surface.unit.test.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { FALLBACK_BYTES_PER_ROW } from '../ibl/skylight-bind-group';
+
+const ownerSource = readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8');
+const rendererSource = readFileSync(
+  new URL('../renderer/renderer-factory.ts', import.meta.url),
+  'utf8',
+);
+
+describe('fallback texture row-stride owner', () => {
+  it('keeps both 1x1 fallback upload paths on one owner', () => {
+    expect(FALLBACK_BYTES_PER_ROW).toBe(256);
+    expect(ownerSource.match(/export const FALLBACK_BYTES_PER_ROW\s*=\s*256/g)).toHaveLength(1);
+    expect(rendererSource).toContain('FALLBACK_BYTES_PER_ROW');
+    expect(rendererSource).not.toMatch(/const FALLBACK_BYTES_PER_ROW\s*=\s*256/);
+  });
+});

package/src/__tests__/fog-ai-user.fixture.ts

@@ -0,0 +1,350 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { World } from '@forgeax/engine-ecs';
+import {
+  Camera,
+  Fog,
+  type FogOwnerConflictError,
+  type FogParametersInvalidError,
+} from '@forgeax/engine-render';
+import { createRenderer } from '@forgeax/engine-render/internal';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { expect } from 'vitest';
+
+const WORKTREE_ROOT = resolve(fileURLToPath(new URL('.', import.meta.url)), '../../../..');
+const FEATURE_ID = 'feat-20260823-scene-fog-height-aerial-perspective-v1';
+const FEATURE_DIR =
+  process.env.FORGEAX_FOG_FEATURE_DIR ??
+  resolve(WORKTREE_ROOT, `.forgeax-harness/forgeax-loop/${FEATURE_ID}`);
+const EVIDENCE_DIR = resolve(FEATURE_DIR, 'evidence');
+const EVIDENCE_PATH = resolve(EVIDENCE_DIR, 'ai-fog-walkthrough.json');
+const BROWSER_TRACE_PATH = resolve(EVIDENCE_DIR, 'browser-fog-trace.json');
+const DAWN_TRACE_PATH = resolve(EVIDENCE_DIR, 'dawn-fog-trace.json');
+const DAWN_READBACK_PATH = resolve(EVIDENCE_DIR, 'dawn-producer-pixels.json');
+
+function engineRevision(): string {
+  return process.env.FORGEAX_ENGINE_REVISION ?? 'unknown';
+}
+
+function evidenceRelativePath(path: string): string {
+  return relative(FEATURE_DIR, path).replaceAll('\\', '/');
+}
+
+type FogFailure = FogOwnerConflictError | FogParametersInvalidError;
+
+function manifestUrl(): string {
+  const manifest = {
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: '/* pbr stub */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+      { hash: 'tonemap0', wgsl: '/* tonemap stub */', glsl: '', bindings: '' },
+    ],
+  };
+  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+}
+
+function canvas(): HTMLCanvasElement {
+  return {
+    width: 64,
+    height: 64,
+    getContext: () => null,
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  } as unknown as HTMLCanvasElement;
+}
+
+function recoveryAction(
+  error: FogFailure,
+): 'remove-duplicate-and-retry' | 'repair-field-and-retry' {
+  switch (error.code) {
+    case 'fog-owner-conflict':
+      return 'remove-duplicate-and-retry';
+    case 'fog-parameters-invalid':
+      return 'repair-field-and-retry';
+  }
+}
+
+function readJson(path: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+}
+
+function browserPngReadback(trace: Record<string, unknown>): {
+  readonly path: string;
+  readonly sha256: string;
+  readonly bytes: number;
+  readonly width: number;
+  readonly height: number;
+  readonly sameExecutionContext: boolean;
+  readonly activePhase: string;
+  readonly center: readonly number[];
+} {
+  const screenshot = trace.screenshot as {
+    readonly path?: unknown;
+    readonly bytes?: unknown;
+    readonly sha256?: unknown;
+    readonly read?: {
+      readonly width?: unknown;
+      readonly height?: unknown;
+      readonly phase?: unknown;
+      readonly center?: unknown;
+    };
+  };
+  const path = typeof screenshot.path === 'string' ? screenshot.path : '';
+  expect(path).not.toBe('');
+  expect(existsSync(path)).toBe(true);
+  const png = readFileSync(path);
+  expect(
+    Buffer.from(png.subarray(0, 8)).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])),
+  ).toBe(true);
+  const width = png.readUInt32BE(16);
+  const height = png.readUInt32BE(20);
+  const sha256 = createHash('sha256').update(png).digest('hex');
+  expect(sha256).toBe(screenshot.sha256);
+  expect(png.byteLength).toBe(screenshot.bytes);
+  expect(width).toBe(screenshot.read?.width);
+  expect(height).toBe(screenshot.read?.height);
+  expect(screenshot.read?.phase).toEqual(expect.any(String));
+  expect(screenshot.read?.phase).not.toBe('disabled');
+  expect(Array.isArray(screenshot.read?.center)).toBe(true);
+  expect((screenshot.read?.center as unknown[]).length).toBe(4);
+  expect((screenshot.read?.center as unknown[]).every((value) => typeof value === 'number')).toBe(
+    true,
+  );
+  return {
+    path: evidenceRelativePath(resolve(EVIDENCE_DIR, 'browser-fog.png')),
+    sha256,
+    bytes: png.byteLength,
+    width,
+    height,
+    sameExecutionContext:
+      screenshot.read?.width === width &&
+      screenshot.read?.height === height &&
+      screenshot.sha256 === sha256,
+    activePhase: screenshot.read?.phase as string,
+    center: screenshot.read?.center as number[],
+  };
+}
+
+function activeVisual(trace: Record<string, unknown>): Record<string, unknown> {
+  const visuals = trace.visualEvidence as Array<Record<string, unknown>>;
+  const visual = visuals.find((entry) => entry.phase !== 'disabled');
+  expect(visual).toBeDefined();
+  if (visual === undefined) throw new Error('missing active sampled visual evidence');
+  expect(visual).toMatchObject({
+    phase: expect.any(String),
+    observed: expect.any(Array),
+    verdict: 'pass',
+    confidence: expect.stringMatching(/^(medium|high)$/),
+  });
+  return visual;
+}
+
+export async function runFogAiUserWalkthrough(): Promise<void> {
+  const renderer = await createRenderer(canvas(), { rhi }, { shaderManifestUrl: manifestUrl() });
+  const routedErrors: FogFailure[] = [];
+  const detachErrorListener = renderer.onError((error) => {
+    switch (error.code) {
+      case 'fog-owner-conflict':
+      case 'fog-parameters-invalid':
+        routedErrors.push(error);
+        break;
+    }
+  });
+  const world = new World();
+  const fogEntity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: Camera, data: { fov: 60, near: 0.1, far: 1000 } },
+      { component: Fog, data: {} },
+    )
+    .unwrap();
+
+  try {
+    expect((await renderer.ready).ok).toBe(true);
+    expect(renderer.attachWorld(world).ok).toBe(true);
+
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    const accepted = renderer.renderScene.fog;
+    expect(accepted).toMatchObject({
+      enabled: true,
+      resourceOwner: 0,
+      entity: fogEntity,
+      reactive: true,
+      failure: undefined,
+    });
+    expect(Object.keys(accepted).sort()).toEqual([
+      'enabled',
+      'entity',
+      'failure',
+      'reactive',
+      'resourceOwner',
+      'revision',
+    ]);
+    const acceptedRevision = accepted.revision;
+    expect(acceptedRevision).toEqual(expect.any(Number));
+
+    const duplicate = world.spawn({ component: Fog, data: {} }).unwrap();
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    const conflict = routedErrors.find(
+      (error): error is FogOwnerConflictError => error.code === 'fog-owner-conflict',
+    );
+    expect(conflict).toBeDefined();
+    expect(conflict && recoveryAction(conflict)).toBe('remove-duplicate-and-retry');
+    expect(conflict).toMatchObject({
+      code: 'fog-owner-conflict',
+      expected: 'resourceOwner contains zero or one Fog entity',
+      hint: 'remove every Fog entity except one from the resourceOwner World, then retry draw',
+      detail: {
+        resourceOwner: 0,
+        entities: expect.arrayContaining([fogEntity, duplicate]),
+        omitted: 0,
+      },
+    });
+    expect(renderer.renderScene.fog).toMatchObject({
+      enabled: true,
+      entity: fogEntity,
+      revision: acceptedRevision,
+      reactive: false,
+      failure: 'fog-owner-conflict',
+    });
+
+    expect(world.despawn(duplicate).ok).toBe(true);
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    expect(renderer.renderScene.fog.failure).toBeUndefined();
+
+    expect(world.set(fogEntity, Fog, { density: Number.NaN }).ok).toBe(true);
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    const invalid = routedErrors.find(
+      (error): error is FogParametersInvalidError => error.code === 'fog-parameters-invalid',
+    );
+    expect(invalid).toBeDefined();
+    expect(invalid && recoveryAction(invalid)).toBe('repair-field-and-retry');
+    expect(invalid).toMatchObject({
+      code: 'fog-parameters-invalid',
+      expected: 'a finite non-negative number',
+      detail: {
+        entity: fogEntity,
+        field: 'density',
+        actual: Number.NaN,
+      },
+    });
+    expect(renderer.renderScene.fog).toMatchObject({
+      enabled: true,
+      entity: fogEntity,
+      revision: acceptedRevision,
+      reactive: false,
+      failure: 'fog-parameters-invalid',
+    });
+
+    expect(world.set(fogEntity, Fog, { density: 0.02 }).ok).toBe(true);
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    const repaired = renderer.renderScene.fog;
+    expect(repaired).toMatchObject({
+      enabled: true,
+      entity: fogEntity,
+      reactive: true,
+      failure: undefined,
+    });
+    expect(repaired.revision).not.toBe(acceptedRevision);
+
+    const visualEvidenceAvailable = [BROWSER_TRACE_PATH, DAWN_TRACE_PATH, DAWN_READBACK_PATH].every(
+      (path) => existsSync(path),
+    );
+    if (!visualEvidenceAvailable) {
+      if (process.env.CI) return;
+      throw new Error(
+        'Fog visual evidence is missing; set FORGEAX_FOG_FEATURE_DIR to the feature evidence directory',
+      );
+    }
+
+    const browserTrace = readJson(BROWSER_TRACE_PATH);
+    const dawnTrace = readJson(DAWN_TRACE_PATH);
+    const dawnReadback = readJson(DAWN_READBACK_PATH);
+    const browserPng = browserPngReadback(browserTrace);
+    const browserVisual = activeVisual(browserTrace);
+    const dawnVisual = activeVisual(dawnTrace);
+    expect(browserTrace.backend).toBe('browser');
+    expect(browserTrace.frames).toBe(300);
+    expect(browserTrace.errors).toEqual([]);
+    expect(browserTrace.verdict).toBe('pass');
+    expect(dawnTrace.backend).toBe('dawn');
+    expect(dawnTrace.frames).toBe(300);
+    expect(dawnTrace.errors).toEqual([]);
+    expect(dawnTrace.verdict).toBe('pass');
+    expect(dawnReadback.backend).toBe('dawn');
+    expect(browserPng.sameExecutionContext).toBe(true);
+
+    const evidence = {
+      schemaVersion: 'forgeax-fog-ai-walkthrough-v1',
+      featureId: FEATURE_ID,
+      engineRevision: engineRevision(),
+      command:
+        'pnpm exec vitest run --project=@forgeax/engine-render packages/render/src/__tests__/fog-inspection.integration.test.ts',
+      result: browserTrace.verdict === 'pass' && dawnTrace.verdict === 'pass' ? 'pass' : 'fail',
+      evidence: {
+        authoring: {
+          imports: ['@forgeax/engine-render/Fog', '@forgeax/engine-ecs/World'],
+          draw: 'renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })',
+          resourceOwner: 0,
+          acceptedRevision,
+          repairedRevision: repaired.revision,
+          inspectionKeys: Object.keys(accepted).sort(),
+        },
+        recovery: {
+          conflict: {
+            code: conflict?.code,
+            action: recoveryAction(conflict as FogOwnerConflictError),
+            detail: conflict?.detail,
+          },
+          invalid: {
+            code: invalid?.code,
+            action: recoveryAction(invalid as FogParametersInvalidError),
+            detail: invalid?.detail
+              ? {
+                  ...invalid.detail,
+                  actual: Number.isNaN(invalid.detail.actual) ? 'NaN' : invalid.detail.actual,
+                }
+              : undefined,
+          },
+          retry: {
+            failure: repaired.failure,
+            reactive: repaired.reactive,
+            revisionChanged: repaired.revision !== acceptedRevision,
+          },
+        },
+        visualEvidence: {
+          browser: {
+            trace: evidenceRelativePath(BROWSER_TRACE_PATH),
+            png: browserPng,
+            observed: browserVisual?.observed,
+            phase: browserPng.activePhase,
+            verdict: browserTrace.verdict,
+            confidence: browserVisual?.confidence,
+          },
+          dawn: {
+            trace: evidenceRelativePath(DAWN_TRACE_PATH),
+            readback: evidenceRelativePath(DAWN_READBACK_PATH),
+            observed: dawnVisual?.observed,
+            phase: (dawnTrace.phaseTrace as unknown[]).find((phase) => phase !== 'disabled'),
+            verdict: dawnTrace.verdict,
+            confidence: dawnVisual?.confidence,
+          },
+        },
+      },
+    };
+    mkdirSync(dirname(EVIDENCE_PATH), { recursive: true });
+    writeFileSync(EVIDENCE_PATH, `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
+  } finally {
+    detachErrorListener();
+    renderer.dispose();
+  }
+}