@forgeax/engine-render 0.1.20 → 0.1.21

package/src/extract/visibility.ts

@@ -1,4 +1,5 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { createWorldProjection } from '@forgeax/engine-ecs/projection';
 import {
   projectHierarchy,
   type SceneHierarchyDiagnostic,
@@ -37,6 +38,14 @@ interface ResolutionState {
   readonly source: VisibilitySource;
 }
 
+interface VisibilityCacheEntry {
+  readonly changes: ReturnType<typeof createWorldProjection>;
+  readonly hierarchy: SceneHierarchySnapshot;
+  readonly snapshot: VisibilitySnapshot;
+}
+
+const VISIBILITY_CACHE = new WeakMap<World, VisibilityCacheEntry>();
+
 /**
  * Resolve author intent against the scene-owned valid parent projection.
  * Diagnostics are preserved for callers to repair hierarchy input before retry.
@@ -45,6 +54,19 @@ export function resolveVisibility(
   world: World,
   hierarchy: SceneHierarchySnapshot = projectHierarchy(world),
 ): VisibilitySnapshot {
+  const cached = VISIBILITY_CACHE.get(world);
+  const changes = cached?.changes ?? createWorldProjection(world, { components: [Visibility] });
+  if (cached !== undefined) {
+    const evidence = changes.poll();
+    if (
+      evidence.status === 'delta' &&
+      evidence.changes.length === 0 &&
+      cached.hierarchy === hierarchy
+    ) {
+      return cached.snapshot;
+    }
+  }
+
   // Visibility is an opt-in component. Query only the owning archetypes
   // instead of walking every Entity row with an optional column; the latter
   // made a World with no visibility intents pay a full-scene scan on each
@@ -123,7 +145,7 @@ export function resolveVisibility(
     };
   };
 
-  return {
+  const snapshot: VisibilitySnapshot = {
     diagnostics: hierarchy.diagnostics,
     hasAnyIntent: intentCount > 0,
     hasAnyHiddenIntent,
@@ -136,4 +158,6 @@ export function resolveVisibility(
       return resolveEntity?.(entity)?.effective ?? 'visible';
     },
   };
+  VISIBILITY_CACHE.set(world, { changes, hierarchy, snapshot });
+  return snapshot;
 }

package/src/features/fullscreen.ts

@@ -28,6 +28,9 @@ export function createFullscreenRenderFeature(
   const resourceName = `fullscreen.${options.identity.replace(/[^a-z0-9.-]/gi, '-').toLowerCase()}`;
   return Object.freeze({
     identity: options.identity,
+    requiredFullscreenPostProcesses: Object.freeze([
+      Object.freeze({ identity: options.identity, source: options.source }),
+    ]),
     extract: (_context: RenderFeatureExtractContext) => ok(undefined),
     plan: (_data: undefined, _context: RenderFeaturePlanContext) =>
       ok({

package/src/features/targets.ts

@@ -57,8 +57,11 @@ export function resolveStandardRenderFeatureTargets(input: {
   readonly colorAttachmentFormat: TextureFormat;
 }): readonly RenderFeatureTargetHandle[] {
   const sampleCount: 1 | 4 = input.antialias === 'msaa' && input.multisample ? 4 : 1;
+  // Standard always exposes the scene to features as a linear float target;
+  // the shared Output Transform owns the eventual RGBA8 write for every
+  // antialias mode, including no-AA/WebGL2.
   const linearLdr =
-    (input.tonemap === 'none' && input.storageBuffer) ||
+    input.tonemap === 'none' ||
     input.antialias === 'fxaa' ||
     (input.antialias === 'msaa' && input.multisample);
   const colorFormat =

package/src/features/types.ts

@@ -98,6 +98,16 @@ export interface RenderFeature<FrameData> {
    * the same lazy module cache used by prepared graphics.
    */
   readonly requiredMaterialShaders?: readonly string[];
+  /**
+   * Fullscreen program sources that must be module-ready before the first
+   * frame. The renderer seeds the same lazy post-process module cache used by
+   * the typed graph, so a synchronous frame driver cannot observe a cleared
+   * target while a boot-installed effect is compiling.
+   */
+  readonly requiredFullscreenPostProcesses?: readonly {
+    readonly identity: string;
+    readonly source: string;
+  }[];
   extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
   plan(data: FrameData, context: RenderFeaturePlanContext): Result<RenderFeaturePlan, RenderError>;
 }

package/src/fullscreen-post-process-pass.ts

@@ -67,7 +67,8 @@ export type PostProcessReadSampleType = 'depth';
  * no paramSchema (params are passed inline via a {type, value} struct — plan-strategy D-4).
  *
  * `params` carries the WGSL struct definition + default value. When `params` is
- * `undefined`, the post-process shader has no UBO (e.g. FXAA — Finding M2-1).
+ * `undefined`, the post-process shader has no params UBO. Special graph-owned
+ * passes such as FXAA may still register an internal policy UBO separately.
  *
  * `reads` declares graph resource keys this pass samples as input texture(s).
  * If omitted, the pass samples the swap-chain color attachment (default path).
@@ -81,7 +82,7 @@ export interface PostProcessShaderEntry {
   /** Composed WGSL source for the fragment stage (post-naga_oil). */
   readonly source: string;
   /**
-   * Params UBO schema. When undefined, the shader has no uniform buffer (e.g. FXAA)
+   * Params UBO schema. When undefined, the generic shader has no uniform buffer
    * and the BGL degrades to 2 entries (texture@0 + sampler@1). When present, the
    * primitive eager-creates a params UBO (at register, sized `byteSize`) and binds
    * it at bindgroup(1) binding(2) as part of a 3-entry BGL
@@ -104,6 +105,46 @@ export interface PostProcessShaderEntry {
   readonly reads?: readonly (string | PostProcessReadEntry)[] | undefined;
 }
 
+function postProcessSourceDigest(source: string): string {
+  let first = 0x811c9dc5;
+  let second = 0x9e3779b9;
+  for (let index = 0; index < source.length; index += 1) {
+    const code = source.charCodeAt(index);
+    first = Math.imul(first ^ code, 0x01000193);
+    second = Math.imul(second ^ (code + index), 0x01000193);
+  }
+  return `${source.length.toString(16)}-${(first >>> 0).toString(16).padStart(8, '0')}-${(second >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+/** Content-addressed PSO label shared by the post-process pipeline factory. */
+export function postProcessShaderPipelineLabel(identity: string, source: string): string {
+  return `post-process-${identity}-pso-${postProcessSourceDigest(source)}`;
+}
+
+/** Content-addressed shader-module label shared by prewarm and lazy paths. */
+export function postProcessShaderModuleLabel(identity: string, source: string): string {
+  return `${postProcessShaderPipelineLabel(identity, source)}-module`;
+}
+
+/**
+ * Stable declaration identity used by graph admission and the renderer's
+ * device-bound pipeline cache.  Shader source, bind-group-affecting params,
+ * and graph reads must move together when a feature reuses its identity.
+ */
+export function postProcessShaderEntrySignature(entry: PostProcessShaderEntry): string {
+  return JSON.stringify({
+    source: entry.source,
+    params:
+      entry.params === undefined
+        ? undefined
+        : {
+            byteSize: entry.params.byteSize,
+            defaultValue: Array.from(entry.params.defaultValue),
+          },
+    reads: entry.reads,
+  });
+}
+
 /** Whether a feature binding opts into the temporal multi-read contract. */
 export function isTemporalFullscreenBinding(values: Readonly<Record<string, unknown>>): boolean {
   return (

package/src/gpu-driven/batch-topology.ts

@@ -53,6 +53,7 @@ function eligibleKeys(slot: RenderSceneSlot): readonly GpuDrivenBatchKey[] {
   if (
     draws === undefined ||
     draws.length === 0 ||
+    snapshot.instances?.instanceCount === 0 ||
     snapshot.localAabb === undefined ||
     snapshot.skin !== undefined ||
     snapshot.spriteInstances !== undefined

package/src/gpu-driven/production-raster.ts

@@ -427,7 +427,6 @@ export class GpuDrivenProduction {
     readonly meshes: ReadonlyMap<number, MeshGpuHandles>;
     readonly viewBindGroupLayout: BindGroupLayout;
     readonly meshResidencyEpoch: number;
-    readonly hdrp: boolean;
   }): Result<PreparedGpuDrivenFrame | undefined, RhiError> {
     this.gpuOwnedSnapshotsMaterialized = 0;
     this.filteredPlanBuilds = 0;
@@ -435,7 +434,6 @@ export class GpuDrivenProduction {
     this.validatedGpuOwnedRows = 0;
     this.cpuFallbackDrawItems = 0;
     if (
-      input.hdrp ||
       input.scene === undefined ||
       !this.device.caps.compute ||
       !this.device.caps.storageBuffer ||
@@ -611,7 +609,7 @@ export class GpuDrivenProduction {
             // shared by the GPU-driven raster pipeline, so even rigid draws
             // must provide the binding-10 offset (zero selects the frame
             // default slot).
-            pass.setBindGroup(0, viewBindGroup, [0]);
+            pass.setBindGroup(0, viewBindGroup, [0, 0]);
             let currentPipeline: RenderPipeline | undefined;
             let currentVertex: GraphBuffer | undefined;
             let currentIndex: GraphBuffer | undefined;

package/src/gpu-scene.ts

@@ -633,7 +633,14 @@ export class GpuScene {
     record: RenderSceneSlot,
     writes: Record<GpuSceneTableName, number[]>,
   ): void {
-    const instanceCount = Math.max(1, record.snapshot.instances?.instanceCount ?? 1);
+    // A present Instances component is authoritative even when its array is
+    // empty: preserve zero so neither the GPU Scene nor the indirect topology
+    // turns it into a synthetic identity instance. Entities without the
+    // component retain the ordinary one-instance identity path.
+    const instanceCount =
+      record.snapshot.instances === undefined
+        ? 1
+        : Math.max(0, Math.floor(record.snapshot.instances.instanceCount));
     const drawCount = Math.max(1, record.snapshot.gpuDrivenDraws?.length ?? 0);
     const materialCount = Math.max(1, record.snapshot.materials.length);
     const existing = this.allocations.get(record.slot);

package/src/hdrp-buffers.ts

@@ -48,6 +48,7 @@ import {
   GPU_BUFFER_USAGE_UNIFORM,
 } from './gpu-usage';
 import { BYTES_PER_LIGHT_SLOT } from './light-buffer-layout';
+import { createPbrSkinMeshBindGroupEntries } from './pbr-pipeline';
 import {
   CLUSTER_GRID_STRIDE_U32,
   DEFAULT_CLUSTER_GRID,
@@ -55,20 +56,12 @@ import {
   MAX_LIGHTS,
 } from './pipeline/standard-profile';
 import { createHdrpBindGroupLayoutDescriptor } from './pipeline-spec';
-import { MESH_PER_ENTITY_STRIDE, MESH_UBO_FULL_ARRAY_BYTES } from './record/mesh-ssbo';
+import { MESH_PER_ENTITY_STRIDE } from './record/mesh-ssbo';
 import type { RenderSystemRuntime } from './record/render-context';
 import { getOrCreateSsaoFallbackTexture } from './ssao-buffers';
 
 export { getOrCreateSsaoFallbackTexture } from './ssao-buffers';
 
-/**
- * WebGL2 HDRP downlevel light-list capacity. 128 x 64 B = 8 KiB, below the
- * WebGL2 minimum uniform-buffer binding size of 16 KiB. The storage path
- * keeps the full MAX_LIGHTS budget; the uniform path uses the same LightSlot
- * POD and only changes the transport.
- */
-export const HDRP_UNIFORM_LIGHT_CAPACITY = 128;
-
 /** Bind-group layout used only by the WebGPU cluster membership producer. */
 export function createHdrpClusterMembershipBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor {
   return {
@@ -111,9 +104,9 @@ export function createHdrpClusterMembershipBindGroupLayoutDescriptor(): BindGrou
  * cluster 4 buffer).
  */
 export interface HdrpBuffers {
-  /** Whether bindings 3..5 carry storage buffers or uniform-buffer fallback data. */
-  readonly storageBuffer: boolean;
-  /** light_data -- 256 x 64 B on storage, 128 x 64 B on uniform fallback. */
+  /** Device identity that owns every handle in this bundle. */
+  readonly device: RenderSystemRuntime['device'];
+  /** light_data -- the full 256 x 64 B Standard light budget. */
   readonly lightDataBuffer: Buffer;
   readonly lightDataBytes: number;
   /** cluster_grid SSBO -- gridX*gridY*gridZ * 2 u32, BGL slot 4. */
@@ -145,66 +138,92 @@ const cache = new WeakMap<RenderSystemRuntime, HdrpBuffers>();
  * pipeline disable (charter P3 explicit failure).
  *
  * `grid` defaults to `DEFAULT_CLUSTER_GRID` when undefined (matches the M5
- * record-stage default). The buffers are sized at the *first* call's grid; a
- * later install with a different grid keeps the existing allocation as long as
- * it has enough capacity (gridX*gridY*gridZ <= cached.grid product). Different
- * grids that exceed capacity are not currently re-allocated -- M-future.
+ * record-stage default). A smaller grid reuses the existing capacity. When a
+ * later install requests a larger grid, this owner allocates a complete new
+ * bundle, publishes it atomically, and retires the previous bundle after the
+ * device queue fence so graph and bind-group caches never observe a partially
+ * replaced resource set.
  */
 export function getOrCreateHdrpBuffers(
   runtime: RenderSystemRuntime,
   grid: { x: number; y: number; z: number } = DEFAULT_CLUSTER_GRID,
 ): HdrpBuffers | null {
+  // Cluster has one code-level transport. Capability failure is handled by
+  // Standard transport admission; this owner never creates a second UBO ABI.
+  if (runtime.device.caps?.storageBuffer !== true) return null;
+  // Contract tests and reduced host adapters may advertise storage buffers
+  // without implementing the resource-creation surface. Treat that as a
+  // capability miss rather than dereferencing an absent method; callers
+  // already route `null` through the structured cluster-transport fallback.
+  const deviceSurface = runtime.device as unknown as {
+    readonly createBuffer?: unknown;
+    readonly createBindGroupLayout?: unknown;
+    readonly destroyBuffer?: unknown;
+  };
+  if (
+    typeof deviceSurface.createBuffer !== 'function' ||
+    typeof deviceSurface.createBindGroupLayout !== 'function' ||
+    typeof deviceSurface.destroyBuffer !== 'function'
+  ) {
+    return null;
+  }
   const cached = cache.get(runtime);
-  if (cached !== undefined) return cached;
-
+  if (cached !== undefined && cached.device === runtime.device) {
+    const requestedCells = grid.x * grid.y * grid.z;
+    const cachedCells = cached.grid.x * cached.grid.y * cached.grid.z;
+    if (requestedCells <= cachedCells) return cached;
+  }
   const device = runtime.device;
-  const storageBuffer = runtime.device.caps?.storageBuffer === true;
   const clusterUniformBytes = 32;
-  const lightDataBytes =
-    (storageBuffer ? MAX_LIGHTS : HDRP_UNIFORM_LIGHT_CAPACITY) * BYTES_PER_LIGHT_SLOT;
+  const lightDataBytes = MAX_LIGHTS * BYTES_PER_LIGHT_SLOT;
   const clusterCells = grid.x * grid.y * grid.z;
-  const clusterGridBytes = storageBuffer
-    ? clusterCells * CLUSTER_GRID_STRIDE_U32 * 4
-    : clusterUniformBytes;
-  const lightIndexListBytes = storageBuffer ? LIGHT_INDEX_LIST_CAPACITY * 4 : clusterUniformBytes;
+  const clusterGridBytes = clusterCells * CLUSTER_GRID_STRIDE_U32 * 4;
+  const lightIndexListBytes = LIGHT_INDEX_LIST_CAPACITY * 4;
   const lightBoundsBytes = MAX_LIGHTS * 6 * 4;
+  const created: Buffer[] = [];
+  const releaseCreated = (): void => {
+    for (const buffer of created) {
+      const result = device.destroyBuffer(buffer);
+      if (!result.ok) runtime.errorRegistry.fire(result.error);
+    }
+    created.length = 0;
+  };
+  const failAllocation = (error: RhiError): null => {
+    runtime.errorRegistry.fire(error);
+    releaseCreated();
+    return null;
+  };
 
   const lightData = device.createBuffer({
     label: 'hdrp-light-data',
     size: lightDataBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!lightData.ok) {
-    runtime.errorRegistry.fire(lightData.error);
-    return null;
+    return failAllocation(lightData.error);
   }
+  created.push(lightData.value);
   const clusterGrid = device.createBuffer({
     label: 'hdrp-cluster-grid',
     size: clusterGridBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!clusterGrid.ok) {
-    runtime.errorRegistry.fire(clusterGrid.error);
-    return null;
+    return failAllocation(clusterGrid.error);
   }
+  created.push(clusterGrid.value);
   const lightIndexList = device.createBuffer({
     label: 'hdrp-light-index-list',
     size: lightIndexListBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!lightIndexList.ok) {
-    runtime.errorRegistry.fire(lightIndexList.error);
-    return null;
+    return failAllocation(lightIndexList.error);
   }
+  created.push(lightIndexList.value);
   const clusterUniform = device.createBuffer({
     label: 'hdrp-cluster-uniform',
     size: clusterUniformBytes,
@@ -212,36 +231,30 @@ export function getOrCreateHdrpBuffers(
     mappedAtCreation: false,
   });
   if (!clusterUniform.ok) {
-    runtime.errorRegistry.fire(clusterUniform.error);
-    return null;
+    return failAllocation(clusterUniform.error);
   }
+  created.push(clusterUniform.value);
   const lightBounds = device.createBuffer({
     label: 'hdrp-light-bounds',
     size: lightBoundsBytes,
-    usage:
-      (storageBuffer ? GPU_BUFFER_USAGE_STORAGE : GPU_BUFFER_USAGE_UNIFORM) |
-      GPU_BUFFER_USAGE_COPY_DST,
+    usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
   if (!lightBounds.ok) {
-    runtime.errorRegistry.fire(lightBounds.error);
-    return null;
+    return failAllocation(lightBounds.error);
   }
+  created.push(lightBounds.value);
 
   // Create the unified 7-entry BGL layout for group(2)
   // (plan D-6, feat-20260609-hdrp-cluster-fragment-ggx M3).
   // The HDRP BGL descriptor is owned by pipeline-spec and shared with the
   // pipeline dispatcher and its byte-identical tests.
-  const storageBufferCap = runtime.device.caps?.storageBuffer === true;
-  const unifiedBglRes = device.createBindGroupLayout(
-    createHdrpBindGroupLayoutDescriptor(storageBufferCap),
-  );
+  const unifiedBglRes = device.createBindGroupLayout(createHdrpBindGroupLayoutDescriptor());
   if (!unifiedBglRes.ok) {
-    runtime.errorRegistry.fire(unifiedBglRes.error);
-    return null;
+    return failAllocation(unifiedBglRes.error);
   }
   const buffers: HdrpBuffers = {
-    storageBuffer,
+    device,
     lightDataBuffer: lightData.value,
     lightDataBytes,
     clusterGridBuffer: clusterGrid.value,
@@ -256,16 +269,57 @@ export function getOrCreateHdrpBuffers(
     unifiedBindGroupLayout: unifiedBglRes.value,
   };
   cache.set(runtime, buffers);
+  if (cached !== undefined) {
+    retireHdrpBuffers(runtime, cached);
+  }
   return buffers;
 }
 
+/**
+ * Drop the cached bundle before a device recovery or renderer disposal. The
+ * bundle carries the old device identity, so retirement fences that device's
+ * queue instead of consulting the replacement runtime device.
+ */
+export function resetHdrpBuffers(runtime: RenderSystemRuntime): void {
+  const cached = cache.get(runtime);
+  if (cached === undefined) return;
+  cache.delete(runtime);
+  retireHdrpBuffers(runtime, cached);
+}
+
+function retireHdrpBuffers(runtime: RenderSystemRuntime, buffers: HdrpBuffers): void {
+  const device = buffers.device;
+  const destroy = (): void => {
+    for (const buffer of [
+      buffers.lightDataBuffer,
+      buffers.clusterGridBuffer,
+      buffers.lightIndexListBuffer,
+      buffers.clusterUniformBuffer,
+      buffers.lightBoundsBuffer,
+    ]) {
+      const result = device.destroyBuffer(buffer);
+      if (!result.ok) runtime.errorRegistry.fire(result.error);
+    }
+  };
+  const queue = device.queue as {
+    readonly onSubmittedWorkDone?: () => Promise<undefined>;
+  };
+  if (typeof queue.onSubmittedWorkDone === 'function') {
+    queue.onSubmittedWorkDone().then(destroy, destroy);
+  } else {
+    // Minimal null/test devices may not expose queue fences; they also have no
+    // submitted work that can retain the old bundle, so release synchronously.
+    destroy();
+  }
+}
+
 /**
  * Build the 8-float cluster_uniform std140 payload.
  *
  *   [0] gridX  u32 (cast in shader)
  *   [1] gridY  u32
  *   [2] gridZ  u32
- *   [3] lightCount u32 (vec4 alignment; capped by the active transport)
+ *   [3] lightCount u32 (vec4 alignment; capped by MAX_LIGHTS)
  *   [4] near   f32
  *   [5] far    f32
  *   [6] logFarOverNear  f32
@@ -286,7 +340,6 @@ export function packClusterUniform(
   far: number,
   ssaoIntensity: number = 0,
   lightCount: number = 0,
-  lightCapacity: number = HDRP_UNIFORM_LIGHT_CAPACITY,
 ): ArrayBuffer {
   const buf = new ArrayBuffer(32);
   const u32 = new Uint32Array(buf);
@@ -294,7 +347,7 @@ export function packClusterUniform(
   u32[0] = grid.x >>> 0;
   u32[1] = grid.y >>> 0;
   u32[2] = grid.z >>> 0;
-  u32[3] = Math.min(Math.max(lightCount, 0), lightCapacity) >>> 0;
+  u32[3] = Math.min(Math.max(lightCount, 0), MAX_LIGHTS) >>> 0;
   f32[4] = near;
   f32[5] = far;
   // logFarOverNear: log(far/near) used by the shader for log-z slice mapping.
@@ -318,7 +371,7 @@ export function packClusterUniform(
  * feat-20260609-hdrp-cluster-fragment-ggx M4 / w19. Called per-frame from the
  * recordFrame HDRP block after binner+writeBuffer; the resulting BindGroup
  * lands on `passCtx.hdrpClusterBindGroup` and recordMainPass binds it at
- * group(2) when `frameState.isHdrpActive`.
+ * group(2) when the prepared Standard topology selects clustered lighting.
  *
  * Returns `null` on `device.createBindGroup` failure (a structured RhiError
  * is fired on `runtime.errorRegistry`); recordMainPass gracefully falls back
@@ -386,7 +439,7 @@ export function createHdrpUnifiedBindGroup(
           value: {
             buffer: meshStorageBuffer,
             offset: 0,
-            size: hdrpBuffers.storageBuffer ? MESH_PER_ENTITY_STRIDE : MESH_UBO_FULL_ARRAY_BYTES,
+            size: MESH_PER_ENTITY_STRIDE,
           },
         },
       },
@@ -435,6 +488,59 @@ export function createHdrpUnifiedBindGroup(
   return result.value;
 }
 
+/** Build the clustered skin group(2) bind group with one shared palette window. */
+export function createHdrpSkinUnifiedBindGroup(
+  runtime: RenderSystemRuntime,
+  hdrpBuffers: HdrpBuffers,
+  layout: BindGroupLayout,
+  meshStorageBuffer: Buffer,
+  paletteBuffer: Buffer,
+  paletteBindingWindowBytes: number,
+  ssaoOptions: SsaoBindOptions = { enabled: false },
+): BindGroup | null {
+  const fallback = getOrCreateSsaoFallbackTexture(runtime);
+  if (fallback === null) return null;
+  const meshSize = MESH_PER_ENTITY_STRIDE;
+  const result = runtime.device.createBindGroup({
+    label: 'hdrp-skin-unified-bg-group2',
+    layout,
+    entries: [
+      ...createPbrSkinMeshBindGroupEntries(
+        meshStorageBuffer,
+        meshSize,
+        paletteBuffer,
+        paletteBindingWindowBytes,
+      ),
+      { binding: 3, resource: { kind: 'buffer', value: { buffer: hdrpBuffers.lightDataBuffer } } },
+      {
+        binding: 4,
+        resource: { kind: 'buffer', value: { buffer: hdrpBuffers.clusterGridBuffer } },
+      },
+      {
+        binding: 5,
+        resource: { kind: 'buffer', value: { buffer: hdrpBuffers.lightIndexListBuffer } },
+      },
+      {
+        binding: 6,
+        resource: { kind: 'buffer', value: { buffer: hdrpBuffers.clusterUniformBuffer } },
+      },
+      {
+        binding: 7,
+        resource: {
+          kind: 'textureView',
+          value: ssaoOptions.enabled ? ssaoOptions.ssaoBlurredView : fallback.view,
+        },
+      },
+      { binding: 8, resource: { kind: 'sampler', value: fallback.sampler } },
+    ],
+  });
+  if (!result.ok) {
+    runtime.errorRegistry.fire(result.error);
+    return null;
+  }
+  return result.value;
+}
+
 /**
  * Build the compute-only bind group for ordered cluster membership output.
  * Its group is intentionally separate from the fragment group: the same

package/src/ibl/IblPipelineCache.ts

@@ -43,6 +43,14 @@ import {
   type TextureView,
 } from '@forgeax/engine-rhi';
 import type { DeviceScope } from '../device/device-scope';
+import { createIblKernelCache, type IblKernelCache } from './kernel-cache';
+
+export {
+  createIblKernelCache,
+  type IblKernelCache,
+  resetIblKernelCaches,
+} from './kernel-cache';
+
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
 import {
   GPU_TEXTURE_USAGE_COPY_DST,
@@ -90,6 +98,8 @@ export interface IblPipelineError {
  * (idempotent).
  */
 export interface IblPipelineCache {
+  /** Reusable generation-scoped kernel state; per-probe outputs stay elsewhere. */
+  readonly probeKernel: IblKernelCache;
   /** Color format shared by all precompute outputs for this device. */
   outputFormat?: TextureFormat;
   /** Equirectangular-to-cubemap pipeline. */
@@ -151,6 +161,7 @@ export function getOrCreateIblCache(scope: DeviceScope): IblPipelineCache {
   if (existing !== undefined) return existing;
 
   const cache: IblPipelineCache = {
+    probeKernel: createIblKernelCache(scope.generation),
     irradianceBakeCount: 0,
     prefilterBakeCount: 0,
     brdfLutBakeCount: 0,