@forgeax/engine-render 0.1.19 → 0.1.21

package/src/volume/recovery.ts

@@ -0,0 +1,86 @@
+import type { VolumeProjectorTuple } from './temporal';
+
+export interface VolumeSelectedLightFacts {
+  readonly entity: number;
+  readonly kind: 'directional' | 'point' | 'spot';
+  readonly revision: number;
+  readonly shadowTile: number;
+  readonly pointLightEntity?: number;
+  readonly spotLightEntity?: number;
+  readonly projector?: VolumeProjectorTuple;
+}
+
+export interface VolumeRecoveryState {
+  readonly guid: string;
+  readonly generation: number;
+  readonly deviceEpoch: number;
+  readonly status: 'accepted' | 'candidate' | 'degraded' | 'recovering';
+  readonly candidateGeneration?: number;
+  readonly candidateDigest?: string;
+  readonly lkgGeneration?: number;
+  readonly candidateFailure?:
+    | 'submit-failed'
+    | 'stale-generation'
+    | 'missing-selected-light'
+    | 'missing-shadow';
+  readonly selectedLight?: VolumeSelectedLightFacts;
+  readonly candidateSelectedLight?: VolumeSelectedLightFacts;
+}
+
+export type VolumeRecoveryEvent =
+  | { readonly kind: 'submit-failed' }
+  | { readonly kind: 'device-lost'; readonly deviceEpoch: number }
+  | { readonly kind: 'accepted'; readonly generation: number };
+
+export function stageVolumetricFog(
+  state: VolumeRecoveryState,
+  candidate: {
+    readonly generation: number;
+    readonly digest: string;
+    readonly selectedLight?: VolumeSelectedLightFacts;
+  },
+): VolumeRecoveryState {
+  return {
+    ...state,
+    status: 'candidate',
+    candidateGeneration: candidate.generation,
+    candidateDigest: candidate.digest,
+    ...(candidate.selectedLight === undefined
+      ? {}
+      : { candidateSelectedLight: candidate.selectedLight }),
+  };
+}
+
+export function recoverVolumetricFog(
+  state: VolumeRecoveryState,
+  event: VolumeRecoveryEvent,
+): VolumeRecoveryState {
+  if (event.kind === 'device-lost') {
+    return { ...state, status: 'recovering', deviceEpoch: event.deviceEpoch };
+  }
+  if (event.kind === 'submit-failed') {
+    return {
+      ...state,
+      status: 'degraded',
+      lkgGeneration: state.generation,
+      candidateFailure: 'submit-failed',
+    };
+  }
+  const expectedGeneration = state.candidateGeneration ?? state.generation;
+  if (state.status === 'degraded' || event.generation !== expectedGeneration) {
+    return {
+      ...state,
+      status: 'degraded',
+      lkgGeneration: state.generation,
+      candidateFailure: 'stale-generation',
+    };
+  }
+  return {
+    ...state,
+    status: 'accepted',
+    lkgGeneration: state.generation,
+    ...(state.candidateSelectedLight === undefined
+      ? {}
+      : { selectedLight: state.candidateSelectedLight }),
+  };
+}

package/src/volume/resources.ts

@@ -0,0 +1,236 @@
+import type {
+  CompiledRenderGraphInfo,
+  GraphTexture,
+  GraphTextureDescriptor,
+  GraphTextureView,
+  RenderGraphBuilder,
+  RenderGraphError,
+} from '@forgeax/engine-render-graph';
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame } from '../render-pipeline';
+
+export const VOLUME_FROXEL_FORMAT = 'rgba8unorm' as const;
+export const VOLUME_HISTORY_FORMAT = 'rgba16float' as const;
+export const VOLUME_RESOLVED_FORMAT = 'rgba16float' as const;
+export const VOLUME_DEPTH_FORMAT = 'r32float' as const;
+export const VOLUME_PACKING_Z = 4;
+/** Renderer-owned parameter allocation shared by staging and inspection. */
+export const VOLUMETRIC_FOG_PARAMS_BYTES = 8 * 16;
+
+export interface VolumetricFogExtent {
+  readonly width: number;
+  readonly height: number;
+  readonly depth: number;
+}
+
+/** Derive the renderer's high profile grid from the actual surface descriptor. */
+export function deriveVolumetricFogExtent(
+  surface: { readonly width: number; readonly height: number },
+  depth = 64,
+  tileSize = 4,
+): VolumetricFogExtent {
+  // The profile tile describes the source-resolution quality lane. Packed
+  // visibility stores two source pixels per physical tile in each dimension.
+  const physicalTileSize = Math.max(2, Math.floor(tileSize / 2));
+  return {
+    width: Math.max(1, Math.ceil(surface.width / physicalTileSize)),
+    height: Math.max(1, Math.ceil(surface.height / physicalTileSize)),
+    depth: Math.max(1, depth),
+  };
+}
+
+/** Derive the 2D resolve extent from the same profile tile without a second profile. */
+export function deriveVolumetricFogResolvedExtent(
+  surface: { readonly width: number; readonly height: number },
+  froxelTileSize = 4,
+): VolumetricFogExtent {
+  // Three's high-quality volume lane resolves at resolution=.25. The packed
+  // high profile uses a physical froxel tile of two source pixels, so its
+  // resolve needs the next coarser four-pixel lane. Keep the low profile's
+  // existing eight-pixel resolve so its quality/budget contract is stable.
+  const resolveTileSize = froxelTileSize === 4 ? 8 : Math.max(1, froxelTileSize);
+  return deriveVolumetricFogExtent(surface, 1, resolveTileSize);
+}
+
+export interface VolumetricFogResources {
+  readonly extent: VolumetricFogExtent;
+  readonly resolvedExtent: VolumetricFogExtent;
+  readonly froxel: GraphTexture;
+  readonly froxelView: GraphTextureView;
+  readonly resolved: GraphTexture;
+  readonly resolvedView: GraphTextureView;
+  readonly history: GraphTexture;
+  readonly historyView: GraphTextureView;
+  readonly temporal: GraphTexture;
+  readonly temporalView: GraphTextureView;
+}
+
+export interface VolumetricFogResourceFacts {
+  readonly generation: number;
+  readonly liveResourceCount: number;
+  readonly currentBytes: number;
+  readonly historyBytes: number;
+  readonly scratchBytes: number;
+  readonly bufferBytes: number;
+  readonly totalBytes: number;
+  readonly physicalResourceCount: number;
+  readonly sampleCount: number;
+  readonly resolvedPixelCount: number;
+}
+
+/** Project graph descriptors into the volume inspection without a second ledger. */
+export interface VolumetricFogResourceInspectionOptions {
+  /** Number of non-null parameter buffers retained by the frame owner. */
+  readonly parameterBufferCount?: number;
+}
+
+export function inspectVolumetricFogResources(
+  graph: CompiledRenderGraphInfo,
+  options: VolumetricFogResourceInspectionOptions = {},
+): VolumetricFogResourceFacts {
+  const volumeResources = graph.resources.filter(
+    (resource) =>
+      resource.label === 'volume-froxel' ||
+      resource.label === 'volume-resolved-current' ||
+      resource.label === 'volume-history' ||
+      resource.label === 'volume-temporal' ||
+      resource.label === 'volume-params',
+  );
+  const bytes = (label: string): number =>
+    volumeResources
+      .filter((resource) => resource.label === label)
+      .reduce((total, resource) => total + (resource.byteSize ?? 0), 0);
+  const graphParameterResources = volumeResources.filter(
+    (resource) => resource.label === 'volume-params',
+  );
+  const graphParameterBufferCount = graphParameterResources.length;
+  const parameterBufferCount = Math.max(
+    0,
+    Math.floor(options.parameterBufferCount ?? graphParameterBufferCount),
+  );
+  const froxel = volumeResources.find((resource) => resource.label === 'volume-froxel');
+  const froxelExtent = froxel?.extent;
+  const resolvedExtent = volumeResources.find(
+    (resource) => resource.label === 'volume-resolved-current',
+  )?.extent;
+  const currentBytes = bytes('volume-resolved-current');
+  // The two graph labels are ping-pong slots for one logical history volume.
+  // Report one slot and physical total separately so the budget remains honest.
+  const historyBytes = bytes('volume-history') + bytes('volume-temporal');
+  const scratchBytes = bytes('volume-froxel');
+  const bufferBytes = parameterBufferCount * VOLUMETRIC_FOG_PARAMS_BYTES;
+  const physicalAllocations = new Set<string>();
+  for (const resource of volumeResources) {
+    if (resource.label === 'volume-params') continue;
+    physicalAllocations.add(resource.physicalAllocationKey ?? resource.label);
+  }
+  // `physicalAllocationKey` remains the authoritative lifecycle identity for
+  // counting live allocations, while category bytes report each declared
+  // history slot so the public sum stays inspectable and exact.
+  const totalBytes = currentBytes + historyBytes + scratchBytes + bufferBytes;
+  return Object.freeze({
+    generation: graph.generation,
+    liveResourceCount: volumeResources.length - graphParameterBufferCount + parameterBufferCount,
+    currentBytes,
+    historyBytes,
+    scratchBytes,
+    bufferBytes,
+    totalBytes,
+    physicalResourceCount: physicalAllocations.size + parameterBufferCount,
+    sampleCount:
+      froxelExtent === undefined
+        ? 0
+        : froxelExtent.width *
+          froxelExtent.height *
+          froxelExtent.depthOrArrayLayers *
+          VOLUME_PACKING_Z,
+    resolvedPixelCount:
+      resolvedExtent === undefined ? 0 : resolvedExtent.width * resolvedExtent.height,
+  });
+}
+
+function textureDescriptor(
+  format: GPUTextureFormat,
+  extent: VolumetricFogExtent,
+): GraphTextureDescriptor {
+  return {
+    format,
+    size: {
+      width: extent.width,
+      height: extent.height,
+      depthOrArrayLayers: Math.ceil(extent.depth / VOLUME_PACKING_Z),
+    },
+    dimension: '2d',
+  };
+}
+
+function resolvedDescriptor(extent: VolumetricFogExtent): GraphTextureDescriptor {
+  return {
+    format: VOLUME_RESOLVED_FORMAT,
+    size: { width: extent.width, height: extent.height, depthOrArrayLayers: 1 },
+    dimension: '2d',
+  };
+}
+
+export function createVolumetricFogResources(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  extent: VolumetricFogExtent = { width: 64, height: 64, depth: 64 },
+  resolvedExtent?: VolumetricFogExtent,
+): Result<VolumetricFogResources, RenderGraphError> {
+  const effectiveResolvedExtent = resolvedExtent ?? {
+    width: extent.width,
+    height: extent.height,
+    depth: 1,
+  };
+  const froxel = graph.createTexture(
+    'volume-froxel',
+    textureDescriptor(VOLUME_FROXEL_FORMAT, extent),
+  );
+  if (!froxel.ok) return froxel;
+  const froxelView = graph.view(froxel.value, {
+    label: 'volume-froxel.view',
+    dimension: '2d-array',
+    baseArrayLayer: 0,
+    arrayLayerCount: Math.ceil(extent.depth / VOLUME_PACKING_Z),
+  });
+  if (!froxelView.ok) return froxelView;
+  const resolved = graph.createTexture(
+    'volume-resolved-current',
+    resolvedDescriptor(effectiveResolvedExtent),
+  );
+  if (!resolved.ok) return resolved;
+  const resolvedView = graph.view(resolved.value, {
+    label: 'volume-resolved-current.view',
+    dimension: '2d',
+  });
+  if (!resolvedView.ok) return resolvedView;
+  const history = graph.createTexture(
+    'volume-history',
+    resolvedDescriptor(effectiveResolvedExtent),
+  );
+  if (!history.ok) return history;
+  const historyView = graph.view(history.value, { label: 'volume-history.view', dimension: '2d' });
+  if (!historyView.ok) return historyView;
+  const temporal = graph.createTexture(
+    'volume-temporal',
+    resolvedDescriptor(effectiveResolvedExtent),
+  );
+  if (!temporal.ok) return temporal;
+  const temporalView = graph.view(temporal.value, {
+    label: 'volume-temporal.view',
+    dimension: '2d',
+  });
+  if (!temporalView.ok) return temporalView;
+  return ok({
+    extent,
+    resolvedExtent: effectiveResolvedExtent,
+    froxel: froxel.value,
+    froxelView: froxelView.value,
+    resolved: resolved.value,
+    resolvedView: resolvedView.value,
+    history: history.value,
+    historyView: historyView.value,
+    temporal: temporal.value,
+    temporalView: temporalView.value,
+  });
+}

package/src/volume/temporal.ts

@@ -0,0 +1,89 @@
+export interface VolumeTemporalSignature {
+  readonly cameraRevision: number;
+  readonly fogRevision: number;
+  readonly lightRevision: number;
+  readonly densityGeneration: number;
+  readonly width: number;
+  readonly height: number;
+  readonly lightKind?: 'directional' | 'point' | 'spot';
+  readonly lightEntity?: number;
+  readonly pointLightEntity?: number;
+  readonly spotLightEntity?: number;
+  readonly projector?: VolumeProjectorTuple;
+  readonly lightShadowRevision?: number;
+}
+
+/** Accepted projector facts shared by surface and volume consumers. */
+export interface VolumeProjectorTuple {
+  readonly guid: string;
+  readonly generation: number;
+  readonly view: string;
+  readonly sampler: string;
+  readonly projection: string;
+  readonly revision: number;
+}
+
+export type VolumeTemporalResetReason =
+  | 'camera-cut'
+  | 'fog-revision'
+  | 'light-revision'
+  | 'density-generation'
+  | 'resize'
+  | 'reprojection-out-of-screen'
+  | 'reprojection-depth-discontinuity';
+
+export type VolumeTemporalReset =
+  | { readonly reset: false }
+  | { readonly reset: true; readonly reason: VolumeTemporalResetReason };
+
+export function resolveVolumeTemporalReset(
+  previous: VolumeTemporalSignature,
+  next: VolumeTemporalSignature,
+  options: {
+    readonly taaEnabled?: boolean;
+    readonly reprojection?: 'out-of-screen' | 'depth-discontinuity';
+  } = {},
+): VolumeTemporalReset {
+  if (options.reprojection === 'out-of-screen') {
+    return { reset: true, reason: 'reprojection-out-of-screen' };
+  }
+  if (options.reprojection === 'depth-discontinuity') {
+    return { reset: true, reason: 'reprojection-depth-discontinuity' };
+  }
+  if (previous.width !== next.width || previous.height !== next.height) {
+    return { reset: true, reason: 'resize' };
+  }
+  if (previous.cameraRevision !== next.cameraRevision) return { reset: true, reason: 'camera-cut' };
+  if (previous.fogRevision !== next.fogRevision) return { reset: true, reason: 'fog-revision' };
+  if (previous.lightRevision !== next.lightRevision) {
+    return { reset: true, reason: 'light-revision' };
+  }
+  if (previous.lightKind !== next.lightKind || previous.lightEntity !== next.lightEntity) {
+    return { reset: true, reason: 'light-revision' };
+  }
+  if (
+    previous.pointLightEntity !== next.pointLightEntity ||
+    previous.spotLightEntity !== next.spotLightEntity
+  ) {
+    return { reset: true, reason: 'light-revision' };
+  }
+  const previousProjector = previous.projector;
+  const nextProjector = next.projector;
+  if (
+    previousProjector?.guid !== nextProjector?.guid ||
+    previousProjector?.generation !== nextProjector?.generation ||
+    previousProjector?.view !== nextProjector?.view ||
+    previousProjector?.sampler !== nextProjector?.sampler ||
+    previousProjector?.projection !== nextProjector?.projection ||
+    previousProjector?.revision !== nextProjector?.revision
+  ) {
+    return { reset: true, reason: 'light-revision' };
+  }
+  if (previous.lightShadowRevision !== next.lightShadowRevision) {
+    return { reset: true, reason: 'light-revision' };
+  }
+  if (previous.densityGeneration !== next.densityGeneration) {
+    return { reset: true, reason: 'density-generation' };
+  }
+  return { reset: false };
+}

package/dist/chunk-IPXCABEP.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/record/frame-snapshot.ts"],"names":[],"mappings":"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","file":"chunk-IPXCABEP.mjs","sourcesContent":["// @forgeax/engine-runtime - RenderSystem record stage: frame-snapshot.\n// Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).\n\nimport type { World } from '@forgeax/engine-ecs';\nimport { vec3 } from '@forgeax/engine-math';\nimport type { ResolvedColorTargetDescriptor } from '@forgeax/engine-render-graph';\nimport type { Texture } from '@forgeax/engine-rhi';\nimport type { ClusterBinScratch } from '../cluster-binner';\nimport type { EnvironmentGeneration } from '../environment/generation';\nimport type { EnvironmentLifecycle } from '../environment/lifecycle';\nimport type { GpuBuffer } from '../gpu-resource';\nimport type { TemporalGpuState } from '../temporal/gpu';\nimport type { TemporalView } from '../temporal/view';\n\nexport type TemporalCommitOutcome =\n  | { readonly kind: 'none' }\n  | { readonly kind: 'off'; readonly view: TemporalView }\n  | { readonly kind: 'taa'; readonly view: TemporalView };\n\n/**\n * feat-20260708-composited-multi-world-rendering M1 / D-1 / D-9:\n * worldId-entityKey composite key helper. Formula: `worldId * 2^32 + entityKey`.\n *\n * worldId is the index into `worlds[]` (the `draw` call argument). entityKey\n * is the packed Entity u32 (encodeEntity(indexSlot, generation)) surfaced\n * through `RenderableSnapshot.entityKey`.\n *\n * Key properties:\n *   - worldId=0 identity: `worldEntityKey(0, k) === k` — single-world path\n *     cache behavior is bit-for-bit unchanged (AC-03 regression guarantee).\n *   - JS safe integer: worldId < 2^21 keeps the composite key below\n *     Number.MAX_SAFE_INTEGER (2^53).\n *   - SSOT: all cache-key compositing consumers import this single helper;\n *     no inline `worldId * 2^32 + k` duplication (D-9).\n *\n * @internal — exported for unit test + glyph/tilemap/record consumers;\n * not part of the public @forgeax/engine-runtime API surface.\n */\nexport function worldEntityKey(worldId: number, entityKey: number): number {\n  return worldId * 4294967296 + entityKey; // 2^32 = 4294967296\n}\n\n/**\n * Cross-frame cache entry for a material bind group whose source material and\n * all resolved GPU resources are stable. The material snapshot identity is\n * the extract-layer invalidation token; the builder only stores entries after\n * all explicit resource handles resolved to resident GPU objects.\n */\nexport interface MaterialBgAssemblyCacheEntry {\n  readonly material: MaterialSnapshot;\n  /** Invalidates when a texture/sampler residency identity changes. */\n  readonly materialResourceEpoch: number;\n  readonly materialBgl: BindGroupLayout;\n  /** Buffer identity changes when the shared material capacity grows. */\n  readonly materialBuffer: Buffer;\n  readonly skylightResources: SkylightBindGroupResources;\n  readonly bindGroup: BindGroup;\n}\n\nimport type { CompiledRenderGraph } from '@forgeax/engine-render-graph';\nimport type { BindGroup, BindGroupLayout, Buffer, TextureView } from '@forgeax/engine-rhi';\nimport type { MaterialRenderState, RenderPipelineAsset } from '@forgeax/engine-types';\nimport type { MeshGpuHandles } from '../device/gpu-residency';\nimport type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';\nimport type { InstanceBufferCacheEntry } from '../instance-buffer-cache';\nimport type { CameraSnapshot } from '../render-contract';\nimport type { RenderPipeline as RenderPipelineDef, RenderPipelineFrame } from '../render-pipeline';\nimport type {\n  DispatchEntry,\n  MaterialSnapshot,\n  PointShadowSnapshot,\n  RenderableSnapshot,\n  SpotLightSnapshot,\n} from '../render-system-extract';\nimport type { ShadowAtlas } from '../shadow-atlas';\n\n/**\n * feat-20260608-create-app-param-surface-trim / M1 / D-8 (q8 user lock):\n * fallback clear color when the world carries no Camera entity. Opaque\n * black `[0, 0, 0, 1]`, replacing the historical\n * `[0.06, 0.06, 0.08, 1.0]` dark-slate sentinel. Single SSOT consumed by\n * the synthetic CameraSnapshot built when `cameras.length === 0`\n * (Case B in `recordFrame`) and read directly by tests\n * (`zero-camera-clear-fallback.test.ts`). AC-05.\n */\nexport const ZERO_CAMERA_CLEAR_FALLBACK: readonly [number, number, number, number] = [0, 0, 0, 1];\n\nexport interface FrameObservationSource {\n  readonly texture: Texture;\n  readonly descriptor: ResolvedColorTargetDescriptor;\n  readonly frameId: number;\n  readonly pipelineId: 'forgeax::standard';\n  readonly backendId: string;\n}\n\n/** Internal test/diagnostic view of one compiled graph color target. */\nexport interface CurrentGraphTarget {\n  readonly name: string;\n  readonly texture: Texture;\n  /** Stable opaque identity for this RHI handle during the renderer lifetime. */\n  readonly textureIdentity: number;\n  readonly descriptor: ResolvedColorTargetDescriptor;\n  readonly frameId: number;\n  /** Monotonic identity of the compiled graph that owns this texture. */\n  readonly graphGeneration: number;\n}\n\nconst textureIdentities = new WeakMap<object, number>();\nlet nextTextureIdentity = 1;\n\n/**\n * Project an opaque RHI texture handle to a stable diagnostic identity.\n * RHI handles intentionally expose no serializable fields; object identity is\n * the only valid comparison boundary for a copy-time capture.\n */\nexport function getTextureIdentity(texture: Texture): number {\n  const object = texture as object;\n  const existing = textureIdentities.get(object);\n  if (existing !== undefined) return existing;\n  const identity = nextTextureIdentity++;\n  textureIdentities.set(object, identity);\n  return identity;\n}\n\nexport type GraphTargetCaptureReadbackValidation =\n  | { readonly ok: true }\n  | {\n      readonly ok: false;\n      readonly code:\n        | 'capture-readback-length'\n        | 'capture-readback-untouched-sentinel'\n        | 'capture-readback-empty'\n        | 'capture-readback-non-finite';\n    };\n\n/** Validate a mapped rgba16float capture before a consumer decodes its values. */\nexport function validateGraphTargetCaptureReadback(input: {\n  readonly bytes: Uint8Array;\n  readonly expectedByteLength: number;\n  readonly sentinel?: Uint8Array;\n}): GraphTargetCaptureReadbackValidation {\n  const { bytes, expectedByteLength, sentinel } = input;\n  if (bytes.byteLength !== expectedByteLength)\n    return { ok: false, code: 'capture-readback-length' };\n  if (sentinel?.every((value, index) => bytes[index] === value)) {\n    return { ok: false, code: 'capture-readback-untouched-sentinel' };\n  }\n  if (bytes.every((value) => value === 0)) return { ok: false, code: 'capture-readback-empty' };\n  for (let index = 0; index + 1 < bytes.length; index += 2) {\n    const exponent = ((bytes[index + 1] ?? 0) >>> 2) & 0x1f;\n    if (exponent === 0x1f) return { ok: false, code: 'capture-readback-non-finite' };\n  }\n  return { ok: true };\n}\n\n/** Internal readback request consumed by the record encoder in the same submit. */\nexport interface GraphTargetCaptureRequest {\n  readonly name: string;\n  readonly buffer: Buffer;\n  readonly bytesPerRow: number;\n  readonly width: number;\n  readonly height: number;\n  /** Descriptor contract checked against the resolved target at copy time. */\n  readonly expected: {\n    readonly format: ResolvedColorTargetDescriptor['format'];\n    readonly width: number;\n    readonly height: number;\n    readonly usage: number;\n    /** Optional caller binding; when present it is checked at copy time. */\n    readonly identity?: {\n      readonly graphGeneration: number;\n      readonly frameId: number;\n      readonly textureIdentity: number;\n    };\n  };\n}\n\n/**\n * Build a synthetic CameraSnapshot the record stage uses when the world\n * carries no Camera entity. Identity-shaped projection / view inputs\n * keep the existing matrix math numerically stable; clear-color quartet\n * sourced from `ZERO_CAMERA_CLEAR_FALLBACK` so the swap-chain still\n * paints `[0, 0, 0, 1]` (AI-user friendly observable signal that the\n * `'render-system-no-camera'` diagnostic fired without leaving stale\n * pixels on screen).\n */\nexport function makeZeroCameraFallbackSnapshot(): CameraSnapshot {\n  // Identity world mat4 so `mat4.invert(world)` yields identity view.\n  const identityWorld = new Float32Array(16);\n  identityWorld[0] = 1;\n  identityWorld[5] = 1;\n  identityWorld[10] = 1;\n  identityWorld[15] = 1;\n  return {\n    position: vec3.create(0, 0, 0),\n    world: identityWorld,\n    fov: Math.PI / 4,\n    aspect: 1,\n    near: 0.1,\n    far: 100,\n    // feat-20260613 M6 / w20: synthetic camera defaults to perspective so\n    // the CSM extract path stays consistent with the previously-implicit\n    // perspective shape (unchanged behavior; explicit field).\n    projection: 'perspective',\n    orthoLeft: -1,\n    orthoRight: 1,\n    orthoBottom: -1,\n    orthoTop: 1,\n    tonemap: 'none',\n    exposure: 1.0,\n    whitePoint: 4.0,\n    antialias: 'none',\n    bloom: 'off',\n    bloomThreshold: 1.0,\n    bloomIntensity: 1.0,\n    bloomBlurRadius: 4.0,\n    clearColor: ZERO_CAMERA_CLEAR_FALLBACK,\n  };\n}\n\n// feat-20260621-merge-directionallightshadow-into-directionallight M3 / m3-t2\n// (D-7): host-clamp the merged DirectionalLight's pcfKernelSize to the nearest\n// valid odd kernel in {1,3,5} before it reaches the View UBO float [128].\n// lighting-directional.wgsl runs a constant-trip-count loop to MAX_PCF_HALF=2\n// (merged 5.3-production-shadow-demos AC-14 variant-free pattern) and clips each\n// iteration to half = (pcfKernelSize-1)/2, so the supported kernel set is\n// {1,3,5} (cap 5). undefined (no shadow fields) defaults to 3.\nexport function clampPcfKernelSize(value: number | undefined): number {\n  if (value === undefined) return 3;\n  if (value <= 1) return 1;\n  if (value <= 3) return 3;\n  return 5;\n}\n\n/**\n * Per-RenderSystem mutable frame state.\n *\n * Owned by the `createRenderSystem` closure; advanced once per\n * `recordFrame` invocation. The `instanceBuffers` map holds the per-entity\n * GPU storage buffers for Instances-bearing entities (cache key = the\n * packed Entity u32 surfaced via `InstancesSnapshot.cacheKey`); entries\n * are recreated when the `archVersion` bumps or `byteLength` changes.\n *\n * feat-20260518-pbr-direct-lighting-mvp M3 / w14 (AC-17 a): the\n * `warnedZeroLightStandard` flag latches the first-frame warning that\n * fires when the world contains a StandardMaterial entity but zero\n * DirectionalLight entries — once latched the next 100 frames suppress\n * the warning so the AI user is not flooded with repeated noise (charter\n * P3 silent failure -> explicit warning at most once per RenderSystem\n * lifetime).\n */\nexport interface RenderFrameState {\n  frameNumber: number;\n  /** Monotonic compiled-graph identity used by diagnostic readbacks. */\n  graphGeneration: number;\n  /** Number of successfully submitted TAA frames; failed attempts do not advance it. */\n  successfulTemporalFrameIndex?: number;\n  /** Optional graph resource lookup used by low-level record helpers and tests. */\n  perFrameGraph?: {\n    readonly getColorTargetDescriptor: (key: string) => ResolvedColorTargetDescriptor | undefined;\n    readonly getColorTargetView: (key: string) => TextureView | undefined;\n    readonly getColorTargetTexture: (key: string) => Texture | undefined;\n    readonly graphGeneration: number;\n  } | null;\n  graphTargetCapture?: GraphTargetCaptureRequest | undefined;\n  /** Last successfully rendered static directional shadow atlas token. */\n  directionalShadowCache: DirectionalShadowCache | null;\n  /** Last successfully submitted camera post-process mode. */\n  lastSuccessfulBloom: 'off' | 'on';\n  /** Bloom record receipts staged by this frame; cleared on abort. */\n  bloomFrameReceipts?: BloomFrameReceipts | undefined;\n  /** Set by a directional shadow pass when this frame refreshed the atlas. */\n  directionalShadowCacheRecorded: boolean;\n  /** The sole compiled owner for compute, copy, feature, and raster work. */\n  compiledFrameGraph: CompiledRenderGraph<RenderPipelineFrame> | null;\n  compiledFrameGraphTopologyKey: string | null;\n  readonly retiredCompiledFrameGraphs: Set<CompiledRenderGraph<RenderPipelineFrame>>;\n  /** Physical outputs projected by typed graph passes for downstream observers. */\n  currentFrameObservationSource: FrameObservationSource | undefined;\n  /** Camera antialias mode for the last successfully submitted graph. */\n  lastSuccessfulCameraAntialias: CameraSnapshot['antialias'] | undefined;\n  /** Staged TAA GPU state is promoted only after queue.submit succeeds. */\n  temporalGpuState: TemporalGpuState | undefined;\n  /** Last successful TAA GPU state; candidate replacement stays staged until submit. */\n  activeTemporalGpuState: TemporalGpuState | undefined;\n  /** Submitted temporal generations retained until their queue fence resolves. */\n  readonly retiringTemporalGpuStates: Set<TemporalGpuState>;\n  /** Last successful projection; candidate frames never overwrite it. */\n  lastSuccessfulTemporalView: TemporalView | undefined;\n  pendingTemporalCommit: TemporalCommitOutcome;\n  /** Staged environment generation is promoted only after queue.submit succeeds. */\n  environmentGeneration: EnvironmentGeneration | undefined;\n  readonly environmentLifecycle: EnvironmentLifecycle | undefined;\n  currentDirectionalShadowView: TextureView | null;\n  currentSpotShadowView: TextureView | null;\n  readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;\n  /** Per-entity vertex buffers for the Standard CPU morph lane. */\n  readonly morphBuffers?: Map<number, MorphBufferCacheEntry>;\n  readonly hdrpClusterBinScratch: ClusterBinScratch;\n  /** Reusable HDRP cluster output buffers; sized once and grown only if the grid/cap changes. */\n  hdrpClusterGridScratch: Uint32Array | null;\n  hdrpLightIndexListScratch: Uint32Array | null;\n  /** Compute bind group for the optional WebGPU HDRP membership producer. */\n  hdrpClusterMembershipBindGroup: BindGroup | null;\n  transientInstanceBuffers: InstanceBufferCacheEntry[];\n  warnedZeroLightStandard: boolean;\n  /**\n   * feax-20260608-multi-light-warn-once M3: once-warn latch for multi-light\n   * overrun per bucket (directional N>1 / point N>4 / spot N>4). Fires at\n   * most once per RenderSystem lifetime per bucket so AI users see a single\n   * actionable console.warn without per-frame flooding (charter P3 explicit\n   * failure: warn-once preserves signal/noise floor).\n   */\n  warnedMultiLightDirectional: boolean;\n  warnedMultiLightPoint: boolean;\n  warnedMultiLightSpot: boolean;\n  /**\n   * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:\n   * once-warn latches for >1 Skylight / >1 SkyboxBackground entity. Fire at most\n   * once per RenderSystem lifetime so the multi-entity warn (which names the\n   * winning entity handle, F-8) does not flood the console every frame.\n   */\n  warnedMultiSkylight: boolean;\n  warnedMultiSkybox: boolean;\n  /** feat-20260531-skybox-env-background M3 / w20: once-warn when camera\n   * tonemap is 'none' but a SkyboxBackground entity exists. Skybox needs\n   * the HDR render target allocated by the tonemap path; without it the\n   * skybox pass is skipped (plan-strategy D-2 NOTE). */\n  warnedSkyboxTonemapNone: boolean;\n  /**\n   * Per-handle warn-once anchor for the missing baseColor-texture fallback,\n   * shared by every textured material path (sprite / sprite-lit / standard-pbr\n   * / pbr-skin / unlit — feat-20260520-2d-sprite-layer-mvp M-3 / w25 seeded it\n   * for sprites; feat-future-pbr-missing-texture-fallback-explicit generalised\n   * it to PBR/skin so GLB textures that fail to reach the GPU no longer render\n   * silently flat). A `Set<number>` keyed by the raw Handle<TextureAsset> id -\n   * the writer fires `console.warn` exactly once per missing texture handle per\n   * RenderSystem lifetime so AI users see a single actionable message without\n   * per-frame log flooding. The set lives across frames so the second frame on\n   * the same missing handle stays silent (charter P3 explicit failure:\n   * warn-once preserves signal / noise floor while structured RhiError below\n   * stays per-frame fire).\n   *\n   * Note on the WeakSet/Set choice: plan-strategy mentions WeakSet but\n   * Handle values are numeric brand u32s (not object references), so\n   * WeakSet<object> is not applicable; Set<number> gives identical\n   * warn-once-per-handle semantics at zero additional cost (charter F1\n   * minimal surface; the per-RenderSystem lifetime cap is the upper\n   * bound).\n   */\n  readonly warnedMissingBaseColorTextureHandles: Set<number>;\n  /**\n   * feat-20260527-sprite-nineslice M2 / w11 + M4 / w16 (AC-16): once-per-\n   * renderable guard for the `nineslice.scale-too-small` metric increment.\n   * Keyed by `renderableIndex` so the second frame on the same mis-scaled\n   * entity does NOT keep bumping the counter — AI users see one counter\n   * tick per offending entity per RenderSystem lifetime, matching the\n   * single-event semantics of the structured fail-fast (charter P3:\n   * machine-readable signal, not a per-frame inflation). M4 retired the\n   * placeholder console.warn; the increment lands on the per-Renderer\n   * EngineMetrics through `runtime.metrics.increment(...)`.\n   */\n  readonly warnedNineSliceScaleEntities: Set<number>;\n  /**\n   * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w18:\n   * per-handle fire-once anchor for the lazy equirect-to-cubemap projection\n   * failure. A `Set<number>` keyed by the raw Handle<EquirectAsset> id - the\n   * record arm fires the structured `EquirectProjectionFailedError` exactly\n   * once per failed source per RenderSystem lifetime (the store records\n   * `status:'failed'` permanently and never retries, R-2 / AC-09; without this\n   * latch the record arm would re-fire the error every frame). The set lives\n   * across frames so the second frame on the same failed handle stays silent\n   * (charter P3: warn-once preserves signal / noise floor).\n   */\n  readonly firedEquirectProjectionFailedHandles: Set<number>;\n  /**\n   * feat-20260622-handle-to-id-allocator-elimination M1 / w3: per-frame\n   * bind group caches converted to nested WeakMap chain roots (D-3).\n   * Each root is a WeakMap<object, WeakMap<...>> walked by\n   * getOrCreateFromChain; the chain depth varies by variant\n   * (view-main = 7, mesh = 1, hdrp-unified = 5, skin = 2).\n   * Roots are stable between device recoveries and replaced when the renderer\n   * swaps to a fresh device. Chain keys are always inner buffer handles, never\n   * wrappers (D-3).\n   */\n  viewBindGroupCache: WeakMap<object, unknown>;\n  meshBindGroupCache: WeakMap<object, unknown>;\n  /**\n   * feat-20260622-handle-to-id-allocator-elimination M1 / w2: per-entity\n   * bind group caches scoped by entityKey (packed u32 as number).\n   * Outer Map<number, WeakMap<handle, ...>> lets GC collect entries for\n   * destroyed entities whose handles are unreachable; per-entity material\n   * and instances share the same two-level shape (D-1). The inner WeakMap\n   * value is opaque (`unknown`) because `getOrCreateFromChain` walks a\n   * variable-depth chain — intermediate handles map to nested WeakMaps and\n   * only the final handle maps to the variant->BindGroup leaf Map. Direct\n   * readers (HDRP shadow-instances read end) assert the leaf shape locally.\n   */\n  /**\n   * feat-20260708-composited-multi-world-rendering M1 / D-1a #2: outer Map\n   * keyed by `worldEntityKey(worldId, entityKey)`. Inner WeakMap unchanged.\n   */\n  readonly materialBgPerEntity: Map<number, WeakMap<object, unknown>>;\n  /**\n   * feat-20260708-composited-multi-world-rendering M1 / D-1a #3: outer Map\n   * keyed by `worldEntityKey(worldId, entityKey)`. Inner WeakMap unchanged.\n   */\n  readonly instancesBgPerEntity: Map<number, WeakMap<object, unknown>>;\n  /** Identity-keyed instances BGs shared across entities using the same buffer. */\n  readonly instancesBgShared: WeakMap<object, unknown>;\n  /**\n   * feat-20260622-handle-to-id-allocator-elimination M1 / w2: cross-entity\n   * shared material bind group cache (OQ-1 option A). Outer key is the\n   * material shaderId string; inner chain is a WeakMap keyed by the same\n   * handle objects used in per-entity chains. Reuses the generic\n   * `getOrCreatePerEntity` helper with outerKey string|number (D-1).\n   */\n  readonly materialBgShared: Map<string, WeakMap<object, unknown>>;\n  /** Cross-frame fast path for fully-resident, immutable material snapshots. */\n  readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;\n  /**\n   * feat-20260622-handle-to-id-allocator-elimination M1 / w2: singleton\n   * material bind group cache (D-6). Single flat Map<variant, BindGroup>\n   * for the one true singleton in production: shadow-material-singleton.\n   * shadow-instances-singleton is a test fixture fiction (research F3);\n   * no second singleton field is needed.\n   */\n  readonly singletonMaterialCache: Map<string, BindGroup>;\n  /**\n   * Post-process bind group cache: nested WeakMap chain root shared by the\n   * built-in bloom (bright / blur-H / blur-V / composite), FXAA, and HDRP SSAO\n   * (calc / blur) fullscreen passes. Each of these passes samples graph-owned\n   * transient render targets (hdrColor / ldrColor / bloom* / ssaoRaw /\n   * gbuf0 / hdrDepth); on canvas resize the graph retires the old physical\n   * textures and allocates new ones, so the bind group must be rebuilt to\n   * reference the new TextureView identity. Keying the cache on the physical\n   * TextureView (or `::tex` texture handle for passes that recreate their bound\n   * view every frame) makes invalidation automatic: a resized target yields a\n   * new key object -> WeakMap miss -> factory rebuild, and dead views are GC'd\n   * (same identity-invalidation mechanism as view/mesh caches, D-3). Replaces\n   * the pre-fix `pp.*BindGroup === null` single-slot caches that never\n   * invalidated on resize and submitted destroyed textures.\n   */\n  postProcessBgCache: WeakMap<object, unknown>;\n  /**\n   * Raw handle of the currently installed RenderPipelineAsset (0 = builtin).\n   * Installation brands the next candidate topology; the prior compiled graph\n   * remains last-known-good until the candidate compiles successfully.\n   */\n  installedPipelineHandle: number;\n  /**\n   * Active topology declaration resolved from the pipeline registry.\n   */\n  activePipeline: RenderPipelineDef;\n  /**\n   * Install-time config projected into `RenderPipelineTopology.config`.\n   */\n  installedPipelineConfig: RenderPipelineAsset['config'];\n  /**\n   * Whether the configured standard graph resolved to the clustered lane.\n   * Capability gating keeps URP forward bindings on WebGL2 fallback even\n   * when a clustered profile was requested.\n   */\n  isHdrpActive: boolean;\n  /**\n   * feat-20260608-cluster-lighting M5 / w20 + M6 / w23 + M5 / w22:\n   * once-per-frame fire dedup set for HDRP per-frame fail-soft errors\n   * (`hdrp-light-budget-exceeded`, `hdrp-index-list-overflow`). Cleared\n   * at the end of each frame so the next frame re-fires if the condition\n   * persists. Set<string> keyed by RuntimeErrorCode literal.\n   */\n  hdrpOncePerFrameFired: Set<string>;\n  /**\n   * feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-2 (plan-strategy §D-1).\n   * Lazily-allocated cube_array shadow atlas owned by the RenderSystem\n   * lifetime. `null` until the first frame whose `lights.pointShadow` is\n   * non-empty (zero-shadow scenes never allocate; AC-09). The atlas is\n   * disposed by the renderer dispose path; subsequent frames with a non-empty\n   * snapshot list re-allocate.\n   */\n  pointShadowAtlas: ShadowAtlas | null;\n  /**\n   * feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-2 (plan-strategy §D-3):\n   * per-frame projection of `lights.pointShadow` from the extract stage. The\n   * typed point-shadow pass reads this list to drive the 6 x N face iteration.\n   * Empty array means the topology declares no point-shadow passes.\n   */\n  pointShadowSnapshots: readonly PointShadowSnapshot[];\n  /**\n   * feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w4 (D-1):\n   * last fold-pass output, computed at `recordFrame` entry from the\n   * transparent-sort-ordered dispatch + mode-gate (D-5: only mode 0\n   * folds; other modes yield singleton buckets). Currently an\n   * observational compute — the drawIndexed swap (1 instanced draw per\n   * fold bucket) is the follow-on integration that wires each bucket\n   * into the sprite-pass / geometry-pass dispatch loops. The bucket\n   * count is the source of truth for `render.instancing.foldedDraws`\n   * metric (M3 / w13) — every fold-eligible bucket (bucketSize >= 1\n   * under mode 0 AND not bypassed) contributes one increment.\n   */\n  lastFoldBucketCount: number;\n  /**\n   * feat-20260625-spot-light-shadow-mapping M2 / w9 (D-2): per-frame projection\n   * of `lights.spot` from the extract stage. The typed spot-shadow graph\n   * pass reads this list to render each\n   * castShadow spot's perspective depth into its `spotShadowDepth` atlas tile\n   * (viewport keyed on `shadowAtlasTile`). `recordFrame` writes it before\n   * graph execution. Spots with `shadowAtlasTile < 0` (castShadow:false,\n   * degenerate direction, or clipped beyond cap 4) are skipped — zero\n   * shadow-casting spots means zero spot shadow passes (AC-03).\n   */\n  spotShadowSnapshots: readonly SpotLightSnapshot[];\n}\n\nexport interface MorphBufferCacheEntry {\n  readonly buffer: GpuBuffer;\n  readonly byteLength: number;\n}\n\n/**\n * feat-20260518-pbr-direct-lighting-mvp M5 / w22.11 (D-2 + D-10 + AC-06):\n * mutable per-frame dispatch counter object owned by `createRenderSystem`\n * and bumped here at the actual `pass.setPipeline(...)` call site (the\n * only point with both `mat.materialShaderId` and `mesh.layoutProjection` in scope).\n * Unlit / custom shader pipeline dispatch tracked here.\n */\nexport interface DispatchCounts {\n  unlit: number;\n  /** feat-20260523 M4-T07: 'standard' counter removed; schema-driven\n   *  materials are tracked via materialShaderId in the pipeline cache. */\n}\n\n/**\n * feat-20260531-per-frame-bind-group-cache M1 / w4: per-frame\n * createBindGroup counter. Closure-mutable object aligned with\n * DispatchCounts precedent. Reset in draw(world) entry, bumped on\n * cache-miss createBindGroup calls (M2-M4).\n */\nexport interface BindGroupCounts {\n  createBindGroup: number;\n  /**\n   * Debug-only: records the variant of every cache-miss BindGroup created via\n   * `getOrCreateFromChain` for unit-test observability. Production paths do\n   * not read this array.\n   */\n  keys: string[];\n}\n\n/**\n * Successful Bloom record operations staged for the current frame. These\n * counters are promoted only after the shared renderer queue submission.\n */\nexport interface BloomFrameReceipts {\n  readonly uploadCount: number;\n  readonly bindGroupCount: number;\n  readonly encodeCount: number;\n}\n\n/**\n * A renderable resolved against the AssetRegistry for the current frame:\n * its source snapshot, the GPU mesh handles, the row index used to correlate\n * transparent-sort output back to this entry, and an optional per-material\n * renderState override (bug-20260527-renderstate-pipeline-dispatch-gap D-4).\n * Module-scoped so RenderPipelineContext can type `validated` / `validatedOrdered`\n * without a dynamic type escape (was a recordFrame-local interface before F-4).\n */\nexport interface ValidatedRenderable {\n  readonly source: RenderableSnapshot;\n  /** World that owns the renderable's asset handles and material snapshots. */\n  readonly world?: World;\n  readonly mesh: MeshGpuHandles;\n  readonly renderableIndex: number;\n  readonly renderState: MaterialRenderState | undefined;\n  /**\n   * Canonical authored material-variant request folded from the selected\n   * pass's `defines` map. Capability axes are merged at the renderer seam;\n   * this field carries only the pass-owned selection into record.\n   */\n  readonly variantSet?: string | undefined;\n  /**\n   * w10: per-pass stencil reference value folded from\n   * {@link DispatchEntry.stencilReference} (draw-call dynamic state). The draw\n   * loop calls `pass.setStencilReference(stencilReference ?? 0)` before each\n   * draw; `undefined` falls back to the WebGPU default 0 (semantic no-op).\n   */\n  readonly stencilReference: number | undefined;\n}\n\n/**\n * Cross-frame validity token for the directional shadow atlas.\n *\n * The atlas is a render target, not authored state. Keeping its validity\n * token beside the other RenderFrameState caches lets recordFrame skip a\n * static caster submission without teaching the public render-pipeline\n * contract about caching. Every source that can change caster depth is part\n * of the token: world mutation, asset catalogue, graph/target identity, CSM\n * matrices, and the GPU mesh-residency epoch.\n *\n * @internal\n */\nexport interface DirectionalShadowCache {\n  readonly worlds: readonly World[];\n  readonly worldStateTokens: readonly DirectionalShadowWorldState[];\n  readonly assetCatalogEpoch: number;\n  readonly pipelineHandle: number;\n  readonly graphTopologyKey: string | null;\n  readonly shadowMapSize: number;\n  readonly cascadeCount: number;\n  readonly lightViewProj: readonly Float32Array[];\n  readonly meshResidencyEpoch: number;\n}\n\n/**\n * ECS state that can change the contents of a directional shadow map.\n *\n * The ECS-owned RenderReadLease is the only render-facing mutation boundary.\n * Its cursor is intentionally conservative: any published World change\n * invalidates the cached atlas, while render never reaches through World for\n * component-clock storage.\n */\nexport interface DirectionalShadowWorldState {\n  readonly worldIdentity: string;\n  readonly changeCursor: number;\n}\n"]}