@forgeax/engine-render 0.1.19 → 0.1.21

package/src/components/light-helpers.ts

@@ -17,12 +17,17 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { SpawnLightInvalidBoundsError } from '../errors/ecs-validation';
 import { ShadowInvalidConfigError } from '../errors/render';
+import { DirectionalShadowFilterValue } from './directional-shadow-filter';
 
 export type LightValidationError = SpawnLightInvalidBoundsError | ShadowInvalidConfigError;
 export type LightValidationResult = Result<void, LightValidationError>;
 
 const RANGE_ZERO_FALLBACK_INV_R2 = 1e8;
 const DEG_TO_RAD = Math.PI / 180;
+const PCSS_RADIUS_MIN = 0.0001;
+const PCSS_RADIUS_MAX = 0.05;
+const PCSS_PENUMBRA_MIN = 1;
+const PCSS_PENUMBRA_MAX = 64;
 
 /**
  * Convert SpotLight cone half-angle (degrees) to its cosine.
@@ -97,7 +102,9 @@ export function validateDirectionalLightData(
   if (data.castShadow === false) return ok(undefined);
 
   const mapSize = (data.mapSize as number | undefined) ?? 2048;
-  if (mapSize < 1) return err(new ShadowInvalidConfigError('mapSize', mapSize, 1));
+  if (mapSize < 1) {
+    return err(new ShadowInvalidConfigError('mapSize', mapSize, 1));
+  }
   const cascadeCount = (data.cascadeCount as number | undefined) ?? 4;
   if (cascadeCount < 1 || cascadeCount > 4 || !Number.isInteger(cascadeCount)) {
     return err(new ShadowInvalidConfigError('cascadeCount', cascadeCount, 1, 4));
@@ -110,14 +117,65 @@ export function validateDirectionalLightData(
   if (cascadeBlend < 0 || cascadeBlend > 0.5) {
     return err(new ShadowInvalidConfigError('cascadeBlend', cascadeBlend, 0, 0.5));
   }
-  const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
-  if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
-    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
-  }
   const shadowDistance = (data.shadowDistance as number | undefined) ?? 200;
   if (shadowDistance <= 0) {
     return err(new ShadowInvalidConfigError('shadowDistance', shadowDistance, 0, '>'));
   }
+  const shadowFilter =
+    (data.shadowFilter as number | undefined) ?? DirectionalShadowFilterValue.pcf3;
+  const allowedFilters = Object.values(DirectionalShadowFilterValue);
+  if (!Number.isFinite(shadowFilter) || !allowedFilters.includes(shadowFilter as never)) {
+    return err(
+      new ShadowInvalidConfigError(
+        'shadowFilter',
+        shadowFilter,
+        { kind: 'allowed-values', values: allowedFilters },
+        undefined,
+        'one of [pcf1, pcf3, pcf5, pcssMedium, pcssHigh]',
+      ),
+    );
+  }
+  if (
+    shadowFilter === DirectionalShadowFilterValue.pcssMedium ||
+    shadowFilter === DirectionalShadowFilterValue.pcssHigh
+  ) {
+    const shadowAngularRadius = (data.shadowAngularRadius as number | undefined) ?? 0.00465;
+    if (!Number.isFinite(shadowAngularRadius)) {
+      return err(
+        new ShadowInvalidConfigError('shadowAngularRadius', shadowAngularRadius, {
+          kind: 'range',
+          min: PCSS_RADIUS_MIN,
+          max: PCSS_RADIUS_MAX,
+        }),
+      );
+    }
+    if (shadowAngularRadius < PCSS_RADIUS_MIN || shadowAngularRadius > PCSS_RADIUS_MAX) {
+      return err(
+        new ShadowInvalidConfigError('shadowAngularRadius', shadowAngularRadius, {
+          kind: 'range',
+          min: PCSS_RADIUS_MIN,
+          max: PCSS_RADIUS_MAX,
+        }),
+      );
+    }
+    const maxPenumbraTexels = (data.maxPenumbraTexels as number | undefined) ?? 32;
+    if (
+      !Number.isFinite(maxPenumbraTexels) ||
+      !Number.isInteger(maxPenumbraTexels) ||
+      maxPenumbraTexels < PCSS_PENUMBRA_MIN ||
+      maxPenumbraTexels > PCSS_PENUMBRA_MAX
+    ) {
+      return err(
+        new ShadowInvalidConfigError(
+          'maxPenumbraTexels',
+          maxPenumbraTexels,
+          { kind: 'range', min: PCSS_PENUMBRA_MIN, max: PCSS_PENUMBRA_MAX },
+          undefined,
+          'a finite integer in [1, 64]',
+        ),
+      );
+    }
+  }
   return ok(undefined);
 }
 
@@ -153,7 +211,19 @@ export function validateSpotLightData(
   }
   const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
   if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
-    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
+    return err(
+      new ShadowInvalidConfigError(
+        'pcfKernelSize',
+        pcfKernelSize,
+        { kind: 'lower-bound', operator: '>=', value: 1 },
+        undefined,
+        'an odd integer >= 1',
+      ),
+    );
+  }
+  const shadowIntensity = (data.shadowIntensity as number | undefined) ?? 1;
+  if (!Number.isFinite(shadowIntensity) || shadowIntensity < 0 || shadowIntensity > 1) {
+    return err(new ShadowInvalidConfigError('shadowIntensity', shadowIntensity, 0, 1));
   }
   return ok(undefined);
 }
@@ -182,7 +252,15 @@ export function validatePointLightShadowData(
   }
   const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
   if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
-    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
+    return err(
+      new ShadowInvalidConfigError(
+        'pcfKernelSize',
+        pcfKernelSize,
+        { kind: 'lower-bound', operator: '>=', value: 1 },
+        undefined,
+        'an odd integer >= 1',
+      ),
+    );
   }
   return ok(undefined);
 }

package/src/components/reflection-probe.ts

@@ -0,0 +1,49 @@
+// @forgeax/engine-render - local reflection probe vocabulary.
+//
+// A ReflectionProbe is an ECS authoring fact. The renderer owns its six-face
+// capture, PMREM output, box selection, and Skylight fallback; this component
+// never carries a GPU handle or an authored material reference.
+
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { RenderIntentInvalidError } from '../errors/render';
+
+export const REFLECTION_PROBE_UPDATE_ONCE = 0;
+export const REFLECTION_PROBE_UPDATE_ON_CHANGE = 1;
+export const REFLECTION_PROBE_UPDATE_CONTINUOUS = 2;
+
+export type ReflectionProbeUpdateIntent = 'once' | 'on-change' | 'continuous';
+
+export function reflectionProbeUpdateIntentFromF32(value: number): ReflectionProbeUpdateIntent {
+  switch (value) {
+    case REFLECTION_PROBE_UPDATE_ONCE:
+      return 'once';
+    case REFLECTION_PROBE_UPDATE_ON_CHANGE:
+      return 'on-change';
+    case REFLECTION_PROBE_UPDATE_CONTINUOUS:
+      return 'continuous';
+    default:
+      throw new RenderIntentInvalidError('ReflectionProbe', value);
+  }
+}
+
+export function reflectionProbeUpdateIntentToF32(intent: ReflectionProbeUpdateIntent): number {
+  switch (intent) {
+    case 'once':
+      return REFLECTION_PROBE_UPDATE_ONCE;
+    case 'on-change':
+      return REFLECTION_PROBE_UPDATE_ON_CHANGE;
+    case 'continuous':
+      return REFLECTION_PROBE_UPDATE_CONTINUOUS;
+  }
+}
+
+export const ReflectionProbe = defineComponent('ReflectionProbe', {
+  halfExtents: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  priority: { type: 'f32', default: 0 },
+  intensity: { type: 'f32', default: 1 },
+  resolution: { type: 'u32', default: 256 },
+  updateIntent: { type: 'f32', default: REFLECTION_PROBE_UPDATE_ONCE },
+  invalidationVersion: { type: 'u32', default: 0 },
+});
+
+export type ReflectionProbeData = ShapeOf<SchemaOf<typeof ReflectionProbe>>;

package/src/components/spot-light.ts

@@ -21,8 +21,8 @@
 // spotCount === 0" (M5 / w25).
 //
 // feat-20260625-spot-light-shadow-mapping M1 w4: embedded castShadow (default true)
-// + 6 shadow fields (mapSize / depthBias / normalBias / nearPlane / farPlane /
-// pcfKernelSize) aligned with DirectionalLight vocabulary (plan-strategy D-6;
+// + 7 shadow fields (mapSize / depthBias / normalBias / nearPlane / farPlane /
+// pcfKernelSize / shadowIntensity) aligned with DirectionalLight vocabulary (plan-strategy D-6;
 // charter P4 consistent abstraction). Zero-config spawns cast spot shadows;
 // set castShadow:false to opt out (validate short-circuits on false, AC-03).
 // Shadow atlas cap of 4 is enforced at extract stage, not component layer (OOS-5).
@@ -37,6 +37,17 @@
 
 import { defineComponent } from '@forgeax/engine-ecs';
 
+export interface SpotLightProjector {
+  readonly guid: string;
+  readonly generation: number;
+  readonly revision: number;
+}
+
+export interface SpotLightAuthoring {
+  /** Optional GUID-backed TextureAsset projector; absent keeps the normal spot path. */
+  readonly projector?: SpotLightProjector;
+}
+
 /**
  * Cone-restricted spot light (KHR_lights_punctual `spot` type).  Casts shadows
  * by default (castShadow defaults to true) — zero-config spawns project hard
@@ -71,6 +82,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   nearPlane                        — shadow-camera near (default 0.1)
  *   farPlane                         — shadow-camera far (default 50)
  *   pcfKernelSize odd >= 1           — PCF kernel width (default 3)
+ *   shadowIntensity in [0,1]         — residual light in shadow (default 1)
  *
  * Atlas capacity is capped at 4 castShadow spot lights by the extract stage;
  * the 5th light onward keeps direct illumination but shadowAtlasTile = -1
@@ -114,11 +126,18 @@ export const SpotLight = defineComponent('SpotLight', {
   outerConeDeg: { type: 'f32', default: 45 },
   // Shadow opt-out gate: defaults to true so zero-config spawns cast shadows.
   castShadow: { type: 'bool', default: true },
-  // 6 shadow fields aligned with DirectionalLight (plan-strategy D-6).
+  // 7 shadow fields aligned with the shared light shadow vocabulary.
   mapSize: { type: 'f32', default: 2048 },
   depthBias: { type: 'f32', default: 0.005 },
   normalBias: { type: 'f32', default: 0.05 },
   nearPlane: { type: 'f32', default: 0.1 },
   farPlane: { type: 'f32', default: 50 },
   pcfKernelSize: { type: 'f32', default: 3 },
+  // Three's SpotLight.shadow.intensity is the fraction of visibility applied
+  // to a shadowed contribution. Keep it in the author-facing [0,1] domain;
+  // extract/record transport this one fact to surface and volume consumers.
+  shadowIntensity: { type: 'f32', default: 1 },
+  // Shared TextureAsset identity; publication and residency remain owned by
+  // the existing asset and GPU resource owners.
+  projector: { type: 'shared<TextureAsset>', simulationTransient: true },
 });

package/src/device/gpu-residency.ts

@@ -60,6 +60,7 @@ import {
   type AssetError,
   countExtraUvSets,
   type DecodedImage,
+  deriveTextureLayout,
   type EquirectAsset,
   type Handle,
   handleSlot,
@@ -72,6 +73,7 @@ import {
   type SamplerAsset,
   type Submesh,
   type TextureAsset,
+  type TextureShape,
   type MeshAsset as TypesMeshAsset,
   toShared,
 } from '@forgeax/engine-types';
@@ -98,7 +100,6 @@ import {
 import type { RhiErrorListenerRegistry } from '../lifecycle';
 import {
   type CubeRenderData,
-  deriveMipUploadLayout,
   deriveRenderDataCubemap,
   deriveRenderDataMesh,
   deriveRenderDataTexture,
@@ -281,10 +282,25 @@ type RegisterCube = (
 // not destroyable on their own; their lifetime is bound to the parent
 // GpuTexture, which the wrapper owns. destroyAll() walks the GpuResource
 // fields and forwards .destroy() to the RHI shim.
-interface TextureGpuEntry {
+export interface TextureResidencyReceipt {
+  readonly shape: TextureShape;
+  readonly format: GPUTextureFormat;
+  readonly extent: {
+    readonly width: number;
+    readonly height: number;
+    readonly depthOrArrayLayers: number;
+  };
+  readonly bytes: number;
+  readonly view: '2d' | '2d-array' | '3d';
+  readonly generation: number;
+  readonly deviceEpoch: number;
+}
+
+export interface TextureGpuEntry {
   readonly texture: GpuTexture;
   /** Opaque RHI view handle; lifetime is bound to the parent texture. */
   readonly view: TextureView;
+  readonly receipt: TextureResidencyReceipt;
 }
 
 // feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M2 / w11
@@ -388,6 +404,8 @@ export class GpuResidencyCache {
   // Hardware-probe caps injected at `configureGpuDevice`; guards the HDR cubemap
   // path (_uploadCubemapFromEquirect) when `rgba16floatRenderable` is false.
   private caps: RhiCaps | undefined = undefined;
+  private deviceEpoch = 0;
+  private textureGeneration = 0;
 
   private readonly textureGpuHandles: Map<string | number, TextureGpuEntry> = new Map();
   private readonly samplerGpuHandles: Map<string | number, Sampler> = new Map();
@@ -432,6 +450,12 @@ export class GpuResidencyCache {
     registerCube: RegisterCube,
     caps: RhiCaps,
   ): void {
+    for (const entry of this.textureGpuHandles.values()) {
+      if (!entry.texture.isDestroyed) entry.texture.destroy();
+    }
+    if (this.textureGpuHandles.size > 0) this.materialResourceEpoch += 1;
+    this.textureGpuHandles.clear();
+    this.deviceEpoch += 1;
     this.meshResidencyEpoch += 1;
     this.gpuDevice = device;
     this.asyncCreateShaderModule = asyncCreateShaderModule;
@@ -997,7 +1021,7 @@ export class GpuResidencyCache {
     const cacheKey = this.worldKey(handleSlot(handle), worldId);
     if (gpuTexture === undefined) return ok(undefined);
 
-    if (!projected.value.compressed && decoded.mipmap === true && levels > 1) {
+    if (!projected.value.compressed && tex.mips.kind === 'generate' && levels > 1) {
       const factory = this.asyncCreateShaderModule;
       if (factory === undefined) {
         return err(
@@ -1020,8 +1044,8 @@ export class GpuResidencyCache {
       }
       const blitRes = blitMipmapsSync(device, gpuTexture, {
         format: tex.format,
-        width: tex.width,
-        height: tex.height,
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
         levels,
       });
       if (!blitRes.ok) return blitRes as Result<void, RhiError>;
@@ -1029,13 +1053,14 @@ export class GpuResidencyCache {
 
     const viewRes = device.createTextureView(gpuTexture, {
       label: `texture-view-${cacheKey}`,
-      dimension: '2d',
+      dimension: projected.value.shape.viewDimension,
     });
     if (!viewRes.ok) return viewRes;
     const previous = this.textureGpuHandles.get(cacheKey);
-    const next = {
+    const next: TextureGpuEntry = {
       texture: this.wrapTex(gpuTexture),
       view: viewRes.value,
+      receipt: this.textureReceipt(pod, projected.value),
     };
     this.textureGpuHandles.set(cacheKey, next);
     this.materialResourceEpoch += 1;
@@ -1077,11 +1102,11 @@ export class GpuResidencyCache {
     const { tex, levels, gpuTexture } = prepared.value;
     const cacheKey = this.worldKey(handleSlot(handle), worldId);
 
-    if (!renderData.compressed && decoded.mipmap === true && levels > 1) {
+    if (!renderData.compressed && tex.mips.kind === 'generate' && levels > 1) {
       const blitRes = blitMipmapsSync(device, gpuTexture, {
         format: tex.format,
-        width: tex.width,
-        height: tex.height,
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
         levels,
       });
       if (!blitRes.ok) return blitRes as Result<TextureGpuEntry, RhiError>;
@@ -1089,10 +1114,14 @@ export class GpuResidencyCache {
 
     const viewRes = device.createTextureView(gpuTexture, {
       label: `texture-view-${cacheKey}`,
-      dimension: '2d',
+      dimension: renderData.shape.viewDimension,
     });
     if (!viewRes.ok) return viewRes;
-    const entry: TextureGpuEntry = { texture: this.wrapTex(gpuTexture), view: viewRes.value };
+    const entry: TextureGpuEntry = {
+      texture: this.wrapTex(gpuTexture),
+      view: viewRes.value,
+      receipt: this.textureReceipt(pod, renderData),
+    };
     const previous = this.textureGpuHandles.get(cacheKey);
     this.textureGpuHandles.set(cacheKey, entry);
     this.materialResourceEpoch += 1;
@@ -1106,6 +1135,25 @@ export class GpuResidencyCache {
     return ok(entry);
   }
 
+  private textureReceipt(
+    pod: TextureAsset,
+    renderData: TextureRenderData,
+  ): TextureResidencyReceipt {
+    return {
+      shape: pod.shape,
+      format: renderData.format,
+      extent: {
+        width: renderData.physicalExtent.width,
+        height: renderData.physicalExtent.height,
+        depthOrArrayLayers: renderData.depthOrArrayLayers,
+      },
+      bytes: pod.data.byteLength,
+      view: renderData.shape.viewDimension,
+      generation: ++this.textureGeneration,
+      deviceEpoch: this.deviceEpoch,
+    };
+  }
+
   /**
    * Shared texture-upload prelude: format / colorSpace consistency assertion,
    * GPU texture allocation + writeTexture. Returns `gpuTexture: undefined`
@@ -1155,13 +1203,21 @@ export class GpuResidencyCache {
     // upload before allocating a handle; binding a texture that the backend
     // accepted syntactically but cannot use later surfaces only as a generic
     // invalid-bind-group submit error.
-    const maxDimension = device.limits.maxTextureDimension2D;
-    if (tex.width > maxDimension || tex.height > maxDimension) {
+    const maxDimension =
+      tex.shape.viewDimension === '3d'
+        ? device.limits.maxTextureDimension3D
+        : device.limits.maxTextureDimension2D;
+    const width = tex.shape.extent.width;
+    const height = tex.shape.extent.height;
+    const layers = renderData.depthOrArrayLayers;
+    const exceedsLayerLimit =
+      tex.shape.viewDimension === '2d-array' && layers > device.limits.maxTextureArrayLayers;
+    if (width > maxDimension || height > maxDimension || exceedsLayerLimit) {
       return err(
         makeImageError({
           code: 'image-dimension-out-of-bounds',
-          requested: { width: tex.width, height: tex.height },
-          limit: maxDimension,
+          requested: { width, height },
+          limit: exceedsLayerLimit ? device.limits.maxTextureArrayLayers : maxDimension,
         }),
       );
     }
@@ -1171,11 +1227,11 @@ export class GpuResidencyCache {
       size: {
         width: renderData.physicalExtent.width,
         height: renderData.physicalExtent.height,
-        depthOrArrayLayers: 1,
+        depthOrArrayLayers: renderData.depthOrArrayLayers,
       },
       mipLevelCount: levels,
       sampleCount: 1,
-      dimension: '2d',
+      dimension: tex.shape.viewDimension === '3d' ? '3d' : '2d',
       format: renderData.format,
       usage: renderData.usage,
       viewFormats: [],
@@ -1193,28 +1249,77 @@ export class GpuResidencyCache {
       // block math). Full-subresource copies retain their logical size, including
       // non-block-aligned dimensions. queue.writeTexture avoids the 256 B
       // copyBufferToTexture alignment trap.
-      const layout = deriveMipUploadLayout(renderData.format, tex.width, tex.height, levels);
-      for (const lvl of layout) {
-        const slice = decoded.bytes.subarray(lvl.byteOffset, lvl.byteOffset + lvl.byteLength);
-        const writeRes = queue.writeTexture(
-          { texture: gpuTexture, mipLevel: lvl.level, origin: { x: 0, y: 0, z: 0 } },
-          slice,
-          { offset: 0, bytesPerRow: lvl.bytesPerRow, rowsPerImage: lvl.rowsPerImage },
-          { width: lvl.copyWidth, height: lvl.copyHeight, depthOrArrayLayers: 1 },
+      const layout = deriveTextureLayout({
+        shape: tex.shape,
+        format: renderData.format,
+        mips: tex.mips,
+      });
+      if (!layout.ok) {
+        return err(
+          makeAssetError({
+            code: 'invalid-source-format',
+            expected: layout.error.expected,
+            hint: layout.error.hint,
+          }),
         );
-        if (!writeRes.ok) return writeRes;
+      }
+      for (const level of layout.value.levels) {
+        for (let image = 0; image < level.imagesPerMip; image++) {
+          const imageBytes = level.bytesPerRow * level.rowsPerImage;
+          const offset = level.byteOffset + image * imageBytes;
+          const slice = decoded.bytes.subarray(offset, offset + imageBytes);
+          const writeRes = queue.writeTexture(
+            {
+              texture: gpuTexture,
+              mipLevel: level.level,
+              origin: { x: 0, y: 0, z: image },
+            },
+            slice,
+            { offset: 0, bytesPerRow: level.bytesPerRow, rowsPerImage: level.rowsPerImage },
+            {
+              width: level.physicalWidth,
+              height: level.physicalHeight,
+              depthOrArrayLayers: 1,
+            },
+          );
+          if (!writeRes.ok) return writeRes;
+        }
       }
       return ok({ id, tex, levels, gpuTexture });
     }
 
     // Uncompressed base-mip write; higher mips (when mipmap) are GPU-generated by
     // the caller's blit pass. rowsPerImage is the pixel height for linear RGBA.
-    const bytesPerRow = renderData.bytesPerRow;
+    const textureLayout = deriveTextureLayout({
+      shape: tex.shape,
+      format: renderData.format,
+      mips: tex.mips,
+    });
+    if (!textureLayout.ok) {
+      return err(
+        makeAssetError({
+          code: 'invalid-source-format',
+          expected: textureLayout.error.expected,
+          hint: textureLayout.error.hint,
+        }),
+      );
+    }
+    const baseLevel = textureLayout.value.levels[0];
+    if (baseLevel === undefined) {
+      return err(
+        makeAssetError({
+          code: 'invalid-source-format',
+          expected: 'texture layout contains a base mip level',
+          hint: ASSET_ERROR_HINTS['invalid-source-format'],
+        }),
+      );
+    }
+    const bytesPerRow = baseLevel.bytesPerRow;
     const writeTextureRes = queue.writeTexture(
       { texture: gpuTexture, mipLevel: 0, origin: { x: 0, y: 0, z: 0 } },
       decoded.bytes,
-      { offset: 0, bytesPerRow, rowsPerImage: tex.height },
-      { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+      { offset: 0, bytesPerRow, rowsPerImage: height },
+      { width, height, depthOrArrayLayers: renderData.depthOrArrayLayers },
     );
     if (!writeTextureRes.ok) return writeTextureRes;
 
@@ -1333,14 +1438,21 @@ export class GpuResidencyCache {
     // / format / data / colorSpace) but has no CPU mip chain, so the derived
     // texture view declares `mipmap:false` (the IBL prefilter mip chain is a
     // GPU-side pass, not a CPU-authored level set).
+    const sourceData =
+      sourcePod.data instanceof Uint8ClampedArray
+        ? new Uint8Array(
+            sourcePod.data.buffer,
+            sourcePod.data.byteOffset,
+            sourcePod.data.byteLength,
+          )
+        : sourcePod.data;
     const sourceTex: TextureAsset = {
       kind: 'texture',
-      width: sourcePod.width,
-      height: sourcePod.height,
+      shape: { viewDimension: '2d', extent: { width: sourcePod.width, height: sourcePod.height } },
       format: sourcePod.format,
-      data: sourcePod.data,
+      data: sourceData,
       colorSpace: sourcePod.colorSpace,
-      mipmap: false,
+      mips: { kind: 'none' },
     };
 
     // Project the equirect source POD into the cubemap descriptor (D-5): the
@@ -1365,20 +1477,11 @@ export class GpuResidencyCache {
     const tex: TextureAsset = projected.needsHalfConversion
       ? {
           kind: 'texture',
-          width: sourceTex.width,
-          height: sourceTex.height,
+          shape: sourceTex.shape,
           format: projected.outputFormat,
-          data: halfFloat.f32ToF16Bytes(
-            sourceTex.data instanceof Uint8ClampedArray
-              ? new Uint8Array(
-                  sourceTex.data.buffer,
-                  sourceTex.data.byteOffset,
-                  sourceTex.data.byteLength,
-                )
-              : sourceTex.data,
-          ),
+          data: halfFloat.f32ToF16Bytes(sourceTex.data),
           colorSpace: 'linear',
-          mipmap: false,
+          mips: { kind: 'none' },
         }
       : sourceTex;
 
@@ -1503,7 +1606,11 @@ export class GpuResidencyCache {
 
     const equirectTextureResult = device.createTexture({
       label: `equirect-${sourceId}`,
-      size: { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+      size: {
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
+        depthOrArrayLayers: 1,
+      },
       mipLevelCount: 1,
       sampleCount: 1,
       dimension: '2d',
@@ -1526,8 +1633,15 @@ export class GpuResidencyCache {
     const equirectWriteResult = device.queue.writeTexture(
       { texture: equirectGpuTex },
       tex.data,
-      { bytesPerRow: tex.width * bytesPerPixel, rowsPerImage: tex.height },
-      { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+      {
+        bytesPerRow: tex.shape.extent.width * bytesPerPixel,
+        rowsPerImage: tex.shape.extent.height,
+      },
+      {
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
+        depthOrArrayLayers: 1,
+      },
     );
     if (!equirectWriteResult.ok) return recordFailed(equirectWriteResult.error);
 
@@ -1803,20 +1917,16 @@ export class GpuResidencyCache {
 /**
  * Synthesize the `DecodedImage` view the texture-upload prelude consumes from
  * a `TextureAsset` POD (the record-stage pull path holds only the POD). The
- * POD's `data` is the pixel bytes; `colorSpace` + `mipmap` drive the
+ * POD's `data` is the pixel bytes; `colorSpace` + `mips` drive the
  * consistency assertion + mip count.
  */
 function decodedFromTexture(tex: TextureAsset): DecodedImage {
-  const bytes =
-    tex.data instanceof Uint8ClampedArray
-      ? new Uint8Array(tex.data.buffer, tex.data.byteOffset, tex.data.byteLength)
-      : tex.data;
   return {
-    bytes,
-    width: tex.width,
-    height: tex.height,
+    bytes: tex.data,
+    width: tex.shape.extent.width,
+    height: tex.shape.extent.height,
     mime: 'image/png',
     colorSpace: tex.colorSpace,
-    mipmap: tex.mipmap,
+    mipmap: tex.mips.kind === 'generate',
   };
 }