@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/record/typed-frame-graph.ts

@@ -0,0 +1,461 @@
+import {
+  type CompiledRenderGraph,
+  type GraphResourceResolver,
+  RenderGraphBuilder,
+} from '@forgeax/engine-render-graph';
+import type {
+  BindGroupLayout,
+  CommandBuffer,
+  RenderPipeline,
+  RhiCommandEncoder,
+  Texture,
+  TextureFormat,
+} from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { type RenderError, RenderFeatureStageFailedError } from '../errors/render';
+import {
+  getRenderFeaturePlanExecutionProjection,
+  type RenderFeaturePlanExecution,
+} from '../features/host';
+import { type RenderFeaturePlannedFrame, renderFeaturePlanSignature } from '../features/plan';
+import { projectRenderFeaturePlans as projectPlanExecutions } from '../features/render-graph-contribution';
+import type {
+  RenderFeatureGraphBindingsResolution,
+  RenderFeatureGraphTargetResolver,
+} from '../features/render-graph-raster';
+import { isRenderFeatureTargetHandle } from '../features/targets';
+import type { PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
+import { STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
+import type { CameraSnapshot } from '../render-contract';
+import type {
+  RenderPipelineFeatureTarget,
+  RenderPipelineFrame,
+  RenderPipelineTopology,
+} from '../render-pipeline';
+import type { ExtractedLights } from '../render-system-extract';
+import { buildPerFrameBindGroups } from './frame-lighting';
+import type { RenderFrameState } from './frame-snapshot';
+import type { PipelineState, RenderSystemInternals } from './render-context';
+import { resolveSurfaceFormatPair } from './render-context';
+
+export interface RenderFeatureGraphRuntimeState {
+  plans: readonly RenderFeaturePlannedFrame[];
+  fullscreenEffects: ReadonlyMap<
+    string,
+    import('../fullscreen-post-process-pass').PostProcessShaderEntry
+  >;
+}
+
+/** A frame-local graph candidate that is committed only after compilation. */
+export interface RenderFeatureGraphCandidate {
+  readonly plans: readonly RenderFeaturePlannedFrame[];
+  readonly fullscreenEffects: ReadonlyMap<
+    string,
+    import('../fullscreen-post-process-pass').PostProcessShaderEntry
+  >;
+  /**
+   * Physical prepared resources are imported into the compiled graph. A new
+   * prepared batch therefore needs a new graph even when the declarative plan
+   * signature is unchanged; otherwise queue retirement can destroy the buffer
+   * still referenced by the memoized graph.
+   */
+  readonly preparedResourceKey?: string;
+  /** Release candidate-owned prepared resources when graph promotion fails. */
+  readonly onRejected?: () => void;
+}
+
+const featureGraphStates = new WeakMap<RenderSystemInternals, RenderFeatureGraphRuntimeState>();
+
+export function getRenderFeatureGraphState(
+  internals: RenderSystemInternals,
+): RenderFeatureGraphRuntimeState {
+  const existing = featureGraphStates.get(internals);
+  if (existing !== undefined) return existing;
+  const created: RenderFeatureGraphRuntimeState = {
+    plans: [],
+    fullscreenEffects: new Map(),
+  };
+  featureGraphStates.set(internals, created);
+  return created;
+}
+
+export function resetRenderFeatureGraphState(internals: RenderSystemInternals): void {
+  const state = getRenderFeatureGraphState(internals);
+  state.plans = [];
+  state.fullscreenEffects = new Map();
+}
+
+export function reportRenderFeatureGraphError(
+  internals: RenderSystemInternals,
+  error: RenderError,
+): void {
+  if (internals.featureHost !== undefined && 'detail' in error) {
+    const detail = error.detail;
+    if (detail !== undefined && 'featureIdentity' in detail && 'order' in detail) {
+      const owned = internals.featureHost.recordError(detail.featureIdentity, error);
+      internals.errorRegistry.fire(owned);
+      return;
+    }
+  }
+  internals.errorRegistry.fire(error);
+}
+
+export function renderFeatureGraphPlanSignature(
+  plans: readonly RenderFeaturePlannedFrame[],
+): string {
+  return JSON.stringify(
+    plans.map((planned) => [planned.featureIdentity, planned.generation, planned.signature]),
+  );
+}
+
+function validateRenderFeaturePlans(
+  plans: readonly RenderFeaturePlannedFrame[],
+): Result<readonly RenderFeaturePlanExecution[], RenderError> {
+  const identities = new Set<string>();
+  const projected: RenderFeaturePlanExecution[] = [];
+  let previousOrder = -1;
+  for (const [order, planned] of plans.entries()) {
+    const execution = getRenderFeaturePlanExecutionProjection(planned);
+    if (
+      identities.has(planned.featureIdentity) ||
+      planned.signature !== renderFeaturePlanSignature(planned.plan) ||
+      execution === undefined ||
+      execution.featureIdentity !== planned.featureIdentity ||
+      execution.order <= previousOrder
+    ) {
+      return err(
+        new RenderFeatureStageFailedError(planned.featureIdentity, order, 'plan', 'next-frame'),
+      );
+    }
+    identities.add(planned.featureIdentity);
+    previousOrder = execution.order;
+    projected.push(execution);
+  }
+  return ok(Object.freeze(projected));
+}
+
+function commitFeatureCandidate(
+  internals: RenderSystemInternals,
+  candidate: RenderFeatureGraphCandidate,
+): void {
+  const state = getRenderFeatureGraphState(internals);
+  state.plans = candidate.plans;
+  state.fullscreenEffects = candidate.fullscreenEffects;
+}
+
+function topologyOf(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  pipelineState: PipelineState,
+  camera: CameraSnapshot,
+  lights: ExtractedLights,
+  width: number,
+  height: number,
+  shadowMapSize: number | undefined,
+  gpuDriven: PreparedGpuDrivenFrame | undefined,
+  featureGraphCandidate: RenderFeatureGraphCandidate | undefined,
+): RenderPipelineTopology {
+  const cascadeCount = Math.max(1, Math.min(4, Math.round(lights.cascadeCount ?? 1))) as
+    | 1
+    | 2
+    | 3
+    | 4;
+  const surfaceFormats = resolveSurfaceFormatPair(
+    internals.device.caps.backendKind,
+    pipelineState.format as GPUTextureFormat,
+    pipelineState.colorAttachmentFormat as GPUTextureFormat,
+  );
+  const featurePostEffects = [
+    ...(featureGraphCandidate?.fullscreenEffects ??
+      getRenderFeatureGraphState(internals).fullscreenEffects),
+  ].map(([id]) => id);
+  const config =
+    featurePostEffects.length === 0
+      ? frameState.installedPipelineConfig
+      : {
+          ...(frameState.installedPipelineConfig ?? {}),
+          postEffects: [
+            ...new Set([
+              ...(frameState.installedPipelineConfig?.postEffects ?? []),
+              ...featurePostEffects,
+            ]),
+          ],
+        };
+  return {
+    pipelineId: STANDARD_PIPELINE_ID,
+    standardProfile: internals.standardProfile,
+    config,
+    surface: {
+      width,
+      height,
+      storageFormat: surfaceFormats.storage as TextureFormat,
+      viewFormat: surfaceFormats.view as TextureFormat,
+    },
+    camera: {
+      tonemap: camera.tonemap,
+      antialias: camera.antialias,
+      bloom: camera.bloom,
+    },
+    shadow: {
+      mapSize: shadowMapSize ?? 1024,
+      cascadeCount,
+      pointCount: Math.min(4, lights.pointShadow.length),
+      pointFaceSize: lights.pointShadow[0]?.mapSize ?? 512,
+      spotCount: Math.min(
+        4,
+        lights.spot.filter(
+          (light) => light.shadowAtlasTile >= 0 && light.lightViewProj !== undefined,
+        ).length,
+      ),
+    },
+    lane: {
+      compute: internals.device.caps.compute,
+      storageBuffer: internals.device.caps.storageBuffer,
+      multisample: internals.device.caps.backendKind !== 'wgpu-webgl2',
+      maxColorAttachments: internals.device.caps.maxColorAttachments,
+    },
+    featureTopologySignature: JSON.stringify({
+      plans: renderFeatureGraphPlanSignature(
+        featureGraphCandidate?.plans ?? getRenderFeatureGraphState(internals).plans,
+      ),
+      fullscreenEffects: featurePostEffects,
+      preparedResourceKey: featureGraphCandidate?.preparedResourceKey ?? '',
+    }),
+    gpuDrivenTopologySignature: gpuDriven?.topologySignature ?? '',
+  };
+}
+
+function targetResolver(
+  targets: readonly RenderPipelineFeatureTarget[],
+): RenderFeatureGraphTargetResolver {
+  return (resource) => {
+    if (!isRenderFeatureTargetHandle(resource)) return undefined;
+    const target = targets.find(
+      (candidate) =>
+        candidate.kind === resource.kind &&
+        candidate.format === resource.format &&
+        candidate.sampleCount === resource.sampleCount,
+    );
+    return target === undefined
+      ? undefined
+      : {
+          texture: target.texture,
+          view: target.view,
+          ...(target.resolveTarget === undefined ? {} : { resolveTarget: target.resolveTarget }),
+        };
+  };
+}
+
+function resolveTargetBindings(input: {
+  readonly frame: RenderPipelineFrame;
+  readonly binding: import('../prepare/prepared-graphics-resolver').PreparedGraphicsResolvedResource & {
+    readonly kind: 'bindings';
+  };
+  readonly resources: GraphResourceResolver;
+  readonly resolveTarget: RenderFeatureGraphTargetResolver;
+}): RenderFeatureGraphBindingsResolution | undefined {
+  const frame = input.frame as import('./render-context')._InternalRenderPipelineContext;
+  const descriptor = input.binding.descriptor;
+  const pipeline = input.binding.pipeline as
+    | (RenderPipeline & { getBindGroupLayout?: (index: number) => BindGroupLayout })
+    | undefined;
+  const sceneDepth = descriptor?.values.sceneDepth;
+  const sceneDepthBinding = descriptor?.values.sceneDepthBinding;
+  if (pipeline === undefined) return undefined;
+  if (sceneDepthBinding === 1) {
+    const target = sceneDepth === undefined ? undefined : input.resolveTarget(sceneDepth);
+    const depthView =
+      target === undefined
+        ? frame.pipelineState.shadowFallbackTextureView
+        : (() => {
+            const texture = input.resources.texture(target.texture);
+            if (!texture.ok) throw texture.error;
+            const created = frame.runtime.device.createTextureView(texture.value as Texture, {
+              aspect: 'depth-only',
+              dimension: '2d',
+            });
+            if (!created.ok) throw created.error;
+            return created.value;
+          })();
+    const layout = pipeline.getBindGroupLayout?.(0);
+    if (layout === undefined) return undefined;
+    const created = frame.runtime.device.createBindGroup({
+      layout,
+      entries: [
+        {
+          binding: 0,
+          resource: {
+            kind: 'buffer',
+            value: { buffer: frame.pipelineState.viewUniformBuffer },
+          },
+        },
+        { binding: 1, resource: { kind: 'textureView', value: depthView } },
+      ],
+    });
+    if (!created.ok) throw created.error;
+    return created.value;
+  }
+  if (sceneDepth === undefined) {
+    const viewBindGroup = buildPerFrameBindGroups(
+      frame.runtime as RenderSystemInternals,
+      frame.frameState,
+      frame.pipelineState,
+      frame.validated.length > 0,
+      frame.bindGroupCounts,
+      {
+        directionalShadow: frame.frameState.currentDirectionalShadowView ?? undefined,
+        spotShadow: frame.frameState.currentSpotShadowView ?? undefined,
+      },
+    ).viewBindGroup;
+    return viewBindGroup === null ? undefined : { handle: viewBindGroup, dynamicOffsets: [0] };
+  }
+  const target = input.resolveTarget(sceneDepth);
+  if (target === undefined) return undefined;
+  const texture = input.resources.texture(target.texture);
+  if (!texture.ok) throw texture.error;
+  const depthView = frame.runtime.device.createTextureView(texture.value as Texture, {
+    aspect: 'depth-only',
+    dimension: '2d',
+  });
+  if (!depthView.ok) throw depthView.error;
+  const group = descriptor?.values.group === 1 ? 1 : 0;
+  const layout = pipeline.getBindGroupLayout?.(group);
+  if (layout === undefined) return undefined;
+  const created = frame.runtime.device.createBindGroup({
+    layout,
+    entries: [{ binding: 0, resource: { kind: 'textureView', value: depthView.value } }],
+  });
+  if (!created.ok) throw created.error;
+  return created.value;
+}
+
+function retire(
+  frameState: RenderFrameState,
+  graph: CompiledRenderGraph<RenderPipelineFrame>,
+): void {
+  frameState.retiredCompiledFrameGraphs.add(graph);
+  graph
+    .retire()
+    .finally(() => frameState.retiredCompiledFrameGraphs.delete(graph))
+    .catch(() => undefined);
+}
+
+export function ensureCompiledFrameGraph(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  pipelineState: PipelineState,
+  camera: CameraSnapshot,
+  lights: ExtractedLights,
+  width: number,
+  height: number,
+  shadowMapSize: number | undefined,
+  gpuDriven?: PreparedGpuDrivenFrame,
+  featureGraphCandidate?: RenderFeatureGraphCandidate,
+): CompiledRenderGraph<RenderPipelineFrame> | null {
+  const surfaceWidth = Math.max(1, width);
+  const surfaceHeight = Math.max(1, height);
+  const featurePlans = featureGraphCandidate?.plans ?? getRenderFeatureGraphState(internals).plans;
+  const projectedFeaturePlans = validateRenderFeaturePlans(featurePlans);
+  if (!projectedFeaturePlans.ok) {
+    reportRenderFeatureGraphError(internals, projectedFeaturePlans.error);
+    featureGraphCandidate?.onRejected?.();
+    return frameState.compiledFrameGraph;
+  }
+  const topology = topologyOf(
+    internals,
+    frameState,
+    pipelineState,
+    camera,
+    lights,
+    surfaceWidth,
+    surfaceHeight,
+    shadowMapSize,
+    gpuDriven,
+    featureGraphCandidate,
+  );
+  const key = JSON.stringify(topology);
+  if (frameState.compiledFrameGraph !== null && frameState.compiledFrameGraphTopologyKey === key) {
+    if (featureGraphCandidate !== undefined) {
+      commitFeatureCandidate(internals, featureGraphCandidate);
+    }
+    return frameState.compiledFrameGraph;
+  }
+
+  const builder = new RenderGraphBuilder<RenderPipelineFrame>();
+  let projectedFeatures = false;
+  let projectedGpuDriven = false;
+  const built = frameState.activePipeline.build(
+    {
+      graph: builder,
+      projectGpuDriven: (target) => {
+        if (projectedGpuDriven || gpuDriven === undefined) return ok(undefined);
+        projectedGpuDriven = true;
+        return gpuDriven.project(builder, target.format, target.sampleCount);
+      },
+      contributeFeatures: (targets) => {
+        if (projectedFeatures) return ok(undefined);
+        projectedFeatures = true;
+        if (projectedFeaturePlans.value.length === 0) return ok(undefined);
+        const resolveTarget = targetResolver(targets);
+        const projected = projectPlanExecutions(builder, projectedFeaturePlans.value, {
+          resolveTarget,
+          resolveBindings: resolveTargetBindings,
+          reportError: (error) => reportRenderFeatureGraphError(internals, error),
+        });
+        return projected.ok ? ok(undefined) : projected;
+      },
+    },
+    topology,
+  );
+  if (!built.ok) {
+    internals.errorRegistry.fire(built.error);
+    featureGraphCandidate?.onRejected?.();
+    return frameState.compiledFrameGraph;
+  }
+  const compiled = builder.compile({
+    device: internals.device,
+    surfaceSize: { width: surfaceWidth, height: surfaceHeight },
+  });
+  if (!compiled.ok) {
+    internals.errorRegistry.fire(compiled.error);
+    featureGraphCandidate?.onRejected?.();
+    return frameState.compiledFrameGraph;
+  }
+  const previous = frameState.compiledFrameGraph;
+  frameState.compiledFrameGraph = compiled.value;
+  frameState.compiledFrameGraphTopologyKey = key;
+  gpuDriven?._commitResourceReplacement();
+  if (featureGraphCandidate !== undefined) {
+    commitFeatureCandidate(internals, featureGraphCandidate);
+  }
+  if (previous !== null) retire(frameState, previous);
+  return compiled.value;
+}
+
+export function executeCompiledFrameGraph(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  frame: RenderPipelineFrame,
+  encoder: RhiCommandEncoder,
+  runPass?: import('@forgeax/engine-render-graph').RenderGraphPassRunner,
+): boolean {
+  const graph = frameState.compiledFrameGraph;
+  if (graph === null) return false;
+  const executed = graph.execute(frame, runPass);
+  if (!executed.ok) {
+    internals.errorRegistry.fire(executed.error);
+    return false;
+  }
+  const finished = encoder.finish();
+  if (!finished.ok) {
+    internals.errorRegistry.fire(finished.error);
+    return false;
+  }
+  const command: CommandBuffer = finished.value;
+  const submitted = internals.device.queue.submit([command]);
+  if (!submitted.ok) {
+    internals.errorRegistry.fire(submitted.error);
+    return false;
+  }
+  return true;
+}

package/src/record/view-ubo.ts

@@ -0,0 +1,222 @@
+// @forgeax/engine-runtime - RenderSystem record stage: view-ubo.
+// feat-20260704 M3/w18: the View UBO + CSM/spot-shadow matrix pack assembly
+// extracted verbatim from `recordFrame` (frame.ts). Builds the 240-float View
+// UBO payload (worldViewProj, directional light, camera pos, per-cascade
+// lightViewProj matrices, split planes, shadow bias, folded spot lightViewProj
+// lanes) and flushes it in one queue.writeBuffer round-trip. Kept as a
+// standalone function so recordFrame stays an orchestration skeleton (D-2).
+
+import { mat4 } from '@forgeax/engine-math';
+import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import type { PointsLinesStyle } from '../points-lines/snapshot';
+import type { CameraSnapshot } from '../render-contract';
+import type {
+  DirectionalLightSnapshot,
+  ExtractedLights,
+  SpotLightSnapshot,
+} from '../render-system-extract';
+import { clampPcfKernelSize } from './frame-snapshot';
+import { computeProjectionMatrix, computeViewMatrix } from './helpers';
+
+export const VIEW_UNIFORM_BYTES = 960;
+export const POINTS_LINES_VIEW_BYTES = 160;
+export const POINTS_LINES_VIEW_SLOT_STRIDE = 256;
+export const POINTS_LINES_VIEW_SLOT_COUNT = 1024;
+export const POINTS_LINES_VIEW_BUFFER_SIZE =
+  POINTS_LINES_VIEW_SLOT_STRIDE * POINTS_LINES_VIEW_SLOT_COUNT;
+export const VIEW_UNIFORM_SLOT_STRIDE = 1024;
+export const POINT_SHADOW_VIEW_SLOT_COUNT = 24;
+export const VIEW_UNIFORM_BUFFER_SIZE =
+  VIEW_UNIFORM_SLOT_STRIDE * (1 + POINT_SHADOW_VIEW_SLOT_COUNT);
+
+export function pointShadowViewOffset(layer: number, face: number): number {
+  return VIEW_UNIFORM_SLOT_STRIDE * (1 + layer * 6 + face);
+}
+
+export function writePointsLinesViewUbo(
+  queue: RhiQueue,
+  buffer: Buffer,
+  camera: CameraSnapshot,
+  width: number,
+  height: number,
+  model?: ArrayLike<number>,
+  style?: PointsLinesStyle,
+  byteOffset = 0,
+): void {
+  const projection = computeProjectionMatrix(camera);
+  const view = computeViewMatrix(camera);
+  const worldViewProj = mat4.create();
+  mat4.multiply(worldViewProj, projection, view);
+  const payload = new Float32Array(40);
+  payload.set(worldViewProj);
+  if (model === undefined) {
+    payload[16] = 1;
+    payload[21] = 1;
+    payload[26] = 1;
+    payload[31] = 1;
+  } else {
+    for (let index = 0; index < 16; index += 1) {
+      payload[16 + index] = model[index] ?? 0;
+    }
+  }
+  payload[32] = width;
+  payload[33] = height;
+  if (style?.kind === 'points') {
+    payload[36] = style.sizePx;
+    payload[38] = style.shape === 'circle' ? 1 : 0;
+  } else if (style?.kind === 'lines') {
+    payload[36] = style.widthPx;
+    payload[37] = 1;
+  } else {
+    payload[36] = 1;
+  }
+  const uploaded = queue.writeBuffer(buffer, byteOffset, payload);
+  if (!uploaded.ok) throw uploaded.error;
+}
+
+/**
+ * feat-20260704 M3/w18: assemble + upload the per-frame View UBO payload.
+ *
+ * feat-20260518 M3 / w14 (AC-07 / AC-09): builds the full view UBO payload.
+ * Single queue.writeBuffer covers the whole payload (one round-trip per frame,
+ * charter P5 consistent abstraction). Outgoing-direction convention
+ * (DirectionalLight @semantics outgoing): the host uploads light.direction
+ * verbatim; the shader negates it internally via
+ * `let l = normalize(-view.lightDir)` to get the L vector for BRDF (single
+ * SSOT, no double-negation).
+ *
+ * feat-20260520-directional-light-shadow-mapping M1b / w7 + feat-20260613-csm
+ * M4 / w16+w25: viewPayload is 240 floats. Layout matches common.wgsl View
+ * struct byte-for-byte:
+ *   [ 0..15] worldViewProj, [16..18] lightDir, [20..22] lightColor,
+ *   [24..26] cameraPos, [28..43] lightViewProj0 (was lightSpaceMatrix),
+ *   [44..59] inverseViewProj, [60..75] lightViewProj1,
+ *   [76..91] lightViewProj2, [92..107] lightViewProj3,
+ *   [108]/[112]/[116]/[120] splitPlanes (vec4 stride),
+ *   [124] cascadeCount, [125] cascadeBlend,
+ *   [126] depthBias, [127] normalBias, [128] pcfKernelSize (feat-20260621
+ *   M3 / m3-t2-t3), [129..131] align pad,
+ *   [132..195] spotLightViewProj array<mat4x4<f32>, 4> (feat-20260625 w25:
+ *   folded from standalone binding 9 to fix WebGL2 fragment uniform-buffer
+ *   overflow; lane N = spot with shadowAtlasTile === N, 16 f32 / lane,
+ *   16 B-aligned at byte 528 = float 132).
+ *
+ * @internal
+ */
+export function writeViewUbo(
+  queue: RhiQueue,
+  viewUniformBuffer: Buffer,
+  camera: CameraSnapshot,
+  light: DirectionalLightSnapshot,
+  lights: ExtractedLights,
+  spotShadowSnapshots: readonly SpotLightSnapshot[],
+): void {
+  // Compose worldViewProj once per frame (view * proj).
+  const projMatrix = computeProjectionMatrix(camera);
+  const viewMatrix = computeViewMatrix(camera);
+  const worldViewProj = mat4.create();
+  mat4.multiply(worldViewProj, projMatrix, viewMatrix);
+
+  const VIEW_PAYLOAD_FLOATS = 240;
+  const viewPayload = new Float32Array(VIEW_PAYLOAD_FLOATS);
+  for (let i = 0; i < 16; i++) viewPayload[i] = worldViewProj[i] ?? 0;
+  viewPayload[16] = (light.direction[0] ?? 0) * light.intensity;
+  viewPayload[17] = (light.direction[1] ?? -1) * light.intensity;
+  viewPayload[18] = (light.direction[2] ?? 0) * light.intensity;
+  viewPayload[20] = light.color[0] ?? 0;
+  viewPayload[21] = light.color[1] ?? 0;
+  viewPayload[22] = light.color[2] ?? 0;
+  viewPayload[24] = camera.position[0] ?? 0;
+  viewPayload[25] = camera.position[1] ?? 0;
+  viewPayload[26] = camera.position[2] ?? 0;
+  // lightViewProj[0] at [28..43] (replaces lightSpaceMatrix).
+  if (lights.lightViewProj !== undefined && lights.lightViewProj[0] !== undefined) {
+    for (let i = 0; i < 16; i++) viewPayload[28 + i] = lights.lightViewProj[0][i] ?? 0;
+  }
+  // inverseViewProj at [44..59] — unchanged position.
+  // Host pre-computes mat4.invert so the skybox fragment shader avoids
+  // per-pixel matrix inversion (charter P4 consistent abstraction).
+  const inverseViewProj = mat4.create();
+  mat4.invert(inverseViewProj, worldViewProj);
+  for (let i = 0; i < 16; i++) viewPayload[44 + i] = inverseViewProj[i] ?? 0;
+  // lightViewProj[1..3] at [60..107].
+  if (lights.lightViewProj !== undefined) {
+    for (let c = 1; c <= 3; c++) {
+      const base = 60 + (c - 1) * 16;
+      const lvp = lights.lightViewProj[c];
+      if (lvp !== undefined) {
+        for (let i = 0; i < 16; i++) viewPayload[base + i] = lvp[i] ?? 0;
+      }
+    }
+  }
+  // splitPlanes at [108], [112], [116], [120] (vec4 stride = 4 floats).
+  if (lights.splitPlanes !== undefined) {
+    for (let s = 0; s < 4; s++) {
+      viewPayload[108 + s * 4] = lights.splitPlanes[s] ?? 0;
+    }
+  }
+  // cascadeCount / cascadeBlend at [124..125].
+  viewPayload[124] = lights.cascadeCount ?? 0;
+  viewPayload[125] = lights.cascadeBlend ?? 0;
+  // feat-20260621-merge-directionallightshadow-into-directionallight M3 /
+  // m3-t2: shadow bias + PCF kernel width from the merged DirectionalLight
+  // land in the formerly-free tail pad at floats [126/127/128] (bytes
+  // 504/508/512). VIEW_PAYLOAD_FLOATS / VIEW_UBO_BYTES are unchanged --
+  // the WGSL View struct (common.wgsl) appends matching f32 at the same
+  // slots; the host tail pad shrinks 88 B -> 64 B, rest stays zero.
+  // pcfKernelSize is host-clamped to the nearest valid odd kernel {1,3,5}
+  // (cap 5, matching lighting-directional.wgsl MAX_PCF_HALF=2 from the
+  // merged 5.3-production-shadow-demos AC-14 variant-free loop) so the
+  // per-iteration radius clip has a fixed, legal bound; undefined
+  // (no cast-shadow / no shadow fields) defaults to 3.
+  viewPayload[126] = lights.depthBias ?? 0.005;
+  viewPayload[127] = lights.normalBias ?? 0.05;
+  viewPayload[128] = clampPcfKernelSize(lights.pcfKernelSize);
+
+  // feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-fallback):
+  // spotLightViewProj array<mat4x4<f32>, 4> at floats [132..195] (byte 528,
+  // 16 B-aligned after pcfKernelSize). Lane N = the spot with
+  // `shadowAtlasTile === N` (cap = 4); the perspective matrix was already
+  // computed by the extract stage (SpotLightSnapshot.lightViewProj) — record
+  // never recomputes it (Derive). Lanes for non-shadow / clipped spots (tile
+  // < 0 or lightViewProj undefined) stay zeroed; the WGSL sample path gates
+  // on `SpotLight.shadowAtlasTile >= 0` so zeroed lanes are never read.
+  // Folded from the former standalone binding 9 UBO to keep the WebGL2
+  // fallback fragment uniform-buffer count <= 11 (GLES 3.0).
+  {
+    const SPOT_LVP_BASE_FLOAT = 132;
+    const SPOT_LVP_LANE_COUNT = 4;
+    const SPOT_LVP_FLOATS_PER_LANE = 16;
+    const spotSnaps = spotShadowSnapshots;
+    for (let i = 0; i < spotSnaps.length; i++) {
+      const ss = spotSnaps[i];
+      if (ss === undefined) continue;
+      const tile = ss.shadowAtlasTile;
+      if (tile < 0 || tile >= SPOT_LVP_LANE_COUNT) continue;
+      const lvp = ss.lightViewProj;
+      if (lvp === undefined) continue;
+      const base = SPOT_LVP_BASE_FLOAT + tile * SPOT_LVP_FLOATS_PER_LANE;
+      for (let f = 0; f < SPOT_LVP_FLOATS_PER_LANE; f++) {
+        viewPayload[base + f] = lvp[f] ?? 0;
+      }
+    }
+  }
+
+  const viewUploadResult = queue.writeBuffer(viewUniformBuffer, 0, viewPayload);
+  if (!viewUploadResult.ok) throw viewUploadResult.error;
+
+  for (const snapshot of lights.pointShadow ?? []) {
+    if (snapshot.shadowAtlasLayer < 0 || snapshot.shadowAtlasLayer >= 4) continue;
+    for (let face = 0; face < 6; face += 1) {
+      const facePayload = viewPayload.slice();
+      const matrix = snapshot.shadowMatrices.subarray(face * 16, (face + 1) * 16);
+      facePayload.set(matrix, 28);
+      const uploaded = queue.writeBuffer(
+        viewUniformBuffer,
+        pointShadowViewOffset(snapshot.shadowAtlasLayer, face),
+        facePayload,
+      );
+      if (!uploaded.ok) throw uploaded.error;
+    }
+  }
+}