@forgeax/engine-render 0.1.20 → 0.1.21

package/src/mesh-material-bindings.ts

@@ -17,12 +17,144 @@ export interface ResolvedMeshMaterialBinding {
   readonly source: MeshMaterialBindingSource;
 }
 
+/** Lifecycle values projected from an already prepared resident binding. */
+export type MeshMaterialBindingReadiness = 'ready' | 'pending' | 'failed' | 'last-known-good';
+
+/** Structured producer failure retained by the renderer's bounded projection. */
+export interface MeshMaterialBindingPreparationFailure {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+export interface MeshMaterialBindingSamplerObservation {
+  readonly handle: number;
+  readonly resident: boolean;
+}
+
+export interface MeshMaterialBindingTextureObservation {
+  readonly handle: number;
+  readonly mipLevelCount: number;
+}
+
+/**
+ * One material-slot's bounded resident projection. The renderer reports only
+ * resources it actually resolved for the slot; Pack/AssetRegistry lifecycle
+ * records stay owned by the producer and are never copied here.
+ */
+export interface MeshMaterialBindingResidency {
+  readonly readiness: MeshMaterialBindingReadiness;
+  readonly samplers: readonly MeshMaterialBindingSamplerObservation[];
+  readonly textures: readonly MeshMaterialBindingTextureObservation[];
+  readonly preparationFailure?: MeshMaterialBindingPreparationFailure;
+}
+
 /** Public read-only observation of the bindings used by the last frame. */
 export interface MeshMaterialBindingObservation {
   readonly worldId: number;
   readonly entityKey: number;
   readonly bindings: readonly ResolvedMeshMaterialBinding[];
   readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
+  /** One resident projection per resolved material slot. */
+  readonly residency: readonly MeshMaterialBindingResidency[];
+}
+
+export interface MeshMaterialBindingSummary {
+  readonly total: number;
+  readonly ready: number;
+  readonly pending: number;
+  readonly failed: number;
+  readonly lastKnownGood: number;
+  readonly textureCount: number;
+  readonly samplerCount: number;
+}
+
+const EMPTY_RESIDENCY: MeshMaterialBindingResidency = Object.freeze({
+  readiness: 'pending',
+  samplers: Object.freeze([]),
+  textures: Object.freeze([]),
+});
+
+/**
+ * Build the sole renderer observation projection from the resident seam.
+ * Missing facts remain `pending`; they are never guessed from a URL, asset
+ * name, or authoring field. Slot cardinality is normalized so aggregation is
+ * deterministic even while a preparation candidate is incomplete.
+ */
+export function projectMeshMaterialBindingObservation(input: {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly bindings: readonly ResolvedMeshMaterialBinding[];
+  readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
+  readonly residency?: readonly MeshMaterialBindingResidency[];
+}): MeshMaterialBindingObservation {
+  const residency = input.bindings.map((_, index) => {
+    const value = input.residency?.[index] ?? EMPTY_RESIDENCY;
+    return Object.freeze({
+      ...value,
+      samplers: Object.freeze(value.samplers.map((sampler) => Object.freeze({ ...sampler }))),
+      textures: Object.freeze(value.textures.map((texture) => Object.freeze({ ...texture }))),
+      ...(value.preparationFailure === undefined
+        ? {}
+        : {
+            preparationFailure: Object.freeze({
+              ...value.preparationFailure,
+              ...(value.preparationFailure.detail === undefined
+                ? {}
+                : { detail: Object.freeze({ ...value.preparationFailure.detail }) }),
+            }),
+          }),
+    });
+  });
+  return {
+    worldId: input.worldId,
+    entityKey: input.entityKey,
+    bindings: Object.freeze([...input.bindings]),
+    diagnostics: Object.freeze([...input.diagnostics]),
+    residency: Object.freeze(residency),
+  };
+}
+
+/** Recompute bounded readiness/resource counts from retained observations. */
+export function summarizeMeshMaterialBindings(
+  observations: readonly MeshMaterialBindingObservation[],
+): MeshMaterialBindingSummary {
+  let ready = 0;
+  let pending = 0;
+  let failed = 0;
+  let lastKnownGood = 0;
+  let textureCount = 0;
+  let samplerCount = 0;
+  for (const observation of observations) {
+    for (const residency of observation.residency) {
+      switch (residency.readiness) {
+        case 'ready':
+          ready += 1;
+          break;
+        case 'pending':
+          pending += 1;
+          break;
+        case 'failed':
+          failed += 1;
+          break;
+        case 'last-known-good':
+          lastKnownGood += 1;
+          break;
+      }
+      textureCount += residency.textures.length;
+      samplerCount += residency.samplers.length;
+    }
+  }
+  return {
+    total: ready + pending + failed + lastKnownGood,
+    ready,
+    pending,
+    failed,
+    lastKnownGood,
+    textureCount,
+    samplerCount,
+  };
 }
 
 export type ResolveMeshMaterialBindingsResult =

package/src/pbr-pipeline.ts

@@ -382,7 +382,9 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
     {
       binding: 0,
       visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
-      buffer: { type: 'uniform' },
+      // View captures use the same bind group with a per-face view slot.
+      // Keeping this dynamic is also valid for the display slot at offset 0.
+      buffer: { type: 'uniform', hasDynamicOffset: true },
     },
     {
       binding: 1,
@@ -600,6 +602,22 @@ export function isSkinnedShadowCasterVariant(
   );
 }
 
+export type PipelineGroup2Contract = 'mesh' | 'skin' | 'cluster' | 'skin-cluster';
+
+/** Resolve group(2) from the composed WGSL artifact used to build the PSO. */
+export function resolvePipelineGroup2Contract(source: string): PipelineGroup2Contract {
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//gu, '').replace(/\/\/.*$/gmu, '');
+  const bindings = [
+    ...withoutComments.matchAll(/@group\s*\(\s*2\s*\)\s*@binding\s*\(\s*(\d+)\s*\)/gu),
+  ].map((match) => Number(match[1]));
+  const hasSkinBindings = bindings.includes(1) || bindings.includes(2);
+  const hasClusterBindings = bindings.some((binding) => binding >= 3);
+  if (hasSkinBindings && hasClusterBindings) return 'skin-cluster';
+  if (hasSkinBindings) return 'skin';
+  if (hasClusterBindings) return 'cluster';
+  return 'mesh';
+}
+
 /** Returns true for the engine-shipped standard-PBR material shader family. */
 export function isStandardPbrMaterialShader(shaderId: string | undefined): boolean {
   return (
@@ -631,9 +649,10 @@ export function isStandardPbrMaterialShader(shaderId: string | undefined): boole
 
 /**
  * Build the PBR skin pipeline layout (4 slots `[view, material,
- * mesh-array(2-entry), instances]`). View / material / instances BGLs are
+ * mesh-array(3-entry), instances]`). View / material / instances BGLs are
  * shared with the standard-PBR layout (passed in via `pbr` bundle); the only
- * new BGL is the 2-entry mesh-array slot for `meshes` + `palette`.
+ * new BGL is the 3-entry mesh-array slot for `meshes` + current/previous
+ * `palette` buffers.
  *
  * Throws on each `createBindGroupLayout` / `createPipelineLayout` Result
  * failure -- the engine bootstrap path wraps the call in `runShimSyncStep`
@@ -644,8 +663,9 @@ export function buildPbrSkinLayouts(
   caps: PbrCaps,
   pbr: PbrPipelineLayoutBundle,
 ): PbrPipelineLayoutBundle {
-  // 2-entry mesh-array BGL: binding 0 meshes + binding 1 palette. Both
-  // dynamic-offset (palette window per-entity, like meshes window).
+  // 3-entry mesh-array BGL: binding 0 meshes + binding 1 current palette
+  // + binding 2 previous palette. All use dynamic offsets for the same
+  // per-entity window contract.
   const skinMeshArrayBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
       kind: 'pbr-skin-mesh-array',
@@ -676,6 +696,40 @@ export function buildPbrSkinLayouts(
   };
 }
 
+/** Project the canonical group(2) resources for a PBR skin draw. */
+export function createPbrSkinMeshBindGroupEntries(
+  meshBuffer: Buffer,
+  meshSize: number,
+  paletteBuffer: Buffer,
+  paletteWindowBytes: number,
+): BindGroupEntry[] {
+  return [
+    {
+      binding: 0,
+      resource: { kind: 'buffer', value: { buffer: meshBuffer, offset: 0, size: meshSize } },
+    },
+    ...[1, 2].map((binding) => ({
+      binding,
+      resource: {
+        kind: 'buffer' as const,
+        value: {
+          buffer: paletteBuffer,
+          offset: 0,
+          size: paletteWindowBytes,
+        },
+      },
+    })),
+  ];
+}
+
+/** Project all dynamic offsets for the canonical PBR skin group(2) shape. */
+export function pbrSkinMeshDynamicOffsets(
+  meshOffset: number,
+  paletteOffset: number,
+): readonly [number, number, number] {
+  return [meshOffset, paletteOffset, paletteOffset];
+}
+
 // ─── Unlit material BGL factory ─────────────────────────────────────────────
 
 /**
@@ -763,7 +817,7 @@ export type { BindGroup };
 // existing behaviour (plan-strategy D-4 "pbr / unlit / sprite-atlas
 // behaviour unchanged" / requirements Edge Cases).
 //
-// Variant set string format mirrors the existing `URP_PBR_VARIANT_SET` /
+// Variant set string format mirrors the Standard boot variant /
 // HDRP variant set string idiom in `pipeline-spec.ts` (`+`-separated kv
 // pairs); the record stage threads this string through the per-shader
 // pipeline-cache key + lazy-build `getMaterialShaderPipeline` lookup.
@@ -812,7 +866,7 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *      spot lightViewProj matrices moved into the View UBO)
  *    - `'pbr-mesh-array'` — 1 entry: per-entity mesh SSBO (dynamic-offset)
  *    - `'pbr-instances'` — 1 entry: per-instance SSBO (no dynamic-offset)
- *    - `'pbr-skin-mesh-array'` — 2 entries: meshes + skin palette
+ *    - `'pbr-skin-mesh-array'` — 3 entries: meshes + current/previous palette
  * 3. Attachment-driven (fullscreen post-process):
  *    - `'fullscreen-post'` — 2 entries: input texture + sampler. The texture
  *      `sampleType` is derived from `spec.attachments` (plan §R3 fix):
@@ -855,17 +909,20 @@ export interface BindGroupLayoutDescriptorOutput {
 }
 
 /** Build the canonical HDRP group(2) bind-group layout. */
-export function createHdrpBindGroupLayoutDescriptor(
-  storageBuffer: boolean = true,
-): BindGroupLayoutDescriptor {
-  const meshBufType: GPUBufferBindingType = storageBuffer ? 'read-only-storage' : 'uniform';
-  const clusterBufType: GPUBufferBindingType = storageBuffer ? 'read-only-storage' : 'uniform';
+export function createHdrpBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor {
+  const meshBufType: GPUBufferBindingType = 'read-only-storage';
+  const clusterBufType: GPUBufferBindingType = 'read-only-storage';
   return {
     label: 'hdrp-unified-bgl-group2',
     entries: [
       {
         binding: 0,
-        visibility: GPU_SHADER_STAGE_VERTEX,
+        // Standard fragment lighting (transmission/refraction and clustered
+        // evaluation) reads the same mesh transform window as the vertex
+        // stage. Keep this visibility in the HDRP descriptor aligned with
+        // the URP mesh-array descriptor; restricting it to vertex makes the
+        // HDRP pipeline invalid when fs_main accesses `meshes[0]`.
+        visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
         buffer: { type: meshBufType, hasDynamicOffset: true },
       },
       // Bindings 1 and 2 stay absent for the URP physical isolation gap.
@@ -903,6 +960,33 @@ export function createHdrpBindGroupLayoutDescriptor(
   };
 }
 
+/** Build the HDRP group(2) layout for the clustered skin variant. */
+export function createHdrpSkinBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor {
+  const base = createHdrpBindGroupLayoutDescriptor();
+  const baseEntries = base.entries;
+  if (baseEntries === undefined || baseEntries[0] === undefined) {
+    throw new Error('HDRP base group(2) layout must declare mesh binding 0');
+  }
+  const paletteType: GPUBufferBindingType = 'read-only-storage';
+  return {
+    label: 'hdrp-skin-unified-bgl-group2',
+    entries: [
+      baseEntries[0],
+      {
+        binding: 1,
+        visibility: GPU_SHADER_STAGE_VERTEX,
+        buffer: { type: paletteType, hasDynamicOffset: true },
+      },
+      {
+        binding: 2,
+        visibility: GPU_SHADER_STAGE_VERTEX,
+        buffer: { type: paletteType, hasDynamicOffset: true },
+      },
+      ...baseEntries.slice(1),
+    ],
+  };
+}
+
 /**
  * Build a `GPUBindGroupLayoutDescriptor` from a PipelineSpec, dispatching on
  * `options.kind` to one of 9 closed BGL shapes (D-13 round-2).
@@ -1037,6 +1121,11 @@ export function buildBindGroupLayoutDescriptor(
             visibility: GPU_SHADER_STAGE_VERTEX,
             buffer: { type: meshBufType, hasDynamicOffset: true },
           },
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: meshBufType, hasDynamicOffset: true },
+          },
         ],
       };
     }
@@ -1068,10 +1157,10 @@ export function buildBindGroupLayoutDescriptor(
       };
     }
     case 'hdrp-7-slot': {
-      // HDRP unified BGL for group(2): 9 entries (binding 0 + 3..8). The
-      // shape depends on caps.storageBuffer for the cluster-buffer fallback.
-      const caps = options.caps ?? { storageBuffer: true };
-      const desc = createHdrpBindGroupLayoutDescriptor(caps.storageBuffer);
+      // Standard unified BGL for group(2): 9 entries (binding 0 + 3..8).
+      // Cluster variants are admitted only when storage buffers are present;
+      // there is no uniform-backed cluster shape.
+      const desc = createHdrpBindGroupLayoutDescriptor();
       return {
         label: desc.label ?? 'hdrp-unified-bgl-group2',
         entries: [...(desc.entries ?? [])],

package/src/pipeline/standard-forward-lane.ts

@@ -35,6 +35,12 @@ import {
 } from '../typed-render-graph-primitives';
 import { addTypedShadowPasses } from '../typed-shadow-passes';
 import { addAuthoredVolumetricFogPasses } from '../volume/passes';
+import {
+  addStandardClusterMembershipPass,
+  importStandardClusterBuffers,
+  standardClusterReadAccesses,
+} from './standard-lighting/graph';
+import type { StandardTopologyInputValue } from './standard-lighting/topology';
 import { addStandardPost } from './standard-post';
 
 function target(
@@ -48,6 +54,7 @@ function target(
 function buildUrp(
   context: RenderPipelineBuildContext<RenderPipelineFrame>,
   topology: RenderPipelineTopology,
+  lighting: StandardTopologyInputValue,
 ): ReturnType<RenderPipeline['build']> {
   const graph = context.graph;
   const surface = importRenderPipelineSurface(graph, topology);
@@ -60,16 +67,14 @@ function buildUrp(
   const fxaa = !clearOnly && topology.camera.antialias === 'fxaa';
   const taa = !clearOnly && topology.camera.antialias === 'taa';
   const rawOnly = !clearOnly && topology.surface.profile?.kind === 'raw-only';
-  // A direct no-tone/no-FXAA lane writes the final display view directly;
-  // keeping a linear-LDR intermediate would add a redundant fullscreen pass.
-  // FXAA samples the scene before the Output Transform, so its input must
-  // remain float even when tone mapping is disabled. This prevents an
-  // eight-bit quantization before the OETF/display-encoded boundary.
+  // Every non-clear lane keeps a linear float scene target until the shared
+  // Output Transform. This includes no-AA and the no-storage fallback: the
+  // final dither and display encoding must have one graph-owned boundary.
   // MSAA resolves into a separate linear target before presentation. Treat
   // that resolved target like linear LDR so the shared Output Transform owns
   // its write into the surface storage view; without this, the resolve is
   // never presented and MSAA is indistinguishable from the no-AA path.
-  const linearLdr = !clearOnly && ((!hdr && topology.lane.storageBuffer) || fxaa || msaa);
+  const linearLdr = !clearOnly && !hdr;
   const temporalDemand = aggregateTemporalDemand({
     taa,
     motionBlur: !clearOnly && topology.temporal?.motionBlur === true,
@@ -88,7 +93,14 @@ function buildUrp(
   if (!depth.ok) return depth;
 
   const sceneResolved = clearOnly
-    ? ok(surface.value.display ?? surface.value.storage)
+    ? surface.value.display === undefined
+      ? target(graph, 'scene-color', {
+          format: topology.surface.storageFormat,
+          size: 'surface',
+          sampleCount: 1,
+          domain: 'display-encoded',
+        })
+      : ok(surface.value.display)
     : hdr || fxaa || linearLdr || msaa || rawOnly || needsTemporalIntermediate
       ? target(graph, 'scene-color', {
           format: sceneFormat,
@@ -126,6 +138,16 @@ function buildUrp(
   const shadows = addTypedShadowPasses(graph, topology);
   if (!shadows.ok) return shadows;
 
+  const clusterBuffers = clearOnly ? ok(null) : importStandardClusterBuffers(graph, lighting);
+  if (!clusterBuffers.ok) return clusterBuffers;
+  const clusterMembership =
+    clusterBuffers.value === null
+      ? ok(undefined)
+      : addStandardClusterMembershipPass(graph, lighting, clusterBuffers.value);
+  if (!clusterMembership.ok) return clusterMembership;
+  const clusterReads =
+    clusterBuffers.value === null ? [] : standardClusterReadAccesses(clusterBuffers.value);
+
   const skybox = addTypedSkyboxPass(graph, scene.value);
   if (!skybox.ok) return skybox;
   const gpuDriven = context.projectGpuDriven({
@@ -144,22 +166,23 @@ function buildUrp(
     depth: depth.value,
     ...(msaa ? { resolve: sceneResolved.value } : {}),
     sampled: [
-      shadows.value.directional,
+      ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
       shadows.value.spot,
       ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
     ],
-    directionalShadow: shadows.value.directional,
+    ...(shadows.value.directional === undefined
+      ? {}
+      : { directionalShadow: shadows.value.directional }),
     spotShadow: shadows.value.spot,
     selector: { LightMode: ['Forward'] },
     colorLoadOp: 'load',
+    extraAccesses: clusterReads,
     ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
   });
   if (!main.ok) return main;
 
-  const temporalLane = topology.lane.compute
-    ? (topology.standardProfile?.lighting ?? 'direct')
-    : 'cpu-webgl2';
+  const temporalLane = topology.lane.compute ? 'clustered' : 'cpu-webgl2';
   const temporalAdmission = standardTemporalLaneAdmission({
     lane: temporalLane,
     demand: temporalDemand,
@@ -191,6 +214,7 @@ function buildUrp(
     const producer = addStandardSceneDataPass(graph, temporal.value.temporal, depth.value);
     if (!producer.ok) return producer;
   }
+
   const transmission = addTransmissionBackdropPasses({
     graph,
     source: sceneResolved.value,
@@ -207,7 +231,7 @@ function buildUrp(
       depth: depth.value,
       ...(msaa ? { resolve: sceneResolved.value } : {}),
       sampled: [
-        shadows.value.directional,
+        ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
         shadows.value.spot,
         ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
       ],
@@ -217,6 +241,7 @@ function buildUrp(
       colorLoadOp: 'load',
       depthLoadOp: 'load',
       recordMode: 'transmission',
+      extraAccesses: clusterReads,
       // Inject the complete backdrop view so the Standard shader can select
       // the producer's optional roughness mip level. mipViews[0] is only the
       // copy destination view and intentionally exposes one level.
@@ -230,7 +255,7 @@ function buildUrp(
       depth: depth.value,
       ...(msaa ? { resolve: sceneResolved.value } : {}),
       sampled: [
-        shadows.value.directional,
+        ...(shadows.value.directional === undefined ? [] : [shadows.value.directional]),
         shadows.value.spot,
         ...(shadows.value.point === undefined ? [] : [shadows.value.point]),
       ],
@@ -240,6 +265,7 @@ function buildUrp(
       colorLoadOp: 'load',
       depthLoadOp: 'load',
       recordMode: 'transparent',
+      extraAccesses: clusterReads,
     });
     if (!transparentPass.ok) return transparentPass;
     const temporal = addTransmissionBackdropTemporalPass(graph, sceneResolved.value);
@@ -258,7 +284,7 @@ function buildUrp(
       topology,
       sceneResolved.value,
       depthSample.value,
-      shadows.value.directional.view,
+      shadows.value.directional?.view,
       shadows.value.spot.view,
     );
     if (!volume.ok) return volume;
@@ -293,7 +319,7 @@ function buildUrp(
     if (!observation.ok) return observation;
   }
 
-  return addStandardPost(
+  const post = addStandardPost(
     context,
     topology,
     sceneResolved.value,
@@ -301,6 +327,10 @@ function buildUrp(
     surface.value,
     temporal.value?.temporal,
   );
+  if (!post.ok) return post;
+  const cubeCaptures = context.contributeCubeCaptures?.();
+  if (cubeCaptures !== undefined && !cubeCaptures.ok) return cubeCaptures;
+  return ok(undefined);
 }
 
 export const buildStandardForwardLane = buildUrp;

package/src/pipeline/standard-lighting/errors.ts

@@ -0,0 +1,6 @@
+import type { ClusterBinError } from '../../cluster-binner';
+import { StandardClusterIndexOverflowError } from '../../errors/render';
+
+export function fromClusterBinError(error: ClusterBinError): StandardClusterIndexOverflowError {
+  return new StandardClusterIndexOverflowError(error.detail.actual, error.detail.capacity);
+}

package/src/pipeline/standard-lighting/graph.ts

@@ -0,0 +1,157 @@
+import type {
+  GraphAccess,
+  GraphBuffer,
+  RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import { ok, type Result } from '@forgeax/engine-types';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../../gpu-usage';
+import { getOrCreateHdrpBuffers, type HdrpBuffers } from '../../hdrp-buffers';
+import type { _InternalRenderPipelineContext } from '../../record/render-context';
+import type { RenderPipelineFrame } from '../../render-pipeline';
+import type { StandardTopologyInputValue } from './topology';
+
+/** Graph resources projected from one Standard lighting topology input. */
+export interface StandardClusterGraphBuffers {
+  readonly lightData: GraphBuffer;
+  readonly clusterGrid: GraphBuffer;
+  readonly lightIndexList: GraphBuffer;
+  readonly clusterUniform: GraphBuffer;
+  readonly lightBounds: GraphBuffer;
+}
+
+/** Stable graph-time projection; never retain a frame's typed-array payload. */
+interface StandardClusterGraphDescriptor {
+  readonly grid: { readonly x: number; readonly y: number; readonly z: number };
+}
+
+function projectDescriptor(input: StandardTopologyInputValue): StandardClusterGraphDescriptor {
+  const { x, y, z } = input.prepared.layout.grid;
+  return { grid: { x, y, z } };
+}
+
+function resolveBuffers(
+  frame: RenderPipelineFrame,
+  descriptor: StandardClusterGraphDescriptor,
+): HdrpBuffers {
+  const internal = frame as _InternalRenderPipelineContext;
+  const buffers = getOrCreateHdrpBuffers(internal.runtime, descriptor.grid);
+  if (buffers === null) throw new Error('Standard persistent buffer allocation failed');
+  return buffers;
+}
+
+/** Resolve membership execution from the frame's current prepared payload. */
+export function shouldExecuteStandardClusterMembershipPass(frame: RenderPipelineFrame): boolean {
+  const standardLighting = (frame as _InternalRenderPipelineContext).standardLighting;
+  return (
+    standardLighting?.kind === 'clustered' &&
+    standardLighting.transport.kind === 'compute-storage' &&
+    standardLighting.prepared.local.length > 0
+  );
+}
+
+/** Import the shared Standard Cluster buffers with sizes derived from layout. */
+export function importStandardClusterBuffers(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  input: StandardTopologyInputValue,
+): Result<StandardClusterGraphBuffers | null, RenderGraphError> {
+  if (input.kind === 'no-local-lights') return ok(null);
+  const layout = input.prepared.layout;
+  const descriptor = projectDescriptor(input);
+  const usage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
+  const lightData = graph.importBuffer(
+    'hdrp-light-data',
+    { size: layout.lightDataSlotCount * 64, usage },
+    (frame) => resolveBuffers(frame, descriptor).lightDataBuffer,
+  );
+  if (!lightData.ok) return lightData;
+  const clusterGrid = graph.importBuffer(
+    'hdrp-cluster-grid',
+    { size: layout.clusterGridU32Length * 4, usage },
+    (frame) => resolveBuffers(frame, descriptor).clusterGridBuffer,
+  );
+  if (!clusterGrid.ok) return clusterGrid;
+  const lightIndexList = graph.importBuffer(
+    'hdrp-light-index-list',
+    { size: layout.lightIndexListCapacity * 4, usage },
+    (frame) => resolveBuffers(frame, descriptor).lightIndexListBuffer,
+  );
+  if (!lightIndexList.ok) return lightIndexList;
+  const clusterUniform = graph.importBuffer(
+    'hdrp-cluster-uniform',
+    { size: 32, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST },
+    (frame) => resolveBuffers(frame, descriptor).clusterUniformBuffer,
+  );
+  if (!clusterUniform.ok) return clusterUniform;
+  const lightBounds = graph.importBuffer(
+    'hdrp-light-bounds',
+    { size: layout.lightBoundsInt32Length * 4, usage },
+    (frame) => resolveBuffers(frame, descriptor).lightBoundsBuffer,
+  );
+  if (!lightBounds.ok) return lightBounds;
+  return ok({
+    lightData: lightData.value,
+    clusterGrid: clusterGrid.value,
+    lightIndexList: lightIndexList.value,
+    clusterUniform: clusterUniform.value,
+    lightBounds: lightBounds.value,
+  });
+}
+
+/** Accesses used by raster consumers of the shared Cluster payload. */
+export function standardClusterReadAccesses(
+  buffers: StandardClusterGraphBuffers,
+): readonly GraphAccess[] {
+  return [
+    { resource: buffers.lightData, usage: 'storage-read' },
+    { resource: buffers.clusterGrid, usage: 'storage-read' },
+    { resource: buffers.lightIndexList, usage: 'storage-read' },
+    { resource: buffers.clusterUniform, usage: 'uniform-read' },
+  ];
+}
+
+/**
+ * Add the sole GPU membership producer. CPU membership is already materialized
+ * in PreparedStandardLighting and therefore contributes no second pass.
+ */
+export function addStandardClusterMembershipPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  input: StandardTopologyInputValue,
+  buffers: StandardClusterGraphBuffers,
+): Result<void, RenderGraphError> {
+  if (input.kind === 'no-local-lights') return ok(undefined);
+  if (input.transport.kind !== 'compute-storage') return ok(undefined);
+  const descriptor = projectDescriptor(input);
+  return graph.addComputePass('cluster-membership-producer', {
+    accesses: [
+      { resource: buffers.clusterGrid, usage: 'storage-read' },
+      { resource: buffers.clusterUniform, usage: 'uniform-read' },
+      { resource: buffers.lightBounds, usage: 'storage-read' },
+      { resource: buffers.lightIndexList, usage: 'storage-write' },
+    ],
+    // Keep the clustered graph/ABI stable for a directional-only frame, but
+    // do not require a producer bind group when there is no local corpus to
+    // bin.  The zero-length prepared payload is already the complete result;
+    // executing this pass would only turn an otherwise valid frame into a
+    // null-backend encode failure.
+    executeIf: shouldExecuteStandardClusterMembershipPass,
+    encode: ({ pass, frame }) => {
+      const internal = frame as _InternalRenderPipelineContext;
+      const pipeline = internal.pipelineState.hdrpClusterMembershipPipeline;
+      const bindings = internal.hdrpClusterMembershipBindGroup;
+      if (pipeline === null || bindings === null) {
+        throw new Error(
+          'standard-cluster-transport-unavailable: selected compute Cluster producer is not ready',
+        );
+      }
+      const { x, y, z } = descriptor.grid;
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bindings);
+      pass.dispatchWorkgroups(Math.ceil((x * y * z) / 64));
+    },
+  });
+}