@forgeax/engine-runtime 0.1.4 → 0.1.7

package/src/__tests__/renderer-health.unit.test.ts

@@ -1,57 +1,17 @@
-// @forgeax/engine-runtime — renderer health / recover unit + integration tests
-//
-// Covers:
-//   w1 — HealthReason narrowing + detail discriminated union test (AC-05)
-//   w2 — RecoverError union exhaustiveness test (AC-06)
-//   w3 — HealthListenerRegistry replay + unsubscribe + isolation test (AC-07/AC-08)
-//   w4 — HealthSnapshot shape + recoverable derivation + immutability test (AC-02)
-//   w8 — health() healthy-state baseline integration test
-//   w9 — recover() healthy-state returns recover-not-needed test (AC-04)
-//   w10 — recover() degraded-state placeholder + health unchanged test (AC-04b)
-//
-// w1-w4: unit tests (types + registry, GREEN after M1 w5-w7)
-// w8-w10: integration tests (createRenderer + mock RHI, RED until w11-w13)
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import type { HealthReason, HealthSnapshot } from '../../../render/src/lifecycle';
+import { requireRenderer } from './renderer-test-utils';
 
-import type {
-  HealthChangeListener,
-  HealthReason,
-  HealthSnapshot,
-} from '@forgeax/engine-render/internal';
-import {
-  deriveRecoverable,
-  HealthListenerRegistry,
-  RecoverError,
-  type RecoverErrorCode,
-} from '@forgeax/engine-render/internal';
-import type { Result, RhiInstance } from '@forgeax/engine-rhi';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-// ── w1: HealthReason narrowing + detail discriminated union (AC-05) ─────────
+function canvas(): HTMLCanvasElement {
+  return { width: 64, height: 64, getContext: () => null } as unknown as HTMLCanvasElement;
+}
 
-describe('HealthReason narrowing (AC-05)', () => {
-  it('switch(snap.reason) narrows detail per reason without as casts', () => {
-    // Consumer-side switch exercising all 3 HealthReason members.
-    // TS must narrow snap.detail in each case branch — zero `as` casts.
-    function consumeHealth(snap: HealthSnapshot): string {
-      switch (snap.reason) {
-        case 'alive':
-          // alive variant has no detail field — zero as casts
-          return 'alive';
-        case 'device-lost':
-          // detail narrows to HealthDetailDeviceLost; lostReason scoped to this variant
-          return `device-lost(lostReason=${snap.detail.lostReason}): ${snap.detail.message}`;
-        case 'internal-fault':
-          // detail narrows to HealthDetailInternalFault; message is the only field
-          return `internal-fault: ${snap.detail.message}`;
-      }
-    }
-    // Compile-time assertion: the function compiles with zero `as` casts
-    expect(typeof consumeHealth).toBe('function');
-  });
+const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
 
-  it('HealthReason has exactly 3 members — exhaustiveness without default', () => {
-    // If TS compiles this switch without default, the union is exactly 3 members.
-    function exhaustive(reason: HealthReason): string {
+describe('renderer inspection and recovery contract', () => {
+  it('keeps health vocabulary closed for inspection consumers', () => {
+    function describeReason(reason: HealthReason): string {
       switch (reason) {
         case 'alive':
           return 'alive';
@@ -61,875 +21,25 @@ describe('HealthReason narrowing (AC-05)', () => {
           return 'internal-fault';
       }
     }
-    expect(typeof exhaustive).toBe('function');
-  });
-});
-
-// ── w2: RecoverError union exhaustiveness (AC-06) ──────────────────────────
-
-describe('RecoverError closed union (AC-06)', () => {
-  it('switch(err.code) exhaustively matches all members without default', () => {
-    // Consumer-side switch matching every RecoverErrorCode member.
-    // TS must not emit non-exhaustive errors; no `default` branch.
-    // feat-20260622-s5 M3 / w19: union grew add-only to 4 members (adapter /
-    // device unavailable join the S3 not-needed / not-implemented(reserved)).
-    function handleRecover(err: RecoverError): string {
-      switch (err.code) {
-        case 'recover-not-needed':
-          return `not-needed: ${err.hint}`;
-        case 'recover-not-implemented':
-          return `not-implemented: ${err.hint}`;
-        case 'recover-adapter-unavailable':
-          return `adapter-unavailable: ${err.hint}`;
-        case 'recover-device-unavailable':
-          return `device-unavailable: ${err.hint}`;
-      }
-    }
-    expect(typeof handleRecover).toBe('function');
-  });
-
-  it('RecoverErrorCode has exactly 4 members', () => {
-    function exhaustive(code: RecoverErrorCode): string {
-      switch (code) {
-        case 'recover-not-needed':
-          return 'not-needed';
-        case 'recover-not-implemented':
-          return 'not-implemented';
-        case 'recover-adapter-unavailable':
-          return 'adapter-unavailable';
-        case 'recover-device-unavailable':
-          return 'device-unavailable';
-      }
-    }
-    expect(typeof exhaustive).toBe('function');
-  });
-
-  it('RecoverError carries .code, .expected, .hint fields', () => {
-    const err = new RecoverError('recover-not-needed');
-    expect(err.code).toBe('recover-not-needed');
-    expect(typeof err.expected).toBe('string');
-    expect(err.expected.length).toBeGreaterThan(0);
-    expect(typeof err.hint).toBe('string');
-    expect(err.hint.length).toBeGreaterThan(0);
-  });
-
-  it('recover-not-implemented code also carries valid .expected + .hint', () => {
-    const err = new RecoverError('recover-not-implemented');
-    expect(err.code).toBe('recover-not-implemented');
-    expect(typeof err.expected).toBe('string');
-    expect(err.expected.length).toBeGreaterThan(0);
-    expect(typeof err.hint).toBe('string');
-    expect(err.hint.length).toBeGreaterThan(0);
-  });
-});
-
-// ── w3: HealthListenerRegistry replay + unsubscribe + isolation (AC-07/AC-08)
-
-describe('HealthListenerRegistry (AC-07/AC-08)', () => {
-  it('late-attach replay: fire then add calls listener immediately', () => {
-    const registry = new HealthListenerRegistry();
-    const snapshot: HealthSnapshot = {
-      reason: 'device-lost',
-      detail: { lostReason: 'destroyed', message: 'test device lost' },
-      recoverable: true,
-    };
-    registry.fire(snapshot);
-
-    const cb = vi.fn<HealthChangeListener>();
-    registry.add(cb);
-
-    expect(cb).toHaveBeenCalledTimes(1);
-    expect(cb).toHaveBeenCalledWith(snapshot);
-  });
-
-  it('unsubscribe: add returns unsubscribe, listener not called after', () => {
-    const registry = new HealthListenerRegistry();
-    const cb = vi.fn<HealthChangeListener>();
-    const unsubscribe = registry.add(cb);
-
-    // Unsubscribe
-    unsubscribe();
-
-    // Fire after unsubscribe — cb must not be called
-    const snapshot: HealthSnapshot = {
-      reason: 'alive',
-      recoverable: false,
-    };
-    registry.fire(snapshot);
-
-    expect(cb).not.toHaveBeenCalled();
-  });
-
-  it('listener-throw isolation: first throws, second still fires', () => {
-    const registry = new HealthListenerRegistry();
-
-    const cb1 = vi.fn<HealthChangeListener>(() => {
-      throw new Error('cb1 intentional throw');
-    });
-    const cb2 = vi.fn<HealthChangeListener>();
-
-    registry.add(cb1);
-    registry.add(cb2);
-
-    // Suppress console.error from the try/catch isolation
-    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
-
-    const snapshot: HealthSnapshot = {
-      reason: 'internal-fault',
-      detail: { message: 'simulated fault' },
-      recoverable: false,
-    };
-    registry.fire(snapshot);
-
-    expect(cb1).toHaveBeenCalledTimes(1);
-    expect(cb2).toHaveBeenCalledTimes(1);
-    expect(cb2).toHaveBeenCalledWith(snapshot);
-    // cb1's throw should be caught and surfaced via console.error
-    expect(consoleErrorSpy).toHaveBeenCalled();
-
-    consoleErrorSpy.mockRestore();
-  });
-
-  it('clear detaches all listeners but preserves fired/lastSnapshot for replay', () => {
-    const registry = new HealthListenerRegistry();
-
-    const snapshot: HealthSnapshot = {
-      reason: 'device-lost',
-      detail: { lostReason: 'unknown', message: 'test' },
-      recoverable: true,
-    };
-    registry.fire(snapshot);
-
-    registry.clear();
-
-    // Late-attach after clear: fired/lastSnapshot preserved, so replay still works
-    const cb = vi.fn<HealthChangeListener>();
-    registry.add(cb);
-
-    expect(cb).toHaveBeenCalledTimes(1);
-    expect(cb).toHaveBeenCalledWith(snapshot);
-  });
-
-  it('getLastSnapshot returns alive baseline when never fired', () => {
-    const registry = new HealthListenerRegistry();
-    const snapshot = registry.getLastSnapshot();
-
-    expect(snapshot.reason).toBe('alive');
-    expect(snapshot.recoverable).toBe(false);
-  });
-
-  it('getLastSnapshot returns last fired snapshot after fire', () => {
-    const registry = new HealthListenerRegistry();
-    const fired: HealthSnapshot = {
-      reason: 'device-lost',
-      detail: { lostReason: 'destroyed', message: 'lost' },
-      recoverable: true,
-    };
-    registry.fire(fired);
-
-    const snapshot = registry.getLastSnapshot();
-    expect(snapshot.reason).toBe('device-lost');
-    expect(snapshot.recoverable).toBe(true);
-    if (snapshot.reason === 'device-lost') {
-      expect(snapshot.detail).toEqual({ lostReason: 'destroyed', message: 'lost' });
-    }
-  });
-});
-
-// ── w4: HealthSnapshot shape + recoverable derivation + immutability (AC-02) ─
-
-describe('HealthSnapshot shape + recoverable derivation (AC-02)', () => {
-  it('deriveRecoverable: alive -> false', () => {
-    expect(deriveRecoverable('alive')).toBe(false);
-  });
-
-  it('deriveRecoverable: device-lost -> true', () => {
-    expect(deriveRecoverable('device-lost')).toBe(true);
-  });
-
-  it('deriveRecoverable: internal-fault -> false', () => {
-    expect(deriveRecoverable('internal-fault')).toBe(false);
-  });
-
-  it('HealthSnapshot has exactly { reason, detail?, recoverable } fields', () => {
-    // Shape assertion: discriminated union — alive has no detail, degraded
-    // variants have required detail. TS would error on mismatched shapes.
-    const snapAlive: HealthSnapshot = { reason: 'alive', recoverable: false };
-    expect(snapAlive.reason).toBe('alive');
-    expect(snapAlive.recoverable).toBe(false);
-
-    const snapLost: HealthSnapshot = {
-      reason: 'device-lost',
-      detail: { lostReason: 'unknown', message: 'test' },
-      recoverable: true,
-    };
-    expect(snapLost.reason).toBe('device-lost');
-    expect(snapLost.recoverable).toBe(true);
-    expect(snapLost.detail).toEqual({ lostReason: 'unknown', message: 'test' });
-
-    const snapFault: HealthSnapshot = {
-      reason: 'internal-fault',
-      detail: { message: 'simulated' },
-      recoverable: false,
-    };
-    expect(snapFault.reason).toBe('internal-fault');
-    expect(snapFault.recoverable).toBe(false);
-    expect(snapFault.detail).toEqual({ message: 'simulated' });
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// M2 Integration tests (w8 / w9 / w10 — TDD RED)
-//
-// These tests require a Renderer constructed via createRenderer with a mock RHI
-// backend. They are RED until w11 (+ interface) + w12 (+ registry wire) + w13
-// (+ implementation) are complete.
-// ──────────────────────────────────────────────────────────────────────────────
-
-// ── Mock RHI setup (mirrors asset.unit.test.ts pattern) ──────────────────────
-
-/**
- * Module-level resolver hook so M3 integration tests (w14/w15) can
- * control when device.lost resolves. Set by makeFakeRhiDevice on each call.
- * @internal test-only hook, not part of any package surface.
- */
-let _testDeviceLostResolve: ((info: unknown) => void) | null = null;
-
-function makeFakeRhiDevice(): Record<string, unknown> {
-  let resolveLost!: (info: unknown) => void;
-  const lost = new Promise<unknown>((res) => {
-    resolveLost = res;
-  });
-  _testDeviceLostResolve = resolveLost;
-  return {
-    __brand: 'RhiDevice',
-    lost,
-    features: new Set<string>(),
-    limits: {} as Record<string, number>,
-    // feat-20260707 M5 / w33: createRenderer projects RhiCaps.textureCompression*
-    // into TranscodeCaps at registry-build time; the fake device needs a caps
-    // object (the real RhiDevice always carries one).
-    caps: {
-      textureCompressionBc: false,
-      textureCompressionEtc2: false,
-      textureCompressionAstc: false,
-    },
-    queue: {
-      submit: () => undefined,
-      writeBuffer: () => undefined,
-    },
-    createBuffer: () => ({ ok: true, value: { __brand: 'Buffer' } }),
-    createTexture: () => ({ ok: true, value: { __brand: 'Texture' } }),
-    createBindGroupLayout: () => ({ ok: true, value: { __brand: 'BindGroupLayout' } }),
-    createBindGroup: () => ({ ok: true, value: { __brand: 'BindGroup' } }),
-    createPipelineLayout: () => ({ ok: true, value: { __brand: 'PipelineLayout' } }),
-    createRenderPipeline: () => ({ ok: true, value: { __brand: 'RenderPipeline' } }),
-    createSampler: () => ({ ok: true, value: { __brand: 'Sampler' } }),
-    createShaderModule: () => ({ ok: true, value: { __brand: 'ShaderModule' } }),
-    createTextureView: () => ({ ok: true, value: { __brand: 'TextureView' } }),
-    createCommandEncoder: () => ({
-      ok: true,
-      value: {
-        beginRenderPass: () => ({
-          setPipeline: () => undefined,
-          setBindGroup: () => undefined,
-          setVertexBuffer: () => undefined,
-          setIndexBuffer: () => undefined,
-          draw: () => undefined,
-          drawIndexed: () => undefined,
-          end: () => undefined,
-        }),
-        finish: () => ({ __brand: 'CommandBuffer' }),
-      },
-    }),
-  };
-}
-
-function makeExplicitRhi(): RhiInstance {
-  const adapter = {
-    features: new Set<string>(),
-    limits: {},
-    requestDevice: async () => ({ ok: true, value: makeFakeRhiDevice() }),
-  };
-  return {
-    requestAdapter: async () => ({ ok: true, value: adapter }),
-    acquireCanvasContext: () => ({
-      ok: true,
-      value: {
-        configure: () => ({ ok: true, value: undefined }),
-        unconfigure: () => ({ ok: true, value: undefined }),
-        getCurrentTexture: () => ({ ok: true, value: { __brand: 'TextureView' } }),
-      },
-    }),
-    createShaderModule: async () => ({ ok: true, value: { __brand: 'ShaderModule' } }),
-  } as unknown as RhiInstance;
-}
-
-function makeMockCanvas(): HTMLCanvasElement {
-  return {
-    width: 800,
-    height: 600,
-    getContext(kind: string): unknown {
-      if (kind === 'webgpu') {
-        return {
-          __mockTag: 'webgpu-canvas-context',
-          configure: () => undefined,
-          unconfigure: () => undefined,
-          getCurrentTexture: () => ({ createView: () => ({}) }),
-        };
-      }
-      if (kind === 'webgl2') {
-        return {
-          __mockTag: 'webgl2',
-          getExtension: () => null,
-          getParameter: () => 1,
-          isContextLost: () => false,
-        };
-      }
-      return null;
-    },
-    addEventListener: () => undefined,
-    removeEventListener: () => undefined,
-  } as Partial<HTMLCanvasElement> as HTMLCanvasElement;
-}
-
-vi.mock('@forgeax/engine-rhi-webgpu', async () => {
-  const actualRhi =
-    await vi.importActual<typeof import('@forgeax/engine-rhi')>('@forgeax/engine-rhi');
-  const fakeAdapter = {
-    features: new Set<string>(),
-    limits: {} as Readonly<Record<string, number>>,
-    async requestDevice() {
-      return actualRhi.ok(makeFakeRhiDevice());
-    },
-  };
-  return {
-    rhi: {
-      requestAdapter: async () => actualRhi.ok(fakeAdapter),
-      acquireCanvasContext: (_canvas: unknown) =>
-        actualRhi.ok({
-          configure: () => actualRhi.ok(undefined),
-          unconfigure: () => actualRhi.ok(undefined),
-          getCurrentTexture: () => actualRhi.ok({ __brand: 'TextureView' }),
-        }),
-    },
-    createShaderModule: async () => actualRhi.ok({ __brand: 'ShaderModule' } as unknown as object),
-  };
-});
-
-vi.mock('@forgeax/engine-rhi-wgpu', async () => {
-  const actualRhi =
-    await vi.importActual<typeof import('@forgeax/engine-rhi')>('@forgeax/engine-rhi');
-  const fakeAdapter = {
-    features: new Set<string>(),
-    limits: {} as Readonly<Record<string, number>>,
-    async requestDevice() {
-      return actualRhi.ok(makeFakeRhiDevice());
-    },
-  };
-  return {
-    rhi: {
-      requestAdapter: async () => actualRhi.ok(fakeAdapter),
-      acquireCanvasContext: (_canvas: unknown) =>
-        actualRhi.ok({
-          configure: () => actualRhi.ok(undefined),
-          unconfigure: () => actualRhi.ok(undefined),
-          getCurrentTexture: () => actualRhi.ok({ __brand: 'TextureView' }),
-        }),
-    },
-    ensureReady: async () => undefined,
-  };
-});
-
-let makeGPUSpy: ReturnType<typeof makeStubGPU>;
-function makeStubGPU() {
-  return {
-    requestAdapter: async () => ({
-      features: new Set<string>(),
-      limits: {},
-      requestDevice: async () => makeFakeRhiDevice(),
-    }),
-    getPreferredCanvasFormat: () => 'bgra8unorm',
-  };
-}
-
-// Minimal shader manifest as data URL — provides a manifest that the
-// ShaderRegistry can parse without HTTP requests, following the
-// bind-group-cache-frame.test.ts pattern. Includes a pbr stub with the
-// `f_schlick` content marker so `buildReadyWebGPU` finds the PBR entry.
-const HEALTH_TEST_MANIFEST_URL = (() => {
-  const manifest = {
-    schemaVersion: '1.0.0',
-    entries: [
-      {
-        hash: 'pbr00000',
-        wgsl: '/* pbr stub - calls f_schlick( */',
-        glsl: '',
-        bindings: '',
-      },
-    ],
-    materialShaders: [],
-  };
-  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
-})();
-
-describe('Renderer health/recover integration (M2 RED)', () => {
-  beforeEach(() => {
-    makeGPUSpy = makeStubGPU();
-    vi.stubGlobal('navigator', { ...navigator, gpu: makeGPUSpy });
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  // ── w8: health() healthy-state baseline ──────────────────────────────────
-
-  it('w8: health() returns alive baseline when registry has not been fired', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    // TDD RED: renderer.health() does not exist on Renderer until w11.
-    // After w13, this should return { reason: 'alive', recoverable: false }.
-    const snapshot = (
-      (renderer as unknown as Record<string, unknown>).health as () => HealthSnapshot
-    )?.();
-    if (!snapshot) {
-      // RED guard: health() not yet implemented — test fails here until w13.
-      throw new Error('TDD RED: renderer.health() not implemented yet (expected after w11+w13)');
-    }
-    expect(snapshot.reason).toBe('alive');
-    expect(snapshot.recoverable).toBe(false);
-  });
-
-  // ── w9: recover() healthy-state returns recover-not-needed (AC-04) ────────
-  //
-  // feat-20260622-s5 M3 / w19 migration: recover() is now async (device rebuild
-  // is async). The alive-state guard returns recover-not-needed synchronously
-  // inside the Promise. The full rebuild success/failure-code matrix lives in
-  // renderer-recover.unit.test.ts (w10-w14); this stays a health-surface smoke.
-
-  it('w9: recover() on healthy renderer returns recover-not-needed error', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    const recoverFn = (renderer as unknown as Record<string, unknown>).recover as
-      | (() => Promise<Result<void, RecoverError>>)
-      | undefined;
-    if (!recoverFn) {
-      throw new Error('renderer.recover() missing');
-    }
-    const result = await recoverFn();
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.code).toBe('recover-not-needed');
-      expect(typeof result.error.expected).toBe('string');
-      expect(result.error.expected.length).toBeGreaterThan(0);
-      expect(typeof result.error.hint).toBe('string');
-      expect(result.error.hint.length).toBeGreaterThan(0);
-    }
-  });
-
-  // ── w10: recover() on degraded state attempts a rebuild, never fakes alive ─
-  //
-  // feat-20260622-s5 M3 / w19 migration: the S3 placeholder behaviour
-  // (recover-not-implemented, health unchanged) is gone — recover() now runs a
-  // single idempotent rebuild. On this minimal single-entry HEALTH manifest the
-  // rebuild's engine-SSOT-triple check fails, so recover() resolves
-  // recover-device-unavailable and LEAVES health at device-lost (A-AC-07: never
-  // fakes the renderer back to alive on failure). The success path (full triple
-  // manifest -> ok + alive) is covered in renderer-recover.unit.test.ts (w10).
-
-  it('w10: recover() on degraded renderer attempts rebuild; failure keeps health device-lost', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    const healthFn = (renderer as unknown as Record<string, unknown>).health as
-      | (() => HealthSnapshot)
-      | undefined;
-    if (!healthFn) {
-      throw new Error('renderer.health() missing');
-    }
-    const recoverFn = (renderer as unknown as Record<string, unknown>).recover as
-      | (() => Promise<Result<void, RecoverError>>)
-      | undefined;
-    if (!recoverFn) {
-      throw new Error('renderer.recover() missing');
-    }
-
-    // Drive into degraded state via device.lost (same mock path as w14).
-    if (!_testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-    _testDeviceLostResolve({
-      reason: 'unknown',
-      message: 'test device lost for w10 degraded-state',
-    });
-
-    await vi.waitFor(() => {
-      expect(healthFn().reason).toBe('device-lost');
-    });
-    expect(healthFn().reason).toBe('device-lost');
-
-    // recover() runs a single rebuild attempt. The reserved recover-not-implemented
-    // is never produced anymore; on this minimal manifest the rebuild fails with a
-    // device-unavailability code.
-    const result = await recoverFn();
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.code).not.toBe('recover-not-implemented');
-      expect(result.error.code).toBe('recover-device-unavailable');
-    }
-
-    // A-AC-07: failure never fakes the renderer back to alive.
-    const snapAfter = healthFn();
-    expect(snapAfter.reason).toBe('device-lost');
-    expect(snapAfter.recoverable).toBe(true);
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// M2 draw guard tests (w7 — TDD RED)
-//
-// These tests verify device-lost draw() silent return + disposed latch. They are
-// RED until w9 adds the health-state guard in draw().
-// ──────────────────────────────────────────────────────────────────────────────
 
-describe('Renderer draw device-lost guard (w7 TDD RED)', () => {
-  beforeEach(() => {
-    makeGPUSpy = makeStubGPU();
-    vi.stubGlobal('navigator', { ...navigator, gpu: makeGPUSpy });
+    const snapshot: HealthSnapshot = { reason: 'alive', recoverable: false };
+    expect(describeReason(snapshot.reason)).toBe('alive');
   });
 
-  afterEach(() => {
-    vi.unstubAllGlobals();
-    _testDeviceLostResolve = null;
+  it('uses inspect for the public ready state and recover for an explicit retry', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect(renderer.inspect().state).toBe('alive');
+    const recovery = await renderer.recover();
+    expect(recovery.ok).toBe(false);
+    if (!recovery.ok) expect(recovery.error.code).toBe('renderer-state-invalid');
+    await renderer.dispose();
   });
 
-  // ── w7(a): device-lost -> draw() returns err silently ──────────────────────
-
-  it('w7(a): device-lost state draw() returns Result.err without firing onError each frame', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    const healthFn = (renderer as unknown as Record<string, unknown>).health as
-      | (() => HealthSnapshot)
-      | undefined;
-    if (!healthFn) {
-      throw new Error('TDD RED: renderer.health() not found');
-    }
-
-    // Subscribe to onError to verify no per-frame fire
-    const onErrorFn = (renderer as unknown as Record<string, unknown>).onError as
-      | ((cb: (err: { code: string }) => void) => () => void)
-      | undefined;
-    if (!onErrorFn) {
-      throw new Error('TDD RED: renderer.onError() not found');
-    }
-    const errorCb = vi.fn<(err: { code: string }) => void>();
-    onErrorFn(errorCb);
-
-    // Need a World with Camera to reach draw internals
-    const { World } = await import('@forgeax/engine-ecs');
-    const { Transform } = await import('@forgeax/engine-scene');
-    const { Camera } = await import('@forgeax/engine-render/internal');
-    const world = new World();
-    world.spawn(
-      {
-        component: Transform,
-        data: {
-          pos: [0, 0, 10],
-          quat: [0, 0, 0, 1],
-          scale: [1, 1, 1],
-        },
-      },
-      {
-        component: Camera,
-        data: {
-          fov: Math.PI / 4,
-          aspect: 1,
-          near: 0.1,
-          far: 100,
-          clearColor: [0, 0, 0, 1],
-        },
-      },
-    );
-
-    await renderer.ready;
-
-    // Baseline: health is alive
-    expect(healthFn().reason).toBe('alive');
-
-    // Trigger device-lost
-    if (!_testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-    _testDeviceLostResolve({
-      reason: 'unknown',
-      message: 'device lost for draw guard test',
-    });
-
-    await vi.waitFor(() => {
-      expect(healthFn().reason).toBe('device-lost');
-    });
-
-    // Reset error spy counter after lost event (the lost channel itself fires onError once)
-    errorCb.mockClear();
-
-    // Draw N=5 times in device-lost state
-    for (let i = 0; i < 5; i++) {
-      const result = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-      // TDD RED / AC-10: draw returns err silently (not ok for device-lost)
-      expect(result.ok).toBe(false);
-    }
-
-    // TDD RED / AC-10: onError was NOT fired during those 5 draws (silent return)
-    // Current behavior (w7 RED): draw fires onError each frame through the normal
-    // device-lost flow (dual-channel), or the disposed/rhi-not-available path fires.
-    // After w9 fix: zero onError fires for draw() during device-lost.
-    expect(errorCb).not.toHaveBeenCalled();
-  });
-
-  // ── w7(b): disposed latch — post-dispose lost callback is no-op ────────────
-
-  it('w7(b): disposed latch prevents reconstruction on device-lost event', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    // TDD RED: dispose then trigger lost — should not try to reconstruct
-    const disposeFn = (renderer as unknown as Record<string, unknown>).dispose as
-      | (() => void)
-      | undefined;
-    if (!disposeFn) {
-      throw new Error('TDD RED: renderer.dispose() not found');
-    }
-
-    disposeFn();
-
-    // After dispose, trigger device.lost (should be no-op, no throw)
-    if (!_testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-    _testDeviceLostResolve({
-      reason: 'destroyed',
-      message: 'lost after dispose',
-    });
-
-    // Allow microtask flush — no assertion needed beyond "doesn't throw/crash"
-    await new Promise((r) => setTimeout(r, 50));
-
-    // TDD RED: disposed renderer.draw returns err
-    const { World } = await import('@forgeax/engine-ecs');
-    const world = new World();
-    const result = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-    expect(result.ok).toBe(false);
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// M3 Integration tests (w14 / w15 — TDD RED)
-//
-// These tests verify the device.lost health channel wire. They are RED until
-// w16 adds the healthRegistry.fire() call in device.lost.then().
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe('Renderer health device.lost integration (M3 RED)', () => {
-  beforeEach(() => {
-    makeGPUSpy = makeStubGPU();
-    vi.stubGlobal('navigator', { ...navigator, gpu: makeGPUSpy });
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-    _testDeviceLostResolve = null;
-  });
-
-  // ── w14: device.lost health update (AC-10) ─────────────────────────────────
-
-  it('w14: device.lost reason=unknown sets health().reason to device-lost with correct detail + recoverable', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    // TDD RED: health() does not exist on Renderer until w11.
-    const healthFn = (renderer as unknown as Record<string, unknown>).health as
-      | (() => HealthSnapshot)
-      | undefined;
-    if (!healthFn) {
-      throw new Error('TDD RED: renderer.health() not implemented yet');
-    }
-
-    // Baseline: alive before device loss
-    expect(healthFn().reason).toBe('alive');
-
-    // Trigger device.lost via the module-level resolver hook. reason 'unknown'
-    // = genuine unrecoverable loss (driver crash / TDR) which DOES flip health
-    // to device-lost. (reason 'destroyed' = intentional teardown, gated -- see
-    // w14b below.)
-    if (!_testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-    _testDeviceLostResolve({
-      reason: 'unknown',
-      message: 'device lost (driver crash)',
-    });
-
-    // Allow the microtask queue to flush so device.lost.then() fires
-    await vi.waitFor(() => {
-      expect(healthFn().reason).toBe('device-lost');
-    });
-
-    const snap = healthFn();
-    expect(snap.reason).toBe('device-lost');
-    expect(snap.recoverable).toBe(true);
-
-    // TS discriminated union narrows snap: in 'device-lost' branch detail is
-    // HealthDetailDeviceLost with required lostReason (AC-05, no toHaveProperty bypass).
-    if (snap.reason === 'device-lost') {
-      expect(snap.detail.lostReason).toBe('unknown');
-      expect(snap.detail.message).toBe('device lost (driver crash)');
-    }
-  });
-
-  it('w14: device.lost with unknown reason sets lostReason to unknown', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    const healthFn = (renderer as unknown as Record<string, unknown>).health as
-      | (() => HealthSnapshot)
-      | undefined;
-    if (!healthFn) {
-      throw new Error('TDD RED: renderer.health() not implemented yet');
-    }
-
-    // Device lost with reason: 'unknown'
-    if (!_testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-    _testDeviceLostResolve({
-      reason: 'unknown',
-      message: '',
-    });
-
-    await vi.waitFor(() => {
-      expect(healthFn().reason).toBe('device-lost');
-    });
-
-    const snap = healthFn();
-    if (snap.reason === 'device-lost') {
-      expect(snap.detail.lostReason).toBe('unknown');
-    }
-  });
-
-  // ── w15: onHealthChange callback triggered on device.lost (AC-10) ──────────
-
-  it('w15: onHealthChange callback called exactly once on device.lost', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    const onHealthChangeFn = (renderer as unknown as Record<string, unknown>).onHealthChange as
-      | ((cb: HealthChangeListener) => () => void)
-      | undefined;
-    if (!onHealthChangeFn) {
-      throw new Error('TDD RED: renderer.onHealthChange() not implemented yet');
-    }
-
-    const cb = vi.fn<HealthChangeListener>();
-    onHealthChangeFn(cb);
-
-    // Before device loss, cb should not have been called
-    expect(cb).not.toHaveBeenCalled();
-
-    // Trigger device.lost
-    if (!_testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-    _testDeviceLostResolve({ reason: 'unknown', message: 'lost' });
-
-    // Wait for the health channel to fire
-    await vi.waitFor(() => {
-      expect(cb).toHaveBeenCalled();
-    });
-
-    // Called exactly once
-    expect(cb).toHaveBeenCalledTimes(1);
-
-    // Callback received the correct snapshot
-    const snap = cb.mock.calls[0]?.[0];
-    expect(snap).toBeDefined();
-    if (snap) {
-      expect(snap.reason).toBe('device-lost');
-      expect(snap.recoverable).toBe(true);
-    }
-  });
-
-  it('w15: late-attach replay after device.lost fires immediately', async () => {
-    const canvas = makeMockCanvas();
-    const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-    const renderer = await createRenderer(
-      canvas,
-      { rhi: makeExplicitRhi() },
-      { shaderManifestUrl: HEALTH_TEST_MANIFEST_URL },
-    );
-
-    // Trigger device.lost BEFORE registering the callback
-    if (!_testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-    _testDeviceLostResolve({ reason: 'unknown', message: 'late-attach test' });
-
-    // Flush the microtask so healthRegistry.fire() completes
-    const healthFn = (renderer as unknown as Record<string, unknown>).health as
-      | (() => HealthSnapshot)
-      | undefined;
-    if (!healthFn) {
-      throw new Error('TDD RED: renderer.health() not implemented yet');
-    }
-
-    await vi.waitFor(() => {
-      expect(healthFn().reason).toBe('device-lost');
-    });
-
-    // Now register callback — late-attach replay should fire immediately
-    const onHealthChangeFn = (renderer as unknown as Record<string, unknown>).onHealthChange as
-      | ((cb: HealthChangeListener) => () => void)
-      | undefined;
-    if (!onHealthChangeFn) {
-      throw new Error('TDD RED: renderer.onHealthChange() not implemented yet');
-    }
-
-    const cb = vi.fn<HealthChangeListener>();
-    onHealthChangeFn(cb);
-
-    // Called immediately via late-attach replay
-    expect(cb).toHaveBeenCalledTimes(1);
-    const snap = cb.mock.calls[0]?.[0];
-    expect(snap?.reason).toBe('device-lost');
-    expect(snap?.recoverable).toBe(true);
+  it('does not expose the removed health or device getters', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect(renderer).not.toHaveProperty('health');
+    expect(renderer).not.toHaveProperty('device');
+    expect(renderer).not.toHaveProperty('ready');
+    renderer.dispose();
   });
 });