@forgeax/engine-render 0.1.6 → 0.1.19

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

@@ -1,17 +1,112 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { World } from '@forgeax/engine-ecs';
 import { createProfiler } from '@forgeax/engine-profiler';
-import { Camera, type RenderFeature } from '@forgeax/engine-render';
-import { rhi } from '@forgeax/engine-rhi-null';
-import { Transform } from '@forgeax/engine-scene';
-import { ok } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+import { RhiError, type ShaderModule } from '@forgeax/engine-rhi';
+import {
+  RhiNullAdapter,
+  RhiNullCommandEncoder,
+  RhiNullDevice,
+  RhiNullQueue,
+  rhi,
+} from '@forgeax/engine-rhi-null';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import type { RhiBackendPack } from '../assembly/backend-contract';
 import { createRenderer as constructRenderer } from '../assembly/factory';
+import {
+  ANTIALIAS_NONE,
+  ANTIALIAS_TAA,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  Camera as LocalCamera,
+  TONEMAP_ACES_FILMIC,
+} from '../components/camera';
+import type { RenderFeature } from '../features/types';
+import { renderLifecycleManifestUrl } from './shader-manifest-fixture';
 
 function manifestUrl(): string {
   return `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
 }
 
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+async function createBloomScenario() {
+  const canvas = { width: 64, height: 64, getContext: () => null };
+  const renderer = await constructRenderer(
+    canvas,
+    { rhi },
+    { shaderManifestUrl: renderLifecycleManifestUrl() },
+  );
+  if (!(await renderer.initialization).ok) throw new Error('Bloom renderer initialization failed');
+  const world = new World();
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  registerPropagateTransforms(world);
+  const camera = world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 4] } },
+      {
+        component: LocalCamera,
+        data: {
+          fov: 1,
+          aspect: 1,
+          near: 0.1,
+          far: 100,
+          antialias: ANTIALIAS_NONE,
+          tonemap: TONEMAP_ACES_FILMIC,
+          bloom: BLOOM_ENABLED,
+        },
+      },
+    )
+    .unwrap();
+  const frameInput = () => ({
+    leases: [attached.value],
+    camera: { lease: attached.value },
+    environment: { lease: attached.value },
+  });
+  const draw = () => renderer.draw(frameInput());
+  const setBloom = (bloom: 'on' | 'off') => {
+    world
+      .set(camera, LocalCamera, {
+        bloom: bloom === 'on' ? BLOOM_ENABLED : BLOOM_DISABLED,
+        tonemap: TONEMAP_ACES_FILMIC,
+      })
+      .unwrap();
+    const updated = world.update();
+    if (!updated.ok) throw updated.error;
+  };
+  const dispose = async () => {
+    await renderer.dispose();
+  };
+  return { renderer, draw, setBloom, dispose, canvas };
+}
+
 describe('factory contract', () => {
+  it('keeps the public output-transform identity and closes removed tone symbols', () => {
+    const source = [
+      'render-contract.ts',
+      'render-pipeline.ts',
+      'typed-render-graph-primitives.ts',
+      'assembly/factory.ts',
+    ]
+      .map((file) => readFileSync(resolve(import.meta.dirname, '..', file), 'utf8'))
+      .join('\n');
+    expect(source).toContain('STANDARD_OUTPUT_TRANSFORM_FEATURE_ID');
+    expect(source).not.toContain('STANDARD_TONEMAP_FEATURE_ID');
+    expect(source).not.toContain('addTypedTonemapPass');
+    expect(source).not.toContain('tone-output');
+  });
+
   it('releases its profiler catalog contribution on dispose', async () => {
     const profiler = createProfiler();
     const renderer = await constructRenderer(
@@ -19,7 +114,6 @@ describe('factory contract', () => {
       { profiler, rhi },
       { shaderManifestUrl: manifestUrl() },
     );
-
     expect(profiler.phaseCatalog.render.length).toBeGreaterThan(0);
     renderer.dispose();
     expect(profiler.phaseCatalog.render).toEqual([]);
@@ -54,6 +148,33 @@ describe('factory contract', () => {
     renderer.dispose();
   });
 
+  it('projects stable output and observation identity without pixel payloads', async () => {
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const inspection = renderer.inspect() as unknown as Record<string, unknown>;
+    expect(inspection).toMatchObject({
+      // Before the first draw there is no committed graph from which to
+      // claim an output transform or an intermediate target.  Inspection is
+      // intentionally conservative instead of projecting profile defaults.
+      displayEncoded: false,
+      surfaceStorage: expect.any(String),
+      surfaceDisplay: expect.any(String),
+      endpoint: 'surface.storage.raw',
+      capability: 'unavailable',
+      observation: {
+        observationId: expect.any(String),
+        frameId: expect.any(Number),
+      },
+    });
+    expect(inspection).not.toHaveProperty('outputTransform');
+    expect(inspection).not.toHaveProperty('intermediateFormat');
+    expect(inspection).not.toHaveProperty('pixelPayload');
+    renderer.dispose();
+  });
+
   it('does not promote a graph feature without a fullscreen effect into post-effects', async () => {
     let planCalls = 0;
     const feature = {
@@ -65,7 +186,7 @@ describe('factory contract', () => {
       },
     };
     const renderer = await constructRenderer(
-      { getContext: () => null },
+      { width: 64, height: 64, getContext: () => null },
       { rhi, features: [feature] },
       { shaderManifestUrl: manifestUrl() },
     );
@@ -134,7 +255,7 @@ describe('factory contract', () => {
       },
     };
     const renderer = await constructRenderer(
-      { getContext: () => null },
+      { width: 64, height: 64, getContext: () => null },
       { rhi, features: [feature] },
       { shaderManifestUrl: manifestUrl() },
     );
@@ -144,10 +265,11 @@ describe('factory contract', () => {
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
     if (!attached.ok) return;
+    registerPropagateTransforms(world);
     world
       .spawn(
         { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
-        { component: Camera, data: { fov: 1, aspect: 1, near: 0.1, far: 100 } },
+        { component: LocalCamera, data: { fov: 1, aspect: 1, near: 0.1, far: 100 } },
       )
       .unwrap();
     expect(world.update().ok).toBe(true);
@@ -277,4 +399,1253 @@ describe('factory contract', () => {
     renderer.dispose();
     expect(unconfigureCalls).toBe(1);
   });
+
+  it('invalidates deferred TAA shader epochs across off and dispose', async () => {
+    const pending: Array<{
+      readonly label: string;
+      readonly promise: Promise<ReturnType<typeof ok<ShaderModule>>>;
+      readonly resolve: (value: ReturnType<typeof ok<ShaderModule>>) => void;
+    }> = [];
+    const moduleCalls: string[] = [];
+    const backend: RhiBackendPack = {
+      rhi,
+      createShaderModule: (_device, desc) => {
+        const label = desc.label ?? '<unlabeled>';
+        moduleCalls.push(label);
+        if (label !== 'post-process-forgeax.taa-resolve-module') {
+          return Promise.resolve(ok({} as ShaderModule));
+        }
+        let resolve!: (value: ReturnType<typeof ok<ShaderModule>>) => void;
+        const promise = new Promise<ReturnType<typeof ok<ShaderModule>>>((complete) => {
+          resolve = complete;
+        });
+        pending.push({ label, promise, resolve });
+        return promise;
+      },
+    };
+    const renderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      undefined,
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+      backend,
+    );
+    await vi.waitFor(() => expect(pending).toHaveLength(1));
+    const initialization = renderer.initialization;
+    const firstPromise = pending[0]?.promise;
+    pending[0]?.resolve(ok({} as ShaderModule));
+    expect((await 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: LocalCamera,
+          data: {
+            fov: 1,
+            aspect: 1,
+            near: 0.1,
+            far: 100,
+            antialias: ANTIALIAS_TAA,
+          },
+        },
+      )
+      .unwrap();
+    expect(world.update().ok).toBe(true);
+    expect([...world.query({ read: [LocalCamera], with: [Transform] }).unwrap()]).toHaveLength(1);
+    const frameInput = () => ({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+
+    const first = renderer.draw(frameInput());
+    expect(first.ok).toBe(true);
+    expect(pending).toHaveLength(1);
+
+    world.set(camera, LocalCamera, { antialias: ANTIALIAS_NONE }).unwrap();
+    expect(world.update().ok).toBe(true);
+    const off = renderer.draw(frameInput());
+    expect(off.ok).toBe(true);
+
+    expect(
+      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+    ).toHaveLength(1);
+
+    world.set(camera, LocalCamera, { antialias: ANTIALIAS_TAA }).unwrap();
+    expect(world.update().ok).toBe(true);
+    const second = renderer.draw(frameInput());
+    expect(second.ok).toBe(false);
+    expect(pending).toHaveLength(2);
+    expect(pending[1]?.promise).not.toBe(firstPromise);
+
+    pending[1]?.resolve(ok({} as ShaderModule));
+    await pending[1]?.promise;
+    expect(renderer.draw(frameInput()).ok).toBe(true);
+    world.set(camera, LocalCamera, { antialias: ANTIALIAS_NONE }).unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(renderer.draw(frameInput()).ok).toBe(true);
+    world.set(camera, LocalCamera, { antialias: ANTIALIAS_TAA }).unwrap();
+    expect(world.update().ok).toBe(true);
+    const replacement = renderer.draw(frameInput());
+    expect(replacement.ok).toBe(false);
+    expect(pending).toHaveLength(3);
+    expect(pending[2]?.promise).not.toBe(pending[1]?.promise);
+
+    expect((await renderer.dispose()).ok).toBe(true);
+    expect((await renderer.dispose()).ok).toBe(true);
+    pending[2]?.resolve(ok({} as ShaderModule));
+    await pending[2]?.promise;
+    expect(
+      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+    ).toHaveLength(3);
+  });
+
+  it('rebuilds a TAA graph for a same-mode target resize', async () => {
+    const moduleCalls: string[] = [];
+    const created = new Map<object, string>();
+    const destroyed = new Set<object>();
+    let wrappedDevice: object | undefined;
+    const trackDevice = (device: object): object =>
+      new Proxy(device, {
+        get(target, property, receiver) {
+          const value = Reflect.get(target, property, target);
+          if (typeof value !== 'function') return Reflect.get(target, property, receiver);
+          return (...args: unknown[]) => {
+            const label =
+              typeof args[0] === 'object' && args[0] !== null && 'label' in args[0]
+                ? String((args[0] as { label?: unknown }).label ?? '')
+                : '';
+            const result = value.apply(target, args);
+            if (property === 'createTexture' && result?.ok && typeof result.value === 'object') {
+              created.set(result.value, label);
+            }
+            if (property === 'destroyTexture') {
+              const handle = args[0];
+              if (typeof handle === 'object' && handle !== null) destroyed.add(handle);
+            }
+            return result;
+          };
+        },
+      });
+    const adapter = new RhiNullAdapter();
+    const instrumentedRhi = {
+      ...rhi,
+      requestAdapter: async () => {
+        const deviceResult = await adapter.requestDevice();
+        if (!deviceResult.ok) return deviceResult;
+        wrappedDevice = trackDevice(deviceResult.value);
+        return ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => ok(wrappedDevice as never),
+        });
+      },
+    } as never;
+    const backend: RhiBackendPack = {
+      rhi: instrumentedRhi,
+      createShaderModule: async (_device, desc) => {
+        moduleCalls.push(desc.label ?? '<unlabeled>');
+        return ok({} as ShaderModule);
+      },
+    };
+    const canvas = { width: 64, height: 64, getContext: () => null };
+    const renderer = await constructRenderer(
+      canvas,
+      undefined,
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+      backend,
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    expect(wrappedDevice).toBeDefined();
+
+    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: LocalCamera,
+          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 first = renderer.draw(frameInput());
+    if (!first.ok) {
+      await Promise.resolve();
+      first = renderer.draw(frameInput());
+    }
+    expect(first.ok).toBe(true);
+    const firstGeneration = [...created.entries()]
+      .filter(([_, label]) => label.startsWith('taa-history-'))
+      .slice(-4);
+    expect(firstGeneration).toHaveLength(4);
+    expect(
+      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+    ).toHaveLength(1);
+    const firstFrame = renderer.inspect().frame.frameId;
+
+    canvas.width = 96;
+    canvas.height = 80;
+    expect(world.update().ok).toBe(true);
+    const replacement = renderer.draw(frameInput());
+    expect(replacement.ok).toBe(true);
+    if (replacement.ok) expect(replacement.value).toMatchObject({ frameId: firstFrame + 1 });
+    const replacementGeneration = [...created.entries()]
+      .filter(([_, label]) => label.startsWith('taa-history-'))
+      .slice(-4);
+    expect(replacementGeneration).toHaveLength(4);
+    expect(replacementGeneration.map(([handle]) => handle)).not.toEqual(
+      firstGeneration.map(([handle]) => handle),
+    );
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(firstGeneration.every(([handle]) => destroyed.has(handle))).toBe(true);
+    expect(replacementGeneration.every(([handle]) => !destroyed.has(handle))).toBe(true);
+    expect(renderer.inspect().frame.frameId).toBe(firstFrame + 1);
+    expect(renderer.inspect().state).toBe('alive');
+    expect(
+      moduleCalls.filter((label) => label === 'post-process-forgeax.taa-resolve-module'),
+    ).toHaveLength(1);
+    world.set(camera, LocalCamera, { antialias: ANTIALIAS_NONE }).unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(renderer.draw(frameInput()).ok).toBe(true);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(replacementGeneration.every(([handle]) => destroyed.has(handle))).toBe(true);
+    expect((await renderer.dispose()).ok).toBe(true);
+  });
+
+  it('retires factory-owned TAA textures and params on an off submit', async () => {
+    const created = new Map<object, string>();
+    const destroyed = new Set<object>();
+    let wrappedDevice: object | undefined;
+    const trackDevice = (device: object): object =>
+      new Proxy(device, {
+        get(target, property, receiver) {
+          const value = Reflect.get(target, property, target);
+          if (typeof value !== 'function') return Reflect.get(target, property, receiver);
+          return (...args: unknown[]) => {
+            const label =
+              typeof args[0] === 'object' && args[0] !== null && 'label' in args[0]
+                ? String((args[0] as { label?: unknown }).label ?? '')
+                : '';
+            const result = value.apply(target, args);
+            if (property === 'createTexture' || property === 'createBuffer') {
+              if (result?.ok && typeof result.value === 'object' && result.value !== null) {
+                created.set(result.value, label);
+              }
+            }
+            if (property === 'destroyTexture' || property === 'destroyBuffer') {
+              const handle = args[0];
+              if (typeof handle === 'object' && handle !== null) destroyed.add(handle);
+            }
+            return result;
+          };
+        },
+      });
+    const adapter = new RhiNullAdapter();
+    const instrumentedRhi = {
+      ...rhi,
+      requestAdapter: async () => {
+        const deviceResult = await adapter.requestDevice();
+        if (!deviceResult.ok) return deviceResult;
+        wrappedDevice = trackDevice(deviceResult.value);
+        return ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => ok(wrappedDevice as never),
+        });
+      },
+    } as never;
+    const renderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi: instrumentedRhi },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    expect(wrappedDevice).toBeDefined();
+    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: LocalCamera,
+          data: { fov: 1, aspect: 1, near: 0.1, far: 100, antialias: ANTIALIAS_TAA },
+        },
+      )
+      .unwrap();
+    const frameInput = () => ({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(world.update().ok).toBe(true);
+    let first = renderer.draw(frameInput());
+    if (!first.ok) {
+      await Promise.resolve();
+      first = renderer.draw(frameInput());
+    }
+    expect(first.ok).toBe(true);
+    const historyHandles = [...created.entries()].filter(([_, label]) =>
+      label.startsWith('taa-history-'),
+    );
+    expect(historyHandles.length).toBeGreaterThanOrEqual(4);
+    expect([...created.values()]).toContain('taa-resolve-params');
+
+    world.set(camera, LocalCamera, { 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().perFramePassNames).not.toContain('taa-resolve');
+    expect(historyHandles.every(([handle]) => destroyed.has(handle))).toBe(true);
+    const params = [...created.entries()].filter(([, label]) => label === 'taa-resolve-params');
+    expect(params.length).toBeGreaterThan(0);
+    expect(params.every(([handle]) => destroyed.has(handle))).toBe(true);
+    expect((await renderer.dispose()).ok).toBe(true);
+    expect((await renderer.dispose()).ok).toBe(true);
+    expect(destroyed.size).toBeGreaterThanOrEqual(historyHandles.length + 1);
+  });
+
+  it('projects Bloom lifecycle through the factory-created per-pass owner', async () => {
+    const renderer = await constructRenderer(
+      { 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: LocalCamera,
+          data: {
+            fov: 1,
+            aspect: 1,
+            near: 0.1,
+            far: 100,
+            antialias: ANTIALIAS_NONE,
+            tonemap: TONEMAP_ACES_FILMIC,
+            bloom: BLOOM_ENABLED,
+          },
+        },
+      )
+      .unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(renderer.inspect().bloom.state).toBe('off');
+    const on = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(on.ok).toBe(true);
+    const onInspection = renderer.inspect().bloom;
+    expect(onInspection.state).toBe('active');
+    expect(onInspection.graphStatus).toBe('valid');
+    expect(onInspection.targetCount).toBe(4);
+    expect(onInspection.targetBytes).toBe((64 * 64 + 3 * 32 * 32) * 8);
+    expect(onInspection.passCount).toBe(4);
+    expect(onInspection.uploadCount).toBe(4);
+    expect(onInspection.bindGroupCount).toBe(4);
+    expect(onInspection.encodeCount).toBe(4);
+    expect(JSON.parse(JSON.stringify(onInspection))).toEqual(onInspection);
+    const firstGeneration = onInspection.generation;
+    expect(firstGeneration).toBeGreaterThan(0);
+
+    world.set(camera, LocalCamera, { bloom: BLOOM_DISABLED }).unwrap();
+    expect(world.update().ok).toBe(true);
+    const off = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(off.ok).toBe(true);
+    const offInspection = renderer.inspect().bloom;
+    expect(['retiring', 'off']).toContain(offInspection.state);
+    expect(offInspection.resourceCount).toBeGreaterThan(0);
+    expect(offInspection.passCount).toBe(0);
+    const retiringGeneration = offInspection.generation;
+    expect(retiringGeneration).toBe(firstGeneration);
+    world.set(camera, LocalCamera, { bloom: BLOOM_ENABLED }).unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(
+      renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      }).ok,
+    ).toBe(true);
+    const recoveredInspection = renderer.inspect().bloom;
+    expect(recoveredInspection.state).toBe('active');
+    expect(recoveredInspection.resourceCount).toBeGreaterThan(0);
+    expect(recoveredInspection.passCount).toBe(4);
+    expect(recoveredInspection.uploadCount).toBe(4);
+    expect(recoveredInspection.bindGroupCount).toBe(4);
+    expect(recoveredInspection.encodeCount).toBe(4);
+    expect(recoveredInspection.generation).toBeGreaterThan(firstGeneration);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(renderer.inspect().bloom.state).toBe('active');
+    expect((await renderer.dispose()).ok).toBe(true);
+    expect(renderer.inspect().bloom.state).toBe('off');
+    expect((await renderer.dispose()).ok).toBe(true);
+  });
+
+  it('publishes Bloom record receipts only after a successful submit', async () => {
+    const scenario = await createBloomScenario();
+    const submit = vi.spyOn(RhiNullQueue.prototype, 'submit');
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'Bloom queue submission succeeds',
+      hint: 'repair the queue and retry the frame',
+    });
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+
+      submit.mockReturnValueOnce(err(failure));
+      expect(scenario.draw().ok).toBe(false);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'active',
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+
+      expect(scenario.draw().ok).toBe(true);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+    } finally {
+      submit.mockRestore();
+      await scenario.dispose();
+    }
+  });
+
+  it('aborts a Bloom pass write failure without publishing partial receipts', async () => {
+    const originalWriteBuffer = RhiNullQueue.prototype.writeBuffer;
+    const createBuffer = vi.spyOn(RhiNullDevice.prototype, 'createBuffer');
+    const writeBuffer = vi.spyOn(RhiNullQueue.prototype, 'writeBuffer');
+    const submit = vi.spyOn(RhiNullQueue.prototype, 'submit');
+    const scenario = await createBloomScenario();
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'Bloom blur-H params upload succeeds',
+      hint: 'repair the Bloom params buffer and retry the frame',
+    });
+    const errors: unknown[] = [];
+    const unsubscribe = scenario.renderer.onError((error) => errors.push(error));
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      const blurHParams = createBuffer.mock.calls.reduce<object | undefined>(
+        (found, args, index) => {
+          if (found !== undefined || args[0].label !== 'bloom-blur-h-params-ubo') return found;
+          const result = createBuffer.mock.results[index];
+          if (result?.type !== 'return' || !result.value.ok) return undefined;
+          return result.value.value as object;
+        },
+        undefined,
+      );
+      expect(blurHParams).toBeDefined();
+      const lkg = scenario.renderer.inspect().bloom;
+      expect(lkg).toMatchObject({ uploadCount: 4, bindGroupCount: 4, encodeCount: 4 });
+      const submitCount = submit.mock.calls.length;
+
+      let injected = false;
+      writeBuffer.mockImplementation((buffer, ...args) => {
+        if (buffer === blurHParams && !injected) {
+          injected = true;
+          return err(failure);
+        }
+        return originalWriteBuffer.call(RhiNullQueue.prototype, buffer, ...args);
+      });
+      expect(scenario.draw().ok).toBe(false);
+      expect(injected).toBe(true);
+      expect(submit).toHaveBeenCalledTimes(submitCount);
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toMatchObject({
+        code: 'pass-encode-failed',
+        detail: { passName: 'bloom-blur-h', cause: failure },
+      });
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'active',
+        generation: lkg.generation,
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+
+      writeBuffer.mockRestore();
+      expect(scenario.draw().ok).toBe(true);
+      expect(submit).toHaveBeenCalledTimes(submitCount + 1);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+    } finally {
+      writeBuffer.mockRestore();
+      submit.mockRestore();
+      createBuffer.mockRestore();
+      unsubscribe();
+      await scenario.dispose();
+    }
+  });
+
+  const bloomConstructionFailures = [
+    ['createSampler', 'bloom-sampler'],
+    ['createBindGroupLayout', 'bloom-bright-bgl'],
+    ['createBindGroupLayout', 'bloom-blur-bgl'],
+    ['createBindGroupLayout', 'bloom-composite-bgl'],
+    ['createPipelineLayout', 'bloom-bright-pl'],
+    ['createPipelineLayout', 'bloom-blur-pl'],
+    ['createPipelineLayout', 'bloom-composite-pl'],
+    ['createRenderPipeline', 'bloom-bright-pipeline'],
+    ['createRenderPipeline', 'bloom-blur-h-pipeline'],
+    ['createRenderPipeline', 'bloom-composite-pipeline'],
+    ['createBuffer', 'bloom-bright-params-ubo'],
+    ['createBuffer', 'bloom-blur-h-params-ubo'],
+    ['createBuffer', 'bloom-blur-v-params-ubo'],
+    ['createBuffer', 'bloom-composite-params-ubo'],
+  ] as const;
+
+  it.each(
+    bloomConstructionFailures,
+  )('abandons the Bloom candidate when %s(%s) fails and retries cleanly', async (method, label) => {
+    const scenario = await createBloomScenario();
+    const original = RhiNullDevice.prototype[method];
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: `${label} construction succeeds`,
+      hint: 'repair the Bloom construction operation and retry the frame',
+    });
+    let injected = false;
+    const operation = vi.spyOn(RhiNullDevice.prototype, method);
+    const submit = vi.spyOn(RhiNullQueue.prototype, 'submit');
+    const errors: unknown[] = [];
+    const unsubscribe = scenario.renderer.onError((error) => errors.push(error));
+    operation.mockImplementation(function (this: RhiNullDevice, ...args: never[]) {
+      const descriptor = args[0] as { readonly label?: unknown } | undefined;
+      if (!injected && descriptor?.label === label) {
+        injected = true;
+        return err(failure) as never;
+      }
+      return Reflect.apply(original as (...input: never[]) => unknown, this, args) as never;
+    } as never);
+    try {
+      const submitCount = submit.mock.calls.length;
+      expect(scenario.draw().ok).toBe(false);
+      expect(injected).toBe(true);
+      expect(submit).toHaveBeenCalledTimes(submitCount);
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toMatchObject({
+        code: 'webgpu-runtime-error',
+        detail: { error: expect.anything() },
+      });
+      const reported = errors[0] as { readonly detail?: { readonly error?: unknown } };
+      if (method === 'createRenderPipeline') {
+        expect(reported.detail?.error).toMatchObject({
+          code: 'pipeline-build-failed',
+          name: 'PipelineSpecError',
+          detail: { cause: failure },
+        });
+      } else {
+        expect(reported.detail?.error).toBe(failure);
+      }
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'off',
+        graphStatus: 'empty',
+        targetCount: 0,
+        targetBytes: 0,
+        passCount: 0,
+        resourceCount: 0,
+        uploadCount: 0,
+        bindGroupCount: 0,
+        encodeCount: 0,
+      });
+
+      operation.mockRestore();
+      expect(scenario.draw().ok).toBe(true);
+      expect(submit).toHaveBeenCalledTimes(submitCount + 1);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'active',
+        graphStatus: 'valid',
+        targetCount: 4,
+        passCount: 4,
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+    } finally {
+      operation.mockRestore();
+      submit.mockRestore();
+      unsubscribe();
+      await scenario.dispose();
+    }
+  });
+
+  it('aborts a Bloom bind-group failure before submit and preserves committed receipts', async () => {
+    const scenario = await createBloomScenario();
+    const originalCreateBindGroup = RhiNullDevice.prototype.createBindGroup;
+    const createBindGroup = vi.spyOn(RhiNullDevice.prototype, 'createBindGroup');
+    const submit = vi.spyOn(RhiNullQueue.prototype, 'submit');
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'Bloom blur-V bind-group creation succeeds',
+      hint: 'repair the Bloom bind group and retry the frame',
+    });
+    let injected = false;
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      const lkg = scenario.renderer.inspect().bloom;
+      const submitCount = submit.mock.calls.length;
+      scenario.canvas.width = 96;
+      scenario.canvas.height = 64;
+      createBindGroup.mockImplementation(function (this: RhiNullDevice, descriptor) {
+        if (!injected && descriptor.label === 'bloom-blur-v-bg') {
+          injected = true;
+          return err(failure);
+        }
+        return originalCreateBindGroup.call(this, descriptor);
+      });
+      expect(scenario.draw().ok).toBe(false);
+      expect(injected).toBe(true);
+      expect(submit).toHaveBeenCalledTimes(submitCount);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'active',
+        generation: lkg.generation,
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+
+      createBindGroup.mockRestore();
+      expect(scenario.draw().ok).toBe(true);
+      expect(submit).toHaveBeenCalledTimes(submitCount + 1);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'active',
+        uploadCount: 4,
+        bindGroupCount: 4,
+        encodeCount: 4,
+      });
+    } finally {
+      createBindGroup.mockRestore();
+      submit.mockRestore();
+      await scenario.dispose();
+    }
+  });
+
+  it('aggregates active and fence-retiring Bloom bundles through Renderer.inspect', async () => {
+    const fence = deferred<undefined>();
+    const onSubmittedWorkDone = vi
+      .spyOn(RhiNullQueue.prototype, 'onSubmittedWorkDone')
+      .mockReturnValue(fence.promise);
+    const scenario = await createBloomScenario();
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      scenario.setBloom('off');
+      expect(scenario.draw().ok).toBe(true);
+      const retiring = scenario.renderer.inspect().bloom;
+      expect(retiring.state).toBe('retiring');
+      expect(retiring.graphStatus).toBe('empty');
+      expect(retiring.enabled).toBe(false);
+      expect(retiring.passCount).toBe(0);
+      expect(retiring.targetCount).toBe(0);
+      expect(retiring.targetBytes).toBe(0);
+      expect(retiring.encodeCount).toBe(0);
+      expect(retiring.bindGroupCount).toBe(0);
+      expect(retiring.uploadCount).toBe(0);
+      expect(retiring.resourceCount).toBeGreaterThan(0);
+
+      scenario.setBloom('on');
+      expect(scenario.draw().ok).toBe(true);
+      const overlap = scenario.renderer.inspect().bloom;
+      expect(overlap.state).toBe('active');
+      expect(overlap.graphStatus).toBe('valid');
+      expect(overlap.enabled).toBe(true);
+      expect(overlap.passCount).toBe(4);
+      expect(overlap.uploadCount).toBe(4);
+      expect(overlap.bindGroupCount).toBe(4);
+      expect(overlap.encodeCount).toBe(4);
+      expect(overlap.resourceCount).toBeGreaterThan(retiring.resourceCount);
+
+      fence.resolve(undefined);
+      await Promise.resolve();
+      await Promise.resolve();
+      const settled = scenario.renderer.inspect().bloom;
+      expect(settled.state).toBe('active');
+      expect(settled.graphStatus).toBe('valid');
+      expect(settled.passCount).toBe(4);
+      expect(settled.targetCount).toBe(4);
+      expect(settled.targetBytes).toBe((64 * 64 + 3 * 32 * 32) * 8);
+      expect(settled.resourceCount).toBeLessThan(overlap.resourceCount);
+    } finally {
+      onSubmittedWorkDone.mockRestore();
+      await scenario.dispose();
+    }
+  });
+
+  it('settles Bloom off to exact zero without re-enabling it', async () => {
+    const fence = deferred<undefined>();
+    const onSubmittedWorkDone = vi
+      .spyOn(RhiNullQueue.prototype, 'onSubmittedWorkDone')
+      .mockReturnValue(fence.promise);
+    const scenario = await createBloomScenario();
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      scenario.setBloom('off');
+      expect(scenario.draw().ok).toBe(true);
+      const retiring = scenario.renderer.inspect().bloom;
+      expect(retiring.state).toBe('retiring');
+      expect(retiring.enabled).toBe(false);
+      expect(retiring.targetCount).toBe(0);
+      expect(retiring.targetBytes).toBe(0);
+      expect(retiring.passCount).toBe(0);
+      expect(retiring.resourceCount).toBeGreaterThan(0);
+      expect(retiring.uploadCount).toBe(0);
+
+      fence.resolve(undefined);
+      for (let attempt = 0; attempt < 4; attempt += 1) await Promise.resolve();
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'off',
+        graphStatus: 'empty',
+        enabled: false,
+        targetCount: 0,
+        targetBytes: 0,
+        passCount: 0,
+        resourceCount: 0,
+        uploadCount: 0,
+      });
+    } finally {
+      onSubmittedWorkDone.mockRestore();
+      await scenario.dispose();
+    }
+  });
+
+  it('reports one structured Bloom fence rejection and drains late-retiring resources', async () => {
+    const fence = deferred<undefined>();
+    const onSubmittedWorkDone = vi
+      .spyOn(RhiNullQueue.prototype, 'onSubmittedWorkDone')
+      .mockReturnValue(fence.promise);
+    const scenario = await createBloomScenario();
+    const errors: unknown[] = [];
+    let errorSnapshot: ReturnType<typeof scenario.renderer.inspect> | undefined;
+    const unsubscribe = scenario.renderer.onError((error) => {
+      errors.push(error);
+      errorSnapshot = scenario.renderer.inspect();
+    });
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      scenario.setBloom('off');
+      expect(scenario.draw().ok).toBe(true);
+      expect(scenario.renderer.inspect().bloom.resourceCount).toBeGreaterThan(0);
+      fence.reject(new Error('controlled Bloom fence failure'));
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toMatchObject({
+        code: 'webgpu-runtime-error',
+        detail: { error: { code: 'bloom-fence-rejected' } },
+      });
+      expect(errorSnapshot?.bloom).toMatchObject({
+        state: 'retiring',
+        graphStatus: 'empty',
+        enabled: false,
+      });
+      expect(errorSnapshot?.bloom.resourceCount).toBeGreaterThan(0);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'off',
+        enabled: false,
+        resourceCount: 0,
+        passCount: 0,
+        encodeCount: 0,
+        bindGroupCount: 0,
+        uploadCount: 0,
+      });
+      expect((await scenario.renderer.dispose()).ok).toBe(true);
+      expect((await scenario.renderer.dispose()).ok).toBe(true);
+      expect(errors).toHaveLength(1);
+    } finally {
+      unsubscribe();
+      onSubmittedWorkDone.mockRestore();
+      await scenario.dispose();
+    }
+  });
+
+  it('keeps drained Bloom fence rejection callbacks inert', async () => {
+    const callbacks: Array<{
+      readonly resolve: (value: undefined) => unknown;
+      readonly reject: ((reason: unknown) => unknown) | undefined;
+    }> = [];
+    const lateFence = {
+      // biome-ignore lint/suspicious/noThenProperty: The test deliberately exposes a controllable fence thenable.
+      then(onFulfilled: (value: undefined) => unknown, onRejected: (reason: unknown) => unknown) {
+        callbacks.push({ resolve: onFulfilled, reject: onRejected });
+        return Promise.resolve();
+      },
+    } as unknown as Promise<undefined>;
+    const onSubmittedWorkDone = vi
+      .spyOn(RhiNullQueue.prototype, 'onSubmittedWorkDone')
+      .mockReturnValue(lateFence);
+    const scenario = await createBloomScenario();
+    const errors: unknown[] = [];
+    const unsubscribe = scenario.renderer.onError((error) => errors.push(error));
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      scenario.setBloom('off');
+      expect(scenario.draw().ok).toBe(true);
+      expect(scenario.renderer.inspect().bloom.resourceCount).toBeGreaterThan(0);
+      for (let attempt = 0; attempt < 8 && callbacks.length === 0; attempt += 1) {
+        await Promise.resolve();
+      }
+      expect(callbacks.length).toBeGreaterThan(0);
+      for (const callback of callbacks) callback.resolve(undefined);
+      for (let attempt = 0; attempt < 4; attempt += 1) {
+        await Promise.resolve();
+      }
+      expect(scenario.renderer.inspect().bloom.resourceCount).toBe(0);
+      for (const callback of callbacks) {
+        callback.reject?.(new Error('late Bloom fence rejection'));
+      }
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(errors).toHaveLength(0);
+      expect(scenario.renderer.inspect().bloom).toMatchObject({
+        state: 'off',
+        graphStatus: 'empty',
+        resourceCount: 0,
+        passCount: 0,
+        encodeCount: 0,
+        bindGroupCount: 0,
+        uploadCount: 0,
+      });
+    } finally {
+      unsubscribe();
+      onSubmittedWorkDone.mockRestore();
+      await scenario.dispose();
+    }
+  });
+
+  it.each([
+    'execute',
+    'finish',
+    'submit',
+    'throw',
+  ] as const)('keeps the Bloom LKG invisible and retries after %s failure', async (failureAt) => {
+    const scenario = await createBloomScenario();
+    const errors: unknown[] = [];
+    let failureSnapshot: ReturnType<typeof scenario.renderer.inspect> | undefined;
+    const unsubscribe = scenario.renderer.onError((error) => {
+      errors.push(error);
+      failureSnapshot = scenario.renderer.inspect();
+    });
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: `Bloom ${failureAt} operation succeeds`,
+      hint: 'repair the injected operation and retry the same frame',
+    });
+    const createEncoder = vi.spyOn(RhiNullDevice.prototype, 'createCommandEncoder');
+    const beginRenderPass = vi.spyOn(RhiNullCommandEncoder.prototype, 'beginRenderPass');
+    const finish = vi.spyOn(RhiNullCommandEncoder.prototype, 'finish');
+    const submit = vi.spyOn(RhiNullQueue.prototype, 'submit');
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      scenario.setBloom('off');
+      expect(scenario.draw().ok).toBe(true);
+      const lkg = scenario.renderer.inspect().bloom;
+      scenario.setBloom('on');
+      if (failureAt === 'execute') {
+        beginRenderPass.mockImplementation(() => {
+          throw failure;
+        });
+      } else if (failureAt === 'finish') {
+        finish.mockReturnValue(err(failure));
+      } else if (failureAt === 'submit') {
+        submit.mockReturnValue(err(failure));
+      } else {
+        createEncoder.mockImplementation(() => {
+          throw failure;
+        });
+      }
+      expect(scenario.draw().ok).toBe(false);
+      expect(scenario.renderer.inspect().bloom.resourceCount).toBe(lkg.resourceCount);
+      expect(scenario.renderer.inspect().bloom.passCount).toBe(0);
+      expect(failureSnapshot?.bloom.generation).toBe(lkg.generation);
+      expect(failureSnapshot?.bloom.resourceCount).toBe(lkg.resourceCount);
+      expect(failureSnapshot?.bloom.passCount).toBe(0);
+      expect(errors.length).toBeGreaterThan(0);
+      const errorCount = errors.length;
+      createEncoder.mockRestore();
+      beginRenderPass.mockRestore();
+      finish.mockRestore();
+      submit.mockRestore();
+      expect(scenario.draw().ok).toBe(true);
+      expect(scenario.renderer.inspect().bloom.state).toBe('active');
+      expect(scenario.renderer.inspect().bloom.generation).toBeGreaterThan(lkg.generation);
+      expect(errors).toHaveLength(errorCount);
+    } finally {
+      createEncoder.mockRestore();
+      beginRenderPass.mockRestore();
+      finish.mockRestore();
+      submit.mockRestore();
+      unsubscribe();
+      await scenario.dispose();
+    }
+  });
+
+  it('abandons later Bloom params construction and destroys adopted handles once', async () => {
+    const scenario = await createBloomScenario();
+    const originalCreateBuffer = RhiNullDevice.prototype.createBuffer;
+    const originalDestroyBuffer = RhiNullDevice.prototype.destroyBuffer;
+    const createBuffer = vi.spyOn(RhiNullDevice.prototype, 'createBuffer');
+    const destroyBuffer = vi.spyOn(RhiNullDevice.prototype, 'destroyBuffer');
+    const created = new Map<object, string>();
+    const destroyCounts = new Map<object, number>();
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'Bloom blur-v params buffer construction succeeds',
+      hint: 'repair the injected construction failure and retry the same frame',
+    });
+    try {
+      expect(scenario.draw().ok).toBe(true);
+      scenario.setBloom('off');
+      expect(scenario.draw().ok).toBe(true);
+      const lkg = scenario.renderer.inspect().bloom;
+      scenario.setBloom('on');
+      createBuffer.mockImplementation(function (this: RhiNullDevice, descriptor) {
+        if (descriptor.label === 'bloom-blur-v-params-ubo') {
+          return err(failure);
+        }
+        const result = originalCreateBuffer.call(this, descriptor);
+        if (
+          result.ok &&
+          typeof result.value === 'object' &&
+          result.value !== null &&
+          typeof descriptor.label === 'string' &&
+          descriptor.label.startsWith('bloom-')
+        ) {
+          created.set(result.value, descriptor.label);
+        }
+        return result;
+      });
+      destroyBuffer.mockImplementation(function (this: RhiNullDevice, handle) {
+        if (typeof handle === 'object' && handle !== null) {
+          destroyCounts.set(handle, (destroyCounts.get(handle) ?? 0) + 1);
+        }
+        return originalDestroyBuffer.call(this, handle);
+      });
+      expect(scenario.draw().ok).toBe(false);
+      expect(scenario.renderer.inspect().bloom.resourceCount).toBe(lkg.resourceCount);
+      expect(scenario.renderer.inspect().bloom.passCount).toBe(0);
+      const adoptedBeforeFailure = [...created.entries()].filter(
+        ([, label]) => label === 'bloom-bright-params-ubo' || label === 'bloom-blur-h-params-ubo',
+      );
+      expect(adoptedBeforeFailure).toHaveLength(2);
+      expect(adoptedBeforeFailure.every(([handle]) => destroyCounts.get(handle) === 1)).toBe(true);
+      expect(
+        [...created.values()].filter((label) => label === 'bloom-blur-v-params-ubo'),
+      ).toHaveLength(0);
+      createBuffer.mockRestore();
+      destroyBuffer.mockRestore();
+      expect(scenario.draw().ok).toBe(true);
+      expect(scenario.renderer.inspect().bloom.generation).toBeGreaterThan(lkg.generation);
+    } finally {
+      createBuffer.mockRestore();
+      destroyBuffer.mockRestore();
+      await scenario.dispose();
+    }
+  });
+
+  it('keeps Bloom ownership scoped across failed and successful device recovery', async () => {
+    const adapter = new RhiNullAdapter();
+    const lost = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
+    const firstDevice = (await adapter.requestDevice()).unwrap();
+    const replacementDevice = (await adapter.requestDevice()).unwrap();
+    const lostProxy = new Proxy(firstDevice, {
+      get(target, property) {
+        if (property === 'lost') return lost.promise;
+        const value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+    let requestCount = 0;
+    const recoveryFailure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'replacement device acquisition succeeds',
+      hint: 'retry recovery after the backend becomes available',
+    });
+    const recoverableRhi = {
+      ...rhi,
+      requestAdapter: async () =>
+        ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => {
+            requestCount += 1;
+            if (requestCount === 1) return ok(lostProxy);
+            if (requestCount === 2) return { ok: false, error: recoveryFailure };
+            return ok(replacementDevice);
+          },
+        } as never),
+    } as never;
+    const renderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi: recoverableRhi },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    registerPropagateTransforms(world);
+    world.spawn(
+      { component: Transform, data: { pos: [0, 0, 4] } },
+      {
+        component: LocalCamera,
+        data: {
+          fov: 1,
+          aspect: 1,
+          near: 0.1,
+          far: 100,
+          antialias: ANTIALIAS_NONE,
+          bloom: BLOOM_ENABLED,
+        },
+      },
+    );
+    const input = () => ({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    try {
+      expect((await renderer.initialization).ok).toBe(true);
+      expect(world.update().ok).toBe(true);
+      expect(renderer.draw(input()).ok).toBe(true);
+      const beforeLoss = renderer.inspect().bloom;
+      const beforeDeviceGeneration = renderer.inspect().temporal.deviceGeneration;
+      expect(beforeLoss.state).toBe('active');
+      lost.reject({ reason: 'unknown', message: 'forced device loss' });
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(renderer.health().reason).toBe('device-lost');
+      const failed = await renderer.recover();
+      expect(failed.ok).toBe(false);
+      expect(renderer.health().reason).toBe('device-lost');
+      const recovered = await renderer.recover();
+      expect(recovered.ok).toBe(true);
+      expect(world.update().ok).toBe(true);
+      expect(renderer.draw(input()).ok).toBe(true);
+      expect(renderer.inspect().bloom.state).toBe('active');
+      expect(renderer.inspect().bloom.generation).toBeGreaterThan(0);
+      expect(renderer.inspect().temporal.deviceGeneration).toBeGreaterThan(beforeDeviceGeneration);
+      expect((await renderer.dispose()).ok).toBe(true);
+      expect((await renderer.dispose()).ok).toBe(true);
+      expect(renderer.inspect().bloom.state).toBe('off');
+    } finally {
+      await renderer.dispose();
+    }
+  });
+
+  it('abandons a post-process recovery candidate before promotion and retries once', async () => {
+    const adapter = new RhiNullAdapter();
+    const lost = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
+    const firstDevice = (await adapter.requestDevice()).unwrap();
+    const failingReplacement = (await adapter.requestDevice()).unwrap();
+    const successfulReplacement = (await adapter.requestDevice()).unwrap();
+    const lostProxy = new Proxy(firstDevice, {
+      get(target, property) {
+        if (property === 'lost') return lost.promise;
+        const value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+    const createdReplacementHandles = new Set<object>();
+    const createdReplacementLabels = new Map<object, string>();
+    const destroyedReplacementHandles = new Map<object, number>();
+    let failPostProcessRestore = true;
+    const recoveryFailure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'post-process recovery params upload succeeds',
+      hint: 'repair the replacement post-process resource and retry recovery',
+    });
+    const trackReplacement = new Proxy(failingReplacement, {
+      get(target, property) {
+        if (property === 'createBuffer') {
+          return (descriptor: { readonly label?: string }) => {
+            const result = failingReplacement.createBuffer(descriptor as never);
+            if (
+              result.ok &&
+              typeof result.value === 'object' &&
+              result.value !== null &&
+              (descriptor.label?.startsWith('bloom-') ||
+                descriptor.label?.startsWith('post-process-params-'))
+            ) {
+              createdReplacementHandles.add(result.value);
+              if (descriptor.label !== undefined) {
+                createdReplacementLabels.set(result.value, descriptor.label);
+              }
+            }
+            return result;
+          };
+        }
+        if (property === 'queue') {
+          return new Proxy(failingReplacement.queue, {
+            get(queue, queueProperty) {
+              if (queueProperty === 'writeBuffer') {
+                return (buffer: object, ...args: unknown[]) => {
+                  const label = createdReplacementLabels.get(buffer);
+                  if (failPostProcessRestore && label?.startsWith('post-process-params-')) {
+                    return err(recoveryFailure);
+                  }
+                  return failingReplacement.queue.writeBuffer(
+                    buffer as never,
+                    args[0] as number,
+                    args[1] as ArrayBufferView | ArrayBuffer,
+                    args[2] as number | undefined,
+                    args[3] as number | undefined,
+                  );
+                };
+              }
+              const value = Reflect.get(queue, queueProperty, queue);
+              return typeof value === 'function' ? value.bind(queue) : value;
+            },
+          });
+        }
+        if (property === 'destroyBuffer' || property === 'destroyTexture') {
+          return (handle: object) => {
+            destroyedReplacementHandles.set(
+              handle,
+              (destroyedReplacementHandles.get(handle) ?? 0) + 1,
+            );
+            const destroy = failingReplacement[property as 'destroyBuffer' | 'destroyTexture'];
+            return destroy.call(failingReplacement, handle as never);
+          };
+        }
+        const value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+    let requestCount = 0;
+    const recoveryFailureRhi = {
+      ...rhi,
+      requestAdapter: async () =>
+        ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => {
+            requestCount += 1;
+            if (requestCount === 1) return ok(lostProxy);
+            if (requestCount === 2) return ok(trackReplacement as never);
+            return ok(successfulReplacement);
+          },
+        } as never),
+    } as never;
+    const renderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi: recoveryFailureRhi },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+    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: LocalCamera,
+          data: {
+            fov: 1,
+            aspect: 1,
+            near: 0.1,
+            far: 100,
+            antialias: ANTIALIAS_NONE,
+            bloom: BLOOM_DISABLED,
+          },
+        },
+      )
+      .unwrap();
+    const input = () => ({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    try {
+      expect((await renderer.initialization).ok).toBe(true);
+      expect(world.update().ok).toBe(true);
+      expect(renderer.draw(input()).ok).toBe(true);
+      const beforeFailure = renderer.inspect();
+      lost.reject({ reason: 'unknown', message: 'forced recovery candidate failure' });
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(renderer.health().reason).toBe('device-lost');
+      expect((await renderer.recover()).ok).toBe(false);
+      expect(renderer.health().reason).toBe('device-lost');
+      expect(createdReplacementHandles.size).toBeGreaterThan(0);
+      expect(
+        [...createdReplacementHandles].every(
+          (handle) => destroyedReplacementHandles.get(handle) === 1,
+        ),
+      ).toBe(true);
+      const afterFailure = renderer.inspect();
+      expect(afterFailure.frame.deviceGeneration).toBe(beforeFailure.frame.deviceGeneration);
+      expect(afterFailure.temporal.deviceGeneration).toBe(beforeFailure.temporal.deviceGeneration);
+      expect(afterFailure.environment).toEqual(beforeFailure.environment);
+      expect(afterFailure.bloom.state).toBe('off');
+
+      failPostProcessRestore = false;
+      const recovered = await renderer.recover();
+      expect(recovered.ok).toBe(true);
+      expect(renderer.inspect().frame.deviceGeneration).toBeGreaterThan(
+        beforeFailure.frame.deviceGeneration,
+      );
+      world.set(camera, LocalCamera, { bloom: BLOOM_ENABLED }).unwrap();
+      expect(world.update().ok).toBe(true);
+      expect(renderer.draw(input()).ok).toBe(true);
+      expect(renderer.inspect().bloom.state).toBe('active');
+      expect((await renderer.dispose()).ok).toBe(true);
+      expect((await renderer.dispose()).ok).toBe(true);
+      expect(renderer.inspect().bloom).toMatchObject({
+        state: 'off',
+        graphStatus: 'empty',
+        resourceCount: 0,
+        passCount: 0,
+        encodeCount: 0,
+        bindGroupCount: 0,
+        uploadCount: 0,
+      });
+    } finally {
+      await renderer.dispose();
+    }
+  });
 });