@forgeax/engine-render 0.1.19 → 0.1.21

package/src/pipeline/standard-post.ts

@@ -11,7 +11,11 @@ import type {
   RenderPipelineFrame,
   RenderPipelineTopology,
 } from '../render-pipeline';
-import { createRenderPipelineTarget, type RenderPipelineTarget } from '../render-pipeline';
+import {
+  createRenderPipelineTarget,
+  type RenderPipelineTarget,
+  resolveOutputDither,
+} from '../render-pipeline';
 import {
   addTypedBloomPasses,
   addTypedCompositePostEffects,
@@ -134,7 +138,7 @@ function missingTemporalContributor(
   return new SceneDataUnavailableError({
     featureIdentity: 'forgeax::standard',
     schema: 'forgeax::scene-data::temporal-v1',
-    lane: topology.lane.compute ? (topology.standardProfile?.lighting ?? 'direct') : 'cpu-webgl2',
+    lane: topology.lane.compute ? 'clustered' : 'cpu-webgl2',
     reason: 'producer-missing',
     missingContributorIds: [contributorId],
     omittedMissingContributorCount: 0,
@@ -165,9 +169,13 @@ export function addStandardPost(
   // left clear and the following Output Transform presents a black frame.
   const bloomActive = hdr && topology.camera.bloom === 'on' && topology.camera.tonemap !== 'none';
   const fxaa = !clearOnly && topology.camera.antialias === 'fxaa';
-  const msaa = !clearOnly && topology.camera.antialias === 'msaa' && topology.lane.multisample;
-  const linearLdr = !clearOnly && ((!hdr && topology.lane.storageBuffer) || fxaa || msaa);
+  // All non-clear Standard frames use the graph-owned float scene target and
+  // the shared Output Transform, even when AA is disabled or the backend has
+  // no storage buffers.  This keeps the final dither at one owner-level
+  // surface boundary instead of making no-AA/WebGL2 a silent bypass.
+  const linearLdr = !clearOnly && !hdr;
   const rawOnly = !clearOnly && topology.surface.profile?.kind === 'raw-only';
+  const outputDither = resolveOutputDither(topology.config);
   const motionBlur = !clearOnly && topology.temporal?.motionBlur === true;
   const postEffects = clearOnly ? [] : (topology.config?.postEffects ?? []);
   const rawOnlyPostInput =
@@ -312,7 +320,11 @@ export function addStandardPost(
         domain: 'display-encoded',
       });
       if (!output.ok) return output;
-      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, output.value);
+      // FXAA samples this display-encoded intermediate; leave dither to the
+      // final FXAA writer so the same pixel is not dithered twice.
+      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, output.value, {
+        dither: false,
+      });
       if (!outputTransform.ok) return outputTransform;
       const aa = addTypedFullscreenPass(context.graph, {
         name: 'fxaa',
@@ -326,13 +338,20 @@ export function addStandardPost(
         context.graph,
         postInput,
         rawOnlyPostInput.value,
+        {
+          dither: outputDither && postEffects.length === 0,
+        },
       );
       if (!transformed.ok) return transformed;
     } else if (rawOnly || linearLdr) {
-      const transformed = addTypedOutputTransformPass(context.graph, postInput, finalPresent);
+      const transformed = addTypedOutputTransformPass(context.graph, postInput, finalPresent, {
+        dither: outputDither,
+      });
       if (!transformed.ok) return transformed;
     } else {
-      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, finalPresent);
+      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, finalPresent, {
+        dither: outputDither,
+      });
       if (!outputTransform.ok) return outputTransform;
     }
   }

package/src/pipeline/standard-profile.ts

@@ -1,25 +1,22 @@
 export const STANDARD_PIPELINE_ID = 'forgeax::standard' as const;
 export const STANDARD_LIGHT_COUNTS = [1, 32, 256] as const;
-/** Shared clustered-lighting facts consumed by pipeline, record, and buffers. */
-export const DEFAULT_CLUSTER_GRID = { x: 16, y: 9, z: 24 } as const;
-export const CLUSTER_GRID_STRIDE_U32 = 2;
-export const LIGHT_INDEX_LIST_CAPACITY = 1048576;
-export const MAX_LIGHTS = 256;
+export {
+  CLUSTER_GRID_STRIDE_U32,
+  DEFAULT_CLUSTER_GRID,
+  LIGHT_INDEX_LIST_CAPACITY,
+  MAX_LIGHTS,
+} from './standard-lighting/layout';
 
 export type StandardLightCount = (typeof STANDARD_LIGHT_COUNTS)[number];
-export type StandardLightingLane = 'direct' | 'clustered';
-export type StandardFallbackLane = 'native' | 'cpu-webgl2';
 export type StandardShadowMode = 'off' | 'hard' | 'filtered';
-export type StandardTone =
-  | 'none'
-  | 'aces-filmic'
-  | 'agx'
-  | 'cineon'
-  | 'linear'
-  | 'neutral'
-  | 'reinhard'
-  | 'reinhard-extended';
-export type StandardAntialias = 'none' | 'fxaa' | 'msaa';
+export type StandardVolumetricFogQuality = 'low' | 'high';
+
+export interface StandardVolumetricFogProfile {
+  readonly quality: StandardVolumetricFogQuality;
+  readonly depth: 48 | 64;
+  readonly tileSize: 4 | 16;
+}
+
 export const STANDARD_POST_STAGE_NAMES = [
   'transparent-blend',
   'bloom',
@@ -29,37 +26,33 @@ export const STANDARD_POST_STAGE_NAMES = [
   'present',
 ] as const;
 export type StandardPostStage = (typeof STANDARD_POST_STAGE_NAMES)[number];
-
 export interface StandardProfile {
   readonly pipelineId: typeof STANDARD_PIPELINE_ID;
   readonly lightCount: StandardLightCount;
-  readonly lighting: StandardLightingLane;
+  /** Graph topology selector; all local lights use the shared Cluster path. */
+  readonly renderPath: 'forward' | 'deferred';
   readonly shadows: StandardShadowMode;
   readonly pbr: boolean;
   readonly ibl: boolean;
   readonly ssao: boolean;
-  readonly fallback: StandardFallbackLane;
+  /** Renderer-owned 1080p volume profile; tile width/height remain surface-derived. */
+  readonly volumetricFog?: StandardVolumetricFogProfile | undefined;
   readonly postStages: typeof STANDARD_POST_STAGE_NAMES;
 }
 
 export const DEFAULT_STANDARD_PROFILE: StandardProfile = Object.freeze({
   pipelineId: STANDARD_PIPELINE_ID,
   lightCount: 32,
-  lighting: 'direct',
+  renderPath: 'forward',
   shadows: 'filtered',
   pbr: true,
   ibl: true,
   ssao: false,
-  fallback: 'native',
   postStages: STANDARD_POST_STAGE_NAMES,
 });
 
-export type StandardLane = StandardLightingLane | 'cpu-webgl2';
-
-export function resolveStandardLane(
-  profile: Pick<StandardProfile, 'lighting'>,
-  capabilities: { readonly compute: boolean; readonly storageBuffer: boolean },
-): StandardLane {
-  if (!capabilities.compute || !capabilities.storageBuffer) return 'cpu-webgl2';
-  return profile.lighting;
+export function resolveVolumetricFogProfile(
+  profile: Pick<StandardProfile, 'volumetricFog'>,
+): StandardVolumetricFogProfile {
+  return profile.volumetricFog ?? { quality: 'high', depth: 64, tileSize: 4 };
 }

package/src/pipeline-spec.ts

@@ -287,6 +287,69 @@ export function variantSetFromVertexLayoutProjection(
   return ok(parts.join('+'));
 }
 
+/**
+ * Derive the capability axes shared by every Standard PBR draw owner.
+ *
+ * The all-true key is the canonical empty key used by the shader manifest;
+ * every other capability pair stays explicit so a no-local-light frame on a
+ * device without storage buffers cannot accidentally select a storage-backed
+ * PSO. Vertex-color is supplied here because the empty-key rule is only valid
+ * when that geometry-owned axis is also true.
+ */
+export function standardCapabilityVariantSet(
+  clustered: boolean,
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  if (clustered && storageBuffer && vertexColorAvailable) return '';
+  return `CLUSTER_FORWARD_AVAILABLE=${clustered}+STORAGE_BUFFER_AVAILABLE=${storageBuffer}`;
+}
+
+/**
+ * Project the frame-owned Standard topology onto its material variant axes.
+ *
+ * `StandardTopologyInputValue.kind` is the only runtime authority for the
+ * cluster axis: a frame with local lights must request the clustered artifact,
+ * while the no-local-light topology requests the direct artifact.  Keeping
+ * this projection beside the canonical key builder prevents PBR, skin, and
+ * sprite-lit record owners from independently inferring the active lane from
+ * whichever bind group happened to be constructed first.
+ */
+export function standardTopologyVariantSet(
+  topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  return standardCapabilityVariantSet(
+    topology?.kind === 'clustered',
+    storageBuffer,
+    vertexColorAvailable,
+  );
+}
+
+/**
+ * Keep a clustered frame fail-closed when its unified group(2) resource is
+ * unavailable. A missing group is not evidence that the frame is direct; it
+ * is an invalid prepared resource state.
+ */
+export function standardTopologyBindGroupReady(
+  topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
+  clusterBindGroup: unknown,
+): boolean {
+  return (
+    topology?.kind !== 'clustered' || (clusterBindGroup !== null && clusterBindGroup !== undefined)
+  );
+}
+
+/** Derive the storage axis for Standard-compatible unlit material draws. */
+export function standardStorageVariantSet(
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  if (storageBuffer && vertexColorAvailable) return '';
+  return `STORAGE_BUFFER_AVAILABLE=${storageBuffer}+VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`;
+}
+
 /**
  * Build a `GPURenderPipelineDescriptor` from a PipelineSpec + shader modules.
  *
@@ -925,14 +988,14 @@ const TRI_GEOMETRY_PBR = {
   shaderUvSetCount: 8,
 };
 
-// M6 fix-up: URP-variant key string for the standard PBR shader. Mirrors the
-// boot-time variantSet computed at createRenderer.ts step 1b when
-// `isHdrpActive=false` and `storageBufferCapable=true` (the URP default
-// surface). The URP record path requests this exact string at every
+// M6 fix-up: non-clustered boot-variant key string for the standard PBR shader.
+// Mirrors the boot-time variantSet computed at createRenderer.ts step 1b when
+// clustered lighting is not yet admitted and `storageBufferCapable=true` (the
+// surface). The default record path requests this exact string at every
 // `getMaterialShaderPipeline` call site, so seeding the table with these
-// variants keeps the URP cache lookup hot from frame 1 instead of
+// variants keeps the default cache lookup hot from frame 1 instead of
 // skip-drawing the first ~1 frames while the async compile resolves.
-const URP_PBR_VARIANT_SET = 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
+const STANDARD_BOOT_VARIANT_SET = standardCapabilityVariantSet(false, true, false);
 
 /**
  * Build the boot-time pre-warm table: 15 standard PipelineSpec variants.
@@ -944,22 +1007,22 @@ const URP_PBR_VARIANT_SET = 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAI
  *
  * Matrix:
  *   - 8 base material variants — {unlit, standard-pbr} x {LDR, HDR} x {S1, S4}
- *   - 4 URP-variant standard-pbr — standard-pbr (variantSet=URP_PBR_VARIANT_SET)
- *     x {LDR, HDR} x {S1, S4}; URP record path requests these specs by
+ *   - 4 non-clustered standard-pbr — standard-pbr (variantSet=STANDARD_BOOT_VARIANT_SET)
+ *     x {LDR, HDR} x {S1, S4}; the default record path requests these specs by
  *     `getMaterialShaderPipeline` keying off `cacheKeyOf` so the boot-time
  *     prewarm seeds `materialShaderPipelineCache` and avoids a 1-frame
- *     async-compile skip-draw (M6 fix-up; see render-system-record.ts §URP)
+ *     async-compile skip-draw (M6 fix-up; see render-system-record.ts)
  *   - 3 fullscreen-post — tonemap (LDR S1) + skybox (HDR S1, HDR S4)
  *
- * Total: 15. The URP variant is PBR-only because:
- *   - unlit URP record path passes `variantSet=undefined` (the no-variant
+ * Total: 15. The non-clustered variant is PBR-only because:
+ *   - unlit record path passes `variantSet=undefined` (the no-variant
  *     boot-default entries already cover it; createRenderer.ts §unlitRsp)
  *   - sprite goes through `getMaterialShaderPipeline('forgeax::sprite', ...)`
  *     lazily at first transparent-LDR-split draw — no boot-time pre-warm.
- *   - HDRP variant (`variantSet=''` or compound `=true` form) is registered
+ *   - clustered variant (`variantSet=''` or compound `=true` form) is registered
  *     lazily when the clustered Standard profile activates, not at boot — adding clustered
  *     prewarm here would build PSOs against the URP layout (the boot-time
- *     `pbrModule` is the URP variant when `isHdrpActive=false`)
+ *     `pbrModule` is the non-clustered variant before a frame admits local lights)
  *
  * `ldrViewFormat` parameterises the LDR color attachment format. Callers
  * pass the runtime-resolved swap-chain view format (Channel 2 typically
@@ -1074,12 +1137,12 @@ export function buildSpecConstTable(
       renderState: undefined,
     },
 
-    // ── M6 fix-up: URP-variant standard-pbr prewarm ─────────────────────────
-    // URP record path (`getMaterialShaderPipeline`) requests
-    // `variantSet=URP_PBR_VARIANT_SET` for standard-shading entities; pre-M6
+    // ── M6 fix-up: non-clustered standard-pbr prewarm ─────────────────────────
+    // The default record path (`getMaterialShaderPipeline`) requests
+    // `variantSet=STANDARD_BOOT_VARIANT_SET` for standard-shading entities; pre-M6
     // the silent `selectStandardFallbackPipeline` shim served the no-variant
     // boot prewarm during the 1-frame async-compile warmup. With M6's
-    // explicit-failure surface, those URP requests must hit the boot prewarm
+    // explicit-failure surface, those requests must hit the boot prewarm
     // by their own variantSet — these 4 entries close that gap.
 
     // standard PBR URP LDR S1
@@ -1087,7 +1150,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_LDR_S1,
       geometry: TRI_GEOMETRY_PBR,
@@ -1098,7 +1161,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_LDR_S4,
       geometry: TRI_GEOMETRY_PBR,
@@ -1109,7 +1172,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_HDR_S1,
       geometry: TRI_GEOMETRY_PBR,
@@ -1120,7 +1183,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_HDR_S4,
       geometry: TRI_GEOMETRY_PBR,

package/src/point-shadow-inspection.ts

@@ -0,0 +1,55 @@
+import type { PointShadowSnapshot } from './render-system-extract';
+
+/**
+ * Detached point-shadow budget facts from one completed extract/record frame.
+ *
+ * `requested` is the number of PointLight + PointLightShadow pairs. The
+ * renderer owns the bounded cube-array atlas, so `admitted`, `shadowed`, and
+ * `shadowAtlasOccupancy` are all derived from the layer sentinel emitted by
+ * the same extract owner. No consumer needs to maintain a second budget
+ * ledger.
+ */
+export interface PointShadowInspection {
+  readonly status: 'inactive' | 'ready' | 'over-budget';
+  readonly requested: number;
+  readonly admitted: number;
+  readonly shadowed: number;
+  readonly shadowAtlasOccupancy: number;
+  readonly shadowAtlasCapacity: number;
+}
+
+/** Project point-shadow snapshots to the public, JSON-safe inspection shape. */
+export function inspectPointShadow(
+  snapshots: readonly PointShadowSnapshot[],
+  shadowAtlasCapacity: number,
+): PointShadowInspection {
+  const requested = snapshots.length;
+  const admitted = snapshots.reduce(
+    (count, snapshot) =>
+      snapshot.shadowAtlasLayer >= 0 && snapshot.shadowAtlasLayer < shadowAtlasCapacity
+        ? count + 1
+        : count,
+    0,
+  );
+  // Never publish a misleading `ready` state when any requested shadow owns
+  // no atlas layer. The extract sentinel is the single admission projection;
+  // a partial or all-sentinel frame is therefore a failed/over-budget
+  // admission, not an active shadow path with incomplete output.
+  const status =
+    requested === 0
+      ? ('inactive' as const)
+      : requested > shadowAtlasCapacity || admitted !== requested
+        ? ('over-budget' as const)
+        : ('ready' as const);
+  return Object.freeze({
+    status,
+    requested,
+    admitted,
+    // A point shadow only samples an atlas after it owns an atlas layer. Keep
+    // these names explicit for AI diagnostics while deriving both from the
+    // one layer projection above.
+    shadowed: admitted,
+    shadowAtlasOccupancy: admitted,
+    shadowAtlasCapacity,
+  });
+}

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -2,7 +2,7 @@ import { vec3 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import type { CameraSnapshot } from '../../render-contract';
-import type { RenderableSnapshot } from '../../render-system-extract';
+import type { RenderableSnapshot, SpotLightSnapshot } from '../../render-system-extract';
 import type { TemporalView } from '../../temporal/temporal-view';
 import type { ValidatedRenderable } from '../frame-snapshot';
 import { uploadMeshSsboBatch } from '../mesh-ssbo';
@@ -98,6 +98,47 @@ function temporalView(): TemporalView {
 }
 
 describe('temporal GPU payloads', () => {
+  it('publishes a projector-only SpotLight matrix into the explicit lane-0 contract', () => {
+    const { queue, uploads } = recordingQueue();
+    const projectorMatrix = translatedMatrix(9);
+    const projector: SpotLightSnapshot = {
+      kind: 'spot',
+      entity: 4,
+      position: vec3.create(0, 2, 0),
+      direction: vec3.create(0, -1, 0),
+      color: vec3.create(1, 1, 1),
+      intensity: 1,
+      invRangeSquared: 0.04,
+      cosInner: 0.95,
+      cosOuter: 0.8,
+      castShadow: false,
+      lightViewProj: projectorMatrix,
+      mapSize: 512,
+      nearPlane: 0.1,
+      farPlane: 25,
+      shadowAtlasTile: -1,
+      projectorAsset: { kind: 'texture' } as never,
+    };
+    writeViewUbo(
+      queue,
+      {} as Buffer,
+      camera(),
+      {
+        kind: 'directional',
+        direction: vec3.create(0, -1, 0),
+        color: vec3.create(1, 1, 1),
+        intensity: 1,
+      },
+      { point: [], spot: [projector] } as never,
+      [projector],
+      undefined,
+      undefined,
+      0,
+    );
+    const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(payload[132 + 12]).toBe(9);
+  });
+
   it('writes temporal current/previous projection after the spot-light lanes', () => {
     const { queue, uploads } = recordingQueue();
     writeViewUbo(

package/src/record/__tests__/transparent-group2-selection.unit.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { selectPipelineLayoutForVariant } from '../../assembly/factory';
+import { resolvePipelineGroup2Contract } from '../../pbr-pipeline';
+import { projectDeviceOwnedBindGroup } from '../frame-lighting';
+import { selectMaterialGroup2 } from '../main-pass-material';
+
+const meshGroup = { label: 'pbr-mesh-bg' } as never;
+const clusterGroup = { label: 'hdrp-unified-bg-group2' } as never;
+
+describe('transparent material group 2 selection', () => {
+  it('uses the shared cluster layout only for standard materials', () => {
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'cluster')).toBe(clusterGroup);
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'mesh')).toBe(meshGroup);
+  });
+
+  it('returns null when a non-standard material lacks its ordinary mesh group', () => {
+    expect(selectMaterialGroup2(clusterGroup, null, 'mesh')).toBeNull();
+  });
+
+  it('resolves mesh, skin, and clustered skin from the composed shader artifact', () => {
+    expect(
+      resolvePipelineGroup2Contract('@group(2) @binding(0) var<storage> mesh: array<u32>;'),
+    ).toBe('mesh');
+    expect(
+      resolvePipelineGroup2Contract(
+        '@group(2) @binding(0) var<storage> mesh: array<u32>; @group(2) @binding(1) var<uniform> palette: mat4x4<f32>;',
+      ),
+    ).toBe('skin');
+    expect(
+      resolvePipelineGroup2Contract(
+        '@group(2) @binding(0) var<storage> mesh: array<u32>; @group(2) @binding(1) var<storage> palette: array<u32>; @group(2) @binding(4) var<storage> lights: array<u32>;',
+      ),
+    ).toBe('skin-cluster');
+  });
+
+  it('lets the resolved clustered contract select the unified group', () => {
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'cluster')).toBe(clusterGroup);
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'skin')).toBeNull();
+    // A skin-cluster PSO cannot consume the ordinary HDRP group. The caller
+    // must provide the dedicated skin bind group through the skin path; when
+    // it is absent, fail-stop instead of submitting a layout-invalid draw.
+    expect(selectMaterialGroup2(clusterGroup, meshGroup, 'skin-cluster')).toBeNull();
+  });
+
+  it('keeps a mesh contract on the mesh pipeline despite the HDRP variant key', () => {
+    const pbrPipelineLayout = { label: 'pbr-pl' } as never;
+    const hdrpPipelineLayout = { label: 'hdrp-pbr-pl' } as never;
+    expect(
+      selectPipelineLayoutForVariant(
+        {
+          pbrPipelineLayout,
+          hdrpPbrPipelineLayout: hdrpPipelineLayout,
+          pbrSkinPipelineLayout: null,
+          hdrpSkinPipelineLayout: null,
+        },
+        '',
+        'pbr',
+      ),
+    ).toBe(pbrPipelineLayout);
+  });
+
+  it('rejects membership bindings from a retired device or layout', () => {
+    const deviceA = {} as never;
+    const deviceB = {} as never;
+    const layoutA = {} as never;
+    const layoutB = {} as never;
+    const bindGroup = {} as never;
+    const state = { device: deviceA, layout: layoutA, bindGroup };
+    expect(projectDeviceOwnedBindGroup(state, deviceA, layoutA)).toBe(bindGroup);
+    expect(projectDeviceOwnedBindGroup(state, deviceB, layoutA)).toBeNull();
+    expect(projectDeviceOwnedBindGroup(state, deviceA, layoutB)).toBeNull();
+  });
+});

package/src/record/__tests__/view-ubo-layout.unit.test.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const viewUboSrc = readFileSync(fileURLToPath(new URL('../view-ubo.ts', import.meta.url)), 'utf8');
+const commonWgslSrc = readFileSync(
+  fileURLToPath(new URL('../../../..//shader/src/common.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('View UBO directional shadow ABI', () => {
+  it('keeps the 960 B payload inside the existing 1024 B slot', () => {
+    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_BYTES\s*=\s*960/);
+    expect(viewUboSrc).toMatch(/VIEW_UNIFORM_SLOT_STRIDE\s*=\s*1024/);
+    expect(viewUboSrc).toMatch(/VIEW_PAYLOAD_FLOATS\s*=\s*240/);
+  });
+
+  it('packs all four cascade metrics into the existing vec4 lanes', () => {
+    expect(viewUboSrc).toMatch(/viewPayload\[108 \+ s \* 4 \+ lane\]/);
+    expect(viewUboSrc).not.toMatch(/viewPayload\[108 \+ s \* 4\]\s*=\s*lights\.splitPlanes/);
+  });
+
+  it('keeps bias at [126]/[127], directional filter at [128..131], and Spot at 132', () => {
+    expect(viewUboSrc).toMatch(/viewPayload\[126\]\s*=\s*lights\.depthBias/);
+    expect(viewUboSrc).toMatch(/viewPayload\[127\]\s*=\s*lights\.normalBias/);
+    expect(viewUboSrc).toMatch(/viewPayload\[128\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[129\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[130\]/);
+    expect(viewUboSrc).toMatch(/viewPayload\[131\]/);
+    expect(viewUboSrc).toMatch(/SPOT_LVP_BASE_FLOAT\s*=\s*132/);
+    expect(viewUboSrc).not.toMatch(/lights\.pcfKernelSize/);
+  });
+
+  it('declares one shared View binding with a vec4 directional filter carrier', () => {
+    const viewStruct = commonWgslSrc.match(/struct View \{[\s\S]*?\n\};/)?.[0] ?? '';
+    expect(viewStruct).toMatch(/directionalShadowFilter\s*:\s*vec4<f32>/);
+    expect(viewStruct).not.toMatch(/pcfKernelSize/);
+    expect(commonWgslSrc.match(/@group\(0\) @binding\(0\) var<uniform> view/g)).toHaveLength(1);
+  });
+});