@forgeax/engine-render 0.1.29 → 0.1.31

package/src/assembly/webgpu-renderer.ts

@@ -1,6 +1,5 @@
 // @forgeax/engine-render — WebGPU renderer lifecycle/frame interpreter.
 // Runtime selects the backend; structured RHI errors and browser isolation stay intact.
-
 import {
   AssetRegistry,
   adaptDynamicTextureDevice,
@@ -38,6 +37,7 @@ import type {
   PrimitiveTopology,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import { transmissionBackdropAvailable } from './device-feature-admission';
 
 export type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
 
@@ -61,7 +61,6 @@ import {
   postProcessShaderModuleLabel,
 } from '../fullscreen-post-process-pass';
 import { glyphTextLayoutSystem } from '../glyph-text-layout-system';
-import { resolveStandardPbrProgram } from '../gpu-driven/pbr-program';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
 import type { BloomInspection } from '../inspection-types';
 import { DeviceScope } from '../lifecycle';
@@ -147,6 +146,13 @@ import type { RhiBackendPack } from './backend-contract';
 import type { BundlerOptions } from './bundler-contract';
 import { createRendererDynamicGeometryController } from './dynamic-geometry-host';
 import type { RendererAssemblyImplementation } from './host-contract';
+import {
+  isEngineOwnedMaterialShader,
+  resolveMaterialPipelineBindGroups,
+  resolveMaterialPipelineShaderId,
+  resolveMaterialPipelineVertexEntry,
+  resolveRendererMaterialShaderArtifact,
+} from './material/pipeline-helpers';
 import {
   allowsUnlitPreparedFallback,
   invokeDeviceCreateShaderModule,
@@ -243,7 +249,6 @@ export {
   selectPipelineLayoutForVariant,
   shouldDeferMissingPreparedMaterialShader,
 } from './material-shader-policy';
-
 export {
   createMeshSsboGrowController,
   deriveStorageBufferCeiling,
@@ -282,6 +287,7 @@ async function makeWebGPURenderer(
   internals: WebGPURendererInternals,
 ): Promise<RendererAssemblyImplementation> {
   let disposed = false;
+  const observeTiming = observeGpuPassTimingDisabled;
   const frameContinuations = new Set<ContinuationTerminator>();
   type RecoveryInspection = RenderInspection['recovery'];
   let recoveryAttempt = 0;
@@ -571,19 +577,11 @@ async function makeWebGPURenderer(
   // ShaderCatalogDevice adapter (shared between the catalog and per-MaterialShader
   // pipeline cache) is already available at this point.
   const shaderCatalog = getShader();
-  // feat-20260528-material-shader-registration-unification M3 / w14:
-  // placeholder hardcoded installMaterialArtifact calls deleted.
   // bug-20260601-hello-tonemap-material-register M1 (plan-strategy D-1):
   // All material-shader entries are now registered from the manifest
   // BEFORE the renderer is returned, so `register<MaterialAsset>` referencing
   // an engine shader succeeds without waiting for `renderer.initialization`.
-
-  // feat-20260623-asset-payload-generic-open-registry M3 / w10: host apps
-  // that need custom loaders register them on `assets.loaders.register(...)`.
-  // feat-20260604-hdr-equirect-cube-importer-loader M4 / w16 (D-3 / AC-05):
-  // the host-injected ImportTransport (or undefined for the shipped form) is
-  // threaded into the AssetRegistry ctor -- the construction-time-
-  // only single injection point (no setter, no illegal intermediate state).
+  // Host-injected ImportTransport remains a constructor-only dependency.
   // feat-20260705-runtime-tier2-decomposition M1 / w10 (D-1 / D-2): the sole
   // production assembly point injects (a) the post-spawn hook
   // `postSpawnResolveJoints` (auto-wire Skin.joints; D-1) and the audio
@@ -691,7 +689,6 @@ async function makeWebGPURenderer(
     etc2: internals.device.caps.textureCompressionEtc2,
     astc: internals.device.caps.textureCompressionAstc,
   });
-
   // M1 (bug-20260601-hello-tonemap-material-register D-1/D-2): prepare
   // engine-shipped material shaders (cap gate + manifest load + registration)
   // so they are available in ShaderCatalog before `register<MaterialAsset>`.
@@ -799,14 +796,7 @@ async function makeWebGPURenderer(
     { materialBgl: BindGroupLayout; pipelineLayout: PipelineLayout }
   >();
   const preparedMaterialPipelineLayoutCache = new Map<string, PipelineLayout>();
-  // feat-20260621-learn-render-5-5-parallax M2 / w6 (D-1): per-shader material
-  // BGL + pipeline layout cache. Every authored material shader owns the
-  // user-region binding order emitted by its paramSchema, plus the shared
-  // engine-injection suffix. A custom shader with four-or-fewer textures can
-  // still differ from the standard PBR order (for example, baseColorTexture
-  // followed directly by normalTexture), so it cannot safely reuse the
-  // standard material BGL. Built lazily on first request and cached by
-  // shaderId; built-in shader IDs continue to use the boot-time shared layout.
+  // Cache authored material layouts by their exact mesh and lighting contract.
   type PerShaderMaterialLayout = {
     materialBgl: BindGroupLayout;
     pipelineLayout: PipelineLayout;
@@ -818,16 +808,6 @@ async function makeWebGPURenderer(
     readonly layout: PerShaderMaterialLayout | null;
   };
   const perShaderMaterialLayoutCache = new Map<string, PerShaderMaterialLayoutCacheEntry>();
-  const isEngineOwnedMaterialShader = (materialShaderId: string): boolean =>
-    materialShaderId === 'forgeax::default-unlit' ||
-    materialShaderId === 'forgeax::default-shadow-caster' ||
-    materialShaderId === 'forgeax::sprite' ||
-    materialShaderId === 'forgeax::sprite-lit' ||
-    materialShaderId === 'forgeax::default-sprite' ||
-    materialShaderId === 'forgeax::msdf-text' ||
-    materialShaderId === 'forgeax::default-standard-pbr' ||
-    materialShaderId === 'forgeax::pbr-skin' ||
-    materialShaderId === 'forgeax::default-standard-pbr-skin';
   // Material binding contracts are derived from WGSL source, but the lookup
   // is also used by the per-submesh bind-group path. Cache the derived value
   // per renderer so a frame does not re-run the comment stripping and regex
@@ -1139,16 +1119,18 @@ async function makeWebGPURenderer(
     materialShaderId: string,
     explicitParamSchema?: readonly ParamSchemaEntry[],
     layoutKind: LayoutKind = 'pbr',
+    clustered = false,
   ): PerShaderMaterialLayout | null => {
     const cacheState = currentPipelineCacheState();
     const currentState = currentPipelineState();
     if (currentState === null) return null;
-    if (isEngineOwnedMaterialShader(materialShaderId)) return null;
+    if (isEngineOwnedMaterialShader(materialShaderId) && !clustered) return null;
     const lookup = getShader().findMaterialArtifact(materialShaderId);
     const source = lookup.ok ? lookup.value.source : '';
     const paramSchema = lookup.ok ? lookup.value.paramSchema : explicitParamSchema;
     if (paramSchema === undefined) return null;
-    const cached = cacheState.perShaderMaterialLayoutCache.get(materialShaderId);
+    const cacheKey = `${materialShaderId}:${layoutKind}:${clustered}`;
+    const cached = cacheState.perShaderMaterialLayoutCache.get(cacheKey);
     if (
       cached?.source === source &&
       cached.paramSchema === paramSchema &&
@@ -1164,8 +1146,8 @@ async function makeWebGPURenderer(
       isStandardPbrMaterialShader(materialShaderId) ||
       standardPhysicalTextureFields(paramSchema).length > 0;
     const isStandardMapLayout = requiresStandardMapLayout;
-    if (!isStandardMapLayout && isSharedMaterialUserRegionCompatible(paramSchema)) {
-      cacheState.perShaderMaterialLayoutCache.set(materialShaderId, {
+    if (!clustered && !isStandardMapLayout && isSharedMaterialUserRegionCompatible(paramSchema)) {
+      cacheState.perShaderMaterialLayoutCache.set(cacheKey, {
         source,
         paramSchema,
         layoutKind,
@@ -1182,27 +1164,27 @@ async function makeWebGPURenderer(
     const desc = buildBindGroupLayoutDescriptor(spec, {
       kind: 'pbr-material-merged',
       materialParamSchema: paramSchema,
-      caps: { storageBuffer: currentBuildDevice().caps.storageBuffer },
+      caps: {
+        storageBuffer: currentBuildDevice().caps.storageBuffer,
+        transmissionBackdrop: transmissionBackdropAvailable(
+          currentBuildDevice().limits.maxSampledTexturesPerShaderStage,
+        ),
+      },
     });
     const bglRes = currentBuildDevice().createBindGroupLayout(desc);
     if (!bglRes.ok) {
       internals.errorRegistry.fire(bglRes.error);
       return null;
     }
-    const meshLayout =
-      layoutKind === 'pbr-skin'
-        ? currentState.pbrSkinMeshBindGroupLayout
-        : layoutKind === 'hdrp-skin'
-          ? currentState.hdrpSkinMeshBindGroupLayout
-          : currentState.meshBindGroupLayout;
-    if (meshLayout === null) return null;
+    const bindGroups = resolveMaterialPipelineBindGroups(layoutKind, currentState, clustered);
+    if (bindGroups === null) return null;
     const plRes = currentBuildDevice().createPipelineLayout({
       label: `pbr-pl-${materialShaderId}`,
       bindGroupLayouts: [
         currentState.viewBindGroupLayout,
         bglRes.value,
-        meshLayout,
-        currentState.instancesBindGroupLayout,
+        bindGroups.meshLayout,
+        bindGroups.instancesLayout,
       ],
     });
     if (!plRes.ok) {
@@ -1210,7 +1192,7 @@ async function makeWebGPURenderer(
       return null;
     }
     const built = { materialBgl: bglRes.value, pipelineLayout: plRes.value };
-    cacheState.perShaderMaterialLayoutCache.set(materialShaderId, {
+    cacheState.perShaderMaterialLayoutCache.set(cacheKey, {
       source,
       paramSchema,
       layoutKind,
@@ -1320,7 +1302,13 @@ async function makeWebGPURenderer(
       residencyStore,
       internals.pack.createShaderModule,
       internals.errorRegistry,
-      requiredMaterialShaders,
+      candidateBuildState === undefined
+        ? requiredMaterialShaders
+        : [
+            ...new Set([...requiredMaterialShaders, ...getShader().materialShaderIdentifiers()]),
+          ].filter(
+            (id) => requiredMaterialShaders.includes(id) || !isEngineOwnedMaterialShader(id),
+          ),
       materialShaderUvSetCounts.get('forgeax::default-standard-pbr') ?? 0,
       requiredFullscreenPostProcesses,
       // Publish growth and capacity together for the active or candidate device.
@@ -1333,14 +1321,12 @@ async function makeWebGPURenderer(
           internals.meshSsboState = state;
         }
       },
-      // feat-20260609 R3-fixup: seed the lazy adapter cache with the
-      // eagerly-compiled shadow_caster module.
+      // Both module adapters consume the generation's eager shader cache.
       (label, module) => {
         getShaderModuleAdapter().seedModule(label, module);
+        getImmediateShaderModuleAdapter().seedModule(label, module);
       },
-      // M6 fix-up: seed the active or candidate material pipeline cache from
-      // the boot-time SPEC_CONST prewarm. Recovery builds must never put a
-      // candidate-device PSO into the retired generation's cache.
+      // Prewarm only the active build generation's material pipeline cache.
       (key, pso, group2Contract) => {
         const pipelineCache = currentPipelineCacheState().materialShaderPipelineCache;
         if (!pipelineCache.has(key)) {
@@ -1475,20 +1461,21 @@ async function makeWebGPURenderer(
             ? 'pbr-skin'
             : 'pbr';
     const layoutKind = layoutKindOverride ?? contractLayoutKind;
+    const gpuClustered =
+      (layoutKind === 'gpu-driven-pbr' || layoutKind === 'gpu-driven-skin') &&
+      (group2Contract === 'cluster' || group2Contract === 'skin-cluster');
     const usesSharedBootMaterialLayout =
-      materialShaderId !== undefined && isEngineOwnedMaterialShader(materialShaderId);
+      !gpuClustered &&
+      materialShaderId !== undefined &&
+      isEngineOwnedMaterialShader(materialShaderId);
     // Built-in layouts are assembled at boot; authored layouts must not bypass
     // the HDRP group(2) selector or bind the URP mesh BGL to a cluster PSO.
     const perShaderLayout =
-      !usesSharedBootMaterialLayout &&
-      layoutKind !== 'pbr-skin' &&
-      layoutKind !== 'gpu-driven-pbr' &&
-      layoutKind !== 'gpu-driven-skin' &&
-      materialShaderId !== undefined
-        ? getOrBuildPerShaderMaterialLayout(materialShaderId, undefined, layoutKind)
+      !usesSharedBootMaterialLayout && materialShaderId !== undefined
+        ? getOrBuildPerShaderMaterialLayout(materialShaderId, undefined, layoutKind, gpuClustered)
         : null;
-    // Authored shaders use their paramSchema; skin/HDRP retain dedicated
-    // layouts and built-in IDs stay on the shared boot-time layout.
+    // Authored shaders retain their own material schema and selected mesh
+    // layout, including skin. Built-in IDs keep their boot-time layout.
     const bindingContract =
       materialShaderId === undefined
         ? 'render-material'
@@ -1634,6 +1621,7 @@ async function makeWebGPURenderer(
     vertexEntry?: string,
     authoredFragmentEntry?: string,
     particleInputLanes?: number,
+    coverageOnly = false,
   ): RenderPipeline | null => {
     const declaredGroup2Contract = resolvePipelineGroup2Contract(entry.source);
     const group2Contract =
@@ -1643,6 +1631,11 @@ async function makeWebGPURenderer(
       (variantSet === '' || variantSet?.includes('CLUSTER_FORWARD_AVAILABLE=true') === true)
         ? 'cluster'
         : declaredGroup2Contract;
+    const resolvedVertexEntry = resolveMaterialPipelineVertexEntry(
+      layoutKindOverride,
+      vertexEntryPoint,
+      vertexEntry,
+    );
     const ctx = buildPipelineContext(
       variantSet,
       materialShaderId,
@@ -1682,6 +1675,7 @@ async function makeWebGPURenderer(
             : passKindPolicyTable[passKind]?.shape === 'depth-only'
               ? (depthFormatOverride ?? 'depth32float')
               : (depthFormatOverride ?? DEPTH_TEXTURE_FORMAT),
+        coverageOnly,
         label,
         // feat-20260604 w16-b: the shader-MODULE cache identity. Stable across
         // per variant. See PipelineBuilderContext.moduleLabel.
@@ -1702,7 +1696,7 @@ async function makeWebGPURenderer(
               : {}),
           }
         : undefined,
-      vertexEntry ?? vertexEntryPoint,
+      resolvedVertexEntry,
       fragmentEntry,
       undefined, // defines — none
       passKind,
@@ -1766,6 +1760,8 @@ async function makeWebGPURenderer(
     fragmentEntry?: string,
     particleInputLanes?: number,
   ): RenderPipeline | null => {
+    const coverageOnly =
+      passKind === 'temporal' && variantSet?.split('+').includes('COVERAGE_ONLY=true') === true;
     // WebGL2 is a downlevel backend even when the record stage asks for the
     // native-capability variant string. Resolve the variant axes at this
     // shared PSO seam so the shader source, BGL layout, and cache key agree on
@@ -1778,10 +1774,11 @@ async function makeWebGPURenderer(
       (currentState !== null ? currentState.colorAttachmentFormat : 'bgra8unorm-srgb');
     // feat-20260629 M4: auto-fill shaderUvSetCount from naga reflection
     // (stored in materialShaderUvSetCounts during prepareMaterialShaders).
+    const materialShaderIdForPass = resolveMaterialPipelineShaderId(materialShaderId, passKind);
     const pipelineShaderId = resolveMaterialShaderBackendArtifactKey(
-      materialShaderId,
+      materialShaderIdForPass,
       internals.device.caps.backendKind,
-      assets.getMaterialArtifact(materialShaderId),
+      assets.getMaterialArtifact(materialShaderIdForPass),
     );
     const materialShaderLookup = getShader().findMaterialArtifact(pipelineShaderId);
     const materialShaderSource = materialShaderLookup.ok
@@ -1952,6 +1949,10 @@ async function makeWebGPURenderer(
           layoutKindOverride,
           vertexEntryPoint,
           additionalColorFormats,
+          undefined,
+          undefined,
+          undefined,
+          coverageOnly,
         );
       }
       const pbrEntry = findStandardPbrEntry(effectiveVariantSet);
@@ -2009,6 +2010,10 @@ async function makeWebGPURenderer(
         layoutKindOverride,
         vertexEntryPoint,
         additionalColorFormats,
+        undefined,
+        undefined,
+        undefined,
+        coverageOnly,
       );
     }
     // feat-20260609 M4 / w31: resolve variant WGSL from manifest when
@@ -2106,6 +2111,7 @@ async function makeWebGPURenderer(
       vertexEntry,
       fragmentEntry,
       particleInputLanes,
+      coverageOnly,
     );
   };
   const getMaterialShaderPipelineEntry = (
@@ -2241,6 +2247,7 @@ async function makeWebGPURenderer(
       return internals.bundler?.build;
     },
     ssrIdentity: internals.options?.ssrIdentity,
+    captureReflectionFallbackReadback: internals.options?.captureReflectionFallbackReadback,
     get standardProfile() {
       return activeProfile;
     },
@@ -2260,11 +2267,8 @@ async function makeWebGPURenderer(
         getImmediateShaderModuleAdapter().createShaderModule(descriptor),
     },
     profiler: internals.options?.profiler,
-    // feat-20260622-s5 M3 / w17: device + context read live off `internals` via
-    // getters so the recover() rebuild (which swaps internals.device /
-    // internals.context for a freshly-acquired pair) is observed by the record
-    // stage without reconstructing the RenderSystem (RenderSystemRuntime.device
-    // / RenderSystemInternals.context are read at frame time, not cached).
+    // Keep device/context getters live so recovery swaps are observed by the
+    // record stage without reconstructing the RenderSystem.
     get device() {
       return internals.device;
     },
@@ -2329,12 +2333,13 @@ async function makeWebGPURenderer(
     getMaterialShaderPipeline,
     getMaterialShaderPipelineEntry,
     getMaterialShaderBindingContract: getCachedMaterialShaderBindingContract,
-    getMaterialShaderArtifact: (materialShaderId, vertexColorAvailable = false) =>
-      resolveStandardPbrProgram(
-        pipelineState?.gpuDrivenPbrPrograms,
+    getMaterialShaderArtifact: (materialShaderId, options = {}) =>
+      resolveRendererMaterialShaderArtifact(
         materialShaderId,
-        vertexColorAvailable,
-      )?.artifact,
+        getShader(),
+        pipelineState?.gpuDrivenPbrPrograms,
+        options,
+      ),
     getParamSchema,
     getMaterialBindGroupLayout,
     metrics,
@@ -2469,10 +2474,7 @@ async function makeWebGPURenderer(
   const transformReleases = new Map<World, () => void>();
   const attachmentOwner = {};
   let frameId = 0;
-  // Receipts remain observable until their device generation is retired. A
-  // registry avoids invalidating a still-valid frame merely because another
-  // submission completed in the meantime.
-  const currentReceipts = new Set<FrameReceipt>();
+  // Caller-owned receipts remain observable; Renderer does not retain every submitted receipt.
   const issuedReceipts = new WeakSet<FrameReceipt>();
   const receiptTimings = new WeakMap<FrameReceipt, Promise<VolumeTimingObservation>>();
   let latestReceipt: FrameReceipt | undefined;
@@ -2792,6 +2794,7 @@ async function makeWebGPURenderer(
         ),
         dynamicGeometry: dynamicGeometry.inspect(),
         renderScene: renderSystem.renderScene,
+        ...(renderSystem.iblBinding === undefined ? {} : { iblBinding: renderSystem.iblBinding }),
         reflectionProbes: renderSystem.reflectionProbes,
         ssrDependencies: renderSystem.ssrDependencies,
         ssr: renderSystem.ssr,
@@ -3530,7 +3533,6 @@ async function makeWebGPURenderer(
                 return { status: 'complete', frame };
               };
         timingObservationStore?.register(receipt, timingSource);
-        currentReceipts.add(receipt);
         if (timingRequested && gpuPassTimingOptions === undefined) {
           receiptTimings.set(
             receipt,
@@ -3592,11 +3594,11 @@ async function makeWebGPURenderer(
       }
       if (gpuPassTimingOptions !== undefined && !includesDomain) {
         return timingObservationStore === undefined
-          ? observeGpuPassTimingDisabled(receipt, request, () => activeDeviceScope.generation)
+          ? observeTiming(receipt, request, () => activeDeviceScope.generation)
           : timingObservationStore.observe(receipt, request);
       }
       if (
-        !currentReceipts.has(receipt) ||
+        disposed ||
         !issuedReceipts.has(receipt) ||
         receipt.deviceGeneration !== activeDeviceScope.generation ||
         receipt.backendId !== internals.device.caps.backendKind
@@ -3726,11 +3728,11 @@ async function makeWebGPURenderer(
               reason: 'timestamp capture was not requested for this frame',
             }))
         : undefined;
+      const observation = await observeTiming(receipt, request, () => activeDeviceScope.generation);
+      if (!observation.ok) return observation;
       return ok(
         Object.freeze({
-          frameId: receipt.frameId,
-          deviceGeneration: receipt.deviceGeneration,
-          include: Object.freeze([...request.include]),
+          ...observation.value,
           ...(targetReadbacks === undefined
             ? {}
             : { targetReadbacks: Object.freeze(targetReadbacks.value) }),
@@ -3795,16 +3797,8 @@ async function makeWebGPURenderer(
      * `disposed` latch flips up-front so a re-entrant dispose (or a draw
      * that races with the cascade) short-circuits.
      *
-     * NOT calling `device.destroy()` on the raw GPUDevice (w25 lesson from
-     * feat-20260517-vite-plugin-image-build-time-cook CI-fix v4): w23
-     * attempted to evict stale devices from the chromium WebGPU adapter
-     * pool via `_internal_getRawDevice`, but the explicit destroy
-     * accelerated pool poisoning -- after the first `dispose()` the
-     * chromium adapter pool started recycling the just-destroyed device
-     * into the next `requestDevice` so the NEXT test's `Engine.create`
-     * resolved with `ready.error.code: 'device-lost'`. Cross-test isolation
-     * moved to the vitest infra layer (`browser.isolate: true`) instead of
-     * test code self-managing device lifecycle.
+     * Raw-device destruction is owned by backend lifetime, not this facade.
+     * Browser test isolation handles adapter-pool reuse between tests.
      *
      * Stays in sync with the `Renderer.dispose` row of the README "API index".
      */
@@ -3816,7 +3810,6 @@ async function makeWebGPURenderer(
       for (const continuation of frameContinuations) {
         continuation.terminate({ code: 'disposed' });
       }
-      currentReceipts.clear();
       const cleanupFailures: RendererOperationCause[] = [];
       const observationCleanupFailure = disposeReceiptObservationCaptures();
       if (observationCleanupFailure !== undefined) {
@@ -4083,6 +4076,13 @@ async function makeWebGPURenderer(
     buildPipeline,
     getMaterialShaderPipeline,
     getMaterialShaderPipelineEntry,
+    getMaterialShaderArtifact: (materialShaderId, options = {}) =>
+      resolveRendererMaterialShaderArtifact(
+        materialShaderId,
+        getShader(),
+        pipelineState?.gpuDrivenPbrPrograms,
+        options,
+      ),
     getCachedMaterialShaderBindingContract,
     getParamSchema,
     getMaterialBindGroupLayout,

package/src/capture/scene-projection.ts

@@ -0,0 +1,37 @@
+import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+
+/** One retained index domain for auxiliary views and the display's selected draws. */
+export function projectCaptureScene(
+  retained: {
+    readonly renderables: readonly RenderableSnapshot[];
+    readonly dispatch: readonly DispatchEntry[];
+  },
+  visible: readonly RenderableSnapshot[],
+  displayDispatch: readonly DispatchEntry[],
+) {
+  const renderables: RenderableSnapshot[] = [];
+  const retainedIndices = new Map<number, number>();
+  const identityIndices = new Map<string, number>();
+  for (const [index, row] of retained.renderables.entries()) {
+    if (row.authorVisible === false) continue;
+    retainedIndices.set(index, renderables.length);
+    identityIndices.set(`${row.worldId}:${row.entityKey}`, renderables.length);
+    renderables.push(row);
+  }
+  const remap = (
+    entries: readonly DispatchEntry[],
+    indexFor: (index: number) => number | undefined,
+  ) =>
+    entries.flatMap((entry) => {
+      const index = indexFor(entry.renderableIndex);
+      return index === undefined ? [] : [{ ...entry, renderableIndex: index }];
+    });
+  return {
+    renderables,
+    captureDispatch: remap(retained.dispatch, (index) => retainedIndices.get(index)),
+    displayDispatch: remap(displayDispatch, (index) => {
+      const row = visible[index];
+      return row === undefined ? undefined : identityIndices.get(`${row.worldId}:${row.entityKey}`);
+    }),
+  };
+}

package/src/components/__tests__/dynamic-resolution-schema.unit.test.ts

@@ -0,0 +1,65 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  DynamicResolution,
+  type DynamicResolutionData,
+  validateDynamicResolutionParameters,
+} from '../dynamic-resolution';
+
+describe('DynamicResolution authoring schema', () => {
+  it('provides deterministic defaults through the real World component path', () => {
+    const world = new World();
+    const entity = world.spawn({ component: DynamicResolution, data: {} }).unwrap();
+
+    expect(DynamicResolution.name).toBe('DynamicResolution');
+    const defaults = world.get(entity, DynamicResolution).unwrap();
+    expect(defaults).toMatchObject({ maxScale: 1 });
+    // World stores f32 fields, so the authored decimal is represented by its
+    // nearest f32 value rather than the exact JS number.
+    expect(defaults.targetGpuMs).toBeCloseTo(16.67);
+    expect(defaults.minScale).toBeCloseTo(0.67);
+    expect(DynamicResolution.fields).toMatchObject({
+      targetGpuMs: { type: 'f32', default: 16.67 },
+      minScale: { type: 'f32', default: 0.67 },
+      maxScale: { type: 'f32', default: 1 },
+    });
+  });
+
+  it.each([
+    { targetGpuMs: 0, minScale: 0.67, maxScale: 1, field: 'targetGpuMs' },
+    { targetGpuMs: Number.NaN, minScale: 0.67, maxScale: 1, field: 'targetGpuMs' },
+    { targetGpuMs: 16.67, minScale: 0.49, maxScale: 1, field: 'minScale' },
+    { targetGpuMs: 16.67, minScale: 0.8, maxScale: 1.01, field: 'maxScale' },
+    { targetGpuMs: 16.67, minScale: 0.9, maxScale: 0.8, field: 'minScale' },
+  ])('rejects invalid $field before graph construction', (input) => {
+    const result = validateDynamicResolutionParameters(input);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('dynamic-resolution-invalid-parameter');
+      expect(result.error.expected).toContain(input.field);
+      expect(result.error.hint).toContain(input.field);
+      expect(result.error.detail.field).toBe(input.field);
+    }
+  });
+
+  it.each([
+    { targetGpuMs: 1, minScale: 0.5, maxScale: 0.5 },
+    { targetGpuMs: 16.67, minScale: 0.67, maxScale: 1 },
+    { targetGpuMs: 100, minScale: 0.5, maxScale: 1 },
+  ])('accepts boundary values $minScale..$maxScale', (input) => {
+    const result = validateDynamicResolutionParameters(input);
+    expect(result).toEqual({ ok: true, value: input });
+  });
+
+  it('keeps the detached authoring POD limited to the three resolution fields', () => {
+    expectTypeOf<DynamicResolutionData>().toEqualTypeOf<{
+      readonly targetGpuMs: number;
+      readonly minScale: number;
+      readonly maxScale: number;
+    }>();
+    expectTypeOf<keyof DynamicResolutionData>().toEqualTypeOf<
+      'targetGpuMs' | 'minScale' | 'maxScale'
+    >();
+  });
+});

package/src/components/__tests__/light-radius.integration.test.ts

@@ -0,0 +1,59 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { renderComponentsPlugin } from '../../plugin';
+import { DirectionalLight, DirectionalShadowFilterValue } from '../directional-light';
+import { validateDirectionalLightData } from '../light-helpers';
+
+function adjacentFloat32(value: number, direction: -1 | 1): number {
+  const floats = new Float32Array([value]);
+  const bits = new Uint32Array(floats.buffer);
+  bits[0] = (bits[0] ?? 0) + direction;
+  return floats[0] ?? NaN;
+}
+
+describe('PCSS angular radius storage boundary', () => {
+  for (const shadowFilter of [
+    DirectionalShadowFilterValue.pcssMedium,
+    DirectionalShadowFilterValue.pcssHigh,
+  ]) {
+    it(`accepts both authored endpoints after World spawn and set (${shadowFilter})`, async () => {
+      const world = new World();
+      const context = await createWorldContext(world, [renderComponentsPlugin()]);
+      try {
+        for (const radius of [0.0001, 0.05]) {
+          const data = { direction: [0, -1, 0], shadowFilter, shadowAngularRadius: radius };
+          expect(validateDirectionalLightData(data).ok).toBe(true);
+          const entity = world.spawn({ component: DirectionalLight, data }).unwrap();
+          const stored = world.get(entity, DirectionalLight).unwrap();
+          expect(stored.shadowAngularRadius).toBe(Math.fround(radius));
+          expect(validateDirectionalLightData(stored).ok).toBe(true);
+          world.set(entity, DirectionalLight, { shadowAngularRadius: 0.025 }).unwrap();
+          world.set(entity, DirectionalLight, { shadowAngularRadius: radius }).unwrap();
+          expect(
+            validateDirectionalLightData(world.get(entity, DirectionalLight).unwrap()).ok,
+          ).toBe(true);
+        }
+      } finally {
+        await context.fiber.dispose();
+      }
+    });
+  }
+
+  it.each([
+    adjacentFloat32(0.0001, -1),
+    adjacentFloat32(0.05, 1),
+    0,
+    -1,
+    NaN,
+    Infinity,
+    -Infinity,
+  ])('rejects a radius outside the float32 endpoints: %s', (shadowAngularRadius) => {
+    const result = validateDirectionalLightData({
+      direction: [0, -1, 0],
+      shadowFilter: DirectionalShadowFilterValue.pcssHigh,
+      shadowAngularRadius,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('shadow-invalid-config');
+  });
+});

package/src/components/directional-light.ts

@@ -60,8 +60,8 @@ export {
  *   splitLambda    ∈ [0,1]      — PSSM split weight (default 0.75)
  *   cascadeBlend   ∈ [0,0.5]    — blend width between cascades (default 0.2)
  *   mapSize        >= 1         — shadow map resolution (default 2048)
- *   depthBias                    — shadow acne bias (default 0.005)
- *   normalBias                   — shadow acne normal offset (default 0.05)
+ *   depthBias                    — normalized receiver depth subtraction (default 0.00001)
+ *   normalBias                   — world-space receiver normal offset (default 0.05)
  *   shadowDistance > 0           — how far shadows reach in front of the camera,
  *                                  in world units (default 200). This is the sole
  *                                  coverage knob: the CSM cascades are PSSM-split
@@ -123,7 +123,7 @@ export const DirectionalLight = defineComponent('DirectionalLight', {
   splitLambda: { type: 'f32', default: 0.75 },
   cascadeBlend: { type: 'f32', default: 0.2 },
   mapSize: { type: 'f32', default: 2048 },
-  depthBias: { type: 'f32', default: 0.005 },
+  depthBias: { type: 'f32', default: 0.00001 },
   normalBias: { type: 'f32', default: 0.05 },
   // Sole shadow coverage knob (feat replaces nearPlane/farPlane). The PSSM
   // near end derives from the active camera near; shadowDistance is the far