@forgeax/engine-render 0.1.19 → 0.1.20

package/src/assembly/factory.ts

@@ -59,6 +59,7 @@ import type {
 import { err, ok, RhiError, validateDrawArgs } from '@forgeax/engine-rhi';
 import { registerPropagateTransforms } from '@forgeax/engine-scene';
 import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   findVariantByKey,
   type MaterialShaderEntry,
   type MaterialShaderManifestEntry,
@@ -134,6 +135,7 @@ import {
   SPOT_LIGHT_STD430_BYTES,
 } from '../light-buffer-layout';
 import {
+  buildPbrMaterialUserRegionEntries,
   buildPbrPipelineLayouts,
   buildPbrSkinLayouts,
   isSkinnedShadowCasterVariant,
@@ -163,6 +165,7 @@ import {
 } from '../pipeline-spec';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { FrameObservationOptions } from '../record/frame';
+import { GpuTimingCapture, type VolumeTimingObservation } from '../record/gpu-timing';
 import type { BloomPersistentBundle } from '../record/render-context';
 import { SHADOW_CASTER_BUFFER_SIZE } from '../record/shadow-pass';
 import { POINTS_LINES_VIEW_BUFFER_SIZE, VIEW_UNIFORM_BUFFER_SIZE } from '../record/view-ubo';
@@ -185,6 +188,7 @@ import type {
   RenderProfile,
   RenderResult,
   RenderWorldLease,
+  VolumetricFogShaderSources,
 } from '../render-contract';
 import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
 import {
@@ -499,12 +503,15 @@ export function selectHdrpPbrPrewarmVariants(
   manifestEntry: MaterialShaderManifestEntry | undefined,
   storageBufferCapable: boolean,
   transmissionCapable: boolean,
+  projectorAvailable: boolean = true,
 ): readonly MaterialShaderManifestEntry['variants'][number][] {
   return (
     manifestEntry?.variants.filter(
       (variant) =>
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         variant.defines.CLUSTER_FORWARD_AVAILABLE === true &&
+        (!('PROJECTOR_AVAILABLE' in variant.defines) ||
+          variant.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
         (transmissionCapable || variant.defines.TRANSMISSION_AVAILABLE !== true),
     ) ?? []
   );
@@ -518,6 +525,7 @@ export function selectHdrpPbrPrewarmVariants(
 export function selectStandardPbrTransmissionPrewarmVariants(
   manifestEntry: MaterialShaderManifestEntry | undefined,
   storageBufferCapable: boolean,
+  projectorAvailable: boolean = true,
 ): readonly MaterialShaderManifestEntry['variants'][number][] {
   if (manifestEntry === undefined) {
     throw new Error('Standard material shader manifest row is missing');
@@ -529,6 +537,8 @@ export function selectStandardPbrTransmissionPrewarmVariants(
         variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
         variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
         variant.defines.VERTEX_COLOR_AVAILABLE === false &&
+        (!('PROJECTOR_AVAILABLE' in variant.defines) ||
+          variant.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
         variant.defines.TRANSMISSION_AVAILABLE === transmissionAvailable,
     );
     if (declared === undefined) {
@@ -556,6 +566,7 @@ export function selectNoColorPbrVariant(
   manifestEntry: MaterialShaderManifestEntry | undefined,
   storageBufferCapable: boolean,
   variantSet: string | undefined,
+  projectorAvailable: boolean = true,
 ): MaterialShaderManifestEntry['variants'][number] | undefined {
   const hdrpRequested =
     variantSet === '' ||
@@ -565,6 +576,8 @@ export function selectNoColorPbrVariant(
     (variant) =>
       variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
       variant.defines.VERTEX_COLOR_AVAILABLE === false &&
+      (!('PROJECTOR_AVAILABLE' in variant.defines) ||
+        variant.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
       (!('CLUSTER_FORWARD_AVAILABLE' in variant.defines) ||
         variant.defines.CLUSTER_FORWARD_AVAILABLE === hdrpRequested),
   );
@@ -623,6 +636,46 @@ export function resolveMaterialShaderVertexInputContract(
     : 'none';
 }
 
+/**
+ * Decide whether a custom material's user-region can use the shared PBR
+ * bind-group layout. Resource names are not part of a WebGPU layout contract:
+ * the only safe reuse test is that every derived binding in the custom schema
+ * is an identical prefix of the canonical user-region descriptor, including
+ * binding kind and its full shape (sample type, view dimension, sampler mode,
+ * dynamic-offset flags, and visibility). A texture3d/array or comparison /
+ * storage resource must therefore take the per-shader layout path even when
+ * its field count is small.
+ */
+export function isSharedMaterialUserRegionCompatible(
+  paramSchema: readonly ParamSchemaEntry[],
+): boolean {
+  const shared = buildPbrMaterialUserRegionEntries(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
+  const candidate = buildPbrMaterialUserRegionEntries(paramSchema);
+  if (candidate.length > shared.length) return false;
+  return candidate.every((entry, index) => {
+    const canonical = shared[index];
+    if (canonical === undefined) return false;
+    return (
+      JSON.stringify({
+        binding: entry.binding,
+        visibility: entry.visibility,
+        buffer: entry.buffer ?? null,
+        sampler: entry.sampler ?? null,
+        texture: entry.texture ?? null,
+        storageTexture: entry.storageTexture ?? null,
+      }) ===
+      JSON.stringify({
+        binding: canonical.binding,
+        visibility: canonical.visibility,
+        buffer: canonical.buffer ?? null,
+        sampler: canonical.sampler ?? null,
+        texture: canonical.texture ?? null,
+        storageTexture: canonical.storageTexture ?? null,
+      })
+    );
+  });
+}
+
 export function allowsUnlitPreparedFallback(
   depthFormatOverride: GPUTextureFormat | null | undefined,
   vertexLayout: string | undefined,
@@ -727,10 +780,13 @@ export function resolveMaterialShaderVariantSet(
   }>,
   backendKind: RhiDevice['caps']['backendKind'],
   storageBuffer: boolean,
+  projectorAvailable: boolean = true,
 ): string | undefined {
   const declaredAxes = new Set(variants.flatMap((variant) => Object.keys(variant.defines)));
   const declaresCapabilityVariants =
-    declaredAxes.has('WEBGL2_COMPAT') || declaredAxes.has('STORAGE_BUFFER_AVAILABLE');
+    declaredAxes.has('WEBGL2_COMPAT') ||
+    declaredAxes.has('STORAGE_BUFFER_AVAILABLE') ||
+    declaredAxes.has('PROJECTOR_AVAILABLE');
   if (!declaresCapabilityVariants) return requestedVariantSet;
 
   const requested: Record<string, boolean> = {};
@@ -755,7 +811,9 @@ export function resolveMaterialShaderVariantSet(
                   ? requestedVariantSet === '' || (requested[axis] ?? false)
                   : axis === 'TRANSMISSION_AVAILABLE'
                     ? (requested[axis] ?? false)
-                    : (requested[axis] ?? true);
+                    : axis === 'PROJECTOR_AVAILABLE'
+                      ? projectorAvailable
+                      : (requested[axis] ?? true);
   }
   const sorted = Object.entries(filtered).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
   return sorted.every(([, value]) => value)
@@ -951,7 +1009,10 @@ const COMPRESSION_FEATURES: GPUFeatureName[] = [
 // 16; only request the elevated limit when the adapter can provide it.
 const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
 
-function deviceOptionsForAdapter(adapter: Pick<RhiAdapter, 'features' | 'limits'>):
+function deviceOptionsForAdapter(
+  adapter: Pick<RhiAdapter, 'features' | 'limits'>,
+  options?: Pick<RendererOptions, 'captureGpuTimings'>,
+):
   | {
       requiredFeatures?: GPUFeatureName[];
       requiredLimits?: GPUDeviceDescriptor['requiredLimits'];
@@ -961,6 +1022,9 @@ function deviceOptionsForAdapter(adapter: Pick<RhiAdapter, 'features' | 'limits'
   const supportsTransmission =
     (adapter.limits.maxSampledTexturesPerShaderStage ?? 0) >=
     STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
+  if (options?.captureGpuTimings === true && adapter.features.has('timestamp-query')) {
+    requiredFeatures.push('timestamp-query');
+  }
   return {
     ...(requiredFeatures.length > 0 ? { requiredFeatures } : {}),
     ...(supportsTransmission
@@ -1020,7 +1084,7 @@ async function tryCreateWebGPURenderer(
   const adapter = adapterResult.value;
   // M4 w28: filter compression features from adapter.features (AC-07). The
   // same helper is used by recover() below so both paths share one profile.
-  const deviceOpts = deviceOptionsForAdapter(adapter);
+  const deviceOpts = deviceOptionsForAdapter(adapter, options);
   const result = await adapter.requestDevice(deviceOpts);
   if (!result.ok) {
     return { kind: 'rhi-err', error: result.error };
@@ -1150,6 +1214,8 @@ interface WebGPURendererInternals {
    * has wired the controller; identity stable across grow events.
    */
   meshSsboState?: MeshSsboState;
+  /** Device-bound, manifest-owned volumetric utility shader sources. */
+  volumetricFogShaders?: VolumetricFogShaderSources | undefined;
   /** Host-owned producer features; created before device-bound assembly starts. */
   featureHost?: RenderFeatureHost;
   /** App-owned overlay capability read by the typed graph at frame time. */
@@ -1628,6 +1694,18 @@ async function makeWebGPURenderer(
     }
     if (pipelineState === null) return null;
     const paramSchema = lookup.value.paramSchema;
+    // Reuse the shared BGL only when the complete derived resource shape is a
+    // canonical prefix. Field names alone are not a layout contract: a
+    // texture3d/array, comparison sampler, or storage buffer must never be
+    // paired with the PBR texture2d/filtering descriptor by accident.
+    if (isSharedMaterialUserRegionCompatible(paramSchema)) {
+      perShaderMaterialLayoutCache.set(materialShaderId, {
+        source: lookup.value.source,
+        paramSchema,
+        layout: null,
+      });
+      return null;
+    }
     const spec: PipelineSpec = {
       shader: { id: materialShaderId, passKind: 'forward', variantSet: undefined },
       attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
@@ -1674,6 +1752,8 @@ async function makeWebGPURenderer(
         [],
         internals.device.caps.backendKind,
         internals.device.caps.storageBuffer,
+        (internals.device.limits.maxSampledTexturesPerShaderStage ?? 0) >=
+          STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES,
       );
     }
     const variants = manifestEntry.variants;
@@ -1682,13 +1762,17 @@ async function makeWebGPURenderer(
       byRequest = new Map();
       materialShaderVariantResolutionCache.set(variants, byRequest);
     }
-    const cacheKey = `${requestedVariantSet ?? '\u0000'}|${internals.device.caps.backendKind}|${internals.device.caps.storageBuffer ? '1' : '0'}`;
+    const projectorAvailable =
+      (internals.device.limits.maxSampledTexturesPerShaderStage ?? 0) >=
+      STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
+    const cacheKey = `${requestedVariantSet ?? '\u0000'}|${internals.device.caps.backendKind}|${internals.device.caps.storageBuffer ? '1' : '0'}|${projectorAvailable ? '1' : '0'}`;
     if (byRequest.has(cacheKey)) return byRequest.get(cacheKey);
     const resolved = resolveMaterialShaderVariantSet(
       requestedVariantSet,
       variants,
       internals.device.caps.backendKind,
       internals.device.caps.storageBuffer,
+      projectorAvailable,
     );
     byRequest.set(cacheKey, resolved);
     return resolved;
@@ -1782,6 +1866,9 @@ async function makeWebGPURenderer(
         }
         temporalPostProcessesRegistered = true;
       },
+      (sources: VolumetricFogShaderSources) => {
+        internals.volumetricFogShaders = sources;
+      },
     );
   const ready: Promise<Result<void, RhiError>> = buildPipeline().then(
     (state): Result<void, RhiError> => {
@@ -1827,6 +1914,8 @@ async function makeWebGPURenderer(
       pbrManifestEntry,
       internals.device.caps.storageBuffer,
       variantSet,
+      (internals.device.limits.maxSampledTexturesPerShaderStage ?? 0) >=
+        STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES,
     );
     if (noColorVariant !== undefined && noColorVariant.composedWgsl !== standardEntry.wgsl) {
       return { ...standardEntry, wgsl: noColorVariant.composedWgsl };
@@ -2705,6 +2794,9 @@ async function makeWebGPURenderer(
     get meshSsboState() {
       return internals.meshSsboState;
     },
+    get volumetricFogShaders() {
+      return internals.volumetricFogShaders;
+    },
   });
   if (
     internals.device.caps.backendKind === 'null' &&
@@ -2730,7 +2822,8 @@ async function makeWebGPURenderer(
   const transformReleases = new Map<World, () => void>();
   const attachmentOwner = {};
   let frameId = 0;
-  let latestReceipt: FrameReceipt | undefined;
+  const issuedReceipts = new WeakSet<FrameReceipt>();
+  const receiptTimings = new WeakMap<FrameReceipt, Promise<VolumeTimingObservation>>();
   let surfaceReleased = false;
 
   const renderer: RendererAssemblyImplementation = {
@@ -2794,6 +2887,7 @@ async function makeWebGPURenderer(
           ? {}
           : { presentationProof: internals.context.presentationProof }),
       });
+      const volumetricFog = renderSystem.volumetricFog;
       return Object.freeze({
         state,
         surface: surfaceReleased ? 'released' : 'available',
@@ -2807,6 +2901,7 @@ async function makeWebGPURenderer(
           (internals.featureHost?.features ?? []).map((feature) => feature.identity),
         ),
         featureDiagnostics: internals.featureHost?.diagnostics() ?? Object.freeze([]),
+        volumetricFog,
         frustumStats: Object.freeze({ ...renderSystem.frustumStats }),
         visibilityStats: Object.freeze({ ...renderSystem.visibilityStats }),
         renderScene: renderSystem.renderScene,
@@ -3234,8 +3329,23 @@ async function makeWebGPURenderer(
       // through onError separately; the facade Result is the synchronous
       // summary AI users can ignore or branch on).
       try {
-        const submitted = renderSystem.draw(worlds, drawOptions, renderReadLeases);
+        const timingRequested =
+          isFrameRequest &&
+          (frameRequest?.profileFrame !== undefined ||
+            internals.options?.captureGpuTimings === true);
+        let timingCapture: GpuTimingCapture | undefined;
+        let timingUnavailableReason = timingRequested
+          ? 'timestamp capture is unavailable on this device'
+          : 'timestamp capture was not requested for this frame';
+        if (timingRequested) {
+          const createdTiming = GpuTimingCapture.create(internals.device);
+          if (createdTiming.ok) timingCapture = createdTiming.value;
+          else
+            timingUnavailableReason = `timestamp capture setup failed: ${createdTiming.error.code}`;
+        }
+        const submitted = renderSystem.draw(worlds, drawOptions, renderReadLeases, timingCapture);
         if (!submitted) {
+          timingCapture?.discard();
           return err(
             new RendererContractFailureError(
               'draw',
@@ -3265,7 +3375,15 @@ async function makeWebGPURenderer(
             deviceGeneration: receiptGeneration,
             completed,
           });
-          latestReceipt = receipt;
+          receiptTimings.set(
+            receipt,
+            timingCapture?.observation() ??
+              Promise.resolve({
+                status: 'unavailable',
+                reason: timingUnavailableReason,
+              }),
+          );
+          issuedReceipts.add(receipt);
           return ok(receipt);
         }
         return ok(undefined);
@@ -3290,10 +3408,8 @@ async function makeWebGPURenderer(
       request: FrameObservationRequest,
     ): Promise<RenderResult<FrameReceiptObservation, RenderError>> {
       if (
-        latestReceipt === undefined ||
-        latestReceipt !== receipt ||
-        latestReceipt.frameId !== receipt.frameId ||
-        latestReceipt.deviceGeneration !== receipt.deviceGeneration
+        !issuedReceipts.has(receipt) ||
+        receipt.deviceGeneration !== activeDeviceScope.generation
       ) {
         const currentGeneration = activeDeviceScope.generation;
         return err(
@@ -3316,11 +3432,19 @@ async function makeWebGPURenderer(
           }),
         );
       }
+      const timings = request.include.includes('timings')
+        ? await (receiptTimings.get(receipt) ??
+            Promise.resolve({
+              status: 'unavailable',
+              reason: 'timing receipt was not retained',
+            }))
+        : undefined;
       return ok(
         Object.freeze({
           frameId: receipt.frameId,
           deviceGeneration: receipt.deviceGeneration,
           include: Object.freeze([...request.include]),
+          ...(timings === undefined ? {} : { timings }),
         }),
       );
     },
@@ -3595,7 +3719,7 @@ async function makeWebGPURenderer(
         let device: RhiDevice;
         try {
           const deviceResult = await adapterResult.value.requestDevice(
-            deviceOptionsForAdapter(adapterResult.value),
+            deviceOptionsForAdapter(adapterResult.value, internals.options),
           );
           if (!deviceResult.ok) {
             return err(new RecoverError('recover-device-unavailable'));
@@ -3964,6 +4088,11 @@ const RENDER_PROFILE_KEYS = new Set([
   'pbr',
   'ibl',
   'ssao',
+  'bloom',
+  'tone',
+  'antialias',
+  'sky',
+  'volumetricFog',
   'fallback',
   'postStages',
 ]);
@@ -3990,6 +4119,24 @@ function validateRenderProfile(profile: RenderProfile): string | undefined {
   for (const field of ['pbr', 'ibl', 'ssao'] as const) {
     if (typeof profile[field] !== 'boolean') return `RenderProfile.${field} must be boolean`;
   }
+  if (profile.volumetricFog !== undefined) {
+    if (profile.volumetricFog.quality !== 'low' && profile.volumetricFog.quality !== 'high')
+      return "RenderProfile.volumetricFog.quality must be 'low' or 'high'";
+    if (profile.volumetricFog.depth !== 48 && profile.volumetricFog.depth !== 64) {
+      return 'RenderProfile.volumetricFog.depth must be 48 or 64';
+    }
+    if (profile.volumetricFog.tileSize !== 4 && profile.volumetricFog.tileSize !== 16) {
+      return 'RenderProfile.volumetricFog.tileSize must be 4 or 16';
+    }
+    if (profile.volumetricFog.quality === 'low' && profile.volumetricFog.depth !== 48)
+      return 'RenderProfile.volumetricFog.low must use depth 48';
+    if (profile.volumetricFog.quality === 'high' && profile.volumetricFog.depth !== 64)
+      return 'RenderProfile.volumetricFog.high must use depth 64';
+    if (profile.volumetricFog.quality === 'low' && profile.volumetricFog.tileSize !== 16)
+      return 'RenderProfile.volumetricFog.low must use tileSize 16';
+    if (profile.volumetricFog.quality === 'high' && profile.volumetricFog.tileSize !== 4)
+      return 'RenderProfile.volumetricFog.high must use tileSize 4';
+  }
   const stages = STANDARD_POST_STAGE_NAMES;
   if (
     !Array.isArray(profile.postStages) ||
@@ -4767,6 +4914,14 @@ async function prepareMaterialShaders(
     if (!capCheck.ok) throw capCheck.error;
     storageBufferCapable = !webgl2Downlevel && capCheck.value;
   }
+  // The shared PBR view/material ABI consumes the WebGPU minimum of 16
+  // fragment sampled textures. The authored SpotLight projector is the
+  // optional 17th texture; select its shader/BGL pair from the same limit so
+  // low-limit adapters keep analytic lighting instead of failing layout
+  // creation at boot.
+  const projectorAvailable =
+    (rhiDevice.limits.maxSampledTexturesPerShaderStage ?? 0) >=
+    STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
 
   // ── Step 1: manifest load ─────────────────────────────────────────────────
   const registry = getShader();
@@ -4808,6 +4963,12 @@ async function prepareMaterialShaders(
     if (msEntry.variants.some((v) => 'VERTEX_COLOR_AVAILABLE' in v.defines)) {
       variantDefines.VERTEX_COLOR_AVAILABLE = false;
     }
+    if (
+      msEntry.identifier === 'forgeax::default-standard-pbr' &&
+      msEntry.variants.some((v) => 'PROJECTOR_AVAILABLE' in v.defines)
+    ) {
+      variantDefines.PROJECTOR_AVAILABLE = projectorAvailable;
+    }
     if (
       msEntry.identifier === 'forgeax::default-standard-pbr' &&
       msEntry.variants.some((v) => 'TRANSMISSION_AVAILABLE' in v.defines)
@@ -4984,6 +5145,8 @@ async function buildReadyWebGPU(
     readonly motionBlur?: string;
     readonly taaResolve?: string;
   }) => void,
+  /** Install manifest-owned volume utility sources only after all three modules compile. */
+  setVolumetricFogShaderSources: (sources: VolumetricFogShaderSources) => void,
 ): Promise<PipelineState> {
   // bug-20260610: WebGL2 fallback path — read storage-buffer capability up
   // front so both Step 2 (shader-module compile, where we patch engine
@@ -5001,6 +5164,9 @@ async function buildReadyWebGPU(
     const capCheck = assertStorageBufferCap(capValue);
     storageBufferCapable = capCheck.ok ? !webgl2Downlevel && capCheck.value : !webgl2Downlevel;
   }
+  const projectorAvailable =
+    (rhiDevice.limits.maxSampledTexturesPerShaderStage ?? 0) >=
+    STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
 
   // bug-20260612: choose swap-chain storage / view formats by backend.
   // Channel 2 (native WebGPU) follows navigator.gpu.getPreferredCanvasFormat();
@@ -5303,6 +5469,8 @@ async function buildReadyWebGPU(
               v.defines.CLUSTER_FORWARD_AVAILABLE === false) &&
             (!('VERTEX_COLOR_AVAILABLE' in v.defines) ||
               v.defines.VERTEX_COLOR_AVAILABLE === false) &&
+            (!('PROJECTOR_AVAILABLE' in v.defines) ||
+              v.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
             (!('SKINNING_DISABLED' in v.defines) || v.defines.SKINNING_DISABLED === true),
         );
         const v = exact === undefined ? undefined : findVariantByKey(ms, exact.definesKey);
@@ -5346,6 +5514,8 @@ async function buildReadyWebGPU(
             variant.defines.CLUSTER_FORWARD_AVAILABLE === false) &&
           (!('VERTEX_COLOR_AVAILABLE' in variant.defines) ||
             variant.defines.VERTEX_COLOR_AVAILABLE === false) &&
+          (!('PROJECTOR_AVAILABLE' in variant.defines) ||
+            variant.defines.PROJECTOR_AVAILABLE === projectorAvailable) &&
           (!('SKINNING_DISABLED' in variant.defines) ||
             variant.defines.SKINNING_DISABLED === true) &&
           (!('TRANSMISSION_AVAILABLE' in variant.defines) ||
@@ -5480,6 +5650,80 @@ async function buildReadyWebGPU(
       seedShaderModule(label, shaderResult.value);
     }
 
+    // The volume graph is authored from ECS state and therefore cannot be
+    // compiled while the static material manifest is assembled. Its pass
+    // encoder nevertheless uses the same shared lazy shader adapter, so the
+    // four utility modules must be prewarmed before the first synchronous
+    // draw. The sources come from the shader manifest (the package-owned WGSL
+    // files are the sole source of truth); compile all four first and only
+    // then publish the labels and source bundle. A partial bundle would let a
+    // later frame mix generations after a device recovery.
+    if (rhiDevice.caps.compute && rhiDevice.caps.storageTexture) {
+      const volumeSources = [
+        ['inject', 'volume_inject', (source: string) => source.includes('fn volume_inject(')],
+        ['temporal', 'volume_temporal', (source: string) => source.includes('fn volume_temporal(')],
+        [
+          'integrate',
+          'volume_integrate',
+          (source: string) => source.includes('fn volume_integrate('),
+        ],
+        ['composite', 'volume_composite', (source: string) => source.includes('fn volume_fs(')],
+      ] as const;
+      const resolved = volumeSources.map(([stage, label, matches]) => {
+        const entry = manifestEntries.find((candidate) => matches(candidate.wgsl));
+        return { stage, label, entry };
+      });
+      // Volumetric fog is an optional graph feature. Minimal hosts/tests may
+      // intentionally ship only material/post-process entries; keep those
+      // renderers bootable while still rejecting a partially declared volume
+      // bundle (which would otherwise fail later as a lazy pending pipeline).
+      const present = resolved.filter((candidate) => candidate.entry !== undefined).length;
+      if (present === 0) {
+        // No volume manifest entries: leave the source/module bundle unset and
+        // let the topology capability gate keep volume work disabled.
+      } else {
+        const missing = resolved.find((candidate) => candidate.entry === undefined);
+        if (missing !== undefined) {
+          throw new RhiError({
+            code: 'shader-compile-failed',
+            expected: 'shader manifest contains all four volumetric fog utility entries',
+            hint: `add the package-owned WGSL entry for '${missing.label}' to the engine shader manifest`,
+          });
+        }
+        const compiled = [] as Array<{
+          readonly stage: (typeof volumeSources)[number][0];
+          readonly label: string;
+          readonly source: string;
+          readonly module: ShaderModule;
+        }>;
+        for (const { stage, label, entry } of resolved) {
+          // `missing` above proves the narrowing for this loop; keep the guard
+          // explicit so a future refactor cannot publish an undefined source.
+          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 });
+        }
+        for (const { label, module } of compiled) seedShaderModule(label, module);
+        setVolumetricFogShaderSources({
+          inject: compiled.find((candidate) => candidate.stage === 'inject')?.source as string,
+          temporal: compiled.find((candidate) => candidate.stage === 'temporal')?.source as string,
+          integrate: compiled.find((candidate) => candidate.stage === 'integrate')
+            ?.source as string,
+          composite: compiled.find((candidate) => candidate.stage === 'composite')
+            ?.source as string,
+        });
+      }
+    }
+
     const pbrShaderResult = await runShimStep(
       () =>
         asyncCreateShaderModule
@@ -5511,7 +5755,11 @@ async function buildReadyWebGPU(
       (rhiDevice.limits.maxSampledTexturesPerShaderStage ?? 0) >=
       STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
     const transmissionVariants = transmissionCapable
-      ? selectStandardPbrTransmissionPrewarmVariants(pbrManifestEntry, storageBufferCapable)
+      ? selectStandardPbrTransmissionPrewarmVariants(
+          pbrManifestEntry,
+          storageBufferCapable,
+          projectorAvailable,
+        )
       : [];
 
     // HDRP uses the canonical all-true variant key (`''`) and the lazy
@@ -5549,6 +5797,7 @@ async function buildReadyWebGPU(
       pbrManifestEntry,
       storageBufferCapable,
       transmissionCapable,
+      projectorAvailable,
     )) {
       const moduleLabel = `module-forgeax::default-standard-pbr#${hdrpVariant.definesKey}`;
       let hdrpModule = prewarmedHdrpModules.get(hdrpVariant.composedWgsl);
@@ -6042,7 +6291,13 @@ async function buildReadyWebGPU(
   // buildReadyWebGPU (above) so Step 2 (variant patch) and this layout
   // build read the same value.
   const pbrLayouts = runShimSyncStep(
-    () => ok(buildPbrPipelineLayouts(rhiDevice, { storageBuffer: storageBufferCapable })),
+    () =>
+      ok(
+        buildPbrPipelineLayouts(rhiDevice, {
+          storageBuffer: storageBufferCapable,
+          projectorAvailable,
+        }),
+      ),
     'webgpu-runtime-error',
     'buildPbrPipelineLayouts succeeded',
     'check device.limits.maxBindingsPerBindGroup (need >=14) and maxBindGroupsPerPipelineLayout',
@@ -8589,6 +8844,7 @@ async function buildReadyWebGPU(
     colorAttachmentFormat: swapChainFormats.view,
     surfaceProfile: surfaceViewFormats ? 'dual-view' : 'raw-only',
     viewBindGroupLayout: viewBglResult.value,
+    projectorAvailable,
     materialBindGroupLayout: materialBglResult.value,
     meshBindGroupLayout: meshArrayBglResult.value,
     viewUniformBuffer: viewUboResult.value,

package/src/components/light-helpers.ts

@@ -155,6 +155,10 @@ export function validateSpotLightData(
   if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
     return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
   }
+  const shadowIntensity = (data.shadowIntensity as number | undefined) ?? 1;
+  if (!Number.isFinite(shadowIntensity) || shadowIntensity < 0 || shadowIntensity > 1) {
+    return err(new ShadowInvalidConfigError('shadowIntensity', shadowIntensity, 0, 1));
+  }
   return ok(undefined);
 }
 

package/src/components/spot-light.ts

@@ -21,8 +21,8 @@
 // spotCount === 0" (M5 / w25).
 //
 // feat-20260625-spot-light-shadow-mapping M1 w4: embedded castShadow (default true)
-// + 6 shadow fields (mapSize / depthBias / normalBias / nearPlane / farPlane /
-// pcfKernelSize) aligned with DirectionalLight vocabulary (plan-strategy D-6;
+// + 7 shadow fields (mapSize / depthBias / normalBias / nearPlane / farPlane /
+// pcfKernelSize / shadowIntensity) aligned with DirectionalLight vocabulary (plan-strategy D-6;
 // charter P4 consistent abstraction). Zero-config spawns cast spot shadows;
 // set castShadow:false to opt out (validate short-circuits on false, AC-03).
 // Shadow atlas cap of 4 is enforced at extract stage, not component layer (OOS-5).
@@ -37,6 +37,17 @@
 
 import { defineComponent } from '@forgeax/engine-ecs';
 
+export interface SpotLightProjector {
+  readonly guid: string;
+  readonly generation: number;
+  readonly revision: number;
+}
+
+export interface SpotLightAuthoring {
+  /** Optional GUID-backed TextureAsset projector; absent keeps the normal spot path. */
+  readonly projector?: SpotLightProjector;
+}
+
 /**
  * Cone-restricted spot light (KHR_lights_punctual `spot` type).  Casts shadows
  * by default (castShadow defaults to true) — zero-config spawns project hard
@@ -71,6 +82,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   nearPlane                        — shadow-camera near (default 0.1)
  *   farPlane                         — shadow-camera far (default 50)
  *   pcfKernelSize odd >= 1           — PCF kernel width (default 3)
+ *   shadowIntensity in [0,1]         — residual light in shadow (default 1)
  *
  * Atlas capacity is capped at 4 castShadow spot lights by the extract stage;
  * the 5th light onward keeps direct illumination but shadowAtlasTile = -1
@@ -114,11 +126,18 @@ export const SpotLight = defineComponent('SpotLight', {
   outerConeDeg: { type: 'f32', default: 45 },
   // Shadow opt-out gate: defaults to true so zero-config spawns cast shadows.
   castShadow: { type: 'bool', default: true },
-  // 6 shadow fields aligned with DirectionalLight (plan-strategy D-6).
+  // 7 shadow fields aligned with the shared light shadow vocabulary.
   mapSize: { type: 'f32', default: 2048 },
   depthBias: { type: 'f32', default: 0.005 },
   normalBias: { type: 'f32', default: 0.05 },
   nearPlane: { type: 'f32', default: 0.1 },
   farPlane: { type: 'f32', default: 50 },
   pcfKernelSize: { type: 'f32', default: 3 },
+  // Three's SpotLight.shadow.intensity is the fraction of visibility applied
+  // to a shadowed contribution. Keep it in the author-facing [0,1] domain;
+  // extract/record transport this one fact to surface and volume consumers.
+  shadowIntensity: { type: 'f32', default: 1 },
+  // Shared TextureAsset identity; publication and residency remain owned by
+  // the existing asset and GPU resource owners.
+  projector: { type: 'shared<TextureAsset>', simulationTransient: true },
 });