@forgeax/engine-render 0.1.2

package/src/__tests__/recover-error-policy-owner.unit.test.ts

@@ -0,0 +1,127 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { RecoverError, type RecoverErrorCode } from '../errors/recover';
+import {
+  RecoverError as PublicRecoverError,
+  type RecoverErrorCode as PublicRecoverErrorCode,
+} from '../index';
+import {
+  RecoverError as InternalRecoverError,
+  type RecoverErrorCode as InternalRecoverErrorCode,
+} from '../internal';
+
+const expectedCodes = [
+  'recover-not-needed',
+  'recover-not-implemented',
+  'recover-adapter-unavailable',
+  'recover-device-unavailable',
+] as const satisfies readonly RecoverErrorCode[];
+
+const evidence = [
+  {
+    code: 'recover-not-needed',
+    expected:
+      'renderer is healthy; call health() first to confirm degraded state before calling recover()',
+    hint: 'call health() first to confirm degraded state before calling recover()',
+    message: 'recover-not-needed: renderer is not in a degraded state',
+  },
+  {
+    code: 'recover-not-implemented',
+    expected: 'recovery is not yet implemented; self-heal lands in S5',
+    hint: 'self-heal recovery lands in S5; health().reason still reflects the degraded state',
+    message: 'recover-not-implemented: self-heal recovery is not yet implemented',
+  },
+  {
+    code: 'recover-adapter-unavailable',
+    expected: 'requestAdapter returned null; driver/GPU may have been reset',
+    hint: 'retry recover() after a host-chosen delay; adapter availability is transient',
+    message: 'recover-adapter-unavailable: requestAdapter returned no adapter during rebuild',
+  },
+  {
+    code: 'recover-device-unavailable',
+    expected: 'requestDevice failed or threw',
+    hint: 'retry recover() after a host-chosen delay; device creation is driver-dependent',
+    message: 'recover-device-unavailable: requestDevice failed or threw during rebuild',
+  },
+] as const;
+
+describe('RecoverError policy ownership', () => {
+  it('derives the code union from the policy owner', () => {
+    const source = readFileSync(
+      fileURLToPath(new URL('../errors/recover.ts', import.meta.url)),
+      'utf8',
+    );
+
+    expect(source).toContain('export type RecoverErrorCode = keyof typeof RECOVER_ERROR_POLICY;');
+    expect(source).not.toMatch(/export type RecoverErrorCode = 'recover-/);
+  });
+
+  it('preserves the exact four-code vocabulary, order, and public projections', () => {
+    expect(expectedCodes).toHaveLength(4);
+    expect(new Set(expectedCodes).size).toBe(4);
+    expectTypeOf<RecoverErrorCode>().toEqualTypeOf<(typeof expectedCodes)[number]>();
+    expectTypeOf<InternalRecoverErrorCode>().toEqualTypeOf<RecoverErrorCode>();
+    expectTypeOf<PublicRecoverErrorCode>().toEqualTypeOf<RecoverErrorCode>();
+    expect(InternalRecoverError).toBe(RecoverError);
+    expect(PublicRecoverError).toBe(RecoverError);
+  });
+
+  it('preserves all twelve diagnostics byte-for-byte', () => {
+    for (const { code, expected, hint, message } of evidence) {
+      const error = new RecoverError(code);
+      const projected = new PublicRecoverError(code);
+
+      expect(error.code).toBe(code);
+      expect(error.expected).toBe(expected);
+      expect(error.hint).toBe(hint);
+      expect(error.message).toBe(message);
+      expect(projected.code).toBe(code);
+      expect(projected.expected).toBe(expected);
+      expect(projected.hint).toBe(hint);
+      expect(projected.message).toBe(message);
+    }
+  });
+
+  it('preserves Error identity, name, stack, own-key order, and descriptors', () => {
+    const error = new RecoverError('recover-not-needed');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(RecoverError);
+    expect(error).toBeInstanceOf(InternalRecoverError);
+    expect(error).toBeInstanceOf(PublicRecoverError);
+    expect(error.name).toBe('RecoverError');
+    expect(Object.hasOwn(error, 'detail')).toBe(false);
+    expect(typeof error.stack).toBe('string');
+    expect(error.stack).toContain(`RecoverError: ${error.message}`);
+    expect(Object.keys(error)).toEqual(['code', 'expected', 'hint', 'name']);
+    expect(Object.getOwnPropertyNames(error)).toEqual([
+      'stack',
+      'message',
+      'code',
+      'expected',
+      'hint',
+      'name',
+    ]);
+
+    const descriptors = Object.getOwnPropertyDescriptors(error);
+    for (const field of ['code', 'expected', 'hint', 'name'] as const) {
+      expect(descriptors[field]).toMatchObject({
+        configurable: true,
+        enumerable: true,
+        writable: true,
+      });
+    }
+    expect(descriptors.message).toMatchObject({
+      configurable: true,
+      enumerable: false,
+      writable: true,
+    });
+    expect(descriptors.stack).toMatchObject({
+      configurable: true,
+      enumerable: false,
+    });
+    expect(typeof descriptors.stack?.get).toBe('function');
+    expect(typeof descriptors.stack?.set).toBe('function');
+  });
+});

package/src/__tests__/render-dispatch-membership.unit.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildSubmissionCandidateMembership,
+  type SubmissionPlan,
+} from '../gpu-driven/batch-topology';
+import {
+  buildRenderCandidateDomain,
+  buildRenderDispatchMembership,
+  renderCandidateCsmCandidates,
+} from '../render-dispatch-membership';
+import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+import { defaultMaterialSnapshot } from '../render-system-extract';
+
+function dispatchEntry(renderableIndex: number, lightMode: string): DispatchEntry {
+  return { renderableIndex, tags: { LightMode: lightMode } } as unknown as DispatchEntry;
+}
+
+describe('render dispatch membership owner', () => {
+  it('caches one Set per immutable dispatch identity', () => {
+    const dispatch = [dispatchEntry(2, 'ShadowCaster'), dispatchEntry(7, 'Forward')];
+    const first = buildRenderDispatchMembership(dispatch);
+    const second = buildRenderDispatchMembership(dispatch);
+
+    expect(second).toBe(first);
+    expect(first.dispatch).toBe(dispatch);
+    expect([...first.shadowCasterCandidateIndices]).toEqual([2]);
+    expect(first.shadowCasterCandidateIndices.has(7)).toBe(false);
+  });
+
+  it('publishes a new owner when the dispatch domain changes', () => {
+    const firstDispatch = [dispatchEntry(0, 'ShadowCaster')];
+    const secondDispatch = [dispatchEntry(0, 'Forward')];
+
+    const first = buildRenderDispatchMembership(firstDispatch);
+    const second = buildRenderDispatchMembership(secondDispatch);
+
+    expect(second).not.toBe(first);
+    expect(second.shadowCasterCandidateIndices.size).toBe(0);
+  });
+
+  it('reuses the immutable default material projection for handle zero', () => {
+    expect(defaultMaterialSnapshot(0)).toBe(defaultMaterialSnapshot(0));
+    expect(defaultMaterialSnapshot(1)).not.toBe(defaultMaterialSnapshot(0));
+  });
+
+  it('caches the candidate identity index with the dispatch owner', () => {
+    const candidates = [
+      { worldId: 3, entityKey: 11 },
+      { worldId: 4, entityKey: 12 },
+    ] as RenderableSnapshot[];
+    const dispatch = [dispatchEntry(0, 'ShadowCaster')];
+    const first = buildRenderCandidateDomain(candidates, dispatch);
+    const second = buildRenderCandidateDomain(candidates, dispatch);
+
+    expect(second).toBe(first);
+    expect(first.membership).toBe(buildRenderDispatchMembership(dispatch));
+    expect(first.indexByIdentity.get('3:11')).toBe(0);
+    expect(first.indexByIdentity.get('4:12')).toBe(1);
+  });
+
+  it('caches the derived CSM caster view with the candidate owner', () => {
+    const candidates = [
+      {
+        worldId: 3,
+        entityKey: 11,
+        transform: { world: new Float32Array(16) },
+        localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+      },
+    ] as unknown as RenderableSnapshot[];
+    const dispatch = [dispatchEntry(0, 'ShadowCaster')];
+    const domain = buildRenderCandidateDomain(candidates, dispatch);
+
+    expect(renderCandidateCsmCandidates(domain)).toBe(renderCandidateCsmCandidates(domain));
+    expect(renderCandidateCsmCandidates(domain)[0]?.shadowCaster).toBe(true);
+  });
+
+  it('caches the candidate-to-batch reverse owner per immutable submission plan', () => {
+    const plan = {
+      revision: 1,
+      candidateCount: 2,
+      visibleCapacity: 2,
+      batches: [
+        {
+          batchId: 4,
+          generation: 1,
+          key: {} as never,
+          candidates: [{ primitiveIndex: 2, generation: 1, drawItemIndex: 0, instanceOrdinal: 0 }],
+          visibleBase: 0,
+          visibleCapacity: 1,
+          indirectOffset: 0,
+        },
+        {
+          batchId: 9,
+          generation: 1,
+          key: {} as never,
+          candidates: [
+            { primitiveIndex: 2, generation: 1, drawItemIndex: 1, instanceOrdinal: 0 },
+            { primitiveIndex: 7, generation: 1, drawItemIndex: 0, instanceOrdinal: 0 },
+          ],
+          visibleBase: 64,
+          visibleCapacity: 2,
+          indirectOffset: 256,
+        },
+      ],
+    } satisfies SubmissionPlan;
+
+    const first = buildSubmissionCandidateMembership(plan);
+    const second = buildSubmissionCandidateMembership(plan);
+
+    expect(second).toBe(first);
+    expect(first.byPrimitiveIndex.get(2)?.map((entry) => entry.batchId)).toEqual([4, 9]);
+    expect(first.byPrimitiveIndex.get(7)?.[0]?.batchId).toBe(9);
+    expect(first.byBatchId.get(4)?.candidates.map((candidate) => candidate.primitiveIndex)).toEqual(
+      [2],
+    );
+  });
+});

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -0,0 +1,115 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  ObservationUnavailableDetail,
+  ObservationUnavailableReason,
+  RenderError,
+  RenderErrorCode,
+} from '../errors/render';
+import { ObservationUnavailableError, RenderFeatureStageFailedError } from '../errors/render';
+import type { RenderFeatureStageFailedDetail } from '../features/types';
+import type {
+  RenderError as PublicRenderError,
+  RenderErrorCode as PublicRenderErrorCode,
+  RenderFeatureErrorCode,
+  RenderFeatureRecovery,
+  RenderFeatureStage,
+} from '../index';
+
+const expectedCodes = [
+  'fog-owner-conflict',
+  'fog-parameters-invalid',
+  'observation-unavailable',
+  'taa-caps-insufficient',
+  'temporal-unsupported',
+  'atmosphere-cardinality-invalid',
+  'atmosphere-sun-missing',
+  'environment-source-conflict',
+  'atmosphere-parameter-invalid',
+  'atmosphere-caps-insufficient',
+  'atmosphere-producer-failed',
+  'shadow-invalid-config',
+  'equirect-projection-failed',
+  'hdrp-caps-insufficient',
+  'hdrp-light-budget-exceeded',
+  'hdrp-index-list-overflow',
+  'hdrp-deferred-caps-insufficient',
+  'gbuffer-rt-alloc-failed',
+  'gbuffer-attachment-count-mismatch',
+  'point-shadow-atlas-uninitialized',
+  'point-shadow-atlas-bounds-violation',
+  'video-upload-unsupported',
+  'vertex-storage-buffer-unavailable',
+  'skin-palette-overflow',
+  'skin-material-mismatch',
+  'material-skin-attr-missing',
+  'render-feature-registration-conflict',
+  'render-feature-stage-failed',
+  'render-feature-capability-missing',
+  'render-feature-pass-order-conflict',
+  'render-feature-preparation-failed',
+  'render-feature-prepared-state-mismatch',
+  'render-feature-draw-recording-failed',
+] as const satisfies readonly RenderErrorCode[];
+type ExpectedCodeUnion = (typeof expectedCodes)[number];
+
+const expectedFeatureCodes = [
+  'render-feature-registration-conflict',
+  'render-feature-stage-failed',
+  'render-feature-capability-missing',
+  'render-feature-pass-order-conflict',
+  'render-feature-preparation-failed',
+  'render-feature-prepared-state-mismatch',
+  'render-feature-draw-recording-failed',
+] as const satisfies readonly RenderFeatureErrorCode[];
+type ExpectedFeatureCodeUnion = (typeof expectedFeatureCodes)[number];
+
+describe('RenderError code owner', () => {
+  it('derives the exact code union from RenderError and preserves projections', () => {
+    expectTypeOf<RenderErrorCode>().toEqualTypeOf<ExpectedCodeUnion>();
+    expectTypeOf<ExpectedCodeUnion>().toEqualTypeOf<RenderErrorCode>();
+    expectTypeOf<RenderErrorCode>().toEqualTypeOf<RenderError['code']>();
+    expectTypeOf<RenderError['code']>().toEqualTypeOf<RenderErrorCode>();
+    expectTypeOf<PublicRenderErrorCode>().toEqualTypeOf<RenderErrorCode>();
+    expectTypeOf<RenderErrorCode>().toEqualTypeOf<PublicRenderErrorCode>();
+    expectTypeOf<PublicRenderError>().toEqualTypeOf<RenderError>();
+    expectTypeOf<RenderFeatureErrorCode>().toEqualTypeOf<ExpectedFeatureCodeUnion>();
+    expectTypeOf<ExpectedFeatureCodeUnion>().toEqualTypeOf<RenderFeatureErrorCode>();
+
+    const acceptsCode = (code: RenderErrorCode): RenderErrorCode => code;
+    acceptsCode(expectedCodes[0]);
+    // @ts-expect-error unknown codes remain outside the closed RenderErrorCode union.
+    acceptsCode('render-error-code-not-real');
+    // @ts-expect-error unknown codes cannot be assigned to the public alias either.
+    const unknownCode: PublicRenderErrorCode = 'render-error-code-not-real';
+    void unknownCode;
+  });
+
+  it('preserves correlated detail and value declarations', () => {
+    type ObservationError = Extract<RenderError, { readonly code: 'observation-unavailable' }>;
+    expectTypeOf<ObservationError['detail']>().toEqualTypeOf<ObservationUnavailableDetail>();
+    expectTypeOf<
+      ObservationError['detail']['reason']
+    >().toEqualTypeOf<ObservationUnavailableReason>();
+    expectTypeOf<ObservationError['detail']['recovery']>().toEqualTypeOf<
+      ObservationUnavailableDetail['recovery']
+    >();
+
+    const observation = new ObservationUnavailableError('stale', 'draw a current frame');
+    expectTypeOf(observation).toEqualTypeOf<ObservationError>();
+    expectTypeOf(observation.code).toEqualTypeOf<'observation-unavailable'>();
+    expectTypeOf(observation.detail.reason).toEqualTypeOf<ObservationUnavailableReason>();
+
+    type StageFailedError = Extract<RenderError, { readonly code: 'render-feature-stage-failed' }>;
+    expectTypeOf<StageFailedError['detail']>().toEqualTypeOf<RenderFeatureStageFailedDetail>();
+
+    const stageFailed = new RenderFeatureStageFailedError(
+      'test.feature',
+      0,
+      'prepare',
+      'next-frame',
+    );
+    expectTypeOf(stageFailed).toEqualTypeOf<StageFailedError>();
+    expectTypeOf(stageFailed.detail.stage).toEqualTypeOf<RenderFeatureStage>();
+    expectTypeOf(stageFailed.detail.recovery).toEqualTypeOf<RenderFeatureRecovery>();
+  });
+});

package/src/__tests__/render-error-detail-ssot.test-d.ts

@@ -0,0 +1,234 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  PipelineErrorCode,
+  PipelineErrorDetail,
+  PipelineErrorDetailFor,
+  PipelineError as PipelineErrorType,
+  PipelineNotFoundDetail,
+  PipelinePreviouslyRegisteredDetail,
+  VertexColorVariantConflictDetail,
+} from '../pipeline-errors';
+import { PipelineError } from '../pipeline-errors';
+import type {
+  FullscreenInputNotFoundDetail,
+  PostProcessErrorCode,
+  PostProcessErrorDetail,
+  PostProcessErrorDetailFor,
+  PostProcessError as PostProcessErrorType,
+  PostProcessNotFoundDetail,
+  PostProcessParamsSizeMismatchDetail,
+  PostProcessParamsUpdateSizeMismatchDetail,
+  PostProcessPreviouslyRegisteredDetail,
+  SsaoBiasNegativeDetail,
+  SsaoRadiusNonPositiveDetail,
+} from '../post-process-errors';
+import { PostProcessError } from '../post-process-errors';
+
+type ExpectedPostProcessDetails = {
+  readonly 'post-process-already-registered': PostProcessPreviouslyRegisteredDetail;
+  readonly 'post-process-not-found': PostProcessNotFoundDetail;
+  readonly 'fullscreen-input-not-found': FullscreenInputNotFoundDetail;
+  readonly 'ssao-radius-non-positive': SsaoRadiusNonPositiveDetail;
+  readonly 'ssao-bias-negative': SsaoBiasNegativeDetail;
+  readonly 'params-size-mismatch': PostProcessParamsSizeMismatchDetail;
+  readonly 'params-update-size-mismatch': PostProcessParamsUpdateSizeMismatchDetail;
+};
+
+type ExpectedPostProcessCodes = keyof ExpectedPostProcessDetails;
+type DetailFor<C extends PostProcessErrorCode> = Extract<
+  PostProcessErrorType,
+  { readonly code: C }
+>['detail'];
+
+type ExpectedPipelineDetails = {
+  readonly 'pipeline-already-registered': PipelinePreviouslyRegisteredDetail;
+  readonly 'pipeline-not-found': PipelineNotFoundDetail;
+  readonly 'vertex-color-variant-conflict': VertexColorVariantConflictDetail;
+};
+
+type ExpectedPipelineCodes = keyof ExpectedPipelineDetails;
+type PipelineDetailFor<C extends PipelineErrorCode> = Extract<
+  PipelineErrorType,
+  { readonly code: C }
+>['detail'];
+
+describe('render error detail aliases derive from their code resolvers', () => {
+  it('preserves the complete pipeline detail union', () => {
+    expectTypeOf<PipelineErrorDetail>().toEqualTypeOf<PipelineErrorDetailFor<PipelineErrorCode>>();
+  });
+
+  it('keeps the exact closed vocabulary and derives the public code view', () => {
+    expectTypeOf<PipelineErrorCode>().toEqualTypeOf<ExpectedPipelineCodes>();
+    expectTypeOf<ExpectedPipelineCodes>().toEqualTypeOf<PipelineErrorCode>();
+    expectTypeOf<PipelineErrorType['code']>().toEqualTypeOf<PipelineErrorCode>();
+    expectTypeOf<PipelineErrorCode>().toEqualTypeOf<PipelineErrorType['code']>();
+  });
+
+  it('preserves every pipeline code/detail correlation in the mapped error view', () => {
+    expectTypeOf<PipelineDetailFor<'pipeline-already-registered'>>().toMatchTypeOf<
+      ExpectedPipelineDetails['pipeline-already-registered']
+    >();
+    expectTypeOf<PipelineDetailFor<'pipeline-not-found'>>().toMatchTypeOf<
+      ExpectedPipelineDetails['pipeline-not-found']
+    >();
+    expectTypeOf<PipelineDetailFor<'vertex-color-variant-conflict'>>().toMatchTypeOf<
+      ExpectedPipelineDetails['vertex-color-variant-conflict']
+    >();
+  });
+
+  it('preserves the complete post-process detail union', () => {
+    expectTypeOf<PostProcessErrorDetail>().toEqualTypeOf<
+      PostProcessErrorDetailFor<PostProcessErrorCode>
+    >();
+  });
+
+  it('keeps the exact seven-code vocabulary and derives the public code view', () => {
+    expectTypeOf<PostProcessErrorCode>().toEqualTypeOf<ExpectedPostProcessCodes>();
+    expectTypeOf<ExpectedPostProcessCodes>().toEqualTypeOf<PostProcessErrorCode>();
+    expectTypeOf<PostProcessErrorType['code']>().toEqualTypeOf<PostProcessErrorCode>();
+    expectTypeOf<PostProcessErrorCode>().toEqualTypeOf<PostProcessErrorType['code']>();
+  });
+
+  it('preserves every code/detail correlation in the mapped error view', () => {
+    expectTypeOf<DetailFor<'post-process-already-registered'>>().toMatchTypeOf<
+      ExpectedPostProcessDetails['post-process-already-registered']
+    >();
+    expectTypeOf<DetailFor<'post-process-not-found'>>().toMatchTypeOf<
+      ExpectedPostProcessDetails['post-process-not-found']
+    >();
+    expectTypeOf<DetailFor<'fullscreen-input-not-found'>>().toMatchTypeOf<
+      ExpectedPostProcessDetails['fullscreen-input-not-found']
+    >();
+    expectTypeOf<DetailFor<'ssao-radius-non-positive'>>().toMatchTypeOf<
+      ExpectedPostProcessDetails['ssao-radius-non-positive']
+    >();
+    expectTypeOf<DetailFor<'ssao-bias-negative'>>().toMatchTypeOf<
+      ExpectedPostProcessDetails['ssao-bias-negative']
+    >();
+    expectTypeOf<DetailFor<'params-size-mismatch'>>().toMatchTypeOf<
+      ExpectedPostProcessDetails['params-size-mismatch']
+    >();
+    expectTypeOf<DetailFor<'params-update-size-mismatch'>>().toMatchTypeOf<
+      ExpectedPostProcessDetails['params-update-size-mismatch']
+    >();
+  });
+
+  it('rejects unknown codes and mismatched code/detail pairs', () => {
+    // @ts-expect-error unknown literals are outside the closed code view.
+    const invalidPipelineCode: PipelineErrorCode = 'pipeline-not-real';
+    void invalidPipelineCode;
+
+    new PipelineError({
+      code: 'pipeline-not-found',
+      // @ts-expect-error the detail must match the selected code.
+      detail: { id: 'already-registered' },
+    });
+
+    // @ts-expect-error unknown literals are outside the closed code view.
+    const invalidCode: PostProcessErrorCode = 'post-process-not-real';
+    void invalidCode;
+
+    new PostProcessError({
+      code: 'post-process-not-found',
+      // @ts-expect-error the detail must match the selected code.
+      detail: { readsKey: 'hdrColor', passName: 'tonemap' },
+    });
+  });
+
+  it('preserves generic PipelineError constructor inference for each selected variant', () => {
+    const previouslyRegistered = new PipelineError({
+      code: 'pipeline-already-registered',
+      detail: { id: 'forward' },
+    });
+    expectTypeOf(previouslyRegistered).toEqualTypeOf<
+      Extract<PipelineErrorType, { readonly code: 'pipeline-already-registered' }>
+    >();
+    expectTypeOf(previouslyRegistered.detail.id).toEqualTypeOf<string>();
+
+    const notFound = new PipelineError({
+      code: 'pipeline-not-found',
+      detail: { handle: 42 },
+    });
+    expectTypeOf(notFound).toEqualTypeOf<
+      Extract<PipelineErrorType, { readonly code: 'pipeline-not-found' }>
+    >();
+    expectTypeOf(notFound.detail.handle).toEqualTypeOf<number>();
+  });
+
+  it('supports exhaustive PipelineError narrowing across every mapped variant', () => {
+    const describePipeline = (error: PipelineErrorType): string => {
+      switch (error.code) {
+        case 'pipeline-already-registered':
+          expectTypeOf(error.detail.id).toEqualTypeOf<string>();
+          return error.detail.id;
+        case 'pipeline-not-found':
+          expectTypeOf(error.detail.handle).toEqualTypeOf<number>();
+          return `${error.detail.handle}`;
+        case 'vertex-color-variant-conflict':
+          expectTypeOf(error.detail.authoredValue).toEqualTypeOf<string>();
+          return error.detail.authoredValue;
+      }
+      const exhaustive: never = error;
+      return exhaustive;
+    };
+
+    expectTypeOf(describePipeline).returns.toEqualTypeOf<string>();
+  });
+
+  it('preserves generic constructor inference for each selected variant', () => {
+    const previouslyRegistered = new PostProcessError({
+      code: 'post-process-already-registered',
+      detail: { id: 'tonemap' },
+    });
+    expectTypeOf(previouslyRegistered).toEqualTypeOf<
+      Extract<PostProcessErrorType, { readonly code: 'post-process-already-registered' }>
+    >();
+    expectTypeOf(previouslyRegistered.detail.id).toEqualTypeOf<string>();
+
+    const notFound = new PostProcessError({
+      code: 'post-process-not-found',
+      detail: { id: 'missing' },
+    });
+    expectTypeOf(notFound).toEqualTypeOf<
+      Extract<PostProcessErrorType, { readonly code: 'post-process-not-found' }>
+    >();
+    expectTypeOf(notFound.detail.id).toEqualTypeOf<string>();
+  });
+
+  it('supports exhaustive narrowing across every mapped variant', () => {
+    const describe = (error: PostProcessErrorType): string => {
+      switch (error.code) {
+        case 'post-process-already-registered':
+          expectTypeOf(error.detail.id).toEqualTypeOf<string>();
+          return error.detail.id;
+        case 'post-process-not-found':
+          expectTypeOf(error.detail.id).toEqualTypeOf<string>();
+          return error.detail.id;
+        case 'fullscreen-input-not-found':
+          expectTypeOf(error.detail.readsKey).toEqualTypeOf<string>();
+          expectTypeOf(error.detail.passName).toEqualTypeOf<string>();
+          return `${error.detail.readsKey}:${error.detail.passName}`;
+        case 'ssao-radius-non-positive':
+          expectTypeOf(error.detail.paramName).toEqualTypeOf<string>();
+          expectTypeOf(error.detail.value).toEqualTypeOf<number>();
+          return `${error.detail.paramName}:${error.detail.value}`;
+        case 'ssao-bias-negative':
+          expectTypeOf(error.detail.paramName).toEqualTypeOf<string>();
+          expectTypeOf(error.detail.value).toEqualTypeOf<number>();
+          return `${error.detail.paramName}:${error.detail.value}`;
+        case 'params-size-mismatch':
+          expectTypeOf(error.detail.byteSize).toEqualTypeOf<number>();
+          expectTypeOf(error.detail.actualLength).toEqualTypeOf<number>();
+          return `${error.detail.byteSize}:${error.detail.actualLength}`;
+        case 'params-update-size-mismatch':
+          expectTypeOf(error.detail.byteSize).toEqualTypeOf<number>();
+          expectTypeOf(error.detail.actualLength).toEqualTypeOf<number>();
+          return `${error.detail.byteSize}:${error.detail.actualLength}`;
+      }
+      const exhaustive: never = error;
+      return exhaustive;
+    };
+
+    expectTypeOf(describe).returns.toEqualTypeOf<string>();
+  });
+});

package/src/__tests__/render-error-exhaustive.test-d.ts

@@ -0,0 +1,84 @@
+import type {
+  RenderError,
+  RenderErrorCode,
+  RenderFeatureCapabilityMissingError,
+  RenderFeatureDrawRecordingFailedError,
+  RenderFeaturePassOrderConflictError,
+  RenderFeaturePreparationFailedError,
+  RenderFeaturePreparedStateMismatchError,
+  RenderFeatureRegistrationConflictError,
+  RenderFeatureStageFailedError,
+} from '../errors';
+import type { RenderFeatureErrorCode } from '../features/types';
+
+function renderFeatureCodeLabel(code: RenderFeatureErrorCode): string {
+  switch (code) {
+    case 'render-feature-registration-conflict':
+      return code;
+    case 'render-feature-stage-failed':
+      return code;
+    case 'render-feature-capability-missing':
+      return code;
+    case 'render-feature-pass-order-conflict':
+      return code;
+    case 'render-feature-preparation-failed':
+      return code;
+    case 'render-feature-prepared-state-mismatch':
+      return code;
+    case 'render-feature-draw-recording-failed':
+      return code;
+  }
+}
+
+function renderCodeLabel(code: RenderErrorCode): string {
+  switch (code) {
+    case 'render-feature-registration-conflict':
+      return renderFeatureCodeLabel(code);
+    case 'render-feature-stage-failed':
+      return renderFeatureCodeLabel(code);
+    case 'render-feature-capability-missing':
+      return renderFeatureCodeLabel(code);
+    case 'render-feature-pass-order-conflict':
+      return renderFeatureCodeLabel(code);
+    default:
+      return code;
+  }
+}
+
+function renderFeatureErrorLabel(error: RenderError): string {
+  switch (error.code) {
+    case 'render-feature-preparation-failed': {
+      const typed: RenderFeaturePreparationFailedError = error;
+      return `${typed.detail.featureIdentity}:${typed.detail.resourceName}`;
+    }
+    case 'render-feature-prepared-state-mismatch': {
+      const typed: RenderFeaturePreparedStateMismatchError = error;
+      return `${typed.detail.featureIdentity}:${typed.detail.reason}`;
+    }
+    case 'render-feature-draw-recording-failed': {
+      const typed: RenderFeatureDrawRecordingFailedError = error;
+      return `${typed.detail.featureIdentity}:${typed.detail.backendReason}`;
+    }
+    case 'render-feature-registration-conflict': {
+      const typed: RenderFeatureRegistrationConflictError = error;
+      return `${typed.detail.featureIdentity}:${typed.detail.conflictingOrder}`;
+    }
+    case 'render-feature-stage-failed': {
+      const typed: RenderFeatureStageFailedError = error;
+      return `${typed.detail.featureIdentity}:${typed.detail.stage}`;
+    }
+    case 'render-feature-capability-missing': {
+      const typed: RenderFeatureCapabilityMissingError = error;
+      return `${typed.detail.featureIdentity}:${typed.detail.capability}`;
+    }
+    case 'render-feature-pass-order-conflict': {
+      const typed: RenderFeaturePassOrderConflictError = error;
+      return `${typed.detail.featureIdentity}:${typed.detail.passIdentity}`;
+    }
+    default:
+      return error.expected;
+  }
+}
+
+void renderCodeLabel;
+void renderFeatureErrorLabel;