@forgeax/engine-render 0.1.2

package/src/record/view-ubo.ts

@@ -0,0 +1,206 @@
+// @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 {
+  CameraSnapshot,
+  DirectionalLightSnapshot,
+  ExtractedLights,
+  FogSnapshot,
+  SpotLightSnapshot,
+} from '../render-system-extract';
+import type { TemporalView } from '../temporal-view';
+import { clampPcfKernelSize } from './frame-snapshot';
+import { computeProjectionMatrix, computeViewMatrix } from './helpers';
+
+export const VIEW_UNIFORM_BYTES = 960;
+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);
+}
+
+/**
+ * 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[],
+  temporalView?: TemporalView,
+  fog?: FogSnapshot,
+): void {
+  // Compose worldViewProj once per frame (view * proj).
+  const projMatrix = computeProjectionMatrix(camera);
+  const viewMatrix = computeViewMatrix(camera);
+  const unjitteredViewProjection = mat4.create();
+  mat4.multiply(unjitteredViewProjection, projMatrix, viewMatrix);
+  const worldViewProj = temporalView?.currentJitteredViewProjection ?? unjitteredViewProjection;
+
+  const VIEW_PAYLOAD_FLOATS = 240;
+  const viewPayload = new Float32Array(VIEW_PAYLOAD_FLOATS);
+  for (let i = 0; i < 16; i++) viewPayload[i] = (worldViewProj as unknown as number[])[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, unjitteredViewProjection);
+  for (let i = 0; i < 16; i++)
+    viewPayload[44 + i] = (inverseViewProj as unknown as number[])[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 currentTemporalViewProjection =
+    temporalView?.currentUnjitteredViewProjection ?? unjitteredViewProjection;
+  const previousTemporalViewProjection =
+    temporalView?.previousUnjitteredViewProjection ?? currentTemporalViewProjection;
+  for (let index = 0; index < 16; index += 1) {
+    viewPayload[196 + index] = currentTemporalViewProjection[index] ?? 0;
+    viewPayload[212 + index] = previousTemporalViewProjection[index] ?? 0;
+  }
+  viewPayload[228] = camera.near;
+  viewPayload[229] = camera.far;
+  viewPayload[230] = camera.projection === 'orthographic' ? 1 : 0;
+
+  // Fog shares the existing View uniform slot. The two vec4-aligned lanes
+  // start after the temporal projection facts: xyz + density, then
+  // heightFalloff + maxOpacity and two zero padding lanes. An absent snapshot
+  // leaves the payload disabled without allocating another GPU resource.
+  if (fog !== undefined) {
+    viewPayload[232] = fog.color[0] ?? 0;
+    viewPayload[233] = fog.color[1] ?? 0;
+    viewPayload[234] = fog.color[2] ?? 0;
+    viewPayload[235] = fog.density;
+    viewPayload[236] = fog.heightFalloff;
+    viewPayload[237] = fog.maxOpacity;
+  }
+
+  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;
+    }
+  }
+}

package/src/render-data.ts

@@ -0,0 +1,385 @@
+// @forgeax/engine-runtime - RenderData projection layer
+// (feat-20260601-gpu-resource-store-extraction M2 / w5).
+//
+// The middle of the three GPU-asset layers: AssetRegistry catalogues CPU asset
+// POD; `deriveRenderData*` PROJECTS a POD into the GPU descriptor a resource
+// build needs; GpuResourceStore owns device-side resource life/death. These
+// projections are PURE -- they know the asset `kind` but never touch a device
+// (AC-07). The store consumes the descriptor and does the createTexture /
+// createBuffer / writeX work.
+//
+// Coverage is exactly the three GPU-resource kinds (mesh / texture / equirect,
+// the latter projected to a cubemap). Asset kinds with no GPU residency are
+// never projected -- the
+// `ensureResident` miss switch dispatches per-kind with no default, so a fourth
+// GPU-resource kind would surface as a `tsc -b` exhaustiveness error at the
+// switch rather than a silent fallthrough (AC-06).
+
+import {
+  bytesPerRow as blockBytesPerRow,
+  blockParamsForFormat,
+  isCompressedFormat,
+} from '@forgeax/engine-codec';
+import {
+  deriveVertexLayoutProjection,
+  type VertexLayoutProjection,
+} from '@forgeax/engine-geometry';
+import { err, ok, type Result } from '@forgeax/engine-rhi';
+import {
+  ASSET_ERROR_HINTS,
+  type AssetError,
+  type MeshAsset,
+  type Submesh,
+  type TextureAsset,
+} from '@forgeax/engine-types';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from './gpu-texture-usage';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_VERTEX,
+} from './gpu-usage';
+import { numMipLevels } from './mipmap-generator';
+
+// AssetError without importing AssetRegistry: build the 4-field surface
+// (.code / .expected / .hint) directly against the @forgeax/engine-types SSOT
+// (charter P5 producer / consumer split; mirrors the store's RuntimeAssetError).
+class ProjectionAssetError extends Error implements AssetError {
+  readonly code: AssetError['code'];
+  readonly expected: string;
+  readonly hint: string;
+  constructor(fields: { code: AssetError['code']; expected: string; hint: string }) {
+    super(`[AssetError ${fields.code}] expected: ${fields.expected}; hint: ${fields.hint}`);
+    this.name = 'AssetError';
+    this.code = fields.code;
+    this.expected = fields.expected;
+    this.hint = fields.hint;
+  }
+}
+
+function projectionError(fields: {
+  code: AssetError['code'];
+  expected: string;
+  hint: string;
+}): AssetError {
+  return new ProjectionAssetError(fields);
+}
+
+/** Descriptor for a mesh's GPU vertex + index buffers (projected from POD). */
+export interface MeshRenderData {
+  readonly vertexByteLength: number;
+  /** Geometry-owned immutable layout facts used by all GPU consumers. */
+  readonly layoutProjection: VertexLayoutProjection;
+  /** Index byte length padded up to a 4-byte multiple (writeBuffer alignment). */
+  readonly indexByteLength: number;
+  readonly indexCount: number;
+  readonly indexFormat: 'uint16' | 'uint32';
+  readonly vertexUsage: number;
+  readonly indexUsage: number;
+  /**
+   * Submeshes from the source MeshAsset, projected verbatim to the GPU store
+   * so the record stage can iterate per-submesh draw calls (feat-20260608 M4 / w16).
+   * Mirrors MeshAsset.submeshes (readonly Submesh[]) 1:1.
+   */
+  readonly submeshes: readonly Submesh[];
+}
+
+/** Descriptor for a 2D texture's GPU resource (projected from POD). */
+export interface TextureRenderData {
+  /** Logical width retained for existing projection consumers. */
+  readonly width: number;
+  /** Logical height retained for existing projection consumers. */
+  readonly height: number;
+  /** Authored content extent; TextureAsset remains the logical asset SSOT. */
+  readonly logicalExtent: TextureExtent;
+  /** GPU allocation extent, derived from format + logicalExtent. */
+  readonly physicalExtent: TextureExtent;
+  /** Maps logical UVs away from block padding. */
+  readonly uvScale: readonly [number, number];
+  readonly format: GPUTextureFormat;
+  readonly mipLevelCount: number;
+  readonly usage: number;
+  /**
+   * Row pitch for the BASE mip (level 0) the store passes to `writeTexture`.
+   * Uncompressed: `width * 4` (RGBA8). Block-compressed: the block-padded
+   * `ceil(width / blockW) * bytesPerBlock` (feat-20260707 M5 / w35, AC-08).
+   * The per-mip layout for a multi-level compressed upload comes from
+   * {@link deriveMipUploadLayout}.
+   */
+  readonly bytesPerRow: number;
+  /** True iff `format` is a block-compressed format (drives the store's upload arm). */
+  readonly compressed: boolean;
+}
+
+export interface TextureExtent {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The sole logical-content to physical-storage projection for a texture.
+ * Block sizes come from codec's format table; no physical dimensions are
+ * authored or serialized with TextureAsset.
+ */
+export function deriveTextureExtent(
+  format: GPUTextureFormat,
+  width: number,
+  height: number,
+): {
+  readonly logicalExtent: TextureExtent;
+  readonly physicalExtent: TextureExtent;
+  readonly uvScale: readonly [number, number];
+} {
+  const params = blockParamsForFormat(format);
+  const physicalWidth = params === null ? width : Math.ceil(width / params.blockW) * params.blockW;
+  const physicalHeight =
+    params === null ? height : Math.ceil(height / params.blockH) * params.blockH;
+  return {
+    logicalExtent: { width, height },
+    physicalExtent: { width: physicalWidth, height: physicalHeight },
+    uvScale: [width / physicalWidth, height / physicalHeight],
+  };
+}
+
+/** One mip level's GPU-upload layout (feat-20260707 M5 / w35, AC-08). */
+export interface MipUploadLevel {
+  /** Mip level index (0 = base / largest). */
+  readonly level: number;
+  /** Logical pixel width of this level (`baseWidth >> level`, min 1). */
+  readonly width: number;
+  /** Logical pixel height of this level (`baseHeight >> level`, min 1). */
+  readonly height: number;
+  /** Block-aligned storage dimensions for this logical mip. */
+  readonly physicalWidth: number;
+  readonly physicalHeight: number;
+  /** Logical `writeTexture` copy width; full-subresource copies may end mid-block. */
+  readonly copyWidth: number;
+  /** Logical `writeTexture` copy height; full-subresource copies may end mid-block. */
+  readonly copyHeight: number;
+  /** Bytes per compressed row: `ceil(width / blockW) * bytesPerBlock`. */
+  readonly bytesPerRow: number;
+  /** Block rows: `ceil(height / blockH)` (the writeTexture `rowsPerImage`). */
+  readonly rowsPerImage: number;
+  /** Byte offset of this level in the mip-major payload (sum of prior levels). */
+  readonly byteOffset: number;
+  /** Byte length of this level (`bytesPerRow * rowsPerImage`). */
+  readonly byteLength: number;
+}
+
+/**
+ * Derive the per-mip GPU-upload layout for a block-compressed texture
+ * (feat-20260707 M5 / w35, AC-08). Each level pads the pixel width up to a full
+ * block (`ceil(width / blockW) * bytesPerBlock`) and counts block rows
+ * (`ceil(height / blockH)`); `byteOffset` accumulates the prior levels' byte
+ * lengths (mip-major layout). The GPU samples only the valid texel region, so a
+ * non-4-multiple size or a 1x1 / 2x2 mip tail pads up to a block without image
+ * corruption (t5). Block math is sourced from the codec block table (SSOT --
+ * Derive, Don't Duplicate); TextureAsset carries no block fields (F-6).
+ *
+ * `format` must be a block-compressed format; callers branch on the projection's
+ * `compressed` flag first (the uncompressed path uses the linear `width * 4`
+ * pitch). Level dimensions floor-halve per mip, clamped to a 1-pixel minimum.
+ */
+export function deriveMipUploadLayout(
+  format: GPUTextureFormat,
+  baseWidth: number,
+  baseHeight: number,
+  mipLevelCount: number,
+): readonly MipUploadLevel[] {
+  const params = blockParamsForFormat(format);
+  if (params === null) return [];
+  const levels: MipUploadLevel[] = [];
+  let byteOffset = 0;
+  for (let level = 0; level < mipLevelCount; level++) {
+    const width = Math.max(1, baseWidth >> level);
+    const height = Math.max(1, baseHeight >> level);
+    const blockCols = Math.ceil(width / params.blockW);
+    const blockRows = Math.ceil(height / params.blockH);
+    const rowBytes = blockCols * params.bytesPerBlock;
+    const byteLength = rowBytes * blockRows;
+    levels.push({
+      level,
+      width,
+      height,
+      physicalWidth: blockCols * params.blockW,
+      physicalHeight: blockRows * params.blockH,
+      copyWidth: blockCols * params.blockW,
+      copyHeight: blockRows * params.blockH,
+      bytesPerRow: rowBytes,
+      rowsPerImage: blockRows,
+      byteOffset,
+      byteLength,
+    });
+    byteOffset += byteLength;
+  }
+  return levels;
+}
+
+/** Descriptor for a cubemap built from an equirect source (projected from POD). */
+export interface CubeRenderData {
+  /** Square cube face edge length (== source equirect height). */
+  readonly cubeFaceSize: number;
+  /** Filterable output format the IBL pipeline BGL expects. */
+  readonly outputFormat: 'rgba16float';
+  /** True when the source is rgba32float and the store must pack to rgba16float. */
+  readonly needsHalfConversion: boolean;
+  readonly cubeUsage: number;
+}
+
+/**
+ * Project a `MeshAsset` POD into its GPU vertex / index buffer descriptor.
+ * Pure: computes byte lengths, the 4-byte-aligned index size, index format,
+ * and the buffer usage flags the store's `createBuffer` calls need.
+ */
+export function deriveRenderDataMesh(mesh: MeshAsset): Result<MeshRenderData, AssetError> {
+  // Vertex-only meshes (no `indices`) take the non-indexed draw path. Their
+  // index-side fields are zeroed; `indexFormat` keeps a `'uint16'` placeholder
+  // (never consumed when no index buffer is built).
+  const indices = mesh.indices;
+  const indexBytesUnpadded = indices === undefined ? 0 : indices.byteLength;
+  const indexByteLength = ((indexBytesUnpadded + 3) >> 2) << 2;
+  const layoutProjection = deriveVertexLayoutProjection(mesh.attributes);
+  return ok({
+    vertexByteLength: mesh.vertices.byteLength,
+    layoutProjection,
+    indexByteLength,
+    indexCount: indices === undefined ? 0 : indices.length,
+    indexFormat: indices instanceof Uint32Array ? 'uint32' : 'uint16',
+    vertexUsage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+    indexUsage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
+    submeshes: mesh.submeshes,
+  });
+}
+
+/**
+ * Project a `TextureAsset` POD into its GPU texture descriptor. Pure: derives
+ * the mip-level count (when `mipmap`), the row pitch, and the usage flags, and
+ * fails fast if the POD's `format` and `colorSpace` are internally
+ * inconsistent (a `-srgb` format requires an `srgb` colorSpace and vice versa).
+ */
+export function deriveRenderDataTexture(tex: TextureAsset): Result<TextureRenderData, AssetError> {
+  const isSrgbFormat = tex.format.endsWith('-srgb');
+  const expectedColorSpace: 'srgb' | 'linear' = isSrgbFormat ? 'srgb' : 'linear';
+  if (tex.colorSpace !== expectedColorSpace) {
+    return err(
+      projectionError({
+        code: 'invalid-source-format',
+        expected: "format ends in '-srgb' iff colorSpace is 'srgb' (linear otherwise)",
+        hint: ASSET_ERROR_HINTS['invalid-source-format'],
+      }),
+    );
+  }
+
+  const compressed = isCompressedFormat(tex.format);
+  // feat-20260707 M5 / w35 (AC-09, D-9): a block-compressed texture cannot have
+  // its mips GPU-generated (F-7). An OFFLINE chain baked into `data`
+  // (mipLevelCount > 1, e.g. a KTX2 level chain) is the normal compressed path
+  // and passes; requesting RUNTIME mip generation (`mipmap:true` with no offline
+  // chain) fails fast with a self-recovery hint (fail-fast at the projection
+  // layer -- producer self-validate).
+  const hasOfflineMipChain = (tex.mipLevelCount ?? 1) > 1;
+  if (compressed && tex.mipmap === true && !hasOfflineMipChain) {
+    return err(
+      projectionError({
+        code: 'mipgen-unsupported-compressed-format',
+        expected:
+          'a compressed texture requesting mipmap:true must carry an offline mip chain (mipLevelCount > 1)',
+        hint: ASSET_ERROR_HINTS['mipgen-unsupported-compressed-format'],
+      }),
+    );
+  }
+
+  // Uncompressed: runtime mip-gen count from the pixel size. Compressed: the
+  // level count is authored (offline chain) -- honour the POD's mipLevelCount,
+  // never re-derive it from the size (a compressed chain may stop early).
+  const mipLevelCount = compressed
+    ? Math.max(1, tex.mipLevelCount ?? 1)
+    : tex.mipmap
+      ? numMipLevels(tex)
+      : 1;
+
+  const uncompressedBytesPerTexel =
+    tex.format === 'rgba32float' ? 16 : tex.format === 'rgba16float' ? 8 : 4;
+  if (!compressed && tex.data.byteLength < tex.width * tex.height * uncompressedBytesPerTexel) {
+    return err(
+      projectionError({
+        code: 'invalid-source-format',
+        expected: 'uncompressed texture data contains at least one complete base mip',
+        hint: ASSET_ERROR_HINTS['invalid-source-format'],
+      }),
+    );
+  }
+
+  // Compressed rows derive from block format. Uncompressed row pitch derives
+  // from the format, not aggregate payload length: imported images may retain
+  // trailing decoder bytes and offline mip chains contain more than the base mip.
+  const bytesPerRow = compressed
+    ? (blockBytesPerRow(tex.format, tex.width) ?? tex.width * 4)
+    : tex.width * uncompressedBytesPerTexel;
+
+  // Compressed formats are not renderable -- RENDER_ATTACHMENT would fail
+  // createTexture validation, and the runtime mipmap blit (which needs it) never
+  // runs on a compressed texture anyway (the mip gate above rules out runtime
+  // mip-gen). Both paths keep COPY_SRC so a real consumer can validate the
+  // uploaded texture through the standard GPU readback contract.
+  const usage = compressed
+    ? GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_COPY_SRC
+    : GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING |
+      GPU_TEXTURE_USAGE_COPY_DST |
+      GPU_TEXTURE_USAGE_COPY_SRC;
+
+  return ok({
+    width: tex.width,
+    height: tex.height,
+    ...deriveTextureExtent(tex.format, tex.width, tex.height),
+    format: tex.format,
+    mipLevelCount,
+    usage,
+    bytesPerRow,
+    compressed,
+  });
+}
+
+/**
+ * Project an equirectangular HDR `TextureAsset` source into its cubemap
+ * descriptor. Pure: validates the source is a linear HDR format, computes the
+ * square cube face size (== source height), narrows the output to the filterable
+ * `rgba16float` the IBL pipeline expects, and flags whether the store must pack
+ * an rgba32float source down to rgba16float. The store keeps the resource build
+ * (createTexture / cube + face views / IBL precompute) and the rgba32f->rgba16f
+ * byte conversion.
+ *
+ * feat-20260707 M5 fix: the accepted-format whitelist is `rgba16float |
+ * rgba32float` only -- a block-compressed HDR format (`bc6h-rgb-ufloat`) is NOT
+ * accepted here. An equirect cube source drives equirect-to-cube / irradiance /
+ * prefilter RENDER passes, and a BC6H texture is sample-only, never a color-
+ * renderable render target ("BC6HRGBUfloat is not color renderable"). The
+ * equirect is therefore always delivered uncompressed rgba16float; this
+ * fail-fast whitelist is the projection-layer guard that rejects a non-
+ * renderable cube source rather than letting it blow up at GPU createTexture.
+ */
+export function deriveRenderDataCubemap(source: TextureAsset): Result<CubeRenderData, AssetError> {
+  const isAcceptedHdr = source.format === 'rgba16float' || source.format === 'rgba32float';
+  if (!isAcceptedHdr || source.colorSpace !== 'linear') {
+    return err(
+      projectionError({
+        code: 'invalid-source-format',
+        expected: "format 'rgba16float' or 'rgba32float' with colorSpace 'linear'",
+        hint: ASSET_ERROR_HINTS['invalid-source-format'],
+      }),
+    );
+  }
+  return ok({
+    cubeFaceSize: source.height,
+    outputFormat: 'rgba16float',
+    needsHalfConversion: source.format === 'rgba32float',
+    cubeUsage:
+      GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING |
+      GPU_TEXTURE_USAGE_COPY_DST |
+      GPU_TEXTURE_USAGE_COPY_SRC,
+  });
+}