@forgeax/engine-render 0.1.28 → 0.1.30

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

@@ -118,3 +118,66 @@ export function executeRendererFrameTransaction<T>(
   steps.commit(built.value);
   return { ok: true, value: built.value };
 }
+
+export interface AutoExposureFrameTransactionOptions {
+  readonly failAt?: RendererFrameStage;
+}
+
+export type AutoExposureFrameTransactionResult =
+  | {
+      readonly ok: true;
+      readonly state: AutoExposureState;
+      readonly commitCount: 1;
+    }
+  | {
+      readonly ok: false;
+      readonly error: RendererFrameStageFailure;
+      readonly state: AutoExposureState;
+      readonly commitCount: 0;
+    };
+
+/**
+ * Adapt the auto-exposure candidate to the renderer's single submit barrier.
+ * This helper deliberately has no encoder or history state of its own.
+ */
+export function executeAutoExposureFrameTransaction(
+  state: AutoExposureState,
+  candidate: AutoExposureCandidate,
+  options: AutoExposureFrameTransactionOptions = {},
+): AutoExposureFrameTransactionResult {
+  let committed = false;
+  const prepared = prepareAutoExposureCandidate(state, candidate);
+  const transaction = executeRendererFrameTransaction<AutoExposureCandidate>({
+    build: () =>
+      prepared.ok && options.failAt !== 'build'
+        ? { ok: true, value: prepared.value }
+        : { ok: false, stage: 'build' },
+    execute: (_value) =>
+      options.failAt === 'execute'
+        ? { ok: false, stage: 'execute' }
+        : { ok: true, value: undefined },
+    finish: (_value) =>
+      options.failAt === 'finish' ? { ok: false, stage: 'finish' } : { ok: true, value: undefined },
+    submit: (_value) =>
+      options.failAt === 'submit' ? { ok: false, stage: 'submit' } : { ok: true, value: undefined },
+    commit: (_value) => {
+      committed = true;
+    },
+  });
+  if (!transaction.ok || !committed) {
+    return {
+      ok: false,
+      error: transaction.ok ? { stage: 'submit' } : transaction.error,
+      state,
+      commitCount: 0,
+    };
+  }
+  return { ok: true, state: commitAutoExposureCandidate(state, candidate), commitCount: 1 };
+}
+
+import {
+  type AutoExposureCandidate,
+  type AutoExposureState,
+  commitAutoExposureCandidate,
+  prepareAutoExposureCandidate,
+} from '../pipeline/standard-output/auto-exposure/state';

package/src/assembly/renderer-helpers.ts

@@ -1,6 +1,7 @@
 import type { Result, RhiCanvasContext, RhiDevice } from '@forgeax/engine-rhi';
 import { err, ok, RhiError } from '@forgeax/engine-rhi';
 import type { RhiErrorListenerRegistry } from '../lifecycle';
+import type { PipelineSpecError } from '../pipeline-spec';
 import { configureSurface, type PipelineState } from '../render-system';
 
 /** Minimum device-bound surface contract needed by lazy context configuration. */
@@ -24,6 +25,31 @@ export function wrapDisposeError(cause: unknown, step: string): RhiError {
   });
 }
 
+export function rendererInitializationPipelineError(error: PipelineSpecError): RhiError {
+  return new RhiError({
+    code: 'webgpu-runtime-error',
+    expected: 'Renderer.initialization three-step strict-serial succeeds',
+    hint: 'inspect detail.error for the underlying PipelineSpecError and GPU cause',
+    detail: {
+      error: {
+        name: error.name,
+        code: error.code,
+        message: error.message,
+        detail: error.detail,
+      },
+    },
+  });
+}
+
+export function rendererInitializationError(cause: unknown): RhiError {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return new RhiError({
+    code: 'webgpu-runtime-error',
+    expected: 'Renderer.initialization three-step strict-serial succeeds',
+    hint: `pipeline build raised: ${message}`,
+  });
+}
+
 export function ensureContextConfigured(
   internals: RendererSurfaceInternals,
   state: PipelineState,

package/src/assembly/renderer-inspection.ts

@@ -1,5 +1,7 @@
 import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
 import type { RhiCanvasSurfacePresentationProof, TextureFormat } from '@forgeax/engine-rhi';
+import type { AutoExposureInspection } from '../pipeline/standard-output/auto-exposure/inspection';
+import type { StandardLutInspection } from '../pipeline/standard-output/lut-state';
 import {
   type RenderOutputInspection,
   type RenderStandardOutputColorInspection,
@@ -15,6 +17,8 @@ export interface RendererOutputInspectionInput {
   readonly surfaceProfile?: 'dual-view' | 'raw-only';
   readonly rgba16floatRenderable: boolean;
   readonly presentationProof?: RhiCanvasSurfacePresentationProof | undefined;
+  readonly autoExposure?: AutoExposureInspection | undefined;
+  readonly standardLut?: StandardLutInspection | undefined;
 }
 
 function isSrgbFormat(format: TextureFormat): boolean {
@@ -75,6 +79,8 @@ export function projectRendererOutputInspection(
   const outputReady = input.surfaceAvailable && displayEncoded;
 
   return {
+    ...(input.autoExposure === undefined ? {} : { autoExposure: input.autoExposure }),
+    ...(input.standardLut === undefined ? {} : { standardLut: input.standardLut }),
     ...(outputTransformPass === undefined
       ? {}
       : { outputTransform: STANDARD_OUTPUT_TRANSFORM_FEATURE_ID }),

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

@@ -2,7 +2,13 @@ import type { Result, RhiError, ShaderModule } from '@forgeax/engine-rhi';
 import { findVariantByKey, type MaterialShaderManifestEntry } from '@forgeax/engine-shader';
 
 /** Minimum sampled-texture limit needed by Standard transmission variants. */
-export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 18;
+
+function isOrdinaryMaterialVariant(
+  variant: MaterialShaderManifestEntry['variants'][number],
+): boolean {
+  return variant.defines.COVERAGE_ONLY !== true;
+}
 
 /** Select HDRP variants that must be seeded during ready-state construction. */
 export function selectHdrpPbrPrewarmVariants(
@@ -27,6 +33,7 @@ export function selectHdrpPbrPrewarmVariants(
   return (
     variants.filter(
       (variant) =>
+        isOrdinaryMaterialVariant(variant) &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         (!('EXTENDED_LIGHTING_AVAILABLE' in variant.defines) ||
           variant.defines.EXTENDED_LIGHTING_AVAILABLE === extendedLightingShaderAvailable) &&
@@ -49,6 +56,7 @@ export function selectSkinPrewarmVariants(
   return (
     manifestEntry?.variants.filter(
       (variant) =>
+        isOrdinaryMaterialVariant(variant) &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         (storageBufferCapable || variant.defines.CLUSTER_FORWARD_AVAILABLE !== true) &&
         variant.defines.PROBE_BLEND_AVAILABLE !== true,
@@ -56,6 +64,41 @@ export function selectSkinPrewarmVariants(
   );
 }
 
+/**
+ * Select the explicit storage-backed, non-clustered GPU scene-index variant.
+ * The GPU raster adapter owns a dedicated slot-3 BGL, so this source must not
+ * be reused by direct, probe, clustered, or transmission material draws.
+ */
+export function selectGpuDrivenSceneIndexVariant(
+  manifestEntry: MaterialShaderManifestEntry | undefined,
+  extendedLightingAvailable: boolean,
+  directionalPcssAvailable: boolean,
+  projectorAvailable: boolean,
+  vertexColorAvailable = false,
+): MaterialShaderManifestEntry['variants'][number] | undefined {
+  return manifestEntry?.variants.find(
+    (variant) =>
+      isOrdinaryMaterialVariant(variant) &&
+      variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
+      variant.defines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE === true &&
+      (!('CLUSTER_FORWARD_AVAILABLE' in variant.defines) ||
+        variant.defines.CLUSTER_FORWARD_AVAILABLE === false) &&
+      (variant.defines.VERTEX_COLOR_AVAILABLE === true) === vertexColorAvailable &&
+      (!('PROBE_BLEND_AVAILABLE' in variant.defines) ||
+        variant.defines.PROBE_BLEND_AVAILABLE === false) &&
+      (!('EXTENDED_LIGHTING_AVAILABLE' in variant.defines) ||
+        variant.defines.EXTENDED_LIGHTING_AVAILABLE === extendedLightingAvailable) &&
+      (!('DIRECTIONAL_PCSS_AVAILABLE' in variant.defines) ||
+        variant.defines.DIRECTIONAL_PCSS_AVAILABLE === directionalPcssAvailable) &&
+      (!('PROJECTOR_AVAILABLE' in variant.defines) ||
+        variant.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
+      (!('REFLECTION_FALLBACK_AVAILABLE' in variant.defines) ||
+        variant.defines.REFLECTION_FALLBACK_AVAILABLE === false) &&
+      (!('TRANSMISSION_AVAILABLE' in variant.defines) ||
+        variant.defines.TRANSMISSION_AVAILABLE === false),
+  );
+}
+
 /** Select probe-enabled material modules for recovery candidate prewarming. */
 export function selectProbePrewarmVariants(
   manifestEntry: MaterialShaderManifestEntry | undefined,
@@ -71,6 +114,7 @@ export function selectProbePrewarmVariants(
     manifestEntry?.variants.filter((variant) => {
       const defines = variant.defines;
       return (
+        isOrdinaryMaterialVariant(variant) &&
         defines.PROBE_BLEND_AVAILABLE === true &&
         defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         (!('WEBGL2_COMPAT' in defines) || defines.WEBGL2_COMPAT === webgl2Downlevel) &&
@@ -124,6 +168,7 @@ export function selectStandardPbrTransmissionPrewarmVariants(
   for (const transmissionAvailable of [false, true]) {
     const declared = manifestEntry.variants.find(
       (variant) =>
+        isOrdinaryMaterialVariant(variant) &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         variant.defines.CLUSTER_FORWARD_AVAILABLE === standardBootClusterAxis() &&
         variant.defines.VERTEX_COLOR_AVAILABLE === false &&

package/src/assembly/skin-palette-owner.ts

@@ -0,0 +1,21 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import {
+  createSkinPaletteAllocator,
+  type SkinPaletteAllocator,
+} from '../systems/skin-palette-allocator';
+
+/**
+ * Constructs the renderer's single skin palette owner. Capability selection
+ * stays at assembly, while allocation and writes remain in the allocator.
+ */
+export function createSkinPaletteOwner(
+  device: RhiDevice,
+  storageBufferCapable: boolean,
+): SkinPaletteAllocator {
+  const limitKey = storageBufferCapable
+    ? 'maxStorageBufferBindingSize'
+    : 'maxUniformBufferBindingSize';
+  const deviceLimit = (device.limits as Readonly<Record<string, number>>)[limitKey];
+  const maxBindingBytes = typeof deviceLimit === 'number' && deviceLimit > 0 ? deviceLimit : 65536;
+  return createSkinPaletteAllocator(device, maxBindingBytes, storageBufferCapable);
+}

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

@@ -0,0 +1,41 @@
+import { RhiError, type ShaderModule } from '@forgeax/engine-rhi';
+import type { ManifestEntry } from '@forgeax/engine-types';
+import type { SsrShaderSources } from '../render-contract';
+
+/** Admit and compile the entire SSR bundle before exposing any of its modules. */
+export async function prewarmSsrShaders(
+  entries: readonly ManifestEntry[],
+  compile: (label: string, source: string) => Promise<ShaderModule>,
+  seed: (label: string, module: ShaderModule) => void,
+): Promise<SsrShaderSources | undefined> {
+  const stages = [
+    ['hiz', 'ssr_hiz_seed', 'ssr_hiz_seed'],
+    ['hizReduce', 'ssr_hiz_reduce', 'ssr_hiz_reduce'],
+    ['trace', 'ssr_trace', 'ssr_trace'],
+    ['temporal', 'ssr_temporal', 'ssr_temporal'],
+    ['compose', 'ssr_compose', 'vs_ssr_compose'],
+  ] as const;
+  const resolved = stages.map(([stage, label, entryPoint]) => ({
+    stage,
+    label,
+    entry: entries.find((entry) => entry.wgsl.includes(`fn ${entryPoint}(`)),
+  }));
+  if (resolved.every(({ entry }) => entry === undefined)) return undefined;
+  const missing = resolved.find(({ entry }) => entry === undefined);
+  if (missing !== undefined) {
+    throw new RhiError({
+      code: 'shader-compile-failed',
+      expected: 'shader manifest contains all five SSR utility entries',
+      hint: `add the package-owned WGSL entry for '${missing.label}' to the engine shader manifest`,
+    });
+  }
+  const compiled: Array<{ label: string; module: ShaderModule }> = [];
+  const sources = {} as Record<keyof SsrShaderSources, string>;
+  for (const { stage, label, entry } of resolved) {
+    if (entry === undefined) throw new Error(`missing SSR shader ${label}`);
+    compiled.push({ label, module: await compile(label, entry.wgsl) });
+    sources[stage] = entry.wgsl;
+  }
+  for (const { label, module } of compiled) seed(label, module);
+  return sources;
+}

package/src/assembly/webgpu-device-loss.ts

@@ -0,0 +1,75 @@
+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's shared health, error,
+ * and lost listener registries. The same helper is used during construction
+ * and recovery so a fresh device cannot silently lose the host subscriptions.
+ */
+export function attachDeviceLostFanout(
+  device: RhiDevice,
+  pack: RhiBackendPack,
+  registries: {
+    lostRegistry: LostListenerRegistry;
+    errorRegistry: RhiErrorListenerRegistry;
+    healthRegistry: HealthListenerRegistry;
+    onDeviceLost?: (detail: string) => void;
+  },
+): void {
+  const { lostRegistry, errorRegistry, healthRegistry, onDeviceLost } = registries;
+  const lost = pack.instrumentation?.deviceLost?.(device) ?? device.lost;
+  lost
+    .then((info) => {
+      const safe = {
+        reason: info?.reason ?? 'unknown',
+        message: info?.message ?? '',
+      };
+      onDeviceLost?.(`device.lost: ${safe.reason}; ${safe.message || '<empty>'}`);
+      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>'}`,
+            }),
+          );
+        }
+      }
+    })
+    .catch((error: unknown) => {
+      pack.instrumentation?.onDeviceLost?.();
+      onDeviceLost?.(`device.lost rejected: ${String(error)}`);
+      lostRegistry.fire({ reason: 'unknown', message: String(error) });
+      healthRegistry.fire({
+        reason: 'device-lost',
+        detail: { lostReason: 'unknown', message: String(error) },
+        recoverable: true,
+      });
+      errorRegistry.fire(
+        new RhiError({
+          code: 'device-lost',
+          expected: 'device.lost Promise resolves with GPUDeviceLostInfo',
+          hint: `device.lost Promise rejected unexpectedly: ${String(error)}`,
+        }),
+      );
+    });
+}

package/src/assembly/webgpu-pbr-ready.ts

@@ -0,0 +1,232 @@
+import type {
+  BindGroupLayout,
+  PipelineLayout,
+  Result,
+  RhiDevice,
+  ShaderModule,
+} from '@forgeax/engine-rhi';
+import { ok, type RhiError } from '@forgeax/engine-rhi';
+import type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
+import type { ManifestEntry } from '@forgeax/engine-types';
+import { type GpuDrivenPbrProgram, standardPbrProgramKey } from '../gpu-driven/pbr-program';
+import { GPU_DRIVEN_VIEW_WGSL } from '../gpu-driven/view-gpu';
+import {
+  buildGpuDrivenPbrInstancesBindGroupLayout,
+  buildGpuDrivenPbrPipelineLayout,
+  buildGpuDrivenPbrSkinPipelineLayout,
+  buildPbrSkinLayouts,
+  type PbrPipelineLayoutBundle,
+  SKIN_MATERIAL_SHADER_ID,
+} from '../pbr-pipeline';
+import { assembleStandardPbrArtifact } from './material/assembly';
+import { invokeDeviceCreateShaderModule } from './material-shader-policy';
+import { runShimStep, runShimSyncStep } from './renderer-helpers';
+import {
+  selectGpuDrivenSceneIndexVariant,
+  selectSkinPrewarmVariants,
+} from './shader-prewarm-policy';
+
+export type AsyncCreateShaderModule = (
+  device: RhiDevice,
+  desc: { code: string; label?: string | undefined },
+) => Promise<Result<ShaderModule, RhiError>>;
+
+export interface GpuDrivenPbrReadyModules {
+  readonly pbrSkinModule: ShaderModule | null;
+  readonly gpuDrivenPbrPrograms: ReadonlyMap<string, GpuDrivenPbrProgram>;
+}
+
+export interface GpuDrivenPbrReadyLayouts {
+  readonly pbrSkinPipelineLayout: PipelineLayout | null;
+  readonly pbrSkinProbePipelineLayout: PipelineLayout | null;
+  readonly pbrSkinMeshBindGroupLayout: BindGroupLayout | null;
+  readonly gpuDrivenInstancesBindGroupLayout: BindGroupLayout | null;
+  readonly gpuDrivenPbrPipelineLayout: PipelineLayout | null;
+  readonly gpuDrivenPbrSkinPipelineLayout: PipelineLayout | null;
+}
+
+interface GpuDrivenPbrModuleInput {
+  readonly device: RhiDevice;
+  readonly storageBufferCapable: boolean;
+  readonly asyncCreateShaderModule: AsyncCreateShaderModule | undefined;
+  readonly pbrSkinEntry: ManifestEntry | undefined;
+  readonly pbrManifestEntry: MaterialShaderManifestEntry | undefined;
+  readonly pbrSkinManifestEntry: MaterialShaderManifestEntry | undefined;
+  readonly extendedLightingShaderAvailable: boolean;
+  readonly directionalPcssAvailable: boolean;
+  readonly projectorAvailable: boolean;
+  readonly seedShaderModule: (label: string, module: ShaderModule) => void;
+}
+
+function createShader(
+  input: Pick<GpuDrivenPbrModuleInput, 'device' | 'asyncCreateShaderModule'>,
+  code: string,
+  label: string,
+): Promise<Result<ShaderModule, RhiError>> {
+  return input.asyncCreateShaderModule
+    ? input.asyncCreateShaderModule(input.device, { code, label })
+    : Promise.resolve(invokeDeviceCreateShaderModule(input.device, { code, label }));
+}
+
+export async function buildGpuDrivenPbrReadyModules(
+  input: GpuDrivenPbrModuleInput,
+): Promise<GpuDrivenPbrReadyModules> {
+  let pbrSkinModule: ShaderModule | null = null;
+  const gpuDrivenPbrPrograms = new Map<string, GpuDrivenPbrProgram>();
+  if (input.pbrSkinEntry !== undefined && input.pbrSkinEntry.wgsl.length > 0) {
+    const result = await runShimStep(
+      () => createShader(input, input.pbrSkinEntry?.wgsl ?? '', 'pbr-skin'),
+      'shader-compile-failed',
+      'skinned PBR shader module compiled',
+      'inspect manifest pbr-skin entry composed wgsl; check device.features',
+    );
+    if (!result.ok) throw result.error;
+    pbrSkinModule = result.value;
+    input.seedShaderModule(`module-${SKIN_MATERIAL_SHADER_ID}`, pbrSkinModule);
+  }
+  if (
+    input.storageBufferCapable &&
+    input.device.caps.compute &&
+    input.device.caps.indirectDrawing
+  ) {
+    const result = await runShimStep(
+      () => createShader(input, GPU_DRIVEN_VIEW_WGSL, 'gpu-driven-view'),
+      'shader-compile-failed',
+      'GPU-driven view shader module compiled',
+      'inspect the GPU-driven view compute WGSL and check device.features',
+    );
+    if (!result.ok) throw result.error;
+    input.seedShaderModule('gpu-driven-view', result.value);
+  }
+  if (input.storageBufferCapable) {
+    for (const [materialId, entry] of [
+      ['forgeax::default-standard-pbr', input.pbrManifestEntry],
+      ['forgeax::pbr-skin', input.pbrSkinManifestEntry],
+    ] as const) {
+      for (const color of [false, true]) {
+        const variant = selectGpuDrivenSceneIndexVariant(
+          entry,
+          input.extendedLightingShaderAvailable,
+          input.directionalPcssAvailable,
+          input.projectorAvailable,
+          color,
+        );
+        if (variant === undefined || entry === undefined) continue;
+        const key = standardPbrProgramKey(materialId, color);
+        const artifact = assembleStandardPbrArtifact(materialId, variant.composedWgsl, color);
+        if (key === undefined || artifact === undefined) continue;
+        const result = await runShimStep(
+          () => createShader(input, artifact.wgsl, `gpu-driven-${key}`),
+          'shader-compile-failed',
+          'GPU-driven Standard PBR program compiled',
+          'inspect the selected scene-index and vertex-color variant with its slot-3 ABI',
+        );
+        if (!result.ok) throw result.error;
+        gpuDrivenPbrPrograms.set(key, { module: result.value, artifact });
+        input.seedShaderModule(`gpu-driven-${key}`, result.value);
+      }
+    }
+  }
+  const declaredSkinVariants = selectSkinPrewarmVariants(
+    input.pbrSkinManifestEntry,
+    input.storageBufferCapable,
+  );
+  // The complete Cartesian product is useful for a full local/nightly boot,
+  // but compiling every pbr-skin capability combination in each lightweight
+  // Dawn process dominates CI startup (the renderer only needs the active
+  // device axes plus the two topology/color lanes). Other combinations remain
+  // available in the manifest and are still resolved lazily when requested.
+  const lightweightDawn =
+    (globalThis as { process?: { env?: { FORGEAX_DAWN_LIGHTWEIGHT?: string } } }).process?.env
+      ?.FORGEAX_DAWN_LIGHTWEIGHT === '1';
+  const skinVariants = lightweightDawn
+    ? declaredSkinVariants.filter((variant) => {
+        const defines = variant.defines;
+        return (
+          defines.STORAGE_BUFFER_AVAILABLE === input.storageBufferCapable &&
+          defines.PROBE_BLEND_AVAILABLE !== true &&
+          (!('EXTENDED_LIGHTING_AVAILABLE' in defines) ||
+            defines.EXTENDED_LIGHTING_AVAILABLE === input.extendedLightingShaderAvailable) &&
+          (!('DIRECTIONAL_PCSS_AVAILABLE' in defines) ||
+            defines.DIRECTIONAL_PCSS_AVAILABLE === input.directionalPcssAvailable) &&
+          (!('PROJECTOR_AVAILABLE' in defines) ||
+            defines.PROJECTOR_AVAILABLE === input.projectorAvailable) &&
+          defines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE === false &&
+          defines.TRANSMISSION_AVAILABLE === false
+        );
+      })
+    : declaredSkinVariants;
+  for (const variant of skinVariants) {
+    const label = `module-${SKIN_MATERIAL_SHADER_ID}#${variant.definesKey}`;
+    const result = await runShimStep(
+      () => createShader(input, variant.composedWgsl, label),
+      'shader-compile-failed',
+      `pbr-skin variant ${variant.definesKey || '<default>'} compiled`,
+      'inspect the selected pbr-skin storage/cluster/color variant and device.features',
+    );
+    if (!result.ok) throw result.error;
+    input.seedShaderModule(label, result.value);
+    if (variant.definesKey === '')
+      input.seedShaderModule(`module-${SKIN_MATERIAL_SHADER_ID}`, result.value);
+  }
+  return { pbrSkinModule, gpuDrivenPbrPrograms };
+}
+
+export function buildGpuDrivenPbrReadyLayouts(
+  device: RhiDevice,
+  storageBufferCapable: boolean,
+  pbrLayouts: PbrPipelineLayoutBundle,
+): GpuDrivenPbrReadyLayouts {
+  let pbrSkinPipelineLayout: PipelineLayout | null = null;
+  let pbrSkinProbePipelineLayout: PipelineLayout | null = null;
+  let pbrSkinMeshBindGroupLayout: BindGroupLayout | null = null;
+  let gpuDrivenInstancesBindGroupLayout: BindGroupLayout | null = null;
+  let gpuDrivenPbrPipelineLayout: PipelineLayout | null = null;
+  let gpuDrivenPbrSkinPipelineLayout: PipelineLayout | null = null;
+  const skinResult = runShimSyncStep(
+    () => ok(buildPbrSkinLayouts(device, { storageBuffer: storageBufferCapable }, pbrLayouts)),
+    'webgpu-runtime-error',
+    'buildPbrSkinLayouts succeeded',
+    'check device.limits.maxBindingsPerBindGroup (need >=14) and maxBindGroupsPerPipelineLayout',
+  );
+  if (skinResult.ok) {
+    pbrSkinPipelineLayout = skinResult.value.pipelineLayout;
+    pbrSkinProbePipelineLayout = skinResult.value.probePipelineLayout;
+    pbrSkinMeshBindGroupLayout = skinResult.value.meshArrayBgl;
+  }
+  if (storageBufferCapable) {
+    const layoutResult = runShimSyncStep(
+      () => {
+        const instances = buildGpuDrivenPbrInstancesBindGroupLayout(device, {
+          storageBuffer: true,
+        });
+        const rigid = buildGpuDrivenPbrPipelineLayout(device, pbrLayouts, instances);
+        const skin =
+          pbrSkinMeshBindGroupLayout === null
+            ? null
+            : buildGpuDrivenPbrSkinPipelineLayout(
+                device,
+                { ...pbrLayouts, meshArrayBgl: pbrSkinMeshBindGroupLayout },
+                instances,
+              );
+        return ok({ instances, rigid, skin });
+      },
+      'webgpu-runtime-error',
+      'build GPU-driven PBR pipeline layouts succeeded',
+      'check the dedicated scene-index slot-3 storage layout and four-slot pipeline layouts',
+    );
+    if (layoutResult.ok) {
+      gpuDrivenInstancesBindGroupLayout = layoutResult.value.instances;
+      gpuDrivenPbrPipelineLayout = layoutResult.value.rigid;
+      gpuDrivenPbrSkinPipelineLayout = layoutResult.value.skin;
+    }
+  }
+  return {
+    pbrSkinPipelineLayout,
+    pbrSkinProbePipelineLayout,
+    pbrSkinMeshBindGroupLayout,
+    gpuDrivenInstancesBindGroupLayout,
+    gpuDrivenPbrPipelineLayout,
+    gpuDrivenPbrSkinPipelineLayout,
+  };
+}

package/src/assembly/webgpu-ready-mipmap.ts

@@ -0,0 +1,26 @@
+import type { MipmapShaderModuleFactory } from '@forgeax/engine-assets-runtime';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import type { GpuResidencyCache } from '../device/gpu-residency';
+import type { RhiBackendPack } from './backend-contract';
+import { MIPMAP_PREWARM_FORMATS } from './webgpu-ready-contract';
+
+export function adaptMipmapShaderModuleFactory(
+  factory: RhiBackendPack['createShaderModule'],
+): MipmapShaderModuleFactory | undefined {
+  if (factory === undefined) return undefined;
+  return (device, descriptor) => factory(device as RhiDevice, descriptor);
+}
+
+/**
+ * Prewarm the mipmap pipeline while the renderer is still on its async ready
+ * path. A manifest-free camera-only renderer must not create the shader.
+ */
+export async function prewarmMipmapPipeline(
+  rhiDevice: RhiDevice,
+  gpuStore: GpuResidencyCache,
+  hasMaterialManifest: boolean,
+): Promise<void> {
+  if (!hasMaterialManifest) return;
+  const result = await gpuStore.prewarmMipmapPipeline(rhiDevice, MIPMAP_PREWARM_FORMATS);
+  if (!result.ok) throw result.error;
+}