@forgeax/engine-render 0.1.27 → 0.1.29

package/src/assembly/webgpu-ready.ts

@@ -1,3 +1,4 @@
+import type { GpuDrivenPbrProgram } from '../gpu-driven/pbr-program';
 // 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 +11,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 +27,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 +57,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 +84,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 +117,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 +167,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 +223,29 @@ 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 both 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;
+  // bug-20260610: WebGL2 fallback path — read storage-buffer capability up
+  // front so both Step 2 (shader-module compile, where we patch engine
+  // entries to the STORAGE_BUFFER_AVAILABLE=false variant) and Step 3
+  // (buildPbrPipelineLayouts, which switches between read-only-storage
+  // and uniform BGL entries) walk the same axis. Step 0 already ran in
+  // `prepareMaterialShaders`; this is an idempotent re-read driven by
+  // `device.limits.maxStorageBuffersPerShaderStage`, which is 0 on the
+  // wgpu-wasm WebGL2 backend (downlevel_webgl2_defaults).
+  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 +317,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 +366,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;
@@ -562,6 +592,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');
@@ -675,6 +711,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 +762,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 +778,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 +813,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,
     );
@@ -1487,45 +1570,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 +1787,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 +1801,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 +2022,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 +2108,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 +2124,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 +2136,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 +2685,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 +3869,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 +3889,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,6 +3909,13 @@ 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,
@@ -3937,11 +3960,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,
+    }),
+  };
+}

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

@@ -0,0 +1,69 @@
+import type { RhiCanvasContext, RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import type { ImportTransport } from '@forgeax/engine-types';
+import type { RenderFeatureHost } from '../features/host';
+import type {
+  HealthListenerRegistry,
+  LostListenerRegistry,
+  RhiErrorListenerRegistry,
+} from '../lifecycle';
+import type { GpuPassTimingReason } from '../record/gpu-pass-timing/errors.js';
+import type {
+  GpuPassTimingCapture,
+  GpuPassTimingFrameIdentity,
+} from '../record/gpu-pass-timing/index.js';
+import type {
+  AtmosphereShaderSources,
+  FrameObservationDomain,
+  RenderDebugOverlay,
+  RendererOptions,
+  SsrShaderSources,
+  VolumetricFogShaderSources,
+} from '../render-contract';
+import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
+import type { RhiBackendPack } from './backend-contract';
+import type { BundlerOptions } from './bundler-contract';
+import type { RendererAssemblyImplementation } from './host-contract';
+import type { MeshSsboGrowResult, MeshSsboState } from './mesh-ssbo-grow';
+
+export type WebGPUOutcome =
+  | { kind: 'ok'; renderer: RendererAssemblyImplementation }
+  | { kind: 'rhi-err'; error: RhiError }
+  | { kind: 'throw'; error: Error };
+
+export interface WebGPURendererInternals {
+  canvas: HTMLCanvasElement | OffscreenCanvas;
+  device: RhiDevice;
+  context: RhiCanvasContext;
+  options: RendererOptions | undefined;
+  bundler: BundlerOptions | undefined;
+  lostRegistry: LostListenerRegistry;
+  errorRegistry: RhiErrorListenerRegistry;
+  healthRegistry: HealthListenerRegistry;
+  pack: RhiBackendPack;
+  importTransport?: ImportTransport | undefined;
+  growMeshSsbo?: (neededSlots: number) => MeshSsboGrowResult;
+  meshSsboState?: MeshSsboState;
+  featureHost?: RenderFeatureHost;
+  debugOverlay?: RenderDebugOverlay;
+  volumetricFogShaders?: VolumetricFogShaderSources | undefined;
+  ssrShaders?: SsrShaderSources | undefined;
+  atmosphereShaders?: AtmosphereShaderSources | undefined;
+  gpuPassTimingSubmittedWork?: Promise<void> | undefined;
+  lossObserver: { current?: (detail: string) => void };
+  generationState: {
+    current: number;
+    onStaleLoss?: () => void;
+  };
+  getMaterialShaderUvSetCount?: (materialShaderId: string) => number | undefined;
+  gpuPassTimingFrameIdentity?: GpuPassTimingFrameIdentity | undefined;
+  gpuPassTimingCapture?: GpuPassTimingCapture | undefined;
+  gpuPassTimingBeginReason?: GpuPassTimingReason | undefined;
+  observationCaptureOwner?: {
+    register(capture: TypedFrameObservationCapture): void;
+    consume(frameNumber: number): readonly TypedFrameObservationCapture[];
+    drain(): readonly TypedFrameObservationCapture[];
+  };
+  observationCaptureDomains?: readonly FrameObservationDomain[] | undefined;
+  observationFrameId?: number | undefined;
+  observationGraphGeneration?: number | undefined;
+}

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

@@ -0,0 +1,32 @@
+import type { World } from '@forgeax/engine-ecs';
+import { RendererContractFailureError, RendererOperationError } from '../errors/render';
+
+/**
+ * Derived geometry and voxel physics publish together. A draw is rejected
+ * until that pair has completed its fixed-step writeback, so the renderer
+ * never consumes a half-published World snapshot.
+ */
+export function derivedPhysicsFrameError(
+  worlds: readonly World[],
+): RendererOperationError<'frame-input-invalid'> | undefined {
+  for (const world of worlds) {
+    if (!world.hasResource('PhysicsWorld')) continue;
+    const physics = world.getResource<{
+      readonly getDerivedAdmission?: () => unknown;
+      readonly getDerivedRecoveryState?: () => string;
+    }>('PhysicsWorld');
+    if (
+      physics?.getDerivedAdmission?.() !== undefined ||
+      physics?.getDerivedRecoveryState?.() === 'rebuild-required'
+    ) {
+      return new RendererOperationError('frame-input-invalid', {
+        operation: 'draw',
+        cause: new RendererContractFailureError(
+          'draw',
+          'paired geometry admission must finish physics step and writeback in a healthy World before draw',
+        ),
+      });
+    }
+  }
+  return undefined;
+}