@forgeax/engine-render 0.1.28 → 0.1.30

package/src/assembly/webgpu-ready.ts

@@ -1,3 +1,5 @@
+import type { GpuDrivenPbrProgram } from '../gpu-driven/pbr-program';
+import { transmissionBackdropAvailable } from './device-feature-admission';
 // WebGPU generation-scoped ready-state builder.
 // This owner performs one complete device-generation promotion; it receives
 // policy/adapters and returns a fully prepared PipelineState.
@@ -10,7 +12,7 @@ import {
   HANDLE_SPHERE,
   HANDLE_TRIANGLE,
 } from '@forgeax/engine-assets-runtime';
-import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { deriveVertexCount, deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import type {
   BindGroupLayout,
   Buffer,
@@ -26,6 +28,8 @@ import { ok, RhiError } from '@forgeax/engine-rhi';
 import { findVariantByKey, type ShaderCatalog } from '@forgeax/engine-shader';
 import type { ManifestEntry } from '@forgeax/engine-types';
 import { handleSlot } from '@forgeax/engine-types';
+import { prewarmAtmosphereShaders } from './atmosphere-shader-prewarm';
+import { prewarmSsrShaders } from './ssr-shader-prewarm';
 
 export type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
 
@@ -54,12 +58,13 @@ import {
 } from '../ibl/skylight-bind-group';
 import type { BloomInspection } from '../inspection-types';
 import type { DeviceScope, RhiErrorListenerRegistry } from '../lifecycle';
+import { assertStorageBufferCap } from '../light-buffer-layout';
 import {
   buildPbrPipelineLayouts,
-  buildPbrSkinLayouts,
   createHdrpSkinBindGroupLayoutDescriptor,
   type PipelineGroup2Contract,
   resolvePipelineGroup2Contract,
+  SKIN_MATERIAL_SHADER_ID,
 } from '../pbr-pipeline';
 import { STANDARD_CLUSTER_MEMBERSHIP_WGSL } from '../pipeline/standard-pipeline';
 import { inspectStandardBloomGraph } from '../pipeline/standard-post';
@@ -80,6 +85,8 @@ import type { BloomPersistentBundle } from '../record/render-context';
 import { SHADOW_CASTER_BUFFER_SIZE } from '../record/shadow-pass';
 import { POINTS_LINES_VIEW_BUFFER_SIZE } from '../record/view-ubo';
 import {
+  type AtmosphereShaderSources,
+  type SsrShaderSources,
   STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
   type VolumetricFogShaderSources,
 } from '../render-contract';
@@ -111,14 +118,15 @@ import {
   selectProbePrewarmVariants,
   selectStandardPbrTransmissionPrewarmVariants,
 } from './shader-prewarm-policy';
+import { buildGpuDrivenPbrReadyLayouts, buildGpuDrivenPbrReadyModules } from './webgpu-pbr-ready';
 import {
   BLUR_PARAMS_BYTES,
   BRIGHT_PARAMS_BYTES,
   COMPOSITE_PARAMS_BYTES,
   HDR_COLOR_ATTACHMENT_FORMAT,
-  MIPMAP_PREWARM_FORMATS,
   VIEW_UBO_BYTES,
 } from './webgpu-ready-contract';
+import { prewarmMipmapPipeline } from './webgpu-ready-mipmap';
 
 /**
  * Build the `Renderer.initialization` Promise (D-S3 three-step strict-serial chain).
@@ -160,6 +168,7 @@ export async function buildReadyWebGPU(
    * frame while the shared async shader adapter is still warming up.
    */
   requiredMaterialShaders: readonly string[],
+  standardPbrShaderUvSetCount: number,
   /** Fullscreen feature modules compiled before the first synchronous frame. */
   requiredFullscreenPostProcesses: readonly {
     readonly identity: string;
@@ -215,12 +224,22 @@ export async function buildReadyWebGPU(
   }) => void,
   /** Install manifest-owned volume utility sources only after all four modules compile. */
   setVolumetricFogShaderSources: (sources: VolumetricFogShaderSources) => void,
+  /** Install manifest-owned SSR utility sources only after all five modules compile. */
+  setSsrShaderSources: (sources: SsrShaderSources) => void,
+  /** Install manifest-owned atmosphere utility sources only after all modules compile. */
+  setAtmosphereShaderSources: (sources: AtmosphereShaderSources) => void,
 ): Promise<PipelineState> {
   const extendedLightingShaderAvailable = deriveExtendedLightingCapability(rhiDevice).admitted;
-  // Shader layouts and record-stage buffer usage share the RHI capability.
-  // Backend names and numeric limits must not independently re-enable storage.
-  const storageBufferCapable = rhiDevice.caps.storageBuffer;
+  // Shader and layout construction consume the same storage capability.
+  const capValue = (rhiDevice.limits as Readonly<Record<string, number>>)
+    .maxStorageBuffersPerShaderStage;
   const webgl2Downlevel = rhiDevice.caps.backendKind === 'wgpu-webgl2';
+  let storageBufferCapable = !webgl2Downlevel && rhiDevice.caps.storageBuffer;
+  if (typeof capValue === 'number') {
+    const capCheck = assertStorageBufferCap(capValue);
+    storageBufferCapable =
+      capCheck.ok && !webgl2Downlevel && rhiDevice.caps.storageBuffer && capCheck.value;
+  }
   const directionalPcssAvailable =
     rhiDevice.caps.backendKind === 'webgpu' || rhiDevice.caps.backendKind === 'wgpu-native';
   const projectorAvailable =
@@ -292,6 +311,8 @@ export async function buildReadyWebGPU(
     manifestEntries.push(entry);
   }
   let pbrModule: ShaderModule | null = null;
+  let pbrSkinModule: ShaderModule | null = null;
+  let gpuDrivenPbrPrograms: ReadonlyMap<string, GpuDrivenPbrProgram> = new Map();
   let unlitModule: ShaderModule | null = null;
   let spriteModule: ShaderModule | null = null;
   let spriteLitModule: ShaderModule | null = null;
@@ -339,6 +360,9 @@ export async function buildReadyWebGPU(
     //     brdfLutBake_fs) which survive naga_oil composition unchanged.
     //   - unlit.wgsl: none of the above markers → falls into the unlit slot.
     let pbrEntry = findEngineManifestEntry('forgeax::default-standard-pbr');
+    let pbrSkinEntry =
+      findEngineManifestEntry(SKIN_MATERIAL_SHADER_ID) ??
+      findEngineManifestEntry('forgeax::default-standard-pbr-skin');
     let unlitEntry = findEngineManifestEntry('forgeax::default-unlit');
     let tonemapEntry: ManifestEntry | undefined;
     let motionBlurEntry: ManifestEntry | undefined;
@@ -356,6 +380,7 @@ export async function buildReadyWebGPU(
     let iblIrradianceEntry: ManifestEntry | undefined;
     let iblPrefilterEntry: ManifestEntry | undefined;
     let iblBrdfLutEntry: ManifestEntry | undefined;
+    let probeBackgroundEntry: ManifestEntry | undefined;
     let fxaaEntry: ManifestEntry | undefined;
     let skyboxEntry: ManifestEntry | undefined;
     let bloomBrightEntry: ManifestEntry | undefined;
@@ -411,6 +436,10 @@ export async function buildReadyWebGPU(
         iblBrdfLutEntry ??= entry;
         continue;
       }
+      if (entry.wgsl.includes('probe_background_fs')) {
+        probeBackgroundEntry ??= entry;
+        continue;
+      }
       if (entry.wgsl.includes('f_schlick')) {
         pbrEntry ??= entry;
         continue;
@@ -492,6 +521,7 @@ export async function buildReadyWebGPU(
         const exact = ms.variants.find(
           (v) =>
             v.defines.STORAGE_BUFFER_AVAILABLE === false &&
+            v.defines.COVERAGE_ONLY !== true &&
             (!('CLUSTER_FORWARD_AVAILABLE' in v.defines) ||
               v.defines.CLUSTER_FORWARD_AVAILABLE === false) &&
             (!('VERTEX_COLOR_AVAILABLE' in v.defines) ||
@@ -534,6 +564,7 @@ export async function buildReadyWebGPU(
       const exact = ms.variants.find(
         (variant) =>
           variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+          variant.defines.COVERAGE_ONLY !== true &&
           (!('CLUSTER_FORWARD_AVAILABLE' in variant.defines) ||
             variant.defines.CLUSTER_FORWARD_AVAILABLE === false) &&
           (!('VERTEX_COLOR_AVAILABLE' in variant.defines) ||
@@ -562,6 +593,12 @@ export async function buildReadyWebGPU(
       return wgsl !== undefined ? { ...entry, wgsl } : entry;
     };
     pbrEntry = patchRuntimeVariant(pbrEntry, 'forgeax::default-standard-pbr');
+    if (pbrSkinEntry !== undefined) {
+      pbrSkinEntry = patchRuntimeVariant(
+        patchRuntimeVariant(pbrSkinEntry, SKIN_MATERIAL_SHADER_ID),
+        'forgeax::default-standard-pbr-skin',
+      );
+    }
     unlitEntry = patchRuntimeVariant(unlitEntry, 'forgeax::default-unlit');
     if (shadowCasterEntry !== undefined) {
       shadowCasterEntry = patchRuntimeVariant(shadowCasterEntry, 'forgeax::default-shadow-caster');
@@ -606,13 +643,7 @@ export async function buildReadyWebGPU(
         }
       }
     }
-    // Wire composed IBL shaders into IblPipelineCache before the cache's
-    // createIblPipelines runs (called downstream by the internal
-    // GpuResidencyCache equirect-to-cubemap projection during the first Skylight
-    // dispatch). When all 4 are present, register them; otherwise leave
-    // the cache untouched (charter F1: tests / non-IBL hosts that ship
-    // empty / 3-entry manifests still boot, and the IBL pipeline cache's
-    // own error surfacing covers the "missing" case downstream).
+    // Publish the generation's compiled IBL programs before resource preparation.
     if (
       iblEquirectEntry !== undefined &&
       iblIrradianceEntry !== undefined &&
@@ -624,6 +655,9 @@ export async function buildReadyWebGPU(
         irradiance: iblIrradianceEntry.wgsl,
         prefilter: iblPrefilterEntry.wgsl,
         brdfLut: iblBrdfLutEntry.wgsl,
+        ...(probeBackgroundEntry === undefined
+          ? {}
+          : { probeBackground: probeBackgroundEntry.wgsl }),
       });
     }
     // Points/Lines are an engine-owned record path rather than a producer
@@ -675,6 +709,23 @@ export async function buildReadyWebGPU(
       if (!shaderResult.ok) throw shaderResult.error;
       seedShaderModule(label, shaderResult.value);
     }
+    const compileUtilityShader = async (
+      label: string,
+      source: string,
+      context: string,
+    ): Promise<ShaderModule> => {
+      const result = await runShimStep(
+        () =>
+          asyncCreateShaderModule
+            ? asyncCreateShaderModule(rhiDevice, { code: source, label })
+            : invokeDeviceCreateShaderModule(rhiDevice, { code: source, label }),
+        'shader-compile-failed',
+        `${context} shader module '${label}' compiled`,
+        `inspect manifest WGSL for '${label}' and check device.features`,
+      );
+      if (!result.ok) throw result.error;
+      return result.value;
+    };
     if (rhiDevice.caps.compute && rhiDevice.caps.storageTexture) {
       const volumeSources = [
         ['inject', 'volume_inject', (source: string) => source.includes('fn volume_inject(')],
@@ -709,17 +760,12 @@ export async function buildReadyWebGPU(
         }> = [];
         for (const { stage, label, entry } of resolved) {
           if (entry === undefined) throw new Error(`missing volumetric shader ${label}`);
-          const shaderResult = await runShimStep(
-            () =>
-              asyncCreateShaderModule
-                ? asyncCreateShaderModule(rhiDevice, { code: entry.wgsl, label })
-                : invokeDeviceCreateShaderModule(rhiDevice, { code: entry.wgsl, label }),
-            'shader-compile-failed',
-            `volumetric fog shader module '${label}' compiled`,
-            `inspect manifest WGSL for '${label}' and check device.features`,
-          );
-          if (!shaderResult.ok) throw shaderResult.error;
-          compiled.push({ stage, label, source: entry.wgsl, module: shaderResult.value });
+          compiled.push({
+            stage,
+            label,
+            source: entry.wgsl,
+            module: await compileUtilityShader(label, entry.wgsl, 'volumetric fog'),
+          });
         }
         for (const { label, module } of compiled) seedShaderModule(label, module);
         setVolumetricFogShaderSources({
@@ -730,6 +776,20 @@ export async function buildReadyWebGPU(
         });
       }
     }
+    if (rhiDevice.caps.compute && rhiDevice.caps.storageTexture) {
+      const sources = await prewarmSsrShaders(
+        manifestEntries,
+        (label, source) => compileUtilityShader(label, source, 'SSR'),
+        seedShaderModule,
+      );
+      if (sources !== undefined) setSsrShaderSources(sources);
+    }
+    const atmosphereSources = await prewarmAtmosphereShaders(
+      manifestEntries,
+      (label, source) => compileUtilityShader(label, source, 'Atmosphere'),
+      seedShaderModule,
+    );
+    if (atmosphereSources !== undefined) setAtmosphereShaderSources(atmosphereSources);
     const pbrShaderResult = await runShimStep(
       () =>
         asyncCreateShaderModule
@@ -751,6 +811,27 @@ export async function buildReadyWebGPU(
     const pbrManifestEntry = [...registry.materialShaderManifestEntries()].find(
       (entry) => entry.identifier === 'forgeax::default-standard-pbr',
     );
+    const pbrSkinManifestEntry =
+      [...registry.materialShaderManifestEntries()].find(
+        (entry) => entry.identifier === SKIN_MATERIAL_SHADER_ID,
+      ) ??
+      [...registry.materialShaderManifestEntries()].find(
+        (entry) => entry.identifier === 'forgeax::default-standard-pbr-skin',
+      );
+    const gpuDrivenModules = await buildGpuDrivenPbrReadyModules({
+      device: rhiDevice,
+      storageBufferCapable,
+      asyncCreateShaderModule,
+      pbrSkinEntry,
+      pbrManifestEntry,
+      pbrSkinManifestEntry,
+      extendedLightingShaderAvailable,
+      directionalPcssAvailable,
+      projectorAvailable,
+      seedShaderModule,
+    });
+    pbrSkinModule = gpuDrivenModules.pbrSkinModule;
+    gpuDrivenPbrPrograms = gpuDrivenModules.gpuDrivenPbrPrograms;
     const pbrVariant = pbrManifestEntry?.variants.find(
       (variant) => variant.composedWgsl === pbrEntry.wgsl,
     );
@@ -903,7 +984,8 @@ export async function buildReadyWebGPU(
     const coloredUnlitVariant = unlitManifestEntry?.variants.find(
       (variant) =>
         variant.defines.VERTEX_COLOR_AVAILABLE === true &&
-        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable,
+        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+        variant.defines.COVERAGE_ONLY !== true,
     );
     if (coloredUnlitVariant !== undefined && coloredUnlitVariant.composedWgsl !== unlitEntry.wgsl) {
       const coloredUnlitShaderResult = await runShimStep(
@@ -930,7 +1012,8 @@ export async function buildReadyWebGPU(
     const uncoloredUnlitVariant = unlitManifestEntry?.variants.find(
       (variant) =>
         variant.defines.VERTEX_COLOR_AVAILABLE === false &&
-        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable,
+        variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
+        variant.defines.COVERAGE_ONLY !== true,
     );
     if (uncoloredUnlitVariant !== undefined) {
       seedShaderModule(
@@ -1328,7 +1411,10 @@ export async function buildReadyWebGPU(
     // feat-20260612-hdrp-ssao M6 / w27: SSAO shader module compilation.
     // Optional manifest entry — absent on legacy manifests (zero-overhead
     // opt-out, same as bloom). Identified by 'fs_ssao_calc' content marker.
-    if (ssaoEntry !== undefined) {
+    // The GLES translator cannot read raw depth through this SSAO program.
+    // Keep optional AO out of fallback startup; requesting it is refused by
+    // the record owner instead of breaking every AO-disabled renderer.
+    if (ssaoEntry !== undefined && !webgl2Downlevel) {
       const entry = ssaoEntry;
       const ssaoShaderResult = await runShimStep(
         () =>
@@ -1377,6 +1463,9 @@ export async function buildReadyWebGPU(
           storageBuffer: storageBufferCapable,
           extendedLighting: extendedLightingShaderAvailable,
           projectorAvailable,
+          transmissionBackdrop: transmissionBackdropAvailable(
+            rhiDevice.limits.maxSampledTexturesPerShaderStage,
+          ),
         }),
       ),
     'webgpu-runtime-error',
@@ -1402,6 +1491,7 @@ export async function buildReadyWebGPU(
   // (URP layout) so the manifest entry's URP variant WGSL still builds a
   // valid PSO instead of hard-disabling the entire HDRP-variant build path.
   let hdrpPbrPipelineLayoutHandle: PipelineLayout | null = null;
+  let hdrpMeshBindGroupLayoutHandle: BindGroupLayout | null = null;
   let hdrpProbePbrPipelineLayoutHandle: PipelineLayout | null = null;
   // The cluster layout is storage-buffer backed. On the WebGL2/fallback
   // capability tier its uniform-buffer projection exceeds the backend's
@@ -1410,6 +1500,7 @@ export async function buildReadyWebGPU(
     const hdrpUnifiedBglDesc = createHdrpBindGroupLayoutDescriptor();
     const hdrpUnifiedBglRes = rhiDevice.createBindGroupLayout(hdrpUnifiedBglDesc);
     if (hdrpUnifiedBglRes.ok) {
+      hdrpMeshBindGroupLayoutHandle = hdrpUnifiedBglRes.value;
       const hdrpPlRes = rhiDevice.createPipelineLayout({
         label: 'hdrp-pbr-pl',
         bindGroupLayouts: [
@@ -1487,45 +1578,16 @@ export async function buildReadyWebGPU(
     }
   }
 
-  // bug-20260611-skin-pipeline-layout-mesh-array-bgl-2bindings: boot-time
-  // build of the skin-variant PipelineLayout. Mirrors the HDRP block above
-  // (D-2 / D-3 in plan-strategy): reuse view / material / instances BGLs
-  // from `pbrLayouts` and only create a 2-entry mesh-array BGL (binding 0
-  // meshes + binding 1 palette) so the `forgeax::pbr-skin` shader's
-  // `@group(2) @binding(1) palette` declaration validates. Stays null when
-  // createBindGroupLayout / createPipelineLayout fails;
-  // selectPipelineLayoutForVariant returns null in that case (charter P3
-  // explicit failure -- no silent fallback to URP layout, mirroring memory
-  // anchor `hdrp-active-must-not-fallback-to-urp-pipeline`).
-  let pbrSkinPipelineLayoutHandle: PipelineLayout | null = null;
-  let pbrSkinProbePipelineLayoutHandle: PipelineLayout | null = null;
-  // feat-20260611 R2 / M8 / w28: capture the 2-binding skin mesh-array BGL
-  // produced by `buildPbrSkinLayouts` so the record stage can build a BG
-  // matching `pbr-skin-pl` (pipeline-layout BGL[2] is this 2-entry skin
-  // BGL, NOT the 1-entry `pbr-mesh-array-bgl`). The BGL handle stays null
-  // when the skin pipeline layout itself failed to build, keeping the skin
-  // path explicitly disabled (charter P3 — record-stage falls back to URP
-  // path which is correct for non-skin entries; skin entries hit the
-  // explicit-failure branch).
-  let pbrSkinMeshBindGroupLayoutHandle: BindGroupLayout | null = null;
+  const {
+    pbrSkinPipelineLayout: pbrSkinPipelineLayoutHandle,
+    pbrSkinProbePipelineLayout: pbrSkinProbePipelineLayoutHandle,
+    pbrSkinMeshBindGroupLayout: pbrSkinMeshBindGroupLayoutHandle,
+    gpuDrivenInstancesBindGroupLayout: gpuDrivenInstancesBindGroupLayoutHandle,
+    gpuDrivenPbrPipelineLayout: gpuDrivenPbrPipelineLayoutHandle,
+    gpuDrivenPbrSkinPipelineLayout: gpuDrivenPbrSkinPipelineLayoutHandle,
+  } = buildGpuDrivenPbrReadyLayouts(rhiDevice, storageBufferCapable, pbrLayouts.value);
   let hdrpSkinPipelineLayoutHandle: PipelineLayout | null = null;
   let hdrpSkinMeshBindGroupLayoutHandle: BindGroupLayout | null = null;
-  {
-    const skinLayoutsResult = runShimSyncStep(
-      () =>
-        ok(
-          buildPbrSkinLayouts(rhiDevice, { storageBuffer: storageBufferCapable }, pbrLayouts.value),
-        ),
-      'webgpu-runtime-error',
-      'buildPbrSkinLayouts succeeded',
-      'check device.limits.maxBindingsPerBindGroup (need >=14) and maxBindGroupsPerPipelineLayout',
-    );
-    if (skinLayoutsResult.ok) {
-      pbrSkinPipelineLayoutHandle = skinLayoutsResult.value.pipelineLayout;
-      pbrSkinProbePipelineLayoutHandle = skinLayoutsResult.value.probePipelineLayout;
-      pbrSkinMeshBindGroupLayoutHandle = skinLayoutsResult.value.meshArrayBgl;
-    }
-  }
   if (storageBufferCapable) {
     const skinBglResult = rhiDevice.createBindGroupLayout(
       createHdrpSkinBindGroupLayoutDescriptor(),
@@ -1733,6 +1795,13 @@ export async function buildReadyWebGPU(
     // M-3 / w12: builtin direct-upload fallback path mirrors the gpuStore
     // mesh entry shape -- raw RHI Buffer handles are wrapped in GpuBuffer so
     // the dispose chain (M-5) can walk them via `.destroy()`.
+    const layoutProjection = deriveVertexLayoutProjection(asset.attributes);
+    const vertexCount = deriveVertexCount(asset.vertices, layoutProjection);
+    if (vertexCount === undefined) {
+      throw new Error(
+        `builtin mesh ${id} has vertex bytes that do not match its layout projection`,
+      );
+    }
     meshHandles.set(id, {
       vertexBuffer: new GpuBuffer(rhiDevice, vboResult.value),
       indexBuffer: ibo === null ? null : new GpuBuffer(rhiDevice, ibo),
@@ -1740,17 +1809,10 @@ export async function buildReadyWebGPU(
       iboBytes: meshIndices === undefined ? 0 : indexBytes,
       indexCount: meshIndices?.length ?? 0,
       indexFormat: meshIndices instanceof Uint32Array ? 'uint32' : 'uint16',
-      // bug-20260519: BUILTIN_CUBE / BUILTIN_TRIANGLE migrated to 12F
-      // (position + normal + uv + tangent), so the fallback literal mirrors
-      // every other mesh upload site.
-      layout: '12F',
-      layoutProjection: deriveVertexLayoutProjection(asset.attributes),
+      layoutProjection,
       // BUILTIN_CUBE / BUILTIN_TRIANGLE are single-UV (set 0 only).
       uvSetCount: 1,
-      vertexCount:
-        asset.vertices.length /
-        (deriveVertexLayoutProjection(asset.attributes).arrayStride /
-          Float32Array.BYTES_PER_ELEMENT),
+      vertexCount,
       indexed: meshIndices !== undefined,
       topology: asset.submeshes[0]?.topology ?? 'triangle-list',
       submeshes: asset.submeshes,
@@ -1968,22 +2030,6 @@ export async function buildReadyWebGPU(
   );
   if (!defaultSamplerResult.ok) throw defaultSamplerResult.error;
 
-  const nearestSamplerResult = runShimSyncStep(
-    () =>
-      rhiDevice.createSampler({
-        label: 'nearest-sampler',
-        magFilter: 'nearest',
-        minFilter: 'nearest',
-        mipmapFilter: 'nearest',
-        addressModeU: 'clamp-to-edge',
-        addressModeV: 'clamp-to-edge',
-      }),
-    'webgpu-runtime-error',
-    'createSampler (nearest) succeeded',
-    'check device.limits.maxSamplersPerShaderStage',
-  );
-  if (!nearestSamplerResult.ok) throw nearestSamplerResult.error;
-
   // feat-20260520-directional-light-shadow-mapping M1c / w8 + M2 / w14:
   // shadow comparison sampler — clamp-to-edge, linear filter, compare:'less'.
   // Used for shadow map sampling in M2/M3 and shadow depth pass. comparison
@@ -2070,9 +2116,9 @@ export async function buildReadyWebGPU(
     extendedLightingShaderAvailable,
   );
 
-  // Normal-slot fallback: 1x1 RGBA8 (128, 128, 255, 255). pbr.wgsl decodes
-  // sample.rg * 2 - 1 + z = sqrt(1 - x^2 - y^2), so RG=(128,128)=0.5 maps
-  // to tangent (0, 0, 1) -- zero perturbation when normalTexture is absent.
+  // A declared normal map that is not ready needs an exactly neutral sample.
+  // RGBA8 cannot encode 0.5: 128/255 perturbs the reflected ray even on a
+  // perfectly flat surface. Half float stores (0.5, 0.5, 1, 1) exactly.
   // Cannot share the white fallback (255,255,...) because RG=(255,255)=1.0
   // gives tangent.xy=(1,1) -> 1 - 2 = -1 under the sqrt -> NaN (saturate
   // clamps to 0 z=0, still wrong). White-on-missing semantics for baseColor
@@ -2086,7 +2132,7 @@ export async function buildReadyWebGPU(
         mipLevelCount: 1,
         sampleCount: 1,
         dimension: '2d',
-        format: 'rgba8unorm',
+        format: 'rgba16float',
         usage: GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_COPY_DST,
         viewFormats: [],
         textureBindingViewDimension: undefined,
@@ -2098,10 +2144,7 @@ export async function buildReadyWebGPU(
   if (!fallbackNormalTextureResult.ok) throw fallbackNormalTextureResult.error;
 
   const fallbackNormalPixel = new Uint8Array(FALLBACK_BYTES_PER_ROW);
-  fallbackNormalPixel[0] = 128;
-  fallbackNormalPixel[1] = 128;
-  fallbackNormalPixel[2] = 255;
-  fallbackNormalPixel[3] = 255;
+  new Uint16Array(fallbackNormalPixel.buffer).set([0x3800, 0x3800, 0x3c00, 0x3c00]);
   const fallbackNormalWriteResult = runShimSyncStep(
     () =>
       queue.writeTexture(
@@ -2650,9 +2693,10 @@ export async function buildReadyWebGPU(
   //     - fragment.targets[0].blend: premultiplied alpha (vs no blend)
   //     - depthStencil.depthWriteEnabled: false (vs true)
   //     - depthStencil.depthCompare: 'less-equal' (vs 'less')
-  //   The vertex stride stays 12F (HANDLE_QUAD passes through the same
-  //   12-float interleaved layout as procedural meshes), so no new vertex
-  //   pipeline branch is needed in the record stage (plan-strategy §3 RT4).
+  //   The vertex stride comes from the geometry-owned projection (HANDLE_QUAD
+  //   passes through the same 12-float interleaved layout as procedural meshes),
+  //   so no new vertex pipeline branch is needed in the record stage
+  //   (plan-strategy §3 RT4).
   //
   // Premultiplied alpha blend op (`{ srcFactor: 'one', dstFactor:
   // 'one-minus-src-alpha', operation: 'add' }`) is the industry-default for
@@ -3833,37 +3877,14 @@ export async function buildReadyWebGPU(
     }
   }
 
-  // feat-20260601-device/gpu-residency-extraction M1 (D-9 sub-contract 1): prewarm
-  // the mipmap pipeline cache for the smoke texture formats while still on the
-  // async `renderer.initialization` path. This builds the one-time mipmap shader module +
-  // per-format pipeline into the deviceCache so the record-stage texture
-  // ensureResident (sync) reproduces the pre-extraction async uploadTexture
-  // byte-for-byte without an async stall in the synchronous draw frame. A build
-  // failure here is surfaced through ready's reject channel (structured RhiError).
-  //
-  // Gated on `manifestEntries.length > 0` (the same Camera-only / clear-pass
-  // skip as the Step-2 pipeline compile, bug-20260519 D-3): a zero-manifest
-  // world renders no material geometry, so no texture is ever made resident and
-  // the mipmap shader-module build (a `createShaderModule` call) must not fire
-  // -- preserving the zero-manifest "0 createShaderModule" invariant
-  // (renderer-ready.test.ts AC-02).
-  if (manifestEntries.length > 0) {
-    const prewarmRes = await gpuStore.prewarmMipmapPipeline(rhiDevice, MIPMAP_PREWARM_FORMATS);
-    if (!prewarmRes.ok) throw prewarmRes.error;
-  }
+  await prewarmMipmapPipeline(rhiDevice, gpuStore, manifestEntries.length > 0);
 
   const pipelineState: PipelineState = {
     device: rhiDevice,
-    // feat-20260518-pbr-direct-lighting-mvp M5 / w22.10 (AC-06 dual->triple
-    // pipeline + D-2 + D-10): three distinct GPU render-pipeline handles
-    // backed by 2 distinct shader modules (unlit + pbr) x 2 vertex stride
-    // configurations (6F builtin + 12F procedural; the 6F + pbr combination
-    // does not exist per D-2). All three share the identical 4-BindGroupLayout
-    // chain so material BG entries built once compose for each of the three
-    // pipelines (charter P5 consistent abstraction). The legacy `pipeline`
-    // alias field has been retired; consumers select per
-    // (mat.materialShaderId, mesh.layout) tuple via the record-stage three-way
-    // setPipeline branch (w22.11).
+    // The ready state keeps one canonical mesh vertex projection from the
+    // geometry owner. Material selection and feature layout identity are
+    // derived from that projection; no legacy stride discriminator participates
+    // in pipeline or record routing.
     // bug-20260519: BUILTIN cube migrated to 12F so the legacy
     // `unlitBuiltinPipeline` (+ its zero-stride `unlitBuiltinDummyAttrBuffer`)
     // is gone; consumers pick per `mat.materialShaderId` only via the record-stage
@@ -3876,6 +3897,9 @@ export async function buildReadyWebGPU(
     // (see definition near SPEC_CONST boot-time pre-warm block above)
     unlitPipeline: getCachedPipelineOrNull('forgeax::default-unlit', false, 1),
     standardPipeline: getCachedPipelineOrNull('forgeax::default-standard-pbr', false, 1),
+    standardPbrShaderModule: pbrModule,
+    pbrSkinShaderModule: pbrSkinModule,
+    standardPbrShaderUvSetCount,
     unlitPipelineMsaa: getCachedPipelineOrNull('forgeax::default-unlit', false, 4),
     // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w14 (D-7):
     // four sprite-dedicated boot-time pre-warms are gone. Sprite PSO now
@@ -3893,9 +3917,17 @@ export async function buildReadyWebGPU(
     // standard pipeline fields above).
     pbrPipelineLayout:
       unlitModule !== null && pbrModule !== null ? pipelineLayoutResult.value : null,
+    gpuDrivenInstancesBindGroupLayout:
+      unlitModule !== null && pbrModule !== null ? gpuDrivenInstancesBindGroupLayoutHandle : null,
+    gpuDrivenPbrPipelineLayout:
+      unlitModule !== null && pbrModule !== null ? gpuDrivenPbrPipelineLayoutHandle : null,
+    gpuDrivenPbrPrograms,
+    gpuDrivenPbrSkinPipelineLayout:
+      unlitModule !== null && pbrModule !== null ? gpuDrivenPbrSkinPipelineLayoutHandle : null,
     // HDRP variant uses the unified group(2) layout built above.
     hdrpPbrPipelineLayout:
       unlitModule !== null && pbrModule !== null ? hdrpPbrPipelineLayoutHandle : null,
+    hdrpMeshBindGroupLayout: hdrpMeshBindGroupLayoutHandle,
     hdrpProbePbrPipelineLayout:
       unlitModule !== null && pbrModule !== null ? hdrpProbePbrPipelineLayoutHandle : null,
     hdrpClusterMembershipPipeline,
@@ -3937,11 +3969,9 @@ export async function buildReadyWebGPU(
     probeInstancesBindGroupLayout: probeInstancesBglResult.value,
     identityInstanceBuffer: identityInstanceResult.value,
     defaultSampler: defaultSamplerResult.value,
-    nearestSampler: nearestSamplerResult.value,
     fallbackTextureView: fallbackTextureViewResult.value,
     defaultWhiteTextureView: fallbackTextureViewResult.value,
-    // Normal-slot fallback view (1x1 RGBA8 (128,128,255,255)). RG=(128,128)
-    // decodes to tangent (0,0,1) under pbr.wgsl's RG-only normal decoder.
+    // Exactly neutral half-float RG=(0.5,0.5) decodes to tangent (0,0,1).
     // Distinct from defaultWhiteTextureView because RG=(255,255)=1.0 gives
     // sqrt(1 - 1 - 1) = NaN, breaking the no-normal-map case.
     defaultNormalTextureView: fallbackNormalTextureViewResult.value,

package/src/assembly/webgpu-renderer-bootstrap.ts

@@ -0,0 +1,85 @@
+import type { RhiCanvasContext, RhiDevice } from '@forgeax/engine-rhi';
+import {
+  HealthListenerRegistry,
+  LostListenerRegistry,
+  RhiErrorListenerRegistry,
+} from '../lifecycle';
+import type { RendererOptions } from '../render-contract';
+import type { RhiBackendPack } from './backend-contract';
+import type { BundlerOptions } from './bundler-contract';
+import { deviceOptionsForAdapter } from './device-feature-admission';
+import type { RendererAssemblyImplementation } from './host-contract';
+import { attachDeviceLostFanout } from './recovery/device-loss-fanout';
+import type { WebGPUOutcome, WebGPURendererInternals } from './webgpu-renderer-contract';
+
+export type { WebGPUOutcome, WebGPURendererInternals } from './webgpu-renderer-contract';
+
+export type WebGPURendererFactory = (
+  internals: WebGPURendererInternals,
+) => Promise<RendererAssemblyImplementation>;
+
+/** Acquire the selected backend and build one renderer generation. */
+export async function tryCreateWebGPURenderer(
+  canvas: HTMLCanvasElement | OffscreenCanvas,
+  options: RendererOptions | undefined,
+  pack: RhiBackendPack,
+  bundler: BundlerOptions | undefined,
+  createRenderer: WebGPURendererFactory,
+): Promise<WebGPUOutcome> {
+  const importTransport = bundler?.importTransport;
+  const adapterResult = await pack.rhi.requestAdapter(undefined, canvas);
+  if (!adapterResult.ok) return { kind: 'rhi-err', error: adapterResult.error };
+  const adapter = adapterResult.value;
+  const deviceOpts = deviceOptionsForAdapter(adapter, options);
+  const result = await adapter.requestDevice(deviceOpts);
+  if (!result.ok) return { kind: 'rhi-err', error: result.error };
+  const device: RhiDevice = result.value;
+  const ctxResult = pack.rhi.acquireCanvasContext(canvas);
+  if (!ctxResult.ok) return { kind: 'rhi-err', error: ctxResult.error };
+  const context: RhiCanvasContext = ctxResult.value;
+
+  const lostRegistry = new LostListenerRegistry();
+  const errorRegistry = new RhiErrorListenerRegistry();
+  const healthRegistry = new HealthListenerRegistry();
+  const lossObserver: { current?: (detail: string) => void } = {};
+  const generationState: { current: number; onStaleLoss?: () => void } = { current: 0 };
+  attachDeviceLostFanout(device, pack, {
+    lostRegistry,
+    errorRegistry,
+    healthRegistry,
+    generation: 0,
+    currentGeneration: () => generationState.current,
+    onStaleLoss: () => generationState.onStaleLoss?.(),
+    onDeviceLost: (detail) => lossObserver.current?.(detail),
+  });
+
+  if (pack._internal_getRawDevice && pack.translateErrorEventToRhiError) {
+    const backendDevice = pack._internal_getRawDevice(device);
+    if (backendDevice && typeof backendDevice === 'object') {
+      const target = backendDevice as {
+        onuncapturederror?: ((event: unknown) => void) | null;
+      };
+      target.onuncapturederror = (event: unknown): void => {
+        const translated = pack.translateErrorEventToRhiError?.(event);
+        if (translated && !translated.ok) errorRegistry.fire(translated.error);
+      };
+    }
+  }
+  return {
+    kind: 'ok',
+    renderer: await createRenderer({
+      canvas,
+      device,
+      context,
+      options,
+      bundler,
+      lostRegistry,
+      errorRegistry,
+      healthRegistry,
+      pack,
+      importTransport,
+      lossObserver,
+      generationState,
+    }),
+  };
+}