@forgeax/engine-render 0.1.21 → 0.1.24

package/src/assembly/renderer-facade.ts

@@ -0,0 +1,342 @@
+// Public renderer facade and profile validation.
+// This module narrows the lifetime-heavy host implementation to the stable
+// lease/receipt contract and owns the profile/error projection helpers.
+
+import { err, ok, type RhiError } from '@forgeax/engine-rhi';
+import { type RecoverFailure, RecoveryFailedError } from '../errors/recover';
+import {
+  type RenderError,
+  RendererContractFailureError,
+  type RendererOperationCause,
+  RendererOperationError,
+} from '../errors/render';
+import {
+  STANDARD_LIGHT_COUNTS,
+  STANDARD_PIPELINE_ID,
+  STANDARD_POST_STAGE_NAMES,
+} from '../pipeline/standard-profile';
+import type {
+  Renderer,
+  RendererError,
+  RendererEventListener,
+  RendererState,
+  RenderInspection,
+  RenderProfile,
+  RenderResult,
+} from '../render-contract';
+import type { RendererHostImplementation } from './host-contract';
+import { createRendererLifecycle, isRendererStateOperational } from './renderer-lifecycle';
+
+/** Narrow the concrete host to the lease/receipt-only public contract. */
+export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
+  const listeners = new Set<RendererEventListener>();
+  const lifecycle = createRendererLifecycle(renderer.inspect().state);
+  let disposed = lifecycle.state() === 'disposed';
+  let recoverInFlight: Promise<RenderResult<void, RenderError>> | undefined;
+
+  const emit = (event: Parameters<RendererEventListener>[0]): void => {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch (cause) {
+        console.error('[Renderer.subscribe] listener threw:', cause);
+      }
+    }
+  };
+  const transition = (next: RendererState): void => {
+    const previous = lifecycle.state();
+    if (previous === next || !lifecycle.transition(next)) return;
+    emit(Object.freeze({ kind: 'state-changed', previous, current: next }));
+  };
+  const eventError = (cause: RendererError): RenderError =>
+    cause instanceof RendererOperationError
+      ? cause
+      : new RendererOperationError('device-operation-failed', {
+          operation: 'renderer-event',
+          cause: structuredRendererCause(cause, 'renderer-event'),
+        });
+  const drawError = (cause: RhiError | RenderError): RenderError => {
+    if (cause instanceof RendererOperationError) return cause;
+    if (cause instanceof RendererContractFailureError) {
+      return new RendererOperationError('device-operation-failed', {
+        operation: 'draw',
+        cause: structuredRendererCause(cause, 'draw'),
+      });
+    }
+    return new RendererOperationError('device-operation-failed', {
+      operation: 'draw',
+      cause: structuredRendererCause(cause, 'draw'),
+    });
+  };
+  const offHostEvents = renderer.subscribeHostEvents((event) => {
+    if (event.kind === 'error') {
+      emit(Object.freeze({ kind: 'error', error: eventError(event.error) }));
+      return;
+    }
+    transition(
+      event.health.reason === 'device-lost'
+        ? 'device-lost'
+        : event.health.reason === 'internal-fault'
+          ? 'faulted'
+          : 'alive',
+    );
+  });
+
+  return {
+    attach: (world) => {
+      const result = renderer.attach(world);
+      return result.ok
+        ? result
+        : err(
+            new RendererOperationError('world-lease-invalid', {
+              operation: 'attach',
+              cause: result.error,
+            }),
+          );
+    },
+    createRenderTarget: (descriptor) => renderer.createRenderTarget(descriptor),
+    resizeRenderTarget: (target, descriptor) => renderer.resizeRenderTarget(target, descriptor),
+    createRenderTargetTextureSource: (target, options) =>
+      renderer.createRenderTargetTextureSource(target, options),
+    requestTargetReadback: (target, request) => renderer.requestTargetReadback(target, request),
+    destroyRenderTarget: (target) => renderer.destroyRenderTarget(target),
+    setProfile: (profile) => {
+      const state = lifecycle.state();
+      if (!isRendererStateOperational(state)) {
+        return err(
+          new RendererOperationError('renderer-state-invalid', {
+            operation: 'set-profile',
+            state,
+          }),
+        );
+      }
+      return renderer.setProfile(profile);
+    },
+    state: () => lifecycle.state(),
+    draw: (request) => {
+      const state = lifecycle.state();
+      if (!isRendererStateOperational(state)) {
+        return err(
+          new RendererOperationError('renderer-state-invalid', {
+            operation: 'draw',
+            state,
+          }),
+        );
+      }
+      const result = renderer.drawFrame(request);
+      if (!result.ok) return err(drawError(result.error));
+      emit(
+        Object.freeze({
+          kind: 'frame-submitted',
+          frameId: result.value.frameId,
+          deviceGeneration: result.value.deviceGeneration,
+        }),
+      );
+      return ok(result.value);
+    },
+    inspect: () => ({ ...renderer.inspect(), state: lifecycle.state() }),
+    observe: (receipt, request) => renderer.observe(receipt, request),
+    subscribe: (listener) => {
+      if (disposed) return () => undefined;
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    releaseSurface: () => {
+      const result = renderer.releaseSurface();
+      return result.ok
+        ? result
+        : err(
+            new RendererOperationError('surface-unavailable', {
+              operation: 'release-surface',
+              cause: result.error,
+            }),
+          );
+    },
+    restoreSurface: () => {
+      const result = renderer.restoreSurface();
+      return result.ok
+        ? result
+        : err(
+            new RendererOperationError('surface-unavailable', {
+              operation: 'restore-surface',
+              cause: result.error,
+            }),
+          );
+    },
+    recover: () => {
+      if (recoverInFlight !== undefined) return recoverInFlight;
+      const state = lifecycle.state();
+      if (state !== 'device-lost') {
+        return Promise.resolve(
+          err(
+            new RendererOperationError('renderer-state-invalid', {
+              operation: 'recover',
+              state,
+            }),
+          ),
+        );
+      }
+      transition('recovering');
+      recoverInFlight = renderer
+        .recover()
+        .then((result): RenderResult<void, RenderError> => {
+          if (!result.ok) {
+            const error = new RendererOperationError('recovery-failed', {
+              operation: 'recover',
+              ...projectRecoveryFailureDetail(result.error, renderer.inspect().recovery),
+              cause: structuredRendererCause(result.error, 'recover'),
+            });
+            emit(Object.freeze({ kind: 'error', error }));
+            return err(error);
+          }
+          return ok(undefined);
+        })
+        .finally(() => {
+          transition(renderer.inspect().state);
+          recoverInFlight = undefined;
+        });
+      return recoverInFlight;
+    },
+    dispose: async () => {
+      if (disposed) return ok(undefined);
+      const result = renderer.dispose();
+      if (!result.ok) emit(Object.freeze({ kind: 'error', error: result.error }));
+      disposed = true;
+      transition('disposed');
+      offHostEvents();
+      listeners.clear();
+      return result;
+    },
+  };
+}
+
+// ─── feat-20260520-directional-light-shadow-mapping M1c / w8 helpers ────────
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+export function toError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  return new Error(String(value));
+}
+
+export function structuredRendererCause(cause: unknown, operation: string): RendererOperationCause {
+  if (typeof cause === 'object' && cause !== null) {
+    const candidate = cause as Partial<RendererOperationCause>;
+    if (
+      typeof candidate.code === 'string' &&
+      typeof candidate.expected === 'string' &&
+      typeof candidate.hint === 'string'
+    ) {
+      return {
+        code: candidate.code,
+        expected: candidate.expected,
+        hint: candidate.hint,
+        ...(candidate.detail === undefined ? {} : { detail: candidate.detail }),
+      };
+    }
+  }
+  const contractFailure = new RendererContractFailureError(
+    'draw',
+    `${operation}: ${cause instanceof Error ? cause.message : String(cause)}`,
+  );
+  return {
+    code: contractFailure.code,
+    expected: contractFailure.expected,
+    hint: contractFailure.hint,
+    detail: contractFailure.detail,
+  };
+}
+
+function projectRecoveryFailureDetail(
+  failure: RecoverFailure,
+  inspection: RenderInspection['recovery'],
+): Omit<
+  import('../errors/render').RendererOperationDetailByCode['recovery-failed'],
+  'operation' | 'cause'
+> {
+  if (failure instanceof RecoveryFailedError) {
+    return {
+      phase: failure.detail.phase,
+      oldGeneration: failure.detail.oldGeneration,
+      candidateGeneration: failure.detail.candidateGeneration,
+      attempt: failure.detail.attempt,
+      elapsedMs: failure.detail.elapsedMs,
+      retryable: failure.detail.retryable,
+      guidance: failure.detail.guidance,
+      owner: failure.detail.owner,
+      resourceKind: failure.detail.resourceKind,
+      lastOutcome: failure.detail.lastOutcome,
+      rehydratedRoots: failure.detail.rehydratedRoots,
+      staleLossEvents: failure.detail.staleLossEvents,
+      cleanupFailures: Object.freeze(
+        failure.detail.cleanupFailures.map((cause: unknown) =>
+          structuredRendererCause(cause, 'recovery-cleanup'),
+        ),
+      ),
+    };
+  }
+  const lastOutcome = inspection.lastOutcome === 'disposed' ? 'disposed' : 'failed';
+  return {
+    phase: inspection.phase ?? 'cleanup',
+    oldGeneration: inspection.fromGeneration,
+    candidateGeneration: inspection.candidateGeneration,
+    attempt: inspection.attempt,
+    elapsedMs: inspection.elapsedMs,
+    retryable: false,
+    guidance: 'rebuild-renderer',
+    owner: inspection.failedOwner ?? 'renderer',
+    resourceKind: inspection.failedResourceKind ?? 'pipeline',
+    lastOutcome,
+    rehydratedRoots: inspection.rehydratedRoots,
+    staleLossEvents: inspection.staleLossEvents,
+    cleanupFailures: Object.freeze([]),
+  };
+}
+
+const RENDER_PROFILE_KEYS = new Set([
+  'pipelineId',
+  'lightCount',
+  'renderPath',
+  'shadows',
+  'pbr',
+  'ibl',
+  'ssao',
+  'postStages',
+]);
+
+export function validateRenderProfile(profile: RenderProfile): string | undefined {
+  if (typeof profile !== 'object' || profile === null) return 'RenderProfile must be a POD object';
+  const unknownKey = Object.keys(profile).find((key) => !RENDER_PROFILE_KEYS.has(key));
+  if (unknownKey !== undefined) return `RenderProfile contains unsupported field '${unknownKey}'`;
+  if (profile.pipelineId !== STANDARD_PIPELINE_ID) {
+    return `RenderProfile.pipelineId must be '${STANDARD_PIPELINE_ID}'`;
+  }
+  if (!STANDARD_LIGHT_COUNTS.some((count) => count === profile.lightCount)) {
+    return 'RenderProfile.lightCount must be 1, 32, or 256';
+  }
+  if (profile.renderPath !== 'forward' && profile.renderPath !== 'deferred') {
+    return "RenderProfile.renderPath must be 'forward' or 'deferred'";
+  }
+  if (profile.shadows !== 'off' && profile.shadows !== 'hard' && profile.shadows !== 'filtered') {
+    return "RenderProfile.shadows must be 'off', 'hard', or 'filtered'";
+  }
+  for (const field of ['pbr', 'ibl', 'ssao'] as const) {
+    if (typeof profile[field] !== 'boolean') return `RenderProfile.${field} must be boolean`;
+  }
+  const stages = STANDARD_POST_STAGE_NAMES;
+  if (
+    !Array.isArray(profile.postStages) ||
+    profile.postStages.length !== stages.length ||
+    stages.some((stage, index) => profile.postStages[index] !== stage)
+  ) {
+    return 'RenderProfile.postStages must preserve the Standard post stage order';
+  }
+  return undefined;
+}
+
+export function freezeRenderProfile(profile: RenderProfile): RenderProfile {
+  return Object.freeze({
+    ...profile,
+    postStages: Object.freeze([...profile.postStages]) as RenderProfile['postStages'],
+  });
+}

package/src/assembly/renderer-frame-transaction.ts

@@ -42,6 +42,45 @@ export interface RendererFrameTransactionSteps<T> {
   readonly submit: (candidate: T) => RendererFrameStageResult<void>;
   readonly commit: (candidate: T) => void;
   readonly abort?: (failure: RendererFrameStageFailure) => void;
+  readonly generationFence?: RendererGenerationFence;
+}
+
+export interface RendererGenerationFence {
+  readonly capturedGeneration: number;
+  readonly currentGeneration: () => number;
+}
+
+export type ContinuationKind = 'readback' | 'query' | 'mapAsync' | 'queue-completion';
+
+export interface ContinuationTerminationReason {
+  readonly code: 'device-lost' | 'disposed' | 'stale-generation';
+  readonly detail?: unknown;
+}
+
+export interface ContinuationTerminator {
+  terminate(reason: ContinuationTerminationReason): boolean;
+  promise(): Promise<ContinuationTerminationReason>;
+  isTerminated(): boolean;
+  guard(kind: ContinuationKind): boolean;
+}
+
+export function createContinuationTerminator(): ContinuationTerminator {
+  let termination: ContinuationTerminationReason | undefined;
+  let resolveTermination: ((reason: ContinuationTerminationReason) => void) | undefined;
+  const terminated = new Promise<ContinuationTerminationReason>((resolve) => {
+    resolveTermination = resolve;
+  });
+  return {
+    terminate: (reason) => {
+      if (termination !== undefined) return false;
+      termination = Object.freeze({ ...reason });
+      resolveTermination?.(termination);
+      return true;
+    },
+    promise: () => terminated,
+    isTerminated: () => termination !== undefined,
+    guard: () => termination === undefined,
+  };
 }
 
 /**
@@ -68,6 +107,12 @@ export function executeRendererFrameTransaction<T>(
   if (!executed.ok) return fail('execute');
   const finished = steps.finish(built.value);
   if (!finished.ok) return fail('finish');
+  if (
+    steps.generationFence !== undefined &&
+    steps.generationFence.currentGeneration() !== steps.generationFence.capturedGeneration
+  ) {
+    return fail('submit');
+  }
   const submitted = steps.submit(built.value);
   if (!submitted.ok) return fail('submit');
   steps.commit(built.value);

package/src/assembly/renderer-helpers.ts

@@ -0,0 +1,99 @@
+import type { Result, RhiCanvasContext, RhiDevice } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import type { RhiErrorListenerRegistry } from '../lifecycle';
+import { configureSurface, type PipelineState } from '../render-system';
+
+/** Minimum device-bound surface contract needed by lazy context configuration. */
+export interface RendererSurfaceInternals {
+  readonly device: RhiDevice;
+  readonly context: RhiCanvasContext;
+  readonly pack: {
+    readonly instrumentation?: {
+      readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+    };
+  };
+}
+
+export function wrapDisposeError(cause: unknown, step: string): RhiError {
+  if (cause instanceof RhiError) return cause;
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return new RhiError({
+    code: 'webgpu-runtime-error',
+    expected: `${step} completes during Renderer.dispose() without throwing`,
+    hint: `dispose sub-step '${step}' threw: ${message}; cascade continues to subsequent steps`,
+  });
+}
+
+export function ensureContextConfigured(
+  internals: RendererSurfaceInternals,
+  state: PipelineState,
+  errorRegistry: RhiErrorListenerRegistry,
+  context: RhiCanvasContext = internals.context,
+  device: RhiDevice = internals.device,
+): Result<void, RhiError> {
+  if (state.perPassResources.configured) return ok(undefined);
+  const configuredDevice = internals.pack.instrumentation?.resolveSurfaceDevice?.(device);
+  if (configuredDevice !== undefined && !configuredDevice.ok) {
+    errorRegistry.fire(configuredDevice.error);
+    return err(configuredDevice.error);
+  }
+  const cfgResult = configureSurface(
+    context,
+    configuredDevice?.value ?? device,
+    state.format,
+    state.colorAttachmentFormat,
+  );
+  if (!cfgResult.ok) {
+    errorRegistry.fire(cfgResult.error);
+    return err(cfgResult.error);
+  }
+  state.perPassResources.configured = true;
+  (globalThis as { __forgeaxSwapChainFormat?: GPUTextureFormat }).__forgeaxSwapChainFormat =
+    state.format;
+  return ok(undefined);
+}
+
+export function runShimSyncStep<T>(
+  fn: () => Result<T, RhiError>,
+  fallbackCode:
+    | 'shader-compile-failed'
+    | 'webgpu-runtime-error'
+    | 'queue-write-buffer-out-of-bounds',
+  expected: string,
+  hint: string,
+): Result<T, RhiError> {
+  try {
+    return fn();
+  } catch (caught) {
+    if (caught instanceof RhiError) return err(caught);
+    const detail = caught instanceof Error ? caught.message : String(caught);
+    return err(
+      new RhiError({
+        code: fallbackCode,
+        expected,
+        hint: `${hint} (cause: ${detail})`,
+      }),
+    );
+  }
+}
+
+export async function runShimStep<T>(
+  fn: () => Promise<Result<T, RhiError>>,
+  fallbackCode: 'shader-compile-failed' | 'webgpu-runtime-error',
+  expected: string,
+  hint: string,
+): Promise<Result<T, RhiError>> {
+  try {
+    return await fn();
+  } catch (caught) {
+    if (caught instanceof RhiError) return err(caught);
+    const detail = caught instanceof Error ? caught.message : String(caught);
+    return err(
+      new RhiError({
+        code: fallbackCode,
+        expected,
+        hint: `${hint} (cause: ${detail})`,
+      }),
+    );
+  }
+}

package/src/assembly/renderer-lifecycle.ts

@@ -4,3 +4,162 @@ import type { RendererState } from '../render-contract';
 export function isRendererStateOperational(state: RendererState): boolean {
   return state === 'alive';
 }
+
+export const RECOVERY_TOTAL_DEADLINE_MS = 20_000;
+export const RECOVERY_ADAPTER_DEADLINE_MS = 10_000;
+export const RECOVERY_DEVICE_DEADLINE_MS = 10_000;
+
+export const RECOVERY_PHASES = [
+  'quiesce',
+  'acquire-adapter',
+  'acquire-device',
+  'rehydrate',
+  'compile-graph',
+  'publish',
+  'cleanup',
+] as const;
+
+export type RecoveryPhase = (typeof RECOVERY_PHASES)[number];
+export type RecoveryGuidance = 'retry' | 'repair-owner' | 'rebuild-renderer';
+
+const RENDERER_STATES = [
+  'alive',
+  'device-lost',
+  'recovering',
+  'faulted',
+  'disposed',
+] as const satisfies readonly RendererState[];
+
+const ALLOWED_TRANSITIONS: Readonly<Record<RendererState, readonly RendererState[]>> = {
+  alive: ['device-lost', 'disposed'],
+  'device-lost': ['recovering', 'faulted', 'disposed'],
+  recovering: ['alive', 'device-lost', 'faulted', 'disposed'],
+  faulted: ['disposed'],
+  disposed: [],
+};
+
+export interface RendererLifecycle {
+  state(): RendererState;
+  transition(next: RendererState): boolean;
+  states(): readonly RendererState[];
+}
+
+export function createRendererLifecycle(initial: RendererState = 'alive'): RendererLifecycle {
+  if (!RENDERER_STATES.includes(initial)) {
+    throw new RangeError(`Unknown renderer lifecycle state: ${initial}`);
+  }
+  let current = initial;
+  return {
+    state: () => current,
+    transition: (next) => {
+      if (!ALLOWED_TRANSITIONS[current].includes(next)) return false;
+      current = next;
+      return true;
+    },
+    states: () => RENDERER_STATES,
+  };
+}
+
+export interface RecoveryDeadline {
+  readonly startedAt: number;
+  readonly totalDeadlineMs: number;
+  readonly adapterDeadlineMs: number;
+  readonly deviceDeadlineMs: number;
+  readonly deadlineAt: number;
+  beginDeviceAcquisition(now: number): void;
+  isValid(phase: RecoveryPhase, now: number): boolean;
+  elapsed(now: number): number;
+}
+
+export function createRecoveryDeadline(startedAt: number): RecoveryDeadline {
+  if (!Number.isFinite(startedAt)) throw new RangeError('Recovery deadline requires finite time.');
+  const deadlineAt = startedAt + RECOVERY_TOTAL_DEADLINE_MS;
+  let deviceAcquisitionStartedAt: number | undefined;
+  return {
+    startedAt,
+    totalDeadlineMs: RECOVERY_TOTAL_DEADLINE_MS,
+    adapterDeadlineMs: RECOVERY_ADAPTER_DEADLINE_MS,
+    deviceDeadlineMs: RECOVERY_DEVICE_DEADLINE_MS,
+    deadlineAt,
+    beginDeviceAcquisition: (now) => {
+      if (!Number.isFinite(now)) throw new RangeError('Device acquisition requires finite time.');
+      deviceAcquisitionStartedAt ??= now;
+    },
+    isValid: (phase, now) => {
+      const phaseDeadline =
+        phase === 'acquire-adapter'
+          ? startedAt + RECOVERY_ADAPTER_DEADLINE_MS
+          : phase === 'acquire-device'
+            ? Math.min(
+                (deviceAcquisitionStartedAt ?? startedAt) + RECOVERY_DEVICE_DEADLINE_MS,
+                deadlineAt,
+              )
+            : deadlineAt;
+      return Number.isFinite(now) && now < phaseDeadline;
+    },
+    elapsed: (now) => Math.max(0, now - startedAt),
+  };
+}
+
+export interface RecoveryContinuation {
+  isValid(phase: RecoveryPhase, now: number): boolean;
+  abandon(now: number): void;
+  cleanupOnce(): void;
+}
+
+export function createRecoveryContinuation(
+  deadline: RecoveryDeadline,
+  cleanup: () => void,
+): RecoveryContinuation {
+  let valid = true;
+  let cleaned = false;
+  return {
+    isValid: (phase, now) => {
+      if (!valid || !deadline.isValid(phase, now)) {
+        valid = false;
+        return false;
+      }
+      return true;
+    },
+    abandon: (now) => {
+      if (!deadline.isValid('cleanup', now)) valid = false;
+      valid = false;
+    },
+    cleanupOnce: () => {
+      if (cleaned) return;
+      cleaned = true;
+      cleanup();
+    },
+  };
+}
+
+export interface SingleFlight<T> {
+  run(): Promise<T>;
+  inFlight(): Promise<T> | undefined;
+}
+
+export function createSingleFlight<T>(factory: () => Promise<T>): SingleFlight<T> {
+  let active: Promise<T> | undefined;
+  return {
+    run: () => {
+      if (active !== undefined) return active;
+      let promise: Promise<T>;
+      try {
+        promise = factory();
+      } catch (cause) {
+        promise = Promise.reject(cause);
+      }
+      active = promise;
+      promise.then(
+        () => {
+          if (active === promise) active = undefined;
+        },
+        () => {
+          if (active === promise) active = undefined;
+        },
+      );
+      return promise;
+    },
+    inFlight: () => active,
+  };
+}