@forgeax/engine-render 0.1.2

package/src/scene-instances/post-spawn-resolve-joints.ts

@@ -0,0 +1,168 @@
+// @forgeax/engine-runtime — postSpawnResolveJoints hook (M1 / T-14).
+//
+// Invoked after sceneInstances.instantiate to auto-wire Skin.joints: Entity[]
+// from the SkinAsset.jointPaths via Name-component lookup on the
+// spawned entity subtree. This is the v1 missing item #2: instantiate auto-calls
+// postSpawnResolveJoints so AI users never manually populate Skin.joints.
+//
+// Resolution protocol (plan-strategy D-6a + tweak-20260611 D-7 subtree-scope):
+//   - From the spawnRoot, walk ChildOf relations BFS to collect the spawned
+//     subtree's entities. nameIndex is built only over those entities.
+//   - For each Skin-bearing entity in the subtree, resolve the skeleton handle
+//     to jointPaths via the resolver.
+//   - For each jointPath leaf name, match against the subtree-local Name index.
+//   - Same-name sibling within the subtree: first-match with console.warn (D-6a).
+//   - Missing entity: fail-fast 'skin-joint-path-unresolved' error.
+//   - Empty jointPaths: no-op (no crash).
+//
+// Why subtree-scope (tweak-20260611 D-7):
+//   Without scope, multiple instantiate() calls on the same SceneAsset (e.g. 3
+//   Fox foxes side-by-side) all wire to the FIRST instance's joint entities
+//   because Name leaf strings collide globally — Skin.joints[] points to
+//   instance-0's bones for every spawn, three foxes share one skeleton, poses
+//   cannot differ. Scoping to ChildOf descendants of spawnRoot eliminates the
+//   collision: each spawn has its own copy of the subtree, names collide only
+//   among siblings within the same spawn, where D-6a's first-match-with-warn
+//   remains the correct policy.
+//
+// Decision anchors:
+//   - requirements AC-14 (post-spawn auto-wire)
+//   - plan-strategy D-6a (first-match strategy within subtree)
+//   - tweak-20260611 plan-strategy D-7 (subtree-scope)
+//   - charter P3 (explicit failure: path-unresolved fail-fast)
+
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { Name } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+import type { SkinAsset } from '@forgeax/engine-types';
+import { collectSubtree } from '../scene-utils/collect-subtree';
+
+// feat-20260705-runtime-tier2-decomposition M1 / w6 (D-1): SkinJointResolver
+// relocated to registry/instantiate.ts so the hook contract travels with the
+// instantiate cluster into @forgeax/engine-assets-runtime. Imported back here as
+// a forward (runtime -> assets-runtime-bound module) type-only reference and
+// re-exported for existing consumers of this module's SkinJointResolver export.
+export interface SkinJointResolver {
+  resolveSkinAsset(skeletonHandle: number): SkinAsset | undefined;
+}
+
+interface JointPathUnresolvedError {
+  code: 'skin-joint-path-unresolved';
+  expected: string;
+  hint: string;
+  detail: {
+    skinEntity: number;
+    path: readonly string[];
+    failedAtIndex: number;
+  };
+}
+
+interface SkinAssetUnresolvedError {
+  code: 'skin-asset-unresolved';
+  expected: string;
+  hint: string;
+  detail: {
+    skinEntity: number;
+    skeletonHandle: number;
+  };
+}
+
+type ResolveError = JointPathUnresolvedError | SkinAssetUnresolvedError;
+
+export function postSpawnResolveJoints(
+  world: World,
+  resolver: SkinJointResolver,
+  spawnRoot: EntityHandle,
+): { ok: true } | { ok: false; error: ResolveError } {
+  // tweak-20260611 D-7: scope nameIndex to the spawnRoot's ChildOf-descendant
+  // subtree (incl. spawnRoot itself). Multiple instantiate() calls on the same
+  // SceneAsset each get an independent subtree, so leaf-name collisions across
+  // instances no longer wire all spawns to the first instance's joints.
+  const subtree = collectSubtree(world, spawnRoot);
+  const nameIndex = new Map<string, number[]>();
+  const nameQuery = world.query({ read: [Name] });
+  if (nameQuery.ok) {
+    for (const row of nameQuery.value) {
+      if (!subtree.has(row.entity as number)) continue;
+      const nameVal = row.get(Name).value;
+      const list = nameIndex.get(nameVal) ?? [];
+      list.push(row.entity);
+      nameIndex.set(nameVal, list);
+    }
+  }
+
+  // Walk Skin-bearing entities IN THE SUBTREE and resolve joints. Skin is
+  // matched through the owner identity projection, and entities outside the subtree
+  // are filtered after readEntityAt (cheaper than per-archetype filtering).
+  const skinQuery = world.query({ read: [Skin] });
+  if (!skinQuery.ok) return { ok: true };
+  for (const queryRow of skinQuery.value) {
+    const entity = queryRow.entity;
+    if (!subtree.has(entity as number)) continue;
+    const skeletonHandle = queryRow.get(Skin).skeleton as number;
+
+    const skinAsset = resolver.resolveSkinAsset(skeletonHandle);
+    if (skinAsset === undefined) {
+      // feat-20260612 M2 fixup: was a silent `continue` that left
+      // `Skin.joints` empty -- the M2-introduced
+      // JointCountMismatchError fail-fast in render-system-extract then
+      // triggered every frame on the browser-async-pack-fetch path.
+      // The cure is to load SkinAssets through the SceneAsset.skinGuids
+      // cross-edge (gltfImporter scene branch emits the SkinAsset GUIDs into
+      // the scene envelope's refs[], the runtime recursion source) so this
+      // resolver should always succeed; if it does not, fail-fast here
+      // with a precise errorCode rather than silently producing an
+      // unresolvable Skin.joints state.
+      return {
+        ok: false,
+        error: {
+          code: 'skin-asset-unresolved',
+          expected: `SkinAsset registered for skeleton handle ${skeletonHandle} when instantiate triggers postSpawnResolveJoints`,
+          hint: `SkinAsset matching skeletonGuid for handle ${skeletonHandle} was not found in AssetRegistry; verify the SceneAsset.skinGuids[] cross-edge is populated by the importer (gltfImporter scene branch) and that AssetRegistry.load(sceneGuid, sceneAssetKind) recursively loaded each SkinAsset before instantiate (browser-async-pack-fetch path)`,
+          detail: { skinEntity: entity, skeletonHandle },
+        },
+      };
+    }
+
+    const jointEntityList: number[] = [];
+    for (const jointPath of skinAsset.jointPaths) {
+      const pathSegments = jointPath.split('/').filter(Boolean);
+      if (pathSegments.length === 0) continue;
+
+      const leafName = pathSegments[pathSegments.length - 1];
+      if (leafName === undefined) continue;
+
+      const nameMatches = nameIndex.get(leafName);
+      if (nameMatches === undefined || nameMatches.length === 0) {
+        return {
+          ok: false,
+          error: {
+            code: 'skin-joint-path-unresolved',
+            expected: `joint entity with Name="${leafName}" exists in the spawned subtree (root entity ${spawnRoot})`,
+            hint: `joint path "${jointPath}" for skin entity ${entity} could not be resolved within spawnRoot ${spawnRoot}'s ChildOf-subtree; verify glTF node names are preserved and instantiateScene seeded a Children mirror`,
+            detail: {
+              skinEntity: entity,
+              path: pathSegments,
+              failedAtIndex: pathSegments.length - 1,
+            },
+          },
+        };
+      }
+
+      if (nameMatches.length > 1) {
+        console.warn(
+          `[Skin] same-name sibling: "${leafName}" matches ${nameMatches.length} entities ` +
+            `within spawn subtree of root ${spawnRoot}; using first-match (entity ${nameMatches[0]}) per D-6a`,
+        );
+      }
+
+      jointEntityList.push(nameMatches[0] as number);
+    }
+
+    world.set(entity, Skin, {
+      joints: new Uint32Array(jointEntityList),
+    } as never);
+  }
+
+  return { ok: true };
+}

package/src/scene-utils/collect-subtree.ts

@@ -0,0 +1,40 @@
+// M1 shared util — collectSubtree (AC-16).
+// Extracted from post-spawn-resolve-joints.ts:116-133.
+// Walks Children.entities BFS from spawnRoot; accepts optional external visited Set
+// for cross-root de-duplication (AC-03).
+
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+
+import { Children } from '@forgeax/engine-scene';
+
+/**
+ * Walk `Children.entities` BFS from `spawnRoot` to collect all descendant
+ * entities (incl. spawnRoot itself). When a shared `visited` Set is passed,
+ * it is reused across roots for cross-root de-duplication; when omitted a
+ * fresh Set is created (single-root / backward-compat).
+ *
+ * Entities without a `Children` component surface as leaves.
+ */
+export function collectSubtree(
+  world: World,
+  spawnRoot: EntityHandle,
+  visited?: Set<number>,
+): Set<number> {
+  if (visited === undefined) visited = new Set<number>();
+  if (visited.has(spawnRoot as number)) return visited;
+  const queue: number[] = [spawnRoot as number];
+  visited.add(spawnRoot as number);
+  while (queue.length > 0) {
+    const cur = queue.shift() as number;
+    const childrenData = world.get(cur as EntityHandle, Children);
+    if (!childrenData.ok) continue;
+    const list = childrenData.value.entities as ArrayLike<number>;
+    for (let i = 0; i < list.length; i++) {
+      const child = list[i] as number;
+      if (visited.has(child)) continue;
+      visited.add(child);
+      queue.push(child);
+    }
+  }
+  return visited;
+}

package/src/shadow-atlas.ts

@@ -0,0 +1,244 @@
+// @forgeax/engine-runtime - ShadowAtlas (cube_array depth atlas for point-light shadows).
+//
+// feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-1 (plan-strategy §D-1).
+//
+// Lazy-allocated `texture_depth_cube_array` (depth32float) + per-face 2D
+// TextureView cache. One layer per shadow-casting PointLight (cap = 4 enforced
+// by the PointLightShadow ECS component cardinality). Total texel footprint at
+// the 512x512 default = 4 layers x 6 faces x 512 x 512 x 4 B = 24 MiB.
+//
+// Why a separate module (vs inlining into createRenderer / pipelineState):
+// - zero-shadow scene path stays allocation-free (AC-09): we never call
+//   `device.createTexture` on the cube_array unless `ensure(...)` is invoked
+//   from the extract / record path on a frame that has at least one
+//   PointLightShadow snapshot.
+// - face-view cache is keyed (layer, face) and built lazily during the
+//   per-light shadow caster pass; the cache is invalidated together with the
+//   atlas when `dispose()` runs (renderer teardown or layers re-allocation).
+// - the helper descriptors live in `@forgeax/engine-rhi`
+//   (`cubeArrayDepthDescriptor` / `cubeArrayDepthFaceView` /
+//   `comparisonSamplerDescriptor`) per T-M0-3; this file is the runtime-side
+//   owner of the GPU resources they describe.
+//
+// Lifecycle:
+//   1. `new ShadowAtlas(device, { faceSize, layers })` — construct the
+//      manager; no GPU work yet.
+//   2. `atlas.ensure()` — first call allocates the cube_array texture +
+//      cube_array sampling view + comparison sampler (idempotent thereafter).
+//   3. `atlas.faceView(layer, face)` — lazy 2D depth view used as a render-
+//      pass attachment for the corresponding cube face. Cached per (layer,
+//      face).
+//   4. `atlas.dispose()` — releases the GPU resources and clears caches.
+//      `ensure()` after `dispose()` re-allocates from scratch.
+
+import {
+  comparisonSamplerDescriptor,
+  cubeArrayDepthDescriptor,
+  cubeArrayDepthFaceView,
+  type RhiDevice,
+  type Sampler,
+  type Texture,
+  type TextureView,
+} from '@forgeax/engine-rhi';
+
+import {
+  PointShadowAtlasBoundsViolationError,
+  PointShadowAtlasUninitializedError,
+} from './errors/render';
+import { GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING } from './gpu-texture-usage';
+
+/**
+ * Construction options for {@link ShadowAtlas}.
+ */
+export interface ShadowAtlasOptions {
+  /** Per-face square size in pixels. Default 512 (PointLightShadow.mapSize default). */
+  readonly faceSize?: number;
+  /** Number of cube layers. Default 4 (= PointLightShadow cardinality cap). */
+  readonly layers?: number;
+}
+
+/** Default per-face square size in pixels. Mirrors PointLightShadow.mapSize default. */
+export const SHADOW_ATLAS_DEFAULT_FACE_SIZE = 512;
+/** Default cube layer count. Mirrors PointLightShadow cardinality cap. */
+export const SHADOW_ATLAS_DEFAULT_LAYERS = 4;
+
+/**
+ * Cube-array depth atlas for point-light shadows.
+ *
+ * Shape: `texture_depth_cube_array` (depth32float) with `layers = 4` and per-
+ * face size `faceSize x faceSize`. The cube_array sampling view feeds
+ * `@group(0) @binding(5)` in URP shaders; the per-face 2D view feeds the
+ * shadow-caster render pass attachment for one (layer, face) at a time
+ * (WebGPU forbids cube views as render-pass attachments).
+ *
+ * Construction performs no GPU work. The first `ensure()` call allocates the
+ * texture + view + sampler. `dispose()` releases everything; later `ensure()`
+ * calls re-allocate.
+ *
+ * @example Lazy allocation in the extract / record path:
+ * ```
+ * if (lights.pointShadow.length > 0) {
+ *   atlas.ensure();
+ *   for (const ps of lights.pointShadow) {
+ *     for (let face = 0; face < 6; face++) {
+ *       const view = atlas.faceView(ps.shadowAtlasLayer, face);
+ *       // ... begin shadow caster pass with `view` as the depth attachment
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class ShadowAtlas {
+  /** Backing cube_array depth texture. `null` until `ensure()` has run. */
+  private texture: Texture | null = null;
+  /**
+   * Whole-atlas cube_array sampling view used by URP shaders that bind the
+   * atlas at `@group(0) @binding(5)`. `null` until `ensure()` has run.
+   */
+  private cubeArrayView: TextureView | null = null;
+  /** Comparison sampler for `texture_depth_cube_array`. */
+  private compareSampler: Sampler | null = null;
+  /** Per-face 2D depth view cache, keyed by `layer * 6 + face`. */
+  private readonly faceViews = new Map<number, TextureView>();
+  /** Per-face label cache (debug aid). Reused on re-creation. */
+  private readonly device: RhiDevice;
+  /** Per-face square size in pixels. */
+  readonly faceSize: number;
+  /** Cube layer count. */
+  readonly layers: number;
+
+  constructor(device: RhiDevice, options: ShadowAtlasOptions = {}) {
+    this.device = device;
+    this.faceSize = options.faceSize ?? SHADOW_ATLAS_DEFAULT_FACE_SIZE;
+    this.layers = options.layers ?? SHADOW_ATLAS_DEFAULT_LAYERS;
+  }
+
+  /**
+   * Returns `true` once the atlas texture is allocated. Used by the extract /
+   * record path to gate "no PointLightShadow → no allocation" (AC-09) — the
+   * caller calls {@link ensure} on a frame that has at least one snapshot;
+   * before that, `isAllocated()` stays `false` and tests can assert no GPU
+   * resources were created.
+   */
+  isAllocated(): boolean {
+    return this.texture !== null;
+  }
+
+  /**
+   * Lazy-allocate the atlas texture + cube_array sampling view + comparison
+   * sampler. Idempotent: subsequent calls are zero-cost no-ops once the
+   * resources exist.
+   *
+   * Throws (via the RHI error registry) on allocation failure. This is the
+   * only path that touches the GPU — keeping it inside one method makes the
+   * "zero-shadow scene = zero allocation" gate easy to enforce: the renderer
+   * never calls this method on a frame with no PointLightShadow entities.
+   */
+  ensure(): void {
+    if (this.texture !== null) return;
+    const usage = GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING;
+    const texDesc = cubeArrayDepthDescriptor(this.faceSize, this.layers, usage);
+    const texRes = this.device.createTexture(texDesc);
+    if (!texRes.ok) throw texRes.error;
+    this.texture = texRes.value;
+
+    const viewRes = this.device.createTextureView(this.texture, {
+      label: 'shadow-atlas-cube-array-view',
+      dimension: 'cube-array',
+      aspect: 'depth-only',
+      baseArrayLayer: 0,
+      arrayLayerCount: 6 * this.layers,
+      baseMipLevel: 0,
+      mipLevelCount: 1,
+    });
+    if (!viewRes.ok) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+      throw viewRes.error;
+    }
+    this.cubeArrayView = viewRes.value;
+
+    const sampRes = this.device.createSampler(comparisonSamplerDescriptor());
+    if (!sampRes.ok) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+      this.cubeArrayView = null;
+      throw sampRes.error;
+    }
+    this.compareSampler = sampRes.value;
+  }
+
+  /**
+   * Whole-atlas cube_array sampling view (`texture_depth_cube_array`). Returns
+   * `null` if the atlas is not yet allocated; the caller should gate on a
+   * non-null pointShadow array before calling {@link ensure} + this getter.
+   */
+  getAtlasView(): TextureView | null {
+    return this.cubeArrayView;
+  }
+
+  /**
+   * Comparison sampler (`compare: 'less'`) for cube_array depth sampling.
+   * Returns `null` if the atlas is not yet allocated.
+   */
+  getComparisonSampler(): Sampler | null {
+    return this.compareSampler;
+  }
+
+  /**
+   * Backing texture handle. Returns `null` if the atlas is not yet allocated.
+   */
+  getTexture(): Texture | null {
+    return this.texture;
+  }
+
+  /**
+   * Lazy 2D depth view selecting `(layer, face)` (the caller passes
+   * `shadowAtlasLayer` from the snapshot and a face index 0..5). Used as the
+   * depth attachment of the shadow-caster render pass for one cube face.
+   *
+   * Caches per `(layer, face)` so the per-frame shadow loop pays zero
+   * `createTextureView` cost after the first allocation. Cache is cleared on
+   * {@link dispose}.
+   *
+   * @throws PointShadowAtlasUninitializedError if the atlas is not yet
+   *   allocated (caller must call {@link ensure} first).
+   * @throws PointShadowAtlasBoundsViolationError if `layer` or `face` is out
+   *   of range.
+   * @throws RhiError if the underlying `createTextureView` fails.
+   */
+  faceView(layer: number, face: number): TextureView {
+    if (this.texture === null) {
+      throw new PointShadowAtlasUninitializedError();
+    }
+    if (layer < 0 || layer >= this.layers) {
+      throw new PointShadowAtlasBoundsViolationError('layer', layer, this.layers);
+    }
+    if (face < 0 || face >= 6) {
+      throw new PointShadowAtlasBoundsViolationError('face', face, 6);
+    }
+    const key = layer * 6 + face;
+    const cached = this.faceViews.get(key);
+    if (cached !== undefined) return cached;
+    const desc = cubeArrayDepthFaceView(layer, face);
+    const r = this.device.createTextureView(this.texture, desc);
+    if (!r.ok) throw r.error;
+    this.faceViews.set(key, r.value);
+    return r.value;
+  }
+
+  /**
+   * Release the GPU resources and clear the per-face view cache. Idempotent;
+   * subsequent calls are zero-cost. After dispose, `isAllocated()` returns
+   * `false` and the next `ensure()` re-allocates from scratch.
+   */
+  dispose(): void {
+    this.faceViews.clear();
+    if (this.texture !== null) {
+      this.device.destroyTexture(this.texture);
+      this.texture = null;
+    }
+    this.cubeArrayView = null;
+    this.compareSampler = null;
+  }
+}

package/src/ssao-buffers.ts

@@ -0,0 +1,175 @@
+// @forgeax/engine-runtime — SSAO per-runtime persistent GPU buffers.
+//
+// feat-20260612-hdrp-ssao M1 / w4.
+//
+// Owner of 3 SSAO GPU resources, lazily allocated per RenderSystemRuntime,
+// following the getOrCreateHdrpBuffers WeakMap pattern (research F12):
+//   (1) kernel UBO  — 64 padded vec4 samples (1024 B), label hdrp-ssao-kernel
+//   (2) noise texture — 4x4 rgba32float, label hdrp-ssao-noise, NEAREST/REPEAT
+//   (3) uniform UBO   — 3 mat4 + vec4 intensityPad (256 B aligned),
+//                       label hdrp-ssao-uniform
+//
+// plan-strategy D-1: uniform carries view + projection + inverseProjection.
+// plan-strategy D-C: intensity scalar carried at offset 192 (vec4 pad slot)
+//   so the lighting shader can mix(1.0, ssao*ao, intensity) without a new UBO.
+// The kernel uses a uniform buffer on every backend. 1024 B is below the
+// WebGL2 minimum fragment UBO size, so SSAO does not need a storage-buffer
+// capability gate.
+
+import type { Buffer, Texture } from '@forgeax/engine-rhi';
+import { GPU_TEXTURE_USAGE_COPY_DST, GPU_TEXTURE_USAGE_TEXTURE_BINDING } from './gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from './gpu-usage';
+import type { RenderSystemRuntime } from './render-system';
+import { generateSsaoKernel, generateSsaoNoise, SSAO_KERNEL_SAMPLE_COUNT } from './ssao-data';
+
+// Each vec3<f32> in a WGSL array is 16B (12B payload + 4B padding).
+// 64 samples * 16 B/sample = 1024 B.
+const BYTES_PER_KERNEL_ELEMENT = 16;
+
+// SSAO uniform layout (plan-strategy §D-1 + §D-C, M7 round-2):
+//   bytes [0..63]    view              mat4x4<f32>
+//   bytes [64..127]  projection        mat4x4<f32>
+//   bytes [128..191] inverseProjection mat4x4<f32>
+//   bytes [192..207] intensityPad      vec4<f32>  // x = intensity, y/z/w pad
+//   bytes [208..255] padding           // align to 256B WebGPU UBO offset
+//
+// The total is rounded to 256B so the same UBO can host an additional
+// shader-side scalar binding at the tail without re-allocation.
+const UNIFORM_INTENSITY_OFFSET_BYTES = 192;
+const UNIFORM_BYTES = 256;
+export const SSAO_UNIFORM_INTENSITY_OFFSET = UNIFORM_INTENSITY_OFFSET_BYTES;
+export const SSAO_UNIFORM_BYTES = UNIFORM_BYTES;
+
+/**
+ * SSAO GPU resources owned by this module (plan-strategy D-1, D-4).
+ *
+ * Fields are readonly per charter P5: one resource, one owner.
+ */
+export interface SsaoBuffers {
+  /** 64 padded vec4 uniform buffer for hemisphere samples. */
+  readonly kernelBuffer: Buffer;
+  readonly kernelBytes: number;
+  /** 4x4 rgba32float noise texture for per-pixel TBN rotation. */
+  readonly noiseTexture: Texture;
+  /** SSAO uniform UBO: view (mat4) + projection (mat4) + inverseProjection (mat4). */
+  readonly uniformBuffer: Buffer;
+  readonly uniformBytes: number;
+}
+
+const cache = new WeakMap<RenderSystemRuntime, SsaoBuffers>();
+
+/**
+ * Lazily allocate the 3 SSAO GPU resources for `runtime`. Returns the
+ * same `SsaoBuffers` object on subsequent calls (per-RenderSystem
+ * stable identity, WeakMap).
+ *
+ * On `device.createBuffer` / `device.createTexture` failure, fires a
+ * structured error on the runtime's error registry and returns `null`.
+ *
+ * @returns SsaoBuffers on success, null if any allocation fails.
+ */
+export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffers | null {
+  const cached = cache.get(runtime);
+  if (cached !== undefined) return cached;
+
+  const device = runtime.device;
+
+  // (1) Kernel UBO — 64 padded vec4 samples (1024 B).
+  const kernelSamples = generateSsaoKernel();
+  const kernelData = new Float32Array(SSAO_KERNEL_SAMPLE_COUNT * 4); // 4 floats per padded vec3
+  for (let i = 0; i < SSAO_KERNEL_SAMPLE_COUNT; i++) {
+    const s = kernelSamples[i];
+    if (s === undefined) continue;
+    kernelData[i * 4 + 0] = s[0] ?? 0;
+    kernelData[i * 4 + 1] = s[1] ?? 0;
+    kernelData[i * 4 + 2] = s[2] ?? 0;
+    // kernelData[i * 4 + 3] = 0 (padding for std140 vec3 alignment)
+  }
+
+  const kernelBufferRes = device.createBuffer({
+    label: 'hdrp-ssao-kernel',
+    size: SSAO_KERNEL_SAMPLE_COUNT * BYTES_PER_KERNEL_ELEMENT,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!kernelBufferRes.ok) {
+    runtime.errorRegistry.fire(kernelBufferRes.error);
+    return null;
+  }
+
+  // Upload kernel data to the buffer.
+  const kernelWriteRes = device.queue.writeBuffer(kernelBufferRes.value, 0, kernelData);
+  if (!kernelWriteRes.ok) {
+    runtime.errorRegistry.fire(kernelWriteRes.error);
+    return null;
+  }
+
+  // (2) Noise texture — 4x4 rgba32float, NEAREST/REPEAT.
+  const noiseData = generateSsaoNoise();
+  // Pad to rgba32float: 16 texels * 4 floats = 64 floats.
+  const noiseRgba = new Float32Array(16 * 4);
+  for (let i = 0; i < 16; i++) {
+    noiseRgba[i * 4 + 0] = noiseData[i * 3 + 0] ?? 0;
+    noiseRgba[i * 4 + 1] = noiseData[i * 3 + 1] ?? 0;
+    noiseRgba[i * 4 + 2] = 0;
+    noiseRgba[i * 4 + 3] = 1; // alpha = 1 for rgba32float
+  }
+
+  const noiseTexRes = device.createTexture({
+    label: 'hdrp-ssao-noise',
+    size: { width: 4, height: 4, depthOrArrayLayers: 1 },
+    mipLevelCount: 1,
+    sampleCount: 1,
+    dimension: '2d',
+    format: 'rgba32float',
+    usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    textureBindingViewDimension: undefined,
+  });
+  if (!noiseTexRes.ok) {
+    runtime.errorRegistry.fire(noiseTexRes.error);
+    return null;
+  }
+
+  // Direct CPU-to-GPU upload via writeTexture (no alignment requirement
+  // unlike copyBufferToTexture; WebGPU spec §19.2). 4x4 rgba32float texture
+  // = 16 texels * 4 floats * 4 bytes/float = 256 bytes.
+  // The forgeax Texture brand wraps a raw GPUTexture; cast through unknown
+  // follows the createRenderer.ts fallback-pixel pattern (line 4330).
+  const noiseCopyRes = device.queue.writeTexture(
+    {
+      texture: noiseTexRes.value as unknown as GPUTexture,
+      mipLevel: 0,
+      origin: { x: 0, y: 0, z: 0 },
+    },
+    noiseRgba,
+    { offset: 0, bytesPerRow: 4 * 4 * 4, rowsPerImage: 4 },
+    { width: 4, height: 4, depthOrArrayLayers: 1 },
+  );
+  if (!noiseCopyRes.ok) {
+    runtime.errorRegistry.fire(noiseCopyRes.error);
+    return null;
+  }
+
+  // (3) SSAO uniform UBO — 3 mat4 (192 B).
+  const uniformBufRes = device.createBuffer({
+    label: 'hdrp-ssao-uniform',
+    size: UNIFORM_BYTES,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!uniformBufRes.ok) {
+    runtime.errorRegistry.fire(uniformBufRes.error);
+    return null;
+  }
+
+  const buffers: SsaoBuffers = {
+    kernelBuffer: kernelBufferRes.value,
+    kernelBytes: SSAO_KERNEL_SAMPLE_COUNT * BYTES_PER_KERNEL_ELEMENT,
+    noiseTexture: noiseTexRes.value,
+    uniformBuffer: uniformBufRes.value,
+    uniformBytes: UNIFORM_BYTES,
+  };
+
+  cache.set(runtime, buffers);
+  return buffers;
+}

package/src/ssao-config.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-render - SSAO parameter authority.
+
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { PostProcessError } from './post-process-errors';
+
+export const SSAO_DEFAULT_RADIUS = 0.5;
+export const SSAO_DEFAULT_BIAS = 0.025;
+export const SSAO_DEFAULT_INTENSITY = 1.0;
+
+export interface SsaoParameterConfig {
+  readonly radius?: number | undefined;
+  readonly bias?: number | undefined;
+  readonly intensity?: number | undefined;
+}
+
+export interface ResolvedSsaoParameters {
+  readonly radius: number;
+  readonly bias: number;
+  readonly intensity: number;
+}
+
+/**
+ * Apply the public defaults without deciding whether the values are valid.
+ * The record stage uses this only after the graph build has validated the
+ * active HDRP configuration, or for the disabled/default fallback payload.
+ */
+export function getSsaoParameters(config: SsaoParameterConfig | undefined): ResolvedSsaoParameters {
+  return {
+    radius: config?.radius ?? SSAO_DEFAULT_RADIUS,
+    bias: config?.bias ?? SSAO_DEFAULT_BIAS,
+    intensity: config?.intensity ?? SSAO_DEFAULT_INTENSITY,
+  };
+}
+
+/**
+ * Resolve and validate the SSAO configuration used by both graph routes.
+ * Invalid values remain structured PostProcessErrors instead of becoming
+ * NaNs or silently falling back to shader literals.
+ */
+export function resolveSsaoParameters(
+  config: SsaoParameterConfig | undefined,
+): Result<ResolvedSsaoParameters, PostProcessError> {
+  const resolved = getSsaoParameters(config);
+  if (resolved.radius <= 0) {
+    return err(
+      new PostProcessError({
+        code: 'ssao-radius-non-positive',
+        detail: { paramName: 'radius', value: resolved.radius },
+      }),
+    );
+  }
+  if (resolved.bias < 0) {
+    return err(
+      new PostProcessError({
+        code: 'ssao-bias-negative',
+        detail: { paramName: 'bias', value: resolved.bias },
+      }),
+    );
+  }
+  return ok(resolved);
+}