@forgeax/engine-render 0.1.21 → 0.1.24

package/src/reflection/inspection.ts

@@ -0,0 +1,67 @@
+import type {
+  ReflectionFallbackFailureStage,
+  ReflectionFallbackInspection,
+  ReflectionFallbackReceipt,
+  ReflectionFallbackRecoveryAction,
+} from '../inspection-types';
+
+export interface ReflectionFallbackFailureInput {
+  readonly stage: ReflectionFallbackFailureStage;
+  readonly code: string;
+  readonly expected: string;
+  readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+function recoveryFor(
+  receipt: ReflectionFallbackReceipt,
+  failure?: ReflectionFallbackFailureInput,
+): ReflectionFallbackRecoveryAction {
+  if (failure !== undefined) {
+    const code = failure.code.toLowerCase();
+    if (code.includes('device') || code.includes('format') || code.includes('capability')) {
+      return 'rebuild';
+    }
+    if (failure.stage === 'prepare' || failure.stage === 'filter') return 'recapture';
+    if (failure.stage === 'build' || failure.stage === 'encode') return 'rebuild';
+    if (failure.stage === 'finish' || failure.stage === 'submit') return 'retry';
+    // Completion failures may still retain a source-identical committed row;
+    // use it as LKG, otherwise retry the producer completion.
+    if (failure.stage === 'completion') {
+      if (receipt.source === 'probe' && (receipt.state === 'active' || receipt.state === 'lkg')) {
+        return 'use-LKG';
+      }
+      if (
+        receipt.source === 'skylight' &&
+        (receipt.state === 'active' || receipt.state === 'lkg')
+      ) {
+        return 'use-Skylight';
+      }
+      if (receipt.source === 'neutral' && receipt.state === 'neutral') return 'use-neutral';
+      return 'retry';
+    }
+  }
+  if (receipt.source === 'probe' && (receipt.state === 'active' || receipt.state === 'lkg')) {
+    return 'use-LKG';
+  }
+  if (receipt.source === 'skylight' || receipt.state === 'lkg') return 'use-Skylight';
+  return 'use-neutral';
+}
+
+/** Projects producer state and the latest closed failure into detached facts. */
+export function inspectReflectionFallback(
+  receipt: ReflectionFallbackReceipt,
+  failure?: ReflectionFallbackFailureInput,
+): ReflectionFallbackInspection {
+  return {
+    receipt,
+    recoveryAction: recoveryFor(receipt, failure),
+    ...(failure === undefined
+      ? {}
+      : {
+          failureStage: failure.stage,
+          failureCode: failure.code,
+          expected: failure.expected,
+          ...(failure.detail === undefined ? {} : { detail: failure.detail }),
+        }),
+  };
+}

package/src/reflection/projection.ts

@@ -157,6 +157,199 @@ export interface SkylightSelection {
 
 export type ReflectionProbeSelectionResult = ReflectionProbeSelection | SkylightSelection;
 
+export type ReflectionFallbackSource = 'probe' | 'skylight' | 'neutral';
+
+export interface ReflectionFallbackProjectionInput {
+  /** Stable renderable identity used to join the main-pass projection. */
+  readonly renderableKey?: string;
+  /** Stable producer source identity; never a live GPU handle. */
+  readonly sourceKey?: string;
+  readonly source: ReflectionFallbackSource;
+  readonly coverage: number;
+  readonly extent?: readonly [number, number, number];
+  readonly linearHdr: readonly [number, number, number, number];
+  readonly brdfSignature: string;
+}
+
+export interface ReflectionFallbackProjection extends ReflectionFallbackProjectionInput {
+  readonly source: ReflectionFallbackSource;
+}
+
+export type ReflectionFallbackMismatchKind = 'source' | 'coverage' | 'extent' | 'brdf';
+
+export interface ReflectionFallbackMismatch {
+  readonly code:
+    | 'reflection-fallback-source-mismatch'
+    | 'reflection-fallback-coverage-mismatch'
+    | 'reflection-fallback-extent-mismatch'
+    | 'reflection-fallback-brdf-mismatch';
+  readonly expected: string;
+  readonly actual: string;
+}
+
+export interface ReflectionFallbackInputInvalid {
+  readonly code: 'reflection-fallback-input-invalid';
+  readonly field: string;
+  readonly expected: string;
+}
+
+export type ReflectionFallbackProjectionResult =
+  | { readonly ok: true; readonly value: ReflectionFallbackProjection }
+  | { readonly ok: false; readonly error: ReflectionFallbackInputInvalid };
+
+export function resolveReflectionFallbackSource(
+  selection: ReflectionProbeSelectionResult,
+  probeReady: boolean,
+  skylightAvailable = true,
+): ReflectionFallbackSource {
+  if (selection.kind === 'probe' && probeReady) return 'probe';
+  // An unavailable probe follows the producer recovery order: use the active
+  // Skylight when one exists, then the producer-owned neutral zero. Returning
+  // neutral directly here would make the main Standard lighting lane and the
+  // detached fallback projection disagree.
+  if (skylightAvailable) return 'skylight';
+  return 'neutral';
+}
+
+export function reflectionFallbackCoverage(
+  source: ReflectionFallbackSource,
+  fact: ReflectionProbeFact | undefined,
+  selection: ReflectionProbeSelectionResult,
+): number {
+  if (source === 'neutral') return 0;
+  if (source === 'skylight') return 1;
+  if (fact === undefined || selection.kind !== 'probe') return 0;
+  const normalized = Math.sqrt(Math.max(0, selection.normalizedDistance));
+  return Math.max(0, Math.min(1, 1 - normalized / Math.sqrt(3)));
+}
+
+export function reflectionFallbackSourceKey(
+  source: ReflectionFallbackSource,
+  selection: ReflectionProbeSelectionResult,
+  skylight?: { readonly entityHandle: number; readonly equirectHandle: number },
+): string {
+  if (source === 'probe' && selection.kind === 'probe') {
+    return `probe:${selection.worldId}:${selection.entityKey}`;
+  }
+  if (source === 'skylight' && skylight !== undefined) {
+    return `skylight:${skylight.entityHandle}:${skylight.equirectHandle}`;
+  }
+  return source;
+}
+
+export function reflectionFallbackProjectionSignature(
+  input: ReflectionFallbackProjectionInput,
+): string {
+  return JSON.stringify({
+    renderableKey: input.renderableKey,
+    sourceKey: input.sourceKey,
+    source: input.source,
+    coverage: input.coverage,
+    extent: input.extent,
+    brdfSignature: input.brdfSignature,
+  });
+}
+
+export function deriveReflectionFallbackProjection(
+  input: ReflectionFallbackProjectionInput,
+): ReflectionFallbackProjectionResult {
+  if (!Number.isFinite(input.coverage) || input.coverage < 0 || input.coverage > 1) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-fallback-input-invalid',
+        field: 'coverage',
+        expected: 'a finite number between zero and one',
+      },
+    };
+  }
+  if (input.extent?.some((value) => !Number.isFinite(value) || value <= 0)) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-fallback-input-invalid',
+        field: 'extent',
+        expected: 'three finite numbers greater than zero',
+      },
+    };
+  }
+  if (input.linearHdr.some((value) => !Number.isFinite(value))) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-fallback-input-invalid',
+        field: 'linearHdr',
+        expected: 'four finite linear HDR values',
+      },
+    };
+  }
+  if (input.brdfSignature.length === 0) {
+    return {
+      ok: false,
+      error: {
+        code: 'reflection-fallback-input-invalid',
+        field: 'brdfSignature',
+        expected: 'a non-empty BRDF signature',
+      },
+    };
+  }
+  const linearHdr = input.source === 'neutral' ? ([0, 0, 0, 0] as const) : [...input.linearHdr];
+  return {
+    ok: true,
+    value: Object.freeze({
+      ...(input.renderableKey === undefined ? {} : { renderableKey: input.renderableKey }),
+      ...(input.sourceKey === undefined ? {} : { sourceKey: input.sourceKey }),
+      source: input.source,
+      coverage: input.coverage,
+      ...(input.extent === undefined
+        ? {}
+        : {
+            extent: Object.freeze([...input.extent]) as readonly [number, number, number],
+          }),
+      linearHdr: Object.freeze(linearHdr) as ReflectionFallbackProjection['linearHdr'],
+      brdfSignature: input.brdfSignature,
+    }),
+  };
+}
+
+export function validateReflectionFallbackCompatibility(
+  expected: ReflectionFallbackProjectionInput,
+  actual: ReflectionFallbackProjectionInput,
+): { readonly ok: true } | { readonly ok: false; readonly error: ReflectionFallbackMismatch } {
+  const mismatch = (
+    kind: ReflectionFallbackMismatchKind,
+    expectedValue: string,
+    actualValue: string,
+  ): { readonly ok: false; readonly error: ReflectionFallbackMismatch } => ({
+    ok: false,
+    error: {
+      code: `reflection-fallback-${kind}-mismatch` as ReflectionFallbackMismatch['code'],
+      expected: expectedValue,
+      actual: actualValue,
+    },
+  });
+  if (expected.source !== actual.source) {
+    return mismatch('source', expected.source, actual.source);
+  }
+  if (expected.coverage !== actual.coverage) {
+    return mismatch('coverage', String(expected.coverage), String(actual.coverage));
+  }
+  const expectedExtent = expected.extent;
+  const actualExtent = actual.extent;
+  if (
+    (expectedExtent === undefined && actualExtent !== undefined) ||
+    (expectedExtent !== undefined &&
+      (actualExtent === undefined ||
+        expectedExtent.some((value, index) => value !== actualExtent[index])))
+  ) {
+    return mismatch('extent', JSON.stringify(expectedExtent), JSON.stringify(actualExtent));
+  }
+  if (expected.brdfSignature !== actual.brdfSignature) {
+    return mismatch('brdf', expected.brdfSignature, actual.brdfSignature);
+  }
+  return { ok: true };
+}
+
 function contains(fact: ReflectionProbeFact, point: readonly [number, number, number]): boolean {
   return fact.halfExtents.every((extent, axis) => {
     const center = fact.center[axis] ?? 0;
@@ -222,6 +415,8 @@ export function selectReflectionProbe(
 export interface ReflectionProbePrimitive {
   readonly worldId: number;
   readonly entityKey: number;
+  /** Main-pass renderable key; world/entity is retained as the compatibility fallback. */
+  readonly renderableKey?: string;
   readonly center: readonly [number, number, number];
 }
 
@@ -257,7 +452,7 @@ export class ReflectionProbeProjection {
     this.selected = new Map();
     for (const primitive of primitives) {
       this.selected.set(
-        primitiveKey(primitive.worldId, primitive.entityKey),
+        primitive.renderableKey ?? primitiveKey(primitive.worldId, primitive.entityKey),
         selectReflectionProbe(nextFacts, primitive.center),
       );
     }