@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/visibility-budget.integration.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest';
+import { createVisibilityBudget } from '../scene/visibility/budget';
+import {
+  primitiveKey,
+  primitiveKeyId,
+  VisibilityFacetStore,
+  viewKey,
+  viewKeyId,
+} from '../scene/visibility/facet';
+
+const view = (cameraEntity: number) =>
+  viewKey({
+    attachmentId: 'budget-scene',
+    cameraEntity,
+    viewRole: 'main',
+    viewGeneration: 1,
+  });
+
+const primitive = (slot: number) =>
+  primitiveKey({
+    attachmentId: 'budget-scene',
+    worldGeneration: 1,
+    primitiveSlot: slot,
+    slotGeneration: 1,
+  });
+
+describe('visibility budget integration', () => {
+  it('shares one derived window across views and LOD levels', () => {
+    const budget = createVisibilityBudget(2048);
+    const facets = new VisibilityFacetStore(budget);
+    const views = [view(1), view(2)];
+    for (const currentView of views) {
+      facets.activateView(currentView);
+      for (let level = 0; level < 8; level += 1) {
+        const currentPrimitive = primitive(currentView.cameraEntity * 10 + level);
+        facets.setCandidate(currentView, currentPrimitive, { level, confidence: 1 });
+        facets.applyConfidence(currentView, currentPrimitive, {
+          type: 'result',
+          samples: 0,
+          submissionGeneration: 1,
+        });
+        facets.applyConfidence(currentView, currentPrimitive, {
+          type: 'result',
+          samples: 0,
+          submissionGeneration: 2,
+        });
+      }
+    }
+
+    expect(facets.visibilityBudget()).toBe(budget);
+    expect(facets.visibilityBudget()).toMatchObject({
+      effectiveQueryBudget: 2048,
+      settleSubmits: 98,
+      retestSubmits: 44,
+      expirySubmits: 88,
+    });
+
+    facets.advanceSuccessfulSubmits(2 + budget.retestSubmits);
+    for (const currentView of views) {
+      expect(facets.shouldQuery(currentView, primitive(currentView.cameraEntity * 10))).toBe(true);
+    }
+  });
+
+  it('keeps invalidation visible and requeues the same identity without extending evidence', () => {
+    const budget = createVisibilityBudget(4096);
+    const facets = new VisibilityFacetStore(budget);
+    const currentView = view(3);
+    const currentPrimitive = primitive(3);
+    facets.activateView(currentView);
+    facets.setCandidate(currentView, currentPrimitive, { level: 2, confidence: 1 });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    facets.advanceSuccessfulSubmits(2 + budget.retestSubmits, [
+      { view: currentView, primitive: currentPrimitive },
+    ]);
+    expect(facets.getConfidence(currentView, currentPrimitive).status).toBe('hidden');
+
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'invalidate',
+      reason: 'world-reorder',
+    });
+    expect(facets.getConfidence(currentView, currentPrimitive)).toMatchObject({
+      status: 'visible',
+      dirty: true,
+      queryable: true,
+    });
+    expect(facets.dequeueQueryCandidates(currentView, 1)).toHaveLength(1);
+  });
+
+  it('uses expiry-only scheduling for a due hidden row while its query is in flight', () => {
+    const budget = createVisibilityBudget();
+    const facets = new VisibilityFacetStore(budget);
+    const currentView = view(4);
+    const currentPrimitive = primitive(4);
+    facets.activateView(currentView);
+    facets.setCandidate(currentView, currentPrimitive, { level: 0, confidence: 1 });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    const dueGeneration = 2 + budget.retestSubmits;
+    facets.advanceSuccessfulSubmits(dueGeneration);
+    expect(facets.dequeueQueryCandidates(currentView, 1)).toHaveLength(1);
+
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'submit',
+      submissionGeneration: dueGeneration,
+    });
+    expect(facets.getConfidence(currentView, currentPrimitive).successfulSubmits).toBe(
+      budget.retestSubmits + 1,
+    );
+    const scheduler = facets as unknown as {
+      confidence: { wakeByGeneration: Map<number, Set<string>> };
+    };
+    const key = `${viewKeyId(currentView)}|${primitiveKeyId(currentPrimitive)}`;
+    expect([...scheduler.confidence.wakeByGeneration.values()].flat()).not.toContain(key);
+
+    facets.advanceSuccessfulSubmits(
+      dueGeneration + budget.expirySubmits - budget.retestSubmits - 1,
+    );
+    expect(facets.getConfidence(currentView, currentPrimitive)).toMatchObject({
+      status: 'visible',
+      dirty: true,
+    });
+  });
+});

package/src/__tests__/visibility-budget.unit.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createVisibilityBudget,
+  DEFAULT_CONFIGURED_QUERY_BUDGET,
+  MAX_QUERY_BUDGET,
+} from '../scene/visibility/budget';
+
+describe('visibility budget derivation', () => {
+  it.each([
+    [
+      2048,
+      {
+        effectiveQueryBudget: 2048,
+        oneSweepCandidates: 49,
+        oneSweepOccluded: 44,
+        settleSubmits: 98,
+        retestSubmits: 44,
+        expirySubmits: 88,
+      },
+    ],
+    [
+      4096,
+      {
+        effectiveQueryBudget: 4096,
+        oneSweepCandidates: 25,
+        oneSweepOccluded: 22,
+        settleSubmits: 50,
+        retestSubmits: 22,
+        expirySubmits: 44,
+      },
+    ],
+  ])('derives the approved windows for Q=%d', (configuredQueryBudget, expected) => {
+    expect(createVisibilityBudget(configuredQueryBudget)).toMatchObject({
+      configuredQueryBudget,
+      ...expected,
+    });
+  });
+
+  it('uses the default and clamps larger configured budgets without changing page policy', () => {
+    expect(createVisibilityBudget()).toMatchObject({
+      configuredQueryBudget: DEFAULT_CONFIGURED_QUERY_BUDGET,
+      effectiveQueryBudget: DEFAULT_CONFIGURED_QUERY_BUDGET,
+    });
+    expect(createVisibilityBudget(MAX_QUERY_BUDGET + 1).effectiveQueryBudget).toBe(
+      MAX_QUERY_BUDGET,
+    );
+  });
+
+  it.each([
+    0,
+    -1,
+    1.5,
+    Number.NaN,
+    Number.POSITIVE_INFINITY,
+  ])('rejects invalid configured budget %s', (configuredQueryBudget) => {
+    expect(() => createVisibilityBudget(configuredQueryBudget)).toThrow(
+      'configuredQueryBudget must be a positive safe integer',
+    );
+  });
+
+  it.each([1, 2, 3, 4, 8])('keeps derived windows independent of %d LOD levels', (levels) => {
+    const budget = createVisibilityBudget(2048);
+    expect({ levels, ...budget }).toMatchObject({
+      levels,
+      settleSubmits: 98,
+      retestSubmits: 44,
+      expirySubmits: 88,
+    });
+  });
+});

package/src/__tests__/visibility-extract.integration.test.ts

@@ -1,5 +1,10 @@
 import { World } from '@forgeax/engine-ecs';
-import { ChildOf, registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  GlobalTransform,
+  registerPropagateTransforms,
+  Transform,
+} from '@forgeax/engine-scene';
 import { describe, expect, it, vi } from 'vitest';
 import { Fog } from '../components/fog';
 import { Visibility, VisibilityStateValue } from '../components/visibility';
@@ -67,13 +72,13 @@ describe('visibility extract orchestration', () => {
     const snapshot = frame.visibilitySnapshots[0];
     expect(snapshot?.get(parent)?.effective).toBe('visible');
     expect(snapshot?.get(child)?.effective).toBe('visible');
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(3);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(3);
   });
 
-  it('keeps renderer extraction read-only over derived Transform.world', () => {
+  it('keeps renderer extraction read-only over derived GlobalTransform.world', () => {
     const { world, parent, child } = makeWorld();
     world.update(0).unwrap();
-    const before = [...world.get(child, Transform).unwrap().world];
+    const before = [...world.get(child, GlobalTransform).unwrap().world];
     const beforeInspection = world.inspect();
     const beforeShape = {
       entityCount: beforeInspection.entityCount,
@@ -87,7 +92,7 @@ describe('visibility extract orchestration', () => {
     world.set(parent, Transform, { pos: [9, 0, 0] }).unwrap();
     extractFrames([world], 0);
 
-    expect([...world.get(child, Transform).unwrap().world]).toEqual(before);
+    expect([...world.get(child, GlobalTransform).unwrap().world]).toEqual(before);
     const afterInspection = world.inspect();
     expect({
       entityCount: afterInspection.entityCount,
@@ -98,7 +103,7 @@ describe('visibility extract orchestration', () => {
       resourceKeys: afterInspection.resourceKeys,
     }).toEqual(beforeShape);
     world.update(0).unwrap();
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(11);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(11);
   });
 
   it('keeps direct prepared-kernel output aligned with extractFrames output', () => {

package/src/__tests__/visibility-resolver.unit.test.ts

@@ -82,4 +82,19 @@ describe('visibility resolver truth table', () => {
     expect(result.get(parent)?.intent).toBeUndefined();
     expect(result.get(child)?.effective).toBe('visible');
   });
+
+  it('invalidates the cached snapshot when visibility intent changes', () => {
+    const world = new World();
+    const parent = spawn(world, 'visible');
+    const child = spawn(world, 'inherited', parent);
+
+    const visible = resolveVisibility(world);
+    expect(visible.effective(child)).toBe('visible');
+
+    world.set(parent, Visibility, { state: VisibilityStateValue.hidden }).unwrap();
+
+    const hidden = resolveVisibility(world);
+    expect(hidden).not.toBe(visible);
+    expect(hidden.effective(child)).toBe('hidden');
+  });
 });

package/src/__tests__/volumetric-fog-point-spot-accumulation.integration.test.ts

@@ -13,8 +13,10 @@ const passes = readFileSync(new URL('../volume/passes.ts', import.meta.url), 'ut
 
 describe('volumetric fog Point and Spot accumulation', () => {
   it('accumulates Point and Spot in one fixed inject stage', () => {
-    expect(inject).toContain('pointLightsBuffer');
-    expect(inject).toContain('spotLightsBuffer');
+    expect(inject).toContain('light_data');
+    expect(inject).toContain('cluster_uniform');
+    expect(inject).not.toContain('pointLightsBuffer');
+    expect(inject).not.toContain('spotLightsBuffer');
     expect(inject).toContain('evalVolumePoint');
     expect(inject).toContain('evalVolumeSpot');
     expect(inject).toContain('shadow_visibility');
@@ -37,7 +39,8 @@ describe('volumetric fog Point and Spot accumulation', () => {
   });
 
   it('retains falsifier hooks for off lights, occluders, and shadow visibility', () => {
-    expect(inject).toContain('count');
+    expect(inject).toContain('selected_cluster_light_slot');
+    expect(inject).toContain('cluster_uniform.grid.w');
     expect(inject).toContain('shadowAtlasTile');
     expect(inject).toContain('return 0.0');
     expect(integrate).toContain('evalSpotAttenuation');

package/src/__tests__/volumetric-fog-stage-readback.dawn.test.ts

@@ -2,12 +2,7 @@ import type { RhiDevice, Texture, TextureView } from '@forgeax/engine-rhi';
 import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
 import { buildEngineShaderManifest } from '@forgeax/engine-vite-plugin-shader';
 import { describe, expect, it } from 'vitest';
-import {
-  LIGHT_ARRAY_HEADER_BYTES,
-  LIGHT_ARRAY_MAX_SLOTS,
-  POINT_LIGHT_STD430_BYTES,
-  SPOT_LIGHT_STD430_BYTES,
-} from '../light-buffer-layout';
+import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../light-buffer-layout';
 
 const MAP_READ = 0x0001;
 const BUFFER_COPY_DST = 0x0008;
@@ -21,6 +16,9 @@ const SIZE = 8;
 const PACKED_LAYERS = Math.ceil(SIZE / 4);
 const BYTES_PER_ROW = 256;
 const BYTES_PER_PIXEL = 8;
+const MAX_CLUSTER_LIGHTS = 256;
+const CLUSTER_LIGHT_DATA_BYTES = MAX_CLUSTER_LIGHTS * BYTES_PER_DIRECT_LIGHT_SLOT;
+const CLUSTER_UNIFORM_BYTES = 32;
 const engineManifest = await buildEngineShaderManifest();
 
 interface StageValues {
@@ -190,15 +188,15 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
     size: 128,
     usage: 0x0040 | BUFFER_COPY_DST,
   });
-  const spotLightsBuffer = device.createBuffer({
-    label: 'stage-readback.spot-lights',
-    size: LIGHT_ARRAY_HEADER_BYTES + LIGHT_ARRAY_MAX_SLOTS * SPOT_LIGHT_STD430_BYTES,
+  const lightDataBuffer = device.createBuffer({
+    label: 'stage-readback.cluster-light-data',
+    size: CLUSTER_LIGHT_DATA_BYTES,
     usage: STORAGE_BUFFER | BUFFER_COPY_DST,
   });
-  const pointLightsBuffer = device.createBuffer({
-    label: 'stage-readback.point-lights',
-    size: LIGHT_ARRAY_HEADER_BYTES + LIGHT_ARRAY_MAX_SLOTS * POINT_LIGHT_STD430_BYTES,
-    usage: STORAGE_BUFFER | BUFFER_COPY_DST,
+  const clusterUniformBuffer = device.createBuffer({
+    label: 'stage-readback.cluster-uniform',
+    size: CLUSTER_UNIFORM_BYTES,
+    usage: 0x0040 | BUFFER_COPY_DST,
   });
   const injectReadback = device.createBuffer({
     label: 'stage-readback.inject',
@@ -218,8 +216,8 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   if (
     !viewBuffer.ok ||
     !paramsBuffer.ok ||
-    !spotLightsBuffer.ok ||
-    !pointLightsBuffer.ok ||
+    !lightDataBuffer.ok ||
+    !clusterUniformBuffer.ok ||
     !injectReadback.ok ||
     !temporalReadback.ok ||
     !integrateReadback.ok
@@ -245,19 +243,22 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   paramsData.set([0, -1, 0, 0], 20);
   paramsData.set([1, 1, 1, 0], 24);
   paramsData.set([2, 0, 0, 0], 28);
+  const lightData = new Uint8Array(CLUSTER_LIGHT_DATA_BYTES);
+  const clusterUniformData = new Float32Array(8);
+  const clusterGrid = new Uint32Array(clusterUniformData.buffer);
+  clusterGrid[0] = 1;
+  clusterGrid[1] = 1;
+  clusterGrid[2] = 1;
+  clusterGrid[3] = 1;
   const viewWrite = device.queue.writeBuffer(viewBuffer.value, 0, viewData);
   const paramsWrite = device.queue.writeBuffer(paramsBuffer.value, 0, paramsData);
-  const spotLightsWrite = device.queue.writeBuffer(
-    spotLightsBuffer.value,
-    0,
-    new Uint32Array([0, 0, 0, 0]),
-  );
-  const pointLightsWrite = device.queue.writeBuffer(
-    pointLightsBuffer.value,
+  const lightDataWrite = device.queue.writeBuffer(lightDataBuffer.value, 0, lightData);
+  const clusterUniformWrite = device.queue.writeBuffer(
+    clusterUniformBuffer.value,
     0,
-    new Uint32Array([0, 0, 0, 0]),
+    clusterUniformData,
   );
-  if (!viewWrite.ok || !paramsWrite.ok || !spotLightsWrite.ok || !pointLightsWrite.ok)
+  if (!viewWrite.ok || !paramsWrite.ok || !lightDataWrite.ok || !clusterUniformWrite.ok)
     throw new Error('Dawn volume stage readback unavailable: uniform upload failed');
   const densityData = new Uint8Array((BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE);
   densityData.fill(255);
@@ -291,6 +292,7 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
         storageTexture: { access: 'write-only', format: 'rgba8unorm', viewDimension: '2d-array' },
       },
       { binding: 7, visibility: 4, buffer: { type: 'read-only-storage' } },
+      { binding: 8, visibility: 4, buffer: { type: 'uniform' } },
     ],
   });
   if (!layout.ok) throw layout.error;
@@ -354,7 +356,7 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
         storageTexture: { access: 'write-only', format: 'rgba16float', viewDimension: '2d' },
       },
       { binding: 10, visibility: 4, buffer: { type: 'read-only-storage' } },
-      { binding: 11, visibility: 4, buffer: { type: 'read-only-storage' } },
+      { binding: 11, visibility: 4, buffer: { type: 'uniform' } },
       { binding: 12, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
       { binding: 13, visibility: 4, sampler: { type: 'filtering' } },
     ],
@@ -393,7 +395,8 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
       { binding: 4, resource: { kind: 'sampler', value: comparisonSampler.value } },
       { binding: 5, resource: { kind: 'buffer', value: { buffer: paramsBuffer.value } } },
       { binding: 6, resource: { kind: 'textureView', value: outputView } },
-      { binding: 7, resource: { kind: 'buffer', value: { buffer: spotLightsBuffer.value } } },
+      { binding: 7, resource: { kind: 'buffer', value: { buffer: lightDataBuffer.value } } },
+      { binding: 8, resource: { kind: 'buffer', value: { buffer: clusterUniformBuffer.value } } },
     ],
   });
   if (!bindings.ok) throw bindings.error;
@@ -420,8 +423,8 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
       { binding: 7, resource: { kind: 'sampler', value: densitySampler.value } },
       { binding: 8, resource: { kind: 'textureView', value: historyView } },
       { binding: 9, resource: { kind: 'textureView', value: temporalView } },
-      { binding: 10, resource: { kind: 'buffer', value: { buffer: spotLightsBuffer.value } } },
-      { binding: 11, resource: { kind: 'buffer', value: { buffer: pointLightsBuffer.value } } },
+      { binding: 10, resource: { kind: 'buffer', value: { buffer: lightDataBuffer.value } } },
+      { binding: 11, resource: { kind: 'buffer', value: { buffer: clusterUniformBuffer.value } } },
       { binding: 12, resource: { kind: 'textureView', value: projectorView } },
       { binding: 13, resource: { kind: 'sampler', value: densitySampler.value } },
     ],

package/src/assembly/backend-contract.ts

@@ -10,6 +10,19 @@ import type {
 /** Optional host hooks for recorder and device-lifecycle capabilities. */
 export interface RhiBackendInstrumentation {
   readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+  /**
+   * Optional deterministic submit fault seam for backend-owned integration
+   * fixtures. The callback runs after `finish()` and before the queue submit;
+   * returning an error aborts the frame transaction without changing the
+   * production queue contract.
+   */
+  readonly beforeSubmit?: (device: RhiDevice) => RhiError | undefined;
+  /**
+   * Optional device-loss projection for deterministic recovery fixtures. A
+   * backend may compose this promise with its native `device.lost` promise;
+   * normal production packs leave it undefined and use the native signal.
+   */
+  readonly deviceLost?: (device: RhiDevice) => RhiDevice['lost'];
   readonly onFrameBoundary?: () => void;
   readonly onDeviceLost?: () => void;
 }

package/src/assembly/device-feature-admission.ts

@@ -0,0 +1,80 @@
+import type { RhiAdapter, RhiDevice } from '@forgeax/engine-rhi';
+import { EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES } from '../prepare/extended-lighting/resources';
+
+const COMPRESSION_FEATURES: GPUFeatureName[] = [
+  'texture-compression-bc',
+  'texture-compression-etc2',
+  'texture-compression-astc',
+];
+
+// The Standard transmission fragment ABI needs 17 sampled textures across its
+// material, IBL, clustered-light, and SSAO bindings. Ordinary Standard draws
+// use the non-transmission variant and remain valid on the WebGPU minimum of
+// 16. The extended-lighting topology reserves 20, so a device descriptor must
+// request that larger limit when the adapter can provide it; adapter limits are
+// not automatically inherited by requestDevice().
+export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+
+export interface DeviceFeatureAdmissionOptions {
+  readonly gpuPassTiming?: object | undefined;
+  readonly captureGpuTimings?: boolean | undefined;
+}
+
+export interface DeviceFeatureAdmission {
+  readonly requiredFeatures: GPUFeatureName[];
+  readonly requiredLimits?: {
+    readonly maxSampledTexturesPerShaderStage: number;
+  };
+}
+
+type AdapterFeatureProbe = Pick<RhiAdapter, 'features'> & Partial<Pick<RhiAdapter, 'limits'>>;
+
+export function deriveDeviceFeatureAdmission(
+  adapter: AdapterFeatureProbe,
+  options?: DeviceFeatureAdmissionOptions,
+): DeviceFeatureAdmission {
+  const requiredFeatures = COMPRESSION_FEATURES.filter((feature) => adapter.features.has(feature));
+  const timestampRequested =
+    options?.gpuPassTiming !== undefined || options?.captureGpuTimings === true;
+  if (timestampRequested && adapter.features.has('timestamp-query')) {
+    requiredFeatures.push('timestamp-query');
+  }
+  const adapterSampledTextureLimit = adapter.limits?.maxSampledTexturesPerShaderStage ?? 0;
+  const requiredSampledTextureLimit =
+    adapterSampledTextureLimit >= EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
+      ? EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
+      : adapterSampledTextureLimit >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
+        ? STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
+        : undefined;
+  return {
+    requiredFeatures,
+    ...(requiredSampledTextureLimit === undefined
+      ? {}
+      : {
+          requiredLimits: {
+            maxSampledTexturesPerShaderStage: requiredSampledTextureLimit,
+          },
+        }),
+  };
+}
+
+export function deviceOptionsForAdapter(
+  adapter: AdapterFeatureProbe,
+  options?: DeviceFeatureAdmissionOptions,
+): DeviceFeatureAdmission | undefined {
+  const admission = deriveDeviceFeatureAdmission(adapter, options);
+  return admission.requiredFeatures.length === 0 && admission.requiredLimits === undefined
+    ? undefined
+    : admission;
+}
+
+export function isTimestampQueryAdmitted(
+  caps: Pick<RhiDevice['caps'], 'timestampQuery' | 'timestampPeriodNanoseconds'>,
+): boolean {
+  return (
+    caps.timestampQuery === true &&
+    caps.timestampPeriodNanoseconds !== null &&
+    Number.isFinite(caps.timestampPeriodNanoseconds) &&
+    caps.timestampPeriodNanoseconds > 0
+  );
+}

package/src/assembly/directional-shadow-inspection.ts

@@ -0,0 +1,122 @@
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
+import type {
+  DirectionalShadowInspection,
+  DirectionalShadowInspectionError,
+  DirectionalShadowProfile,
+} from '../inspection-types';
+import type { DirectionalShadowBackendAdmission } from '../render-pipeline';
+
+export interface DirectionalShadowInspectionSource {
+  readonly requested: DirectionalShadowProfile;
+  readonly candidate: 'accepted' | 'failed';
+  readonly lastKnownGood?: DirectionalShadowProfile | undefined;
+  readonly cascadeCount: number;
+  readonly mapSize: number;
+  readonly atlasBytes: number;
+  readonly writerPasses: number;
+  readonly shadowAngularRadius?: number | undefined;
+  readonly maxPenumbraTexels?: number | undefined;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly shadowReady: boolean;
+  readonly error?: DirectionalShadowInspectionError | undefined;
+}
+
+export interface DirectionalShadowInspectionInput {
+  readonly admission: DirectionalShadowBackendAdmission;
+  readonly cascadeCount: number;
+  readonly mapSize: number;
+  readonly atlasBytes: number;
+  readonly writerPasses: number;
+  readonly blockerTaps: number;
+  readonly filterTapUpperBound: number;
+  readonly seamTapUpperBound: number;
+  readonly shadowAngularRadius?: number | undefined;
+  readonly maxPenumbraTexels?: number | undefined;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly error?: DirectionalShadowInspectionError | undefined;
+}
+
+function deepFreeze<T>(value: T, seen = new WeakSet<object>()): T {
+  if (value === null || typeof value !== 'object') return value;
+  const object = value as object;
+  if (seen.has(object)) return value;
+  seen.add(object);
+  for (const child of Object.values(object)) deepFreeze(child, seen);
+  return Object.freeze(value);
+}
+
+/** Project the single bounded Directional inspection POD; no live handles leak. */
+export function projectDirectionalShadowInspection(
+  input: DirectionalShadowInspectionInput,
+): DirectionalShadowInspection {
+  const projection: DirectionalShadowInspection = {
+    requested: input.admission.requested,
+    effective: input.admission.effective,
+    status: input.admission.status,
+    ...(input.admission.fallbackReason === undefined
+      ? {}
+      : { fallbackReason: input.admission.fallbackReason }),
+    lastKnownGood: input.admission.lastKnownGood,
+    pixelEvidence: input.admission.pixelEvidence,
+    cascadeCount: input.cascadeCount,
+    mapSize: input.mapSize,
+    atlasBytes: input.atlasBytes,
+    writerPasses: input.writerPasses,
+    blockerTaps: input.blockerTaps,
+    filterTapUpperBound: input.filterTapUpperBound,
+    seamTapUpperBound: input.seamTapUpperBound,
+    deviceGeneration: input.deviceGeneration,
+    graphGeneration: input.graphGeneration,
+    shadowAngularRadius: input.shadowAngularRadius,
+    maxPenumbraTexels: input.maxPenumbraTexels,
+    ...(input.error === undefined ? {} : { error: input.error }),
+  };
+  return deepFreeze(projection);
+}
+
+export function directionalShadowProfileFromQuality(
+  quality: DirectionalShadowQuality | undefined,
+): DirectionalShadowProfile {
+  if (quality === undefined) return 'off';
+  if (quality.kind === 'pcf') return `pcf${quality.kernel}` as 'pcf1' | 'pcf3' | 'pcf5';
+  return quality.preset === 'medium' ? 'pcssMedium' : 'pcssHigh';
+}
+
+export function projectDirectionalShadowInspectionSource(
+  input: DirectionalShadowInspectionSource,
+): DirectionalShadowInspection {
+  const filter =
+    input.requested === 'pcssMedium'
+      ? { blockerTaps: 8, filterTapUpperBound: 16, seamTapUpperBound: 48 }
+      : input.requested === 'pcssHigh'
+        ? { blockerTaps: 16, filterTapUpperBound: 32, seamTapUpperBound: 96 }
+        : input.requested === 'pcf5'
+          ? { blockerTaps: 0, filterTapUpperBound: 25, seamTapUpperBound: 25 }
+          : input.requested === 'pcf3'
+            ? { blockerTaps: 0, filterTapUpperBound: 9, seamTapUpperBound: 9 }
+            : { blockerTaps: 0, filterTapUpperBound: 1, seamTapUpperBound: 1 };
+  const admission: DirectionalShadowBackendAdmission = {
+    requested: input.requested,
+    effective:
+      input.candidate === 'accepted' ? input.requested : (input.lastKnownGood ?? input.requested),
+    status: input.candidate === 'accepted' ? 'accepted' : 'rejected',
+    ...(input.candidate === 'failed' ? { fallbackReason: 'candidate-failed' as const } : {}),
+    lastKnownGood: input.candidate === 'failed' && input.lastKnownGood !== undefined,
+    pixelEvidence: input.shadowReady ? 'available' : 'not-available',
+  };
+  return projectDirectionalShadowInspection({
+    admission,
+    cascadeCount: input.cascadeCount,
+    mapSize: input.mapSize,
+    atlasBytes: input.atlasBytes,
+    writerPasses: input.writerPasses,
+    ...filter,
+    shadowAngularRadius: input.shadowAngularRadius,
+    maxPenumbraTexels: input.maxPenumbraTexels,
+    deviceGeneration: input.deviceGeneration,
+    graphGeneration: input.graphGeneration,
+    ...(input.error === undefined ? {} : { error: input.error }),
+  });
+}