@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/public-surface.test-d.ts

@@ -0,0 +1,94 @@
+import type {
+  FrameObservationRequest,
+  FrameReceipt,
+  RendererState,
+  RenderFrameInput,
+  RenderInspection,
+  RenderWorldLease,
+} from '@forgeax/engine-render';
+import { Camera, type Tonemap, visibilityStateFromU32 } from '@forgeax/engine-render';
+import { GlyphText, Tilemap } from '@forgeax/engine-render/authoring';
+
+void Camera;
+void visibilityStateFromU32(0);
+void GlyphText;
+void Tilemap;
+
+const publicToneModes: readonly Tonemap[] = [
+  'none',
+  'reinhard-extended',
+  'linear',
+  'reinhard',
+  'cineon',
+  'aces-filmic',
+  'agx',
+  'neutral',
+];
+void publicToneModes;
+
+// M6 red snapshot: the public frame contract is receipt-bound and lease-bound.
+declare const lease: RenderWorldLease;
+declare const receipt: FrameReceipt;
+declare const request: FrameObservationRequest;
+const drawRequest: RenderFrameInput = {
+  leases: [lease],
+  camera: { lease },
+  environment: { lease },
+};
+void receipt;
+void request;
+void drawRequest;
+const alive: RendererState = 'alive';
+void alive;
+
+declare const inspection: RenderInspection;
+const backendKind: RenderInspection['capabilities']['backendKind'] =
+  inspection.capabilities.backendKind;
+void backendKind;
+
+// M6 red snapshot: the root must expose the four target concepts without
+// reopening the old renderer/device/store/readback surface.
+type _RootKeys = keyof typeof import('@forgeax/engine-render');
+type _RendererLegacyKeys = Extract<
+  keyof import('../render-contract').Renderer,
+  | 'ready'
+  | 'onError'
+  | 'device'
+  | 'store'
+  | 'readPixels'
+  | 'observeCurrentFrame'
+  | 'installRenderFeature'
+  | 'uninstallRenderFeature'
+>;
+const noLegacyRendererKeys: never = null as unknown as _RendererLegacyKeys;
+void noLegacyRendererKeys;
+type _ForbiddenRootKeys = Extract<
+  _RootKeys,
+  | 'RendererCreateOptions'
+  | 'RendererBackend'
+  | 'RendererError'
+  | 'FrameObservation'
+  | 'FrameObservationOptions'
+  | 'TONEMAP_POST_PROCESS_ID'
+>;
+const noBroadLegacyRoot: never = null as unknown as _ForbiddenRootKeys;
+void noBroadLegacyRoot;
+
+type _ForbiddenRendererIdentity = Extract<
+  keyof import('../render-contract').Renderer,
+  'projectionLedger' | 'registerPipeline' | 'installPipeline' | 'postProcess' | 'debugReadback'
+>;
+const noLegacyRendererIdentity: never = null as unknown as _ForbiddenRendererIdentity;
+void noLegacyRendererIdentity;
+
+// The host assembly factory belongs to engine-runtime, not the render barrel.
+// @ts-expect-error createRenderer is not a public render export
+type _NoPublicCreateRenderer = typeof import('@forgeax/engine-render')['createRenderer'];
+
+// Optional authoring and frame machinery must not silently re-enter the root.
+// @ts-expect-error GlyphText is authoring-only
+type _NoPublicGlyphText = typeof import('@forgeax/engine-render')['GlyphText'];
+// @ts-expect-error Tilemap is authoring-only
+type _NoPublicTilemap = typeof import('@forgeax/engine-render')['Tilemap'];
+// @ts-expect-error extract stages are package-internal
+type _NoPublicExtractFrame = typeof import('@forgeax/engine-render')['extractFrame'];

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

@@ -0,0 +1,107 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { RecoverError, type RecoverErrorCode } from '../errors/recover';
+
+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 and order', () => {
+    expect(expectedCodes).toHaveLength(4);
+    expect(new Set(expectedCodes).size).toBe(4);
+    expectTypeOf<RecoverErrorCode>().toEqualTypeOf<(typeof expectedCodes)[number]>();
+  });
+
+  it('preserves all twelve diagnostics byte-for-byte', () => {
+    for (const { code, expected, hint, message } of evidence) {
+      const error = new RecoverError(code);
+      expect(error.code).toBe(code);
+      expect(error.expected).toBe(expected);
+      expect(error.hint).toBe(hint);
+      expect(error.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.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-error-code-owner.test-d.ts

@@ -0,0 +1,116 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  ObservationUnavailableDetail,
+  ObservationUnavailableReason,
+  RenderError,
+  RenderErrorCode,
+} from '../errors/render';
+import { ObservationUnavailableError, RenderFeatureStageFailedError } from '../errors/render';
+import type { RenderFeatureErrorCode, RenderFeatureStageFailedDetail } from '../features/types';
+import type { RenderFeatureRecovery, RenderFeatureStage } from '../features/vocabulary';
+import type {
+  RenderError as PublicRenderError,
+  RenderErrorCode as PublicRenderErrorCode,
+} from '../index';
+
+const expectedCodes = [
+  'lifecycle-construction-failed',
+  'world-lease-invalid',
+  'frame-input-invalid',
+  'scene-projection-failed',
+  'asset-binding-failed',
+  'feature-plan-failed',
+  'graph-build-failed',
+  'device-operation-failed',
+  'surface-unavailable',
+  'renderer-state-invalid',
+  'recovery-failed',
+  'cleanup-failed',
+  'frame-receipt-stale',
+  'renderer-contract-failed',
+  'observation-unavailable',
+  'shadow-invalid-config',
+  'equirect-projection-failed',
+  'hdrp-light-budget-exceeded',
+  'hdrp-index-list-overflow',
+  'hdrp-deferred-caps-insufficient',
+  'point-shadow-atlas-uninitialized',
+  'point-shadow-atlas-bounds-violation',
+  'video-upload-unsupported',
+  'vertex-storage-buffer-unavailable',
+  'vertex-color-variant-conflict',
+  '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',
+  'points-lines-invalid-style',
+  'points-lines-topology-mismatch',
+  'points-lines-style-unsupported',
+  'points-lines-material-unsupported',
+  'points-lines-budget-exceeded',
+  'points-lines-prepare-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, 'plan', '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,139 @@
+import { describe, expectTypeOf, it } from 'vitest';
+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'];
+
+describe('render error detail aliases derive from their code resolvers', () => {
+  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 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 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,110 @@
+import type {
+  RenderError,
+  RenderErrorCode,
+  RenderFeatureCapabilityMissingError,
+  RenderFeatureDrawRecordingFailedError,
+  RenderFeaturePassOrderConflictError,
+  RenderFeaturePreparationFailedError,
+  RenderFeaturePreparedStateMismatchError,
+  RenderFeatureRegistrationConflictError,
+  RenderFeatureStageFailedError,
+  VertexColorVariantConflictError,
+} from '../errors/render';
+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);
+    case 'vertex-color-variant-conflict':
+      return code;
+    case 'points-lines-invalid-style':
+      return code;
+    case 'points-lines-topology-mismatch':
+      return code;
+    case 'points-lines-style-unsupported':
+      return code;
+    case 'points-lines-material-unsupported':
+      return code;
+    case 'points-lines-budget-exceeded':
+      return code;
+    case 'points-lines-prepare-failed':
+      return 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}`;
+    }
+    case 'vertex-color-variant-conflict': {
+      const typed: VertexColorVariantConflictError = error;
+      return `${typed.detail.authoredValue}:${typed.detail.projected}`;
+    }
+    case 'points-lines-invalid-style':
+    case 'points-lines-topology-mismatch':
+    case 'points-lines-style-unsupported':
+    case 'points-lines-material-unsupported':
+    case 'points-lines-budget-exceeded':
+    case 'points-lines-prepare-failed':
+      return error.expected;
+    default:
+      return error.expected;
+  }
+}
+
+void renderCodeLabel;
+void renderFeatureErrorLabel;

package/src/__tests__/render-feature-assembly.test-d.ts

@@ -0,0 +1,43 @@
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeature, RenderFeaturePlanContext } from '../features/types';
+import type { RendererOptions } from '../render-contract';
+
+type BoundsFrame = {
+  readonly visibleCount: number;
+};
+
+type OverlayFrame = {
+  readonly layer: 'overlay';
+};
+
+const boundsFeature = {
+  identity: 'test.bounds',
+  extract({ owner }) {
+    return ok({ visibleCount: owner });
+  },
+  plan(data: BoundsFrame, context: RenderFeaturePlanContext) {
+    const count: number = data.visibleCount;
+    void count;
+    void context;
+    return ok({ resources: [], passes: [] });
+  },
+} satisfies RenderFeature<BoundsFrame>;
+
+const overlayFeature = {
+  identity: 'test.overlay',
+  extract() {
+    return ok({ layer: 'overlay' as const });
+  },
+  plan(data: OverlayFrame, context: RenderFeaturePlanContext) {
+    const layer: 'overlay' = data.layer;
+    void layer;
+    void context;
+    return ok({ resources: [], passes: [] });
+  },
+} satisfies RenderFeature<OverlayFrame>;
+
+const rendererOptions = {
+  features: [boundsFeature, overlayFeature],
+} satisfies RendererOptions;
+
+void rendererOptions;

package/src/__tests__/render-feature-context.test-d.ts

@@ -0,0 +1,57 @@
+import type { World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeature } from '../features/types';
+
+type Frame = {
+  readonly count: number;
+};
+
+const feature = {
+  identity: 'synthetic.context-boundary',
+  extract(context) {
+    const worlds: readonly World[] = context.worlds;
+    const owner: number = context.owner;
+    const frameNumber: number = context.frameNumber;
+    void worlds;
+    void owner;
+    void frameNumber;
+
+    // @ts-expect-error extract must not receive a prepare-stage runtime surface
+    context.runtime;
+    // @ts-expect-error extract must not receive a GPU command encoder
+    context.encoder;
+    return ok({ count: worlds.length });
+  },
+  plan(data, context) {
+    const count: number = data.count;
+    const caps = context.caps;
+    const targets = context.targets;
+    const frame = context.frame;
+    const generation = context.generation;
+    void count;
+    void caps;
+    void targets;
+    void frame;
+    void generation;
+
+    // @ts-expect-error plan must not receive the live World collection
+    context.worlds;
+    // @ts-expect-error plan must not receive the complete pipeline context
+    context.pipeline;
+    // @ts-expect-error plan must not receive a raw device
+    context.device;
+    // @ts-expect-error plan must not expose a queue
+    context.queue;
+    // @ts-expect-error plan must not expose submit commands
+    context.submit;
+    // @ts-expect-error plan must not expose a command encoder
+    context.encoder;
+    // @ts-expect-error plan descriptors replace staging callbacks
+    context.staging;
+    // @ts-expect-error plan descriptors replace prepared graphics callbacks
+    context.graphics;
+    return ok({ resources: [], passes: [] });
+  },
+} satisfies RenderFeature<Frame>;
+
+void feature;