@forgeax/engine-render 0.1.23 → 0.1.24

package/src/assembly/material-shader-prewarm.ts

@@ -0,0 +1,88 @@
+import type { Result, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import type { ShaderCatalog } from '@forgeax/engine-shader';
+
+import { invokeDeviceCreateShaderModule } from './material-shader-policy';
+import { runShimStep } from './renderer-helpers';
+
+type AsyncCreateShaderModule = (
+  device: RhiDevice,
+  desc: { code: string; label?: string | undefined },
+) => Promise<Result<ShaderModule, RhiError>>;
+
+/**
+ * Prewarm producer-declared material shaders and all published capability
+ * variants before the first prepared frame. Variant labels mirror the lazy
+ * material pipeline adapter's module lookup contract.
+ */
+export async function prewarmRequiredMaterialShaders({
+  rhiDevice,
+  registry,
+  asyncCreateShaderModule,
+  requiredMaterialShaders,
+  seedShaderModule,
+}: {
+  readonly rhiDevice: RhiDevice;
+  readonly registry: ShaderCatalog;
+  readonly asyncCreateShaderModule: AsyncCreateShaderModule | undefined;
+  readonly requiredMaterialShaders: readonly string[];
+  readonly seedShaderModule: (label: string, module: ShaderModule) => void;
+}): Promise<void> {
+  for (const materialShaderId of requiredMaterialShaders) {
+    const lookup = registry.findMaterialArtifact(materialShaderId);
+    if (!lookup.ok) {
+      throw new RhiError({
+        code: 'shader-compile-failed',
+        expected: `declared render feature material shader '${materialShaderId}' is present in the loaded manifest`,
+        hint: `add material shader '${materialShaderId}' to the shader manifest or remove it from the feature declaration`,
+      });
+    }
+    const label = `module-${materialShaderId}`;
+    const shaderResult = await runShimStep(
+      () =>
+        asyncCreateShaderModule
+          ? asyncCreateShaderModule(rhiDevice, { code: lookup.value.source, label })
+          : invokeDeviceCreateShaderModule(rhiDevice, { code: lookup.value.source, label }),
+      'shader-compile-failed',
+      `declared render feature material shader '${materialShaderId}' compiled`,
+      `inspect the composed WGSL for '${materialShaderId}' and check device.features`,
+    );
+    if (!shaderResult.ok) throw shaderResult.error;
+    seedShaderModule(label, shaderResult.value);
+
+    const prewarmedSources = new Map<string, ShaderModule>([
+      [lookup.value.source, shaderResult.value],
+    ]);
+    const manifestEntry = [...registry.materialShaderManifestEntries()].find(
+      (candidate) => candidate.identifier === materialShaderId,
+    );
+    if (manifestEntry === undefined) continue;
+
+    for (const variant of manifestEntry.variants) {
+      const variantLabel = `module-${materialShaderId}#${variant.definesKey}`;
+      if (variantLabel === label) continue;
+      let variantModule = prewarmedSources.get(variant.composedWgsl);
+      if (variantModule === undefined) {
+        const variantResult = await runShimStep(
+          () =>
+            asyncCreateShaderModule
+              ? asyncCreateShaderModule(rhiDevice, {
+                  code: variant.composedWgsl,
+                  label: variantLabel,
+                })
+              : invokeDeviceCreateShaderModule(rhiDevice, {
+                  code: variant.composedWgsl,
+                  label: variantLabel,
+                }),
+          'shader-compile-failed',
+          `declared render feature material shader variant '${variantLabel}' compiled`,
+          `inspect the composed WGSL for '${materialShaderId}' variant '${variant.definesKey}' and check device.features`,
+        );
+        if (!variantResult.ok) throw variantResult.error;
+        variantModule = variantResult.value;
+        prewarmedSources.set(variant.composedWgsl, variantModule);
+      }
+      seedShaderModule(variantLabel, variantModule);
+    }
+  }
+}

package/src/assembly/mesh-ssbo-grow.ts

@@ -0,0 +1,270 @@
+// Dynamic mesh/material SSBO growth owner.
+// Keeps the stable wrapper identity and capacity policy together with the
+// device allocation producer; renderer lifetime only consumes this contract.
+
+import {
+  MeshSsboCapacityExceededError,
+  MeshSsboCeilingReachedError,
+} from '@forgeax/engine-assets-runtime';
+import type { Buffer } from '@forgeax/engine-rhi';
+
+// feat-20260608-mesh-ssbo-dynamic-grow-l1-lift-1024-entity-cap M2 / T-M2-05:
+// the legacy MESH_SSBO_SLOT_COUNT / MATERIAL_UBO_TOTAL_BYTES /
+// MESH_SSBO_TOTAL_BYTES literal-1024 module constants are gone. The
+// renderer now starts at INITIAL_MESH_SSBO_SLOT_COUNT and grows on demand
+// via `createMeshSsboGrowController` (pow2 doubling, ceiling =
+// device.limits.maxStorageBufferBindingSize / MATERIAL_PER_ENTITY_STRIDE per
+// plan-strategy §2.D-1). The shared allocation stride remains the material
+// owner; only slotCount grows.
+export const INITIAL_MESH_SSBO_SLOT_COUNT = 1024;
+
+// ── createMeshSsboGrowController ───────────────────────────────────────────
+//
+// feat-20260608-mesh-ssbo-dynamic-grow-l1-lift-1024-entity-cap M2 / T-M2-05:
+// pure factory that owns the mesh-SSBO + material-UBO grow state. State is
+// closure-local (plan-strategy §2.D-4: no separate allocator class — state
+// stays beside its createBuffer producer). Outer wrapper-object identity is
+// stable across grow so PipelineState.meshStorageBuffer / materialUniformBuffer
+// references never dangle (research §F8 / §3.1 R1); inner `.buffer` is
+// replaced by a fresh createBuffer return value when the grow path runs.
+//
+// Grow algorithm (AC-05 / AC-06):
+//   1. If `slotCount >= needed` → idempotent guard short-circuits with `{ ok: true }`.
+//   2. Compute `targetSlots = nextPow2 doubling from slotCount until >= needed`.
+//   3. If `targetSlots * stride > device.limits.maxStorageBufferBindingSize`
+//      → fire `MeshSsboCeilingReachedError` and return `{ ok: false, code: 'mesh-ssbo-ceiling-reached' }`.
+//      No createBuffer is called; recordFrame is expected to skip the frame.
+//   4. createBuffer × 2 (mesh + material) sized at `targetSlots * stride`,
+//      using the usage flags captured at construction (mesh = STORAGE|COPY_DST,
+//      material = UNIFORM|COPY_DST — both unchanged from initialBuild).
+//   5. Replace `state.mesh.buffer` and `state.material.buffer` in-place;
+//      update `state.mesh.sizeInBytes` and `state.material.sizeInBytes`;
+//      bump `state.slotCount = targetSlots`.
+//   6. Defensive belt-and-suspenders: if the grow somehow lands with
+//      `state.slotCount < needed` (shouldn't happen given the pow2 invariant)
+//      → fire `MeshSsboCapacityExceededError` and return capacity-exceeded.
+//
+// Errors flow through `errorRegistry.fire` only (D-5: never throw — keeps the
+// grow surface compatible with the recordFrame outer try/catch without
+// dual-firing through 'webgpu-runtime-error').
+
+/** Pow2 round-up — smallest power of 2 >= n (n>=1). */
+function nextPow2(n: number): number {
+  if (n <= 1) return 1;
+  let v = 1;
+  while (v < n) v <<= 1;
+  return v;
+}
+
+/**
+ * WebGPU spec floor for `maxStorageBufferBindingSize` (128 MiB).
+ * @see {@link https://www.w3.org/TR/webgpu/#dom-supported-limits-maxstoragebufferbindingsize}
+ */
+const WEBGPU_SPEC_FLOOR_MAX_STORAGE_BUFFER_BINDING_SIZE = 134217728;
+
+/**
+ * Derive a usable storage-buffer ceiling from device limits.
+ *
+ * Mirrors the `SKIN_PALETTE_MAX_BINDING_BYTES` 0/undefined floor pattern
+ * (createRenderer.ts:4070-4073): when `maxStorageBufferBindingSize` is 0 or
+ * undefined (WebKit `downlevel_webgl2_defaults`), climb the fallback chain —
+ * `maxBufferSize` → `maxUniformBufferBindingSize` → WebGPU spec floor
+ * 134217728 (128 MiB).
+ *
+ * Pure helper — no device dependency, directly testable in node.
+ */
+export function deriveStorageBufferCeiling(
+  limits: Readonly<{
+    maxStorageBufferBindingSize?: number;
+    maxBufferSize?: number;
+    maxUniformBufferBindingSize?: number;
+  }>,
+): number {
+  // Preferred: the device-reported storage-buffer binding size (when > 0).
+  if (
+    typeof limits.maxStorageBufferBindingSize === 'number' &&
+    limits.maxStorageBufferBindingSize > 0
+  ) {
+    return limits.maxStorageBufferBindingSize;
+  }
+  // Fallback 1: maxBufferSize (device-level buffer allocation limit).
+  if (typeof limits.maxBufferSize === 'number' && limits.maxBufferSize > 0) {
+    return limits.maxBufferSize;
+  }
+  // Fallback 2: maxUniformBufferBindingSize (uniform binding limit, lower
+  // but still a real device capacity signal).
+  if (
+    typeof limits.maxUniformBufferBindingSize === 'number' &&
+    limits.maxUniformBufferBindingSize > 0
+  ) {
+    return limits.maxUniformBufferBindingSize;
+  }
+  // Fallback 3: WebGPU spec floor — always non-zero, safe as last resort.
+  return WEBGPU_SPEC_FLOOR_MAX_STORAGE_BUFFER_BINDING_SIZE;
+}
+
+/**
+ * Mesh + material buffer wrapper carrying the inner `Buffer` handle plus
+ * the byte-size at the time of allocation. The wrapper-object identity is
+ * stable across grow events — only `.buffer` and `.sizeInBytes` are mutated
+ * in place — so `PipelineState.meshStorageBuffer` / `materialUniformBuffer`
+ * fields capture the wrapper once and survive grow events without a re-bind
+ * cycle through the public Renderer surface (research §F8 R1).
+ */
+export interface MeshSsboBufferWrapper {
+  buffer: Buffer | null;
+  sizeInBytes: number;
+}
+
+export function requireMeshSsboBuffer(
+  wrapper: MeshSsboBufferWrapper,
+): asserts wrapper is MeshSsboBufferWrapper & { buffer: Buffer } {
+  if (wrapper.buffer === null) throw new Error('mesh SSBO initial allocation was not completed');
+}
+
+/** Closure-local grow state surfaced for spy assertions in unit tests. */
+export interface MeshSsboState {
+  slotCount: number;
+  mesh: MeshSsboBufferWrapper;
+  material: MeshSsboBufferWrapper;
+}
+
+/** `growMeshSsbo` return shape (D-5: Result-like, never throws). */
+export type MeshSsboGrowResult =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly code: 'mesh-ssbo-ceiling-reached' | 'mesh-ssbo-capacity-exceeded';
+      /** Pre-grow slotCount — the caller can render up to this many slots (degraded subset). */
+      readonly degradedToSlotCount: number;
+    };
+
+/** Minimal device surface the grow controller needs (mocked in unit tests). */
+export interface MeshSsboGrowDevice {
+  readonly limits: { readonly maxStorageBufferBindingSize: number };
+  readonly createBuffer: (descriptor: {
+    readonly label?: string;
+    readonly size: number;
+    readonly usage: number;
+    readonly mappedAtCreation?: boolean;
+  }) => Buffer;
+}
+
+/** Minimal error-registry surface (just `fire` — `RhiErrorListenerRegistry` matches). */
+export interface MeshSsboGrowErrorRegistry {
+  fire: (e: MeshSsboCeilingReachedError | MeshSsboCapacityExceededError) => void;
+}
+
+export interface MeshSsboGrowControllerInit {
+  readonly device: MeshSsboGrowDevice;
+  readonly errorRegistry: MeshSsboGrowErrorRegistry;
+  readonly initialSlotCount: number;
+  readonly perEntityStride: number;
+  readonly meshUsage: number;
+  readonly materialUsage: number;
+}
+
+export interface MeshSsboGrowController {
+  readonly state: MeshSsboState;
+  /** Allocate the initial mesh + material buffer pair at `initialSlotCount`. */
+  readonly initialBuild: () => void;
+  /** Grow to satisfy `neededSlots`; idempotent + ceiling-aware. */
+  readonly growMeshSsbo: (neededSlots: number) => MeshSsboGrowResult;
+}
+
+/**
+ * Build a closure-scoped mesh-SSBO grow controller. Module-scope so unit
+ * tests (`__tests__/mesh-ssbo-grow.test.ts`) can construct it with a fake
+ * device + spy errorRegistry without spinning up the full WebGPU renderer
+ * (charter F2 minimal surface — the controller is the testable seam).
+ */
+export function createMeshSsboGrowController(
+  init: MeshSsboGrowControllerInit,
+): MeshSsboGrowController {
+  const { device, errorRegistry, initialSlotCount, perEntityStride, meshUsage, materialUsage } =
+    init;
+  // Wrapper-object identity is set once and shared with PipelineState.
+  // Inner buffer + sizeInBytes are mutated in place during grow.
+  const meshWrapper: MeshSsboBufferWrapper = {
+    buffer: null,
+    sizeInBytes: 0,
+  };
+  const materialWrapper: MeshSsboBufferWrapper = {
+    buffer: null,
+    sizeInBytes: 0,
+  };
+  const state: MeshSsboState = {
+    slotCount: 0,
+    mesh: meshWrapper,
+    material: materialWrapper,
+  };
+  let initialised = false;
+
+  const allocBufferPair = (slots: number): void => {
+    const sizeInBytes = slots * perEntityStride;
+    const meshBuf = device.createBuffer({
+      label: 'pbr-mesh-ssbo',
+      size: sizeInBytes,
+      usage: meshUsage,
+      mappedAtCreation: false,
+    });
+    const materialBuf = device.createBuffer({
+      label: 'pbr-material-ubo',
+      size: sizeInBytes,
+      usage: materialUsage,
+      mappedAtCreation: false,
+    });
+    meshWrapper.buffer = meshBuf;
+    meshWrapper.sizeInBytes = sizeInBytes;
+    materialWrapper.buffer = materialBuf;
+    materialWrapper.sizeInBytes = sizeInBytes;
+    state.slotCount = slots;
+  };
+
+  const initialBuild = (): void => {
+    if (initialised) return;
+    initialised = true;
+    allocBufferPair(initialSlotCount);
+  };
+
+  const growMeshSsbo = (neededSlots: number): MeshSsboGrowResult => {
+    // (1) idempotent guard — already large enough.
+    if (state.slotCount >= neededSlots) {
+      return { ok: true };
+    }
+    // (2) pow2 double until >= needed.
+    let target = state.slotCount > 0 ? state.slotCount : 1;
+    while (target < neededSlots) target = target * 2;
+    // Round up to nextPow2 of needed in case slotCount is 0 / not pow2.
+    target = Math.max(target, nextPow2(neededSlots));
+    const ceilingBytes = deriveStorageBufferCeiling(device.limits);
+    const targetBytes = target * perEntityStride;
+    // (3) ceiling check — refuse + fire structured error.
+    if (targetBytes > ceilingBytes) {
+      errorRegistry.fire(
+        new MeshSsboCeilingReachedError(neededSlots, state.slotCount, ceilingBytes),
+      );
+      return {
+        ok: false,
+        code: 'mesh-ssbo-ceiling-reached',
+        degradedToSlotCount: state.slotCount,
+      };
+    }
+    // (4) + (5) allocate fresh buffers + replace inner refs.
+    allocBufferPair(target);
+    // (6) defensive belt-and-suspenders.
+    if (state.slotCount < neededSlots) {
+      errorRegistry.fire(
+        new MeshSsboCapacityExceededError(neededSlots, state.slotCount, ceilingBytes),
+      );
+      return {
+        ok: false,
+        code: 'mesh-ssbo-capacity-exceeded',
+        degradedToSlotCount: state.slotCount,
+      };
+    }
+    return { ok: true };
+  };
+
+  return { state, initialBuild, growMeshSsbo };
+}

package/src/assembly/recovery/device-loss-fanout.ts

@@ -0,0 +1,89 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import type {
+  HealthListenerRegistry,
+  LostListenerRegistry,
+  RhiErrorListenerRegistry,
+} from '../../lifecycle';
+import type { RhiBackendPack } from '../backend-contract';
+
+/** Wire one device's loss promise into the Renderer-owned observability channels. */
+export function attachDeviceLostFanout(
+  device: RhiDevice,
+  pack: RhiBackendPack,
+  registries: {
+    lostRegistry: LostListenerRegistry;
+    errorRegistry: RhiErrorListenerRegistry;
+    healthRegistry: HealthListenerRegistry;
+    generation: number;
+    currentGeneration: () => number;
+    onStaleLoss?: () => void;
+    onDeviceLost?: (detail: string) => void;
+  },
+): void {
+  const {
+    lostRegistry,
+    errorRegistry,
+    healthRegistry,
+    generation,
+    currentGeneration,
+    onStaleLoss,
+    onDeviceLost,
+  } = registries;
+  const dispatch = (safe: {
+    readonly reason: 'destroyed' | 'unknown';
+    readonly message: string;
+  }) => {
+    const current = currentGeneration();
+    if (generation < current) {
+      onStaleLoss?.();
+      return;
+    }
+    const detail = `device.lost: ${safe.reason}; ${safe.message || '<empty>'}`;
+    // A candidate loss is not an active renderer loss until its generation is
+    // published. The candidate callback remains available to the recovery
+    // owner, while the public lost/health/error channels stay on the active
+    // generation only.
+    if (generation > current) {
+      onDeviceLost?.(detail);
+      return;
+    }
+    onDeviceLost?.(detail);
+    lostRegistry.fire(safe);
+    if (safe.reason !== 'destroyed') {
+      pack.instrumentation?.onDeviceLost?.();
+      healthRegistry.fire({
+        reason: 'device-lost',
+        detail: { lostReason: safe.reason, message: safe.message },
+        recoverable: true,
+      });
+      if (pack.translateErrorEventToRhiError) {
+        const translated = pack.translateErrorEventToRhiError(safe);
+        errorRegistry.fire(translated.error);
+      } else {
+        errorRegistry.fire(
+          new RhiError({
+            code: 'device-lost',
+            expected: 'device must remain alive (driver / browser must not destroy the GPUDevice)',
+            hint: `device-lost reason: ${safe.reason}; message: ${safe.message || '<empty>'}`,
+          }),
+        );
+      }
+    }
+  };
+  // Deterministic recovery fixtures may project a replacement loss promise
+  // without mutating the backend-owned device. Production packs leave this
+  // hook unset, so the native RHI promise remains the default source.
+  const loss = pack.instrumentation?.deviceLost?.(device) ?? device.lost;
+  loss
+    .then((info) => {
+      const safe = {
+        reason: info?.reason ?? 'unknown',
+        message: info?.message ?? '',
+      };
+      dispatch(safe);
+    })
+    .catch((cause: unknown) => {
+      dispatch({ reason: 'unknown', message: String(cause) });
+    });
+}

package/src/assembly/recovery/generation.ts

@@ -0,0 +1,141 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type DeviceResourceKind,
+  type DeviceScope,
+  type LifecycleCleanupFailure,
+  type LifecycleResourceSpec,
+  LifecycleTransaction,
+} from '../../device/device-scope';
+
+/** The private value published by one complete renderer device generation. */
+export interface GenerationAggregate<
+  TDevice = unknown,
+  TContext = unknown,
+  TPipeline = unknown,
+  TProducerBindings = unknown,
+  TGraph = unknown,
+> {
+  readonly generation: number;
+  readonly scope: DeviceScope;
+  readonly device: TDevice;
+  readonly context: TContext;
+  readonly pipeline: TPipeline;
+  readonly producerBindings: TProducerBindings;
+  readonly graph: TGraph | undefined;
+}
+
+export interface GenerationAssemblyInput<
+  TAggregate extends GenerationAggregate = GenerationAggregate,
+> {
+  readonly scope: TAggregate['scope'];
+  readonly device: TAggregate['device'];
+  readonly context: TAggregate['context'];
+  readonly pipeline: TAggregate['pipeline'];
+  readonly producerBindings: TAggregate['producerBindings'];
+  readonly graph?: TAggregate['graph'];
+  readonly roots: readonly LifecycleResourceSpec<unknown>[];
+}
+
+export interface GenerationAssemblyFailure {
+  readonly code: 'generation-assembly-failed';
+  readonly generation: number;
+  readonly resourceKind: DeviceResourceKind;
+  readonly cause: unknown;
+  readonly cleanupFailures: readonly LifecycleCleanupFailure[];
+}
+
+export interface GenerationPublication<TAggregate> {
+  current: TAggregate;
+}
+
+export interface GenerationAllocator {
+  readonly activeGeneration: number;
+  next(): number;
+}
+
+const ROOT_ORDER = new Map<DeviceResourceKind, number>([
+  ['listener', 0],
+  ['surface', 1],
+  ['shader', 2],
+  ['pipeline', 3],
+  ['buffer', 4],
+  ['texture', 5],
+  ['binding', 6],
+  ['scene-table', 7],
+  ['feature', 8],
+  ['post-effect', 9],
+]);
+
+function sortRoots(
+  roots: readonly LifecycleResourceSpec<unknown>[],
+): readonly LifecycleResourceSpec<unknown>[] {
+  return roots
+    .map((root, index) => ({ root, index }))
+    .sort((left, right) => {
+      const leftOrder = ROOT_ORDER.get(left.root.kind) ?? ROOT_ORDER.size;
+      const rightOrder = ROOT_ORDER.get(right.root.kind) ?? ROOT_ORDER.size;
+      return leftOrder - rightOrder || left.index - right.index;
+    })
+    .map(({ root }) => root);
+}
+
+/**
+ * Build all device-bound roots before exposing their generation aggregate.
+ * LifecycleTransaction owns creation failure rollback; this function only
+ * projects its failure into the generation assembly boundary.
+ */
+export async function buildGenerationAggregate<
+  TAggregate extends GenerationAggregate = GenerationAggregate,
+>(
+  input: GenerationAssemblyInput<TAggregate>,
+): Promise<Result<TAggregate, GenerationAssemblyFailure>> {
+  const transaction = new LifecycleTransaction(input.scope);
+  for (const root of sortRoots(input.roots)) transaction.add(root);
+
+  const lifecycle = await transaction.commit();
+  if (!lifecycle.ok) {
+    input.scope.abandon();
+    return err({
+      code: 'generation-assembly-failed',
+      generation: input.scope.generation,
+      resourceKind: lifecycle.error.primary.detail.resourceKind,
+      cause: lifecycle.error.primary.detail.cause,
+      cleanupFailures: lifecycle.error.cleanupFailures,
+    });
+  }
+
+  const aggregate = Object.freeze({
+    generation: input.scope.generation,
+    scope: input.scope,
+    device: input.device,
+    context: input.context,
+    pipeline: input.pipeline,
+    producerBindings: input.producerBindings,
+    graph: input.graph,
+  }) as TAggregate;
+  return ok(aggregate);
+}
+
+/** Replace the owner slot only after the complete candidate has been checked. */
+export function publishGeneration<TAggregate>(
+  publication: GenerationPublication<TAggregate | undefined>,
+  candidate: TAggregate,
+  isPublishable: (candidate: TAggregate) => boolean,
+): void {
+  if (!isPublishable(candidate)) {
+    throw new Error('Generation candidate failed its final publication check.');
+  }
+  publication.current = candidate;
+}
+
+/** Allocate unique candidate generations while leaving the active value unchanged. */
+export function createGenerationAllocator(activeGeneration: number): GenerationAllocator {
+  if (!Number.isSafeInteger(activeGeneration) || activeGeneration < 0) {
+    throw new RangeError('Active generation must be a non-negative safe integer.');
+  }
+  let nextGeneration = activeGeneration + 1;
+  return {
+    activeGeneration,
+    next: () => nextGeneration++,
+  };
+}