@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,245 @@
+// feat-20260704-runtime-tier1-decomposition M2 / w13 (AC-07 c): render cluster
+// exhaustive type-level regression guard. Split out of the former
+// hdrp-error-exhaustive.test-d.ts, which exhaustively switched the whole
+// RuntimeErrorCode union; after the D-3 decomposition each cluster owns its own
+// exhaustive assertion.
+//
+// If any RenderErrorCode member is missing from the switch below, the
+// `const exhaustive: never = code` line stops compiling (tsc red). A `default`
+// arm would defeat the exhaustiveness check, so there is none.
+//
+// This file is *.test-d.ts: vitest typecheck validates it; it is not executed.
+
+import type { RenderError, RenderErrorCode } from '@forgeax/engine-render/internal';
+
+function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
+  switch (code) {
+    case 'fog-owner-conflict':
+      return code;
+    case 'fog-parameters-invalid':
+      return code;
+    case 'observation-unavailable':
+      return code;
+    case 'taa-caps-insufficient':
+      return code;
+    case 'temporal-unsupported':
+      return code;
+    case 'atmosphere-parameter-invalid':
+      return code;
+    case 'atmosphere-cardinality-invalid':
+      return code;
+    case 'atmosphere-sun-missing':
+      return code;
+    case 'environment-source-conflict':
+      return code;
+    case 'atmosphere-caps-insufficient':
+      return code;
+    case 'atmosphere-producer-failed':
+      return code;
+    case 'shadow-invalid-config':
+      return code;
+    case 'equirect-projection-failed':
+      return code;
+    case 'hdrp-caps-insufficient':
+      return code;
+    case 'hdrp-light-budget-exceeded':
+      return code;
+    case 'hdrp-index-list-overflow':
+      return code;
+    case 'hdrp-deferred-caps-insufficient':
+      return code;
+    case 'gbuffer-rt-alloc-failed':
+      return code;
+    case 'gbuffer-attachment-count-mismatch':
+      return code;
+    case 'point-shadow-atlas-uninitialized':
+      return code;
+    case 'point-shadow-atlas-bounds-violation':
+      return code;
+    case 'video-upload-unsupported':
+      return code;
+    case 'vertex-storage-buffer-unavailable':
+      return code;
+    case 'skin-palette-overflow':
+      return code;
+    case 'skin-material-mismatch':
+      return code;
+    case 'material-skin-attr-missing':
+      return 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;
+    default: {
+      const exhaustive: never = code;
+      return exhaustive;
+    }
+  }
+}
+
+function narrowRenderError(err: RenderError): void {
+  switch (err.code) {
+    case 'fog-owner-conflict':
+      void err.detail.resourceOwner;
+      void err.detail.entities;
+      void err.detail.omitted;
+      break;
+    case 'fog-parameters-invalid':
+      void err.detail.entity;
+      void err.detail.field;
+      void err.detail.expected;
+      void err.detail.actual;
+      break;
+    case 'observation-unavailable':
+      void err.detail.reason;
+      void err.detail.recovery;
+      break;
+    case 'taa-caps-insufficient':
+      void err.detail.rgba16floatRenderable;
+      void err.detail.maxColorAttachments;
+      break;
+    case 'temporal-unsupported':
+      void err.detail.reason;
+      void err.detail.actual;
+      break;
+    case 'atmosphere-parameter-invalid':
+      void err.detail.field;
+      void err.detail.value;
+      void err.detail.min;
+      void err.detail.max;
+      void err.detail.minExclusive;
+      break;
+    case 'atmosphere-cardinality-invalid':
+      void err.detail.count;
+      void err.detail.max;
+      void err.detail.entities;
+      break;
+    case 'atmosphere-sun-missing':
+      void err.detail.atmosphereEntity;
+      break;
+    case 'environment-source-conflict':
+      void err.detail.atmosphereEntities;
+      void err.detail.imageEntities;
+      break;
+    case 'atmosphere-caps-insufficient':
+      void err.detail.capability;
+      void err.detail.actual;
+      void err.detail.required;
+      break;
+    case 'atmosphere-producer-failed':
+      void err.detail.stage;
+      void err.detail.reason;
+      void err.detail.generation;
+      break;
+    case 'shadow-invalid-config':
+      void err.detail.field; // string
+      void err.detail.value; // number
+      break;
+    case 'equirect-projection-failed':
+      void err.detail.handle; // number
+      break;
+    case 'hdrp-caps-insufficient':
+      void err.detail.capName; // string
+      void err.detail.actual; // number
+      void err.detail.required; // number
+      break;
+    case 'hdrp-light-budget-exceeded':
+      void err.detail.actual; // number
+      void err.detail.budget; // number
+      break;
+    case 'hdrp-index-list-overflow':
+      void err.detail.actual; // number
+      void err.detail.capacity; // number
+      break;
+    case 'hdrp-deferred-caps-insufficient':
+      void err.detail.actual; // number
+      void err.detail.expected; // number
+      break;
+    case 'gbuffer-rt-alloc-failed':
+      void err.detail.attachmentIndex; // number
+      void err.detail.requestedBytes; // number
+      break;
+    case 'gbuffer-attachment-count-mismatch':
+      void err.detail.actual; // number
+      void err.detail.expected; // number
+      break;
+    case 'point-shadow-atlas-uninitialized':
+      // No detail on this class.
+      break;
+    case 'point-shadow-atlas-bounds-violation':
+      void err.detail.axis; // 'layer' | 'face'
+      void err.detail.value; // number
+      void err.detail.max; // number
+      break;
+    case 'video-upload-unsupported':
+      // No detail on this class.
+      break;
+    case 'vertex-storage-buffer-unavailable':
+      // No detail on this class.
+      break;
+    case 'skin-palette-overflow':
+      void err.detail.requestedBytes;
+      void err.detail.limit;
+      break;
+    case 'skin-material-mismatch':
+      void err.detail.entity;
+      void err.detail.actualShader;
+      break;
+    case 'material-skin-attr-missing':
+      void err.detail.entity;
+      void err.detail.missing;
+      break;
+    case 'render-feature-registration-conflict':
+      void err.detail.featureIdentity;
+      void err.detail.conflictingOrder;
+      break;
+    case 'render-feature-stage-failed':
+      void err.detail.featureIdentity;
+      void err.detail.stage;
+      break;
+    case 'render-feature-capability-missing':
+      void err.detail.featureIdentity;
+      void err.detail.capability;
+      break;
+    case 'render-feature-pass-order-conflict':
+      void err.detail.featureIdentity;
+      void err.detail.passIdentity;
+      break;
+    case 'render-feature-preparation-failed':
+      void err.detail.featureIdentity;
+      void err.detail.resourceName;
+      void err.detail.operation;
+      break;
+    case 'render-feature-prepared-state-mismatch':
+      void err.detail.featureIdentity;
+      void err.detail.reason;
+      void err.detail.operation;
+      break;
+    case 'render-feature-draw-recording-failed':
+      void err.detail.featureIdentity;
+      void err.detail.backendReason;
+      void err.detail.operation;
+      break;
+    default: {
+      const exhaustive: never = err;
+      void exhaustive;
+    }
+  }
+}
+
+export type _RenderExhaustiveChecks = {
+  /** @internal forces tsc to type-check the exhaustive switch on RenderErrorCode. */
+  _check: ReturnType<typeof exhaustiveSwitchOnRenderCode>;
+  /** @internal forces tsc to type-check the RenderError detail narrowing. */
+  _narrow: typeof narrowRenderError;
+};

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

@@ -0,0 +1,28 @@
+import type { RenderFeature } from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+import { createRenderer } from '../createRenderer';
+
+type TestFrameData = {
+  readonly visibleCount: number;
+};
+
+const feature = {
+  identity: 'test.runtime-assembly',
+  extract({ owner }) {
+    return ok({ visibleCount: owner });
+  },
+  prepare(data: TestFrameData) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+  contribute(data: TestFrameData) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<TestFrameData>;
+
+declare const canvas: HTMLCanvasElement;
+
+void createRenderer(canvas, { features: [feature] });

package/src/__tests__/render-feature-prepared-graphics-docs.unit.test.ts

@@ -0,0 +1,124 @@
+import {
+  type HealthSnapshot,
+  RecoverError,
+  RenderFeatureCapabilityMissingError,
+  type RenderFeatureErrorDescriptor,
+  RenderFeatureStageFailedError,
+  type RenderFeatureStatus,
+} from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+interface RecoveryRow {
+  readonly status: RenderFeatureStatus;
+  readonly code: string;
+  readonly detail: string;
+  readonly action: string;
+  readonly error: RenderFeatureErrorDescriptor | undefined;
+}
+
+function featureDetail(error: RenderFeatureErrorDescriptor): string {
+  switch (error.code) {
+    case 'render-feature-registration-conflict':
+      return `${error.detail.featureIdentity}:${error.detail.conflictingOrder}`;
+    case 'render-feature-stage-failed':
+      return `${error.detail.stage}:${error.detail.recovery}`;
+    case 'render-feature-capability-missing':
+      return error.detail.capability;
+    case 'render-feature-pass-order-conflict':
+      return `${error.detail.passIdentity}:${error.detail.dependencyIdentity}`;
+    case 'render-feature-preparation-failed':
+      return `${error.detail.resourceKind}:${error.detail.reason}`;
+    case 'render-feature-prepared-state-mismatch':
+      return `${error.detail.resourceKind}:${error.detail.reason}`;
+    case 'render-feature-draw-recording-failed':
+      return `${error.detail.resourceKind}:${error.detail.backendReason}`;
+  }
+}
+
+function healthDetail(snapshot: HealthSnapshot): string {
+  switch (snapshot.reason) {
+    case 'alive':
+      return 'renderer is ready';
+    case 'device-lost':
+      return `${snapshot.detail.lostReason}:${snapshot.detail.message.length}`;
+    case 'internal-fault':
+      return `internal-fault:${snapshot.detail.message.length}`;
+  }
+}
+
+function recoveryMatrix(): readonly RecoveryRow[] {
+  const failed = new RenderFeatureStageFailedError(
+    'docs.prepared-graphics',
+    0,
+    'prepare',
+    'next-frame',
+  );
+  const disabled = new RenderFeatureCapabilityMissingError('docs.prepared-graphics', 0, 'compute');
+  const disposed = new RenderFeatureStageFailedError(
+    'docs.prepared-graphics',
+    0,
+    'dispose',
+    'registration',
+  );
+  return [
+    {
+      status: 'active',
+      code: 'none',
+      detail: 'no error',
+      action: 'continue renderer.draw(worlds, { cameraOwner: 0, resourceOwner: 0 })',
+      error: undefined,
+    },
+    {
+      status: 'failed',
+      code: failed.code,
+      detail: featureDetail(failed),
+      action: 'fix feature data and retry on the next frame',
+      error: failed,
+    },
+    {
+      status: 'disabled',
+      code: disabled.code,
+      detail: featureDetail(disabled),
+      action: 'disable the feature or use a device with the capability',
+      error: disabled,
+    },
+    {
+      status: 'disposed',
+      code: disposed.code,
+      detail: featureDetail(disposed),
+      action: 'create a new renderer and feature registration',
+      error: disposed,
+    },
+  ];
+}
+
+describe('runtime prepared graphics recovery documentation', () => {
+  it('keeps every feature lifecycle state tied to a structured action', () => {
+    const rows = recoveryMatrix();
+    expect(rows.map((row) => row.status)).toEqual(['active', 'failed', 'disabled', 'disposed']);
+    for (const row of rows) {
+      expect(row.code).not.toBe('message');
+      expect(row.detail).not.toBe('');
+      expect(row.action).not.toBe('');
+      if (row.error !== undefined) {
+        expect(row.code).toBe(row.error.code);
+        expect(row.error.expected).not.toBe('');
+        expect(row.error.hint).not.toBe('');
+      }
+    }
+  });
+
+  it('keeps device-loss recovery aligned with generated health and recover declarations', () => {
+    const health: HealthSnapshot = {
+      reason: 'device-lost',
+      detail: { lostReason: 'unknown', message: 'device reset' },
+      recoverable: true,
+    };
+    const recoveryError = new RecoverError('recover-adapter-unavailable');
+    expect(healthDetail(health)).toBe('unknown:12');
+    expect(health.recoverable).toBe(true);
+    expect(recoveryError.code).toBe('recover-adapter-unavailable');
+    expect(recoveryError.expected).toContain('requestAdapter');
+    expect(recoveryError.hint).toContain('retry recover()');
+  });
+});