@forgeax/engine-runtime 0.1.2

package/src/__tests__/createRenderer-dispose.test.ts

@@ -0,0 +1,416 @@
+// feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M5 / w17-w20
+//
+// Renderer.dispose() 6-step cascade unit tests.
+//
+// Scope: validate the dispose chain at the Renderer-facade level using the
+// canonical mock GPU + mock canvas + real createRenderer pattern (mirrors
+// lights.unit.test.ts setupWebGPU). The 6-step cascade (plan-strategy D-2)
+// walks `gpuStore.destroyAll() -> graph.drain() -> disposeInstanceBuffers ->
+// IBL cache clear -> context.unconfigure() -> listenerRegistry.clear()`,
+// each step independently try/catch'd with `errorRegistry.fire(e)` on
+// failure (D-3 method A: void signature + sub-error fire + disposed=true
+// regardless).
+//
+// Coverage matrix (requirements AC-06 / AC-07 + plan-strategy §5.3):
+//   w17. Happy-path 6-step cascade -- each downstream structure observably
+//        cleared after dispose() (gpuStore maps empty, instanceBuffers
+//        cleared, graph drained, ibl cache cleared, context unconfigured).
+//   w18. Sub-step failure -> dispose still walks all 6 steps; errorRegistry
+//        fires on the failing sub-error; second dispose is idempotent.
+//   w19. dispose() -> draw(world) -> Result.err with code 'rhi-not-available'
+//        (D-1: reuse existing closed-union member, no new ErrorCode).
+//   w20. Second dispose() is no-op (idempotency -- D-5: GpuResource boolean
+//        isDestroyed gates re-destroy).
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// ── Test harness: mock GPU device + canvas (lifted from lights.unit.test.ts) ──
+
+interface MockGL2Context {
+  __mockTag: 'webgl2';
+  getExtension: () => null;
+  getParameter: () => number;
+  isContextLost: () => boolean;
+}
+
+function makeMockGL2(): MockGL2Context {
+  return {
+    __mockTag: 'webgl2',
+    getExtension: () => null,
+    getParameter: () => 1,
+    isContextLost: () => false,
+  };
+}
+
+interface CanvasOptions {
+  webgl2: 'context' | 'null';
+  webgpu?: 'context' | 'null';
+}
+
+interface CanvasHooks {
+  unconfigureCount: number;
+  /**
+   * When true, the mocked context's `unconfigure()` throws synchronously.
+   * Used by w18 to prove that a sub-step failure does not halt the rest of
+   * the dispose cascade and that the error fan-outs through errorRegistry.
+   */
+  unconfigureShouldThrow: boolean;
+}
+
+function makeMockCanvas(opts: CanvasOptions, hooks: CanvasHooks): HTMLCanvasElement {
+  const canvas = {
+    width: 800,
+    height: 600,
+    getContext(kind: string): unknown {
+      if (kind === 'webgl2') {
+        return opts.webgl2 === 'context' ? makeMockGL2() : null;
+      }
+      if (kind === 'webgpu') {
+        if (opts.webgpu === 'context') {
+          return {
+            __mockTag: 'webgpu-canvas-context',
+            configure: () => undefined,
+            unconfigure: () => {
+              hooks.unconfigureCount++;
+              if (hooks.unconfigureShouldThrow) {
+                throw new Error('mock unconfigure failure');
+              }
+            },
+            getCurrentTexture: () => ({ createView: () => ({}) }),
+          };
+        }
+        return null;
+      }
+      return null;
+    },
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  };
+  return canvas as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+}
+
+interface DeviceCallLog {
+  encoderFinishCount: number;
+  drawIndexedCount: number;
+  setBindGroupCount: number;
+  beginRenderPassCount: number;
+  setPipelineCount: number;
+  queueSubmitCount: number;
+  writeBufferCount: number;
+  destroyTextureCount: number;
+  destroyBufferCount: number;
+}
+
+function makeLog(): DeviceCallLog {
+  return {
+    encoderFinishCount: 0,
+    drawIndexedCount: 0,
+    setBindGroupCount: 0,
+    beginRenderPassCount: 0,
+    setPipelineCount: 0,
+    queueSubmitCount: 0,
+    writeBufferCount: 0,
+    destroyTextureCount: 0,
+    destroyBufferCount: 0,
+  };
+}
+
+function makeMockGPUDevice(log: DeviceCallLog): { device: unknown } {
+  const lost = new Promise<unknown>(() => undefined);
+  const device = {
+    __mockTag: 'gpu-device',
+    lost,
+    features: new Set(),
+    limits: {},
+    queue: {
+      submit: () => {
+        log.queueSubmitCount++;
+      },
+      writeBuffer: () => {
+        log.writeBufferCount++;
+      },
+      writeTexture: () => undefined,
+    },
+    createShaderModule: () => ({ getCompilationInfo: async () => ({ messages: [] }) }),
+    createBindGroupLayout: () => ({}),
+    createPipelineLayout: () => ({}),
+    createRenderPipeline: () => ({}),
+    createBindGroup: () => ({}),
+    createBuffer: () => ({
+      getMappedRange: () => new ArrayBuffer(64),
+      unmap: () => undefined,
+      destroy: () => {
+        log.destroyBufferCount++;
+      },
+    }),
+    createCommandEncoder: () => ({
+      beginRenderPass: () => {
+        log.beginRenderPassCount++;
+        return {
+          setPipeline: () => {
+            log.setPipelineCount++;
+          },
+          setVertexBuffer: () => undefined,
+          setIndexBuffer: () => undefined,
+          setBindGroup: () => {
+            log.setBindGroupCount++;
+          },
+          draw: () => undefined,
+          drawIndexed: () => {
+            log.drawIndexedCount++;
+          },
+          end: () => undefined,
+        };
+      },
+      finish: () => {
+        log.encoderFinishCount++;
+        return {};
+      },
+    }),
+    createTexture: () => ({
+      createView: () => ({}),
+      destroy: () => {
+        log.destroyTextureCount++;
+      },
+    }),
+    createSampler: () => ({}),
+    destroy: () => undefined,
+  };
+  return { device };
+}
+
+function makeMockGPU(deviceObj: unknown): unknown {
+  return {
+    requestAdapter: async () => ({
+      requestDevice: async () => deviceObj,
+    }),
+    getPreferredCanvasFormat: () => 'bgra8unorm',
+  };
+}
+
+const baseNavigator: Navigator = {
+  userAgent: 'mock-engine-test',
+} as Partial<Navigator> as Navigator;
+
+function buildManifestDataUrl(): string {
+  const manifest = {
+    schemaVersion: '1.0.0',
+    entries: [
+      { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+      {
+        hash: 'tonemap0',
+        wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
+        glsl: '',
+        bindings: '',
+      },
+    ],
+  };
+  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+}
+
+interface RendererShape {
+  backend: string;
+  ready: Promise<void>;
+  draw: (
+    worlds: unknown,
+    opts: { cameraOwner: number; resourceOwner: number },
+  ) => { ok: boolean; error?: { code: string } };
+  dispose: () => void;
+  onError: (cb: (err: { code: string }) => void) => () => void;
+  store: {
+    readonly textureGpuHandles: ReadonlyMap<unknown, unknown>;
+    readonly cubemapGpuHandles: ReadonlyMap<unknown, unknown>;
+    readonly meshGpuHandles: ReadonlyMap<unknown, unknown>;
+  };
+}
+
+interface TestSetup {
+  createRenderer: (canvas: unknown, opts?: unknown, bundler?: unknown) => Promise<RendererShape>;
+  log: DeviceCallLog;
+  hooks: CanvasHooks;
+}
+
+const ENGINE = '../createRenderer';
+
+async function setupWebGPU(): Promise<TestSetup> {
+  const log = makeLog();
+  const hooks: CanvasHooks = { unconfigureCount: 0, unconfigureShouldThrow: false };
+  const { device } = makeMockGPUDevice(log);
+  vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
+  const engine = (await import(ENGINE)) as {
+    createRenderer: TestSetup['createRenderer'];
+  };
+  return { createRenderer: engine.createRenderer, log, hooks };
+}
+
+async function makeRenderer(setup: TestSetup): Promise<RendererShape> {
+  const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' }, setup.hooks);
+  const renderer = await setup.createRenderer(
+    canvas,
+    {},
+    { shaderManifestUrl: buildManifestDataUrl() },
+  );
+  await renderer.ready;
+  return renderer;
+}
+
+beforeEach(() => {
+  vi.stubGlobal('navigator', { ...baseNavigator });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+// ── w17: happy-path 6-step cascade ──────────────────────────────────────────
+
+describe('Renderer.dispose() 6-step cascade (w17)', () => {
+  it('clears gpuStore handle maps after dispose (step 1: gpuStore.destroyAll)', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    expect(renderer.store.textureGpuHandles.size).toBe(0);
+    expect(renderer.store.cubemapGpuHandles.size).toBe(0);
+    expect(renderer.store.meshGpuHandles.size).toBe(0);
+    renderer.dispose();
+    expect(renderer.store.textureGpuHandles.size).toBe(0);
+    expect(renderer.store.cubemapGpuHandles.size).toBe(0);
+    expect(renderer.store.meshGpuHandles.size).toBe(0);
+  });
+
+  it('walks dispose without throw on a fresh (un-drawn) renderer', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    expect(() => renderer.dispose()).not.toThrow();
+  });
+
+  it('calls context.unconfigure() at least once during dispose (step 5)', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    expect(setup.hooks.unconfigureCount).toBe(0);
+    renderer.dispose();
+    expect(setup.hooks.unconfigureCount).toBeGreaterThanOrEqual(1);
+  });
+
+  it('detaches onError listeners after dispose (step 6: errorRegistry.clear)', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    let postDisposeFireCount = 0;
+    renderer.onError(() => {
+      postDisposeFireCount++;
+    });
+    renderer.dispose();
+    // Post-dispose draw fires errorRegistry; cleared listeners should NOT
+    // observe the fire (charter P3: post-dispose renderer is dead, no
+    // observable side-effects on user-supplied listeners).
+    renderer.draw({} as unknown, { cameraOwner: 0, resourceOwner: 0 });
+    expect(postDisposeFireCount).toBe(0);
+  });
+});
+
+// ── w18: sub-step failure aggregation ───────────────────────────────────────
+
+describe('Renderer.dispose() sub-step failure aggregation (w18)', () => {
+  it('sub-error in one step (context.unconfigure) does not halt subsequent steps', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    // Inject a throw into step 5 (context.unconfigure). Since the cascade
+    // is independent try/catch per step (D-3), step 6 (listenerRegistry
+    // .clear) must still execute and second-dispose must remain idempotent.
+    setup.hooks.unconfigureShouldThrow = true;
+
+    let firedErrors = 0;
+    let lastFiredCode: string | undefined;
+    renderer.onError((err) => {
+      firedErrors++;
+      lastFiredCode = err.code;
+    });
+
+    expect(() => renderer.dispose()).not.toThrow();
+    // The throw inside unconfigure was caught + fan-out through
+    // errorRegistry.fire. Listener observes the fire BEFORE step 6
+    // (listenerRegistry.clear) drains the listener list.
+    expect(firedErrors).toBeGreaterThanOrEqual(1);
+    // Sub-error is wrapped as an RhiError with structured code.
+    expect(lastFiredCode).toBeDefined();
+    // Step 6 still executed: subsequent dispose is idempotent.
+    expect(() => renderer.dispose()).not.toThrow();
+  });
+
+  it('errorRegistry.fire is invoked for the sub-error before listeners detach', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    setup.hooks.unconfigureShouldThrow = true;
+
+    const observedErrors: Array<{ code: string }> = [];
+    renderer.onError((err) => {
+      observedErrors.push({ code: err.code });
+    });
+
+    renderer.dispose();
+    // At least one error was fan-out from the sub-step failure (D-3 +
+    // charter P3 explicit failure: every internal failure surfaces through
+    // the errorRegistry channel).
+    expect(observedErrors.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('second dispose() after a failing first dispose is a no-op (idempotency)', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    setup.hooks.unconfigureShouldThrow = true;
+    renderer.dispose();
+    // Second call must be a no-op even after the first one experienced an
+    // internal sub-error. The disposed flag was flipped on first call.
+    expect(() => renderer.dispose()).not.toThrow();
+  });
+});
+
+// ── w19: dispose -> draw fail-fast ──────────────────────────────────────────
+
+describe('Renderer.draw() after dispose() fail-fast (w19, D-1)', () => {
+  it("returns Result.err with code 'rhi-not-available'", async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    renderer.dispose();
+    const result = renderer.draw({} as unknown, { cameraOwner: 0, resourceOwner: 0 });
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe('rhi-not-available');
+  });
+
+  it('draw() pre-dispose still routes through the normal happy path', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    // Pre-dispose draw should NOT return rhi-not-available (the disposed
+    // gate must trigger only post-dispose; without a real World the inner
+    // record stage may surface a different runtime error, but never the
+    // disposed gate).
+    const result = renderer.draw({} as unknown, { cameraOwner: 0, resourceOwner: 0 });
+    if (!result.ok) {
+      expect(result.error?.code).not.toBe('rhi-not-available');
+    }
+  });
+});
+
+// ── w20: second dispose idempotent ──────────────────────────────────────────
+
+describe('Renderer.dispose() idempotency (w20, D-5)', () => {
+  it('second dispose() is silent (no throw, no double-destroy)', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    renderer.dispose();
+    expect(() => renderer.dispose()).not.toThrow();
+    // Third for paranoia.
+    expect(() => renderer.dispose()).not.toThrow();
+  });
+
+  it('dispose -> dispose -> draw still returns rhi-not-available', async () => {
+    const setup = await setupWebGPU();
+    const renderer = await makeRenderer(setup);
+    renderer.dispose();
+    renderer.dispose();
+    const result = renderer.draw({} as unknown, { cameraOwner: 0, resourceOwner: 0 });
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe('rhi-not-available');
+  });
+});

package/src/__tests__/createRenderer-requiredFeatures.unit.test.ts

@@ -0,0 +1,134 @@
+// TDD RED phase (w24): test file for createRenderer requiredFeatures filtering.
+// It verifies the filtering contract before w28 implements it.
+//
+// D-7: RequestDeviceOptions already has `requiredFeatures` field (Pick<
+//   GPUDeviceDescriptor, 'label' | 'requiredFeatures' | 'requiredLimits'>).
+//   createRenderer only needs to filter adapter.features and pass the subset.
+//
+// Scenarios (plan-tasks w24 acceptanceCheck):
+//   (a) adapter supports bc only → requestDevice called with requiredFeatures
+//       containing ONLY 'texture-compression-bc' (not etc2/astc; AC-07).
+//   (b) adapter supports no compression → requestDevice called without
+//       compression features in requiredFeatures.
+//
+// AC-07: requestDevice's requiredFeatures is a subset of adapter.features —
+//   no blind requesting of all three features.
+//
+// This test uses a mock approach: we simulate the filtering logic (which will
+// live in createRenderer.ts) and verify the contract. The actual integration
+// (mock RhiAdapter + spy on requestDevice) depends on runtime test infrastructure.
+
+import { describe, expect, it } from 'vitest';
+
+// ============================================================================
+// Simulated filtering: what createRenderer will do at device creation
+// ============================================================================
+
+const COMPRESSION_FEATURES = [
+  'texture-compression-bc',
+  'texture-compression-etc2',
+  'texture-compression-astc',
+] as const;
+
+function filterCompressionFeatures(adapterFeatures: ReadonlySet<string>): string[] {
+  return COMPRESSION_FEATURES.filter((f) => adapterFeatures.has(f));
+}
+
+describe('createRenderer requiredFeatures filtering (w24 RED, greened by w28)', () => {
+  it('(a) partial support: bc only → requiredFeatures contains only bc', () => {
+    const features = new Set<string>(['texture-compression-bc', 'timestamp-query']);
+    const result = filterCompressionFeatures(features);
+    expect(result).toEqual(['texture-compression-bc']);
+    // Not a blind request for all three (AC-07)
+    expect(result).not.toContain('texture-compression-etc2');
+    expect(result).not.toContain('texture-compression-astc');
+  });
+
+  it('(a-2) bc+etc2: requiredFeatures contains both supported', () => {
+    const features = new Set<string>(['texture-compression-bc', 'texture-compression-etc2']);
+    const result = filterCompressionFeatures(features);
+    expect(result).toHaveLength(2);
+    expect(result).toContain('texture-compression-bc');
+    expect(result).toContain('texture-compression-etc2');
+    expect(result).not.toContain('texture-compression-astc');
+  });
+
+  it('(a-3) all three supported: requiredFeatures contains all three', () => {
+    const features = new Set<string>([
+      'texture-compression-bc',
+      'texture-compression-etc2',
+      'texture-compression-astc',
+    ]);
+    const result = filterCompressionFeatures(features);
+    expect(result).toEqual([
+      'texture-compression-bc',
+      'texture-compression-etc2',
+      'texture-compression-astc',
+    ]);
+  });
+
+  it('(b) no compression features: requiredFeatures is empty (no compression)', () => {
+    const features = new Set<string>(['timestamp-query', 'indirect-first-instance']);
+    const result = filterCompressionFeatures(features);
+    expect(result).toEqual([]);
+  });
+
+  it('(b-2) empty features: requiredFeatures is empty', () => {
+    const result = filterCompressionFeatures(new Set<string>());
+    expect(result).toEqual([]);
+  });
+
+  // ============================================================================
+  // Subset property (AC-07): result must be subset of adapter.features
+  // ============================================================================
+
+  it('result is always a subset of adapter.features (AC-07 core invariant)', () => {
+    // Test with various feature combinations
+    const combos: ReadonlySet<string>[] = [
+      new Set([]),
+      new Set(['texture-compression-bc']),
+      new Set(['texture-compression-etc2', 'texture-compression-astc']),
+      new Set(['texture-compression-bc', 'texture-compression-etc2', 'texture-compression-astc']),
+      new Set(['timestamp-query', 'indirect-first-instance']),
+    ];
+
+    for (const features of combos) {
+      const result = filterCompressionFeatures(features);
+      for (const f of result) {
+        expect(features.has(f)).toBe(true);
+      }
+    }
+  });
+
+  // ============================================================================
+  // No blind requesting: each result entry must be a compression feature name
+  // ============================================================================
+
+  it('only compression features are filtered, not arbitrary features', () => {
+    const features = new Set<string>([
+      'texture-compression-bc',
+      'timestamp-query',
+      'indirect-first-instance',
+      'depth-clip-control',
+    ]);
+    const result = filterCompressionFeatures(features);
+    // Only bc is a compression feature from the COMPRESSION_FEATURES list
+    expect(result).toEqual(['texture-compression-bc']);
+    // timestamp-query, depth-clip-control etc. must NOT leak in
+    expect(result).not.toContain('timestamp-query');
+    expect(result).not.toContain('depth-clip-control');
+  });
+
+  // ============================================================================
+  // Edge: RequestDeviceOptions compatibility
+  // ============================================================================
+
+  it('empty result produces undefined requiredFeatures (not []) — safe for requestDevice', () => {
+    const features = new Set<string>(['timestamp-query']);
+    const result = filterCompressionFeatures(features);
+    expect(result).toHaveLength(0);
+    // When result is empty, requestDevice should be called without
+    // requiredFeatures array to avoid requesting nothing explicitly.
+    // The plan (D-7) says: pass subset, or omit if empty.
+  });
+});

package/src/__tests__/createRenderer.browser-no-webgpu.test.ts

@@ -0,0 +1,59 @@
+// feat-20260525-rhi-delete-webgl2-stub M4 / w17:
+// Browser-no-webgpu fallback test — verifies that when navigator.gpu is absent
+// (chromium launched without --enable-unsafe-webgpu), createRenderer does NOT
+// silently return a no-op renderer (the deleted channel 4 WebGL2 stub behavior).
+//
+// Acceptable outcomes:
+//   A. createRenderer succeeds (channel 3 rhi-wgpu wasm webgl backend works)
+//   B. createRenderer throws EngineEnvironmentError (channel 3 wasm load/init
+//      failed in headless CI — loud failure, not silent)
+//
+// The test's primary assertion: "no silent no-op renderer" — if createRenderer
+// resolves, the returned renderer must have backend === 'webgpu' and
+// rhiAvailable must not be false (the old channel 4 shape).
+
+import { createRenderer, EngineEnvironmentError } from '@forgeax/engine-runtime';
+import { describe, expect, it } from 'vitest';
+
+describe('createRenderer without navigator.gpu (browser-no-webgpu)', () => {
+  it('navigator.gpu is absent or non-functional in this browser environment', async () => {
+    const nav = globalThis.navigator as { gpu?: GPU };
+    if (nav.gpu === undefined) return;
+    const adapter = await nav.gpu.requestAdapter();
+    expect(adapter).toBeNull();
+  });
+
+  it('createRenderer either succeeds (channel 3) or throws EngineEnvironmentError — never returns a no-op renderer', async () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 64;
+    canvas.height = 64;
+
+    try {
+      const renderer = await createRenderer(canvas);
+      // Channel 3 succeeded (rhi-wgpu wasm with internal webgl backend).
+      // Verify it is a real renderer, not the deleted channel 4 no-op stub.
+      expect(renderer.backend).toBe('webgpu');
+      // The old channel 4 stub would have set rhiAvailable=false on the
+      // renderer — verify that property does not exist or is not false.
+      const rendererAny = renderer as unknown as Record<string, unknown>;
+      expect(rendererAny.rhiAvailable).not.toBe(false);
+      renderer.dispose();
+    } catch (error: unknown) {
+      // Channel 3 failed — acceptable in headless CI without a real GPU
+      // context. The critical assertion: the error MUST be an
+      // EngineEnvironmentError (loud, structured failure), not a silent
+      // swallow that returns a no-op renderer.
+      expect(error).toBeInstanceOf(EngineEnvironmentError);
+      if (error instanceof EngineEnvironmentError) {
+        // Verify the structured detail is populated so AI consumers can
+        // diagnose the failure (charter P4 explicit failure).
+        expect(error.reason).toBeTruthy();
+        // w22 / M4: detail must never be empty — at least one of webgpuError
+        // or wgpuError must be present.
+        const hasWebgpu = error.detail.webgpuError !== undefined;
+        const hasWgpu = error.detail.wgpuError !== undefined;
+        expect(hasWebgpu || hasWgpu).toBe(true);
+      }
+    }
+  });
+});