@forgeax/engine-render 0.1.20 → 0.1.23

package/src/components/directional-shadow-filter.ts

@@ -0,0 +1,57 @@
+// @forgeax/engine-render - closed Directional shadow filter vocabulary.
+
+/** Stable serialized labels for Directional shadow filtering. */
+export const DirectionalShadowFilterValue = Object.freeze({
+  pcf1: 1,
+  pcf3: 2,
+  pcf5: 3,
+  pcssMedium: 4,
+  pcssHigh: 5,
+} as const);
+
+export type DirectionalShadowFilterLabel = keyof typeof DirectionalShadowFilterValue;
+
+/**
+ * Extract-side semantic projection of the serialized Directional filter.
+ * `shadowAngularRadius` is radians and `maxPenumbraTexels` is a finite integer.
+ */
+export type DirectionalShadowQuality =
+  | { readonly kind: 'pcf'; readonly kernel: 1 | 3 | 5 }
+  | {
+      readonly kind: 'pcss';
+      readonly preset: 'medium' | 'high';
+      readonly angularRadiusRadians: number;
+      readonly maxPenumbraTexels: number;
+    };
+
+/** Resolve the closed serialized label to the receiver-facing semantic union. */
+export function directionalShadowQualityFromF32(
+  value: number,
+  angularRadiusRadians: number,
+  maxPenumbraTexels: number,
+): DirectionalShadowQuality | undefined {
+  switch (value) {
+    case DirectionalShadowFilterValue.pcf1:
+      return { kind: 'pcf', kernel: 1 };
+    case DirectionalShadowFilterValue.pcf3:
+      return { kind: 'pcf', kernel: 3 };
+    case DirectionalShadowFilterValue.pcf5:
+      return { kind: 'pcf', kernel: 5 };
+    case DirectionalShadowFilterValue.pcssMedium:
+      return {
+        kind: 'pcss',
+        preset: 'medium',
+        angularRadiusRadians,
+        maxPenumbraTexels,
+      };
+    case DirectionalShadowFilterValue.pcssHigh:
+      return {
+        kind: 'pcss',
+        preset: 'high',
+        angularRadiusRadians,
+        maxPenumbraTexels,
+      };
+    default:
+      return undefined;
+  }
+}

package/src/components/index.ts

@@ -1,9 +1,12 @@
 export * from './atmosphere';
 export * from './camera';
+export * from './cube-camera';
 export * from './directional-light';
 export * from './fog';
 export { Instances, type InstancesData } from './instances';
 export { Layer } from './layer';
+export * from './light-helpers';
+export { LightProbe } from './light-probe';
 export { Lines } from './lines';
 export * from './mesh-filter';
 export * from './mesh-renderer';
@@ -17,6 +20,8 @@ export {
   pointShapeFromU32,
 } from './points';
 export { PostProcessParams } from './post-process-params';
+export { RectAreaLight } from './rect-area-light';
+export * from './reflection-probe';
 export {
   SceneInstance,
   type SceneInstanceOverrideRecord,

package/src/components/light-helpers.ts

@@ -14,15 +14,20 @@
 // transparent to AI users) + D-S5 (Layer 1 host-side range = 0 ->
 // invRangeSquared = 1e8 protects the 0 * Infinity = NaN intermediate).
 
-import { err, ok, type Result } from '@forgeax/engine-types';
+import { err, ok, R_MIN, 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,15 @@ 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) {
@@ -186,7 +252,66 @@ 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);
+}
+
+/** Validate rectangular area-light authoring facts before renderer admission. */
+export function validateRectAreaLightData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const intensity = (data.intensity as number | undefined) ?? 1;
+  if (typeof intensity !== 'number' || !Number.isFinite(intensity) || intensity < 0) {
+    return err(new SpawnLightInvalidBoundsError('RectAreaLight', 'intensity', intensity));
+  }
+  const color = (data.color as ArrayLike<number> | undefined) ?? [1, 1, 1];
+  if (
+    color.length !== 3 ||
+    Array.from(color).some(
+      (value) => typeof value !== 'number' || !Number.isFinite(value) || value < 0,
+    )
+  ) {
+    return err(new SpawnLightInvalidBoundsError('RectAreaLight', 'color', Array.from(color)));
+  }
+  for (const field of ['width', 'height', 'range'] as const) {
+    const value = (data[field] as number | undefined) ?? (field === 'range' ? 10 : 1);
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+      return err(new SpawnLightInvalidBoundsError('RectAreaLight', field, value));
+    }
+  }
+  return ok(undefined);
+}
+
+/** Validate the fixed 27-value SH payload and minimum finite radius. */
+export function validateLightProbeData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const irradiance = data.irradiance as ArrayLike<number> | undefined;
+  if (
+    irradiance === undefined ||
+    irradiance.length !== 27 ||
+    Array.from(irradiance).some((value) => typeof value !== 'number' || !Number.isFinite(value))
+  ) {
+    return err(
+      new SpawnLightInvalidBoundsError(
+        'LightProbe',
+        'irradiance',
+        irradiance === undefined ? [] : Array.from(irradiance),
+      ),
+    );
+  }
+  const radius = (data.radius as number | undefined) ?? R_MIN;
+  if (typeof radius !== 'number' || !Number.isFinite(radius) || radius < R_MIN) {
+    return err(new SpawnLightInvalidBoundsError('LightProbe', 'radius', radius));
   }
   return ok(undefined);
 }

package/src/components/light-probe.ts

@@ -0,0 +1,13 @@
+// @forgeax/engine-render - local diffuse LightProbe authoring facts.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+import { R_MIN } from '@forgeax/engine-types';
+
+/**
+ * Local diffuse irradiance probe. Transform supplies position; the 27 SH
+ * values are nine RGB groups in the fixed real-SH order.
+ */
+export const LightProbe = defineComponent('LightProbe', {
+  irradiance: { type: 'array<f32, 27>' },
+  radius: { type: 'f32', default: R_MIN },
+});

package/src/components/rect-area-light.ts

@@ -0,0 +1,15 @@
+// @forgeax/engine-render - single-sided rectangular area-light authoring facts.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Single-sided rectangular area light. Transform supplies the center and
+ * world orientation; width and height remain authored emitter dimensions.
+ */
+export const RectAreaLight = defineComponent('RectAreaLight', {
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1 },
+  width: { type: 'f32', default: 1 },
+  height: { type: 'f32', default: 1 },
+  range: { type: 'f32', default: 10 },
+});

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/scene-instance.ts

@@ -94,6 +94,12 @@ export interface SceneInstanceState {
    */
   readonly source: import('@forgeax/engine-types').Handle<'SceneAsset', 'shared'>;
 
+  /** Author scene identity used by instance-relative SceneEntityRef resolution. */
+  readonly sceneSourceKey?: string;
+
+  /** Stable author bindingKey to live Entity mapping for this concrete instance. */
+  readonly bindings: Map<string, EntityHandle>;
+
   /**
    * Reverse mapping (live `Entity` -> source `LocalEntityId`). Used by
    * `world.setSceneOverride` to validate the member entity belongs to this

package/src/components/spot-light.ts

@@ -124,6 +124,9 @@ export const SpotLight = defineComponent('SpotLight', {
   range: { type: 'f32', default: 10.0 },
   innerConeDeg: { type: 'f32', default: 0 },
   outerConeDeg: { type: 'f32', default: 45 },
+  iesProfile: { type: 'shared<IesProfileAsset>' },
+  cookie: { type: 'shared<TextureAsset>' },
+  rollDeg: { type: 'f32', default: 0 },
   // Shadow opt-out gate: defaults to true so zero-config spawns cast shadows.
   castShadow: { type: 'bool', default: true },
   // 7 shadow fields aligned with the shared light shadow vocabulary.

package/src/device/__tests__/extended-lighting-recovery.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createExtendedLightingResourceCandidate,
+  inspectExtendedLightingResources,
+} from '../../prepare/extended-lighting/resources';
+import { DeviceScope } from '../device-scope';
+
+describe('extended lighting device recovery', () => {
+  it('retires the old scope and rebuilds one accepted resource generation', async () => {
+    const oldScope = DeviceScope.create(8, 'renderer');
+    const oldResource = oldScope.ref('texture', { id: 'old' });
+    const candidate = await createExtendedLightingResourceCandidate({
+      device: undefined,
+      scope: oldScope,
+      iesSliceCount: 0,
+      cookieSliceCount: 0,
+      cookieMatrices: 0,
+    });
+
+    expect(candidate.ok).toBe(false);
+    expect(oldResource.isCurrent(oldScope)).toBe(true);
+    expect(inspectExtendedLightingResources(oldScope).generation).toBe(8);
+  });
+});

package/src/device/gpu-residency.ts

@@ -324,6 +324,123 @@ interface CubemapGpuEntry {
   faceViews: readonly TextureView[];
 }
 
+interface PackedMeshLodGeometry {
+  readonly vertices: Float32Array;
+  readonly indices: Uint16Array | Uint32Array | undefined;
+  readonly lodRanges: readonly (readonly MeshGpuRange[])[] | undefined;
+}
+
+function packMeshLodGeometry(
+  root: TypesMeshAsset,
+  rootData: MeshRenderData,
+  lowerMeshes: readonly TypesMeshAsset[],
+): Result<PackedMeshLodGeometry, RhiError> {
+  if (lowerMeshes.length === 0) {
+    return ok({ vertices: root.vertices, indices: root.indices, lodRanges: undefined });
+  }
+  const rootStride = rootData.layoutProjection.arrayStride;
+  const allMeshes = [root, ...lowerMeshes];
+  const lowerData: MeshRenderData[] = [];
+  for (const lower of lowerMeshes) {
+    const projected = deriveRenderDataMesh(lower);
+    if (!projected.ok) {
+      return err(
+        new RhiError({
+          code: 'asset-not-registered',
+          expected: 'every MeshAsset LOD to project to a compatible GPU layout',
+          hint: 'repair the lower-detail MeshAsset attributes before drawing the LOD chain',
+        }),
+      );
+    }
+    lowerData.push(projected.value);
+  }
+  if (
+    lowerData.some(
+      (data) =>
+        data.layoutProjection.arrayStride !== rootStride ||
+        data.submeshes.length !== rootData.submeshes.length ||
+        data.indexFormat !== rootData.indexFormat,
+    )
+  ) {
+    return err(
+      new RhiError({
+        code: 'asset-not-registered',
+        expected: 'LOD meshes to share vertex/index layout and material-slot topology',
+        hint: 'reimport LOD meshes with matching attributes, index format, and submesh slots',
+      }),
+    );
+  }
+  if (allMeshes.some((mesh) => (mesh.indices === undefined) !== (root.indices === undefined))) {
+    return err(
+      new RhiError({
+        code: 'asset-not-registered',
+        expected: 'all LOD meshes to use the same indexed or non-indexed draw mode',
+        hint: 'reimport the LOD chain with consistent index data',
+      }),
+    );
+  }
+  const vertices = new Float32Array(allMeshes.reduce((sum, mesh) => sum + mesh.vertices.length, 0));
+  const ranges: MeshGpuRange[][] = [];
+  let vertexCursor = 0;
+  let indexCursor = 0;
+  const indexed = root.indices !== undefined;
+  const sourceIndices: number[] = [];
+  let requiresUint32 = root.indices instanceof Uint32Array;
+  for (let level = 0; level < allMeshes.length; level += 1) {
+    const mesh = allMeshes[level];
+    const data = level === 0 ? rootData : lowerData[level - 1];
+    if (mesh === undefined || data === undefined) continue;
+    vertices.set(mesh.vertices, vertexCursor);
+    const levelRanges: MeshGpuRange[] = [];
+    for (let submeshIndex = 0; submeshIndex < data.submeshes.length; submeshIndex += 1) {
+      const submesh = data.submeshes[submeshIndex];
+      const rootSubmesh = rootData.submeshes[submeshIndex];
+      if (
+        submesh === undefined ||
+        rootSubmesh === undefined ||
+        submesh.materialSlot !== rootSubmesh.materialSlot ||
+        submesh.topology !== rootSubmesh.topology
+      ) {
+        return err(
+          new RhiError({
+            code: 'asset-not-registered',
+            expected: 'LOD submeshes to preserve root material-slot and topology identity',
+            hint: 'repair LOD material slots and primitive topology before import',
+          }),
+        );
+      }
+      levelRanges.push(
+        indexed
+          ? {
+              first: indexCursor + submesh.indexOffset,
+              count: submesh.indexCount,
+              baseVertex: vertexCursor / (rootStride / 4),
+            }
+          : { first: vertexCursor / (rootStride / 4), count: submesh.vertexCount, baseVertex: 0 },
+      );
+    }
+    ranges.push(levelRanges);
+    if (indexed) {
+      const indices = mesh.indices;
+      if (indices === undefined) continue;
+      for (const value of indices) {
+        // Each LOD range carries its vertex cursor as baseVertex, so keep
+        // indices local to that LOD and apply the offset exactly once at draw.
+        sourceIndices.push(value);
+        if (value > 0xffff || indices instanceof Uint32Array) requiresUint32 = true;
+      }
+      indexCursor += indices.length;
+    }
+    vertexCursor += mesh.vertices.length;
+  }
+  const indices = indexed
+    ? requiresUint32
+      ? Uint32Array.from(sourceIndices)
+      : Uint16Array.from(sourceIndices)
+    : undefined;
+  return ok({ vertices, indices, lodRanges: ranges });
+}
+
 export interface MeshGpuHandles {
   readonly vertexBuffer: GpuBuffer;
   /**
@@ -374,6 +491,14 @@ export interface MeshGpuHandles {
    * For single-submesh meshes this is a 1-element array (byte-identical to pre-M4).
    */
   readonly submeshes: readonly import('@forgeax/engine-types').Submesh[];
+  /** Packed root + lower-detail geometry ranges in the shared mesh buffers. */
+  readonly lodRanges?: readonly (readonly MeshGpuRange[])[];
+}
+
+export interface MeshGpuRange {
+  readonly first: number;
+  readonly count: number;
+  readonly baseVertex: number;
 }
 
 /**
@@ -951,6 +1076,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'>,
     pod: TypesMeshAsset,
     worldId?: World | number,
+    lodMeshes?: readonly TypesMeshAsset[],
   ): Result<MeshGpuHandles, RhiError | AssetError | ImageError>;
   ensureResident(
     handle: Handle<'TextureAsset', 'shared'>,
@@ -961,6 +1087,7 @@ export class GpuResidencyCache {
     handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>,
     pod: TypesMeshAsset | TextureAsset,
     worldId: World | number = 0,
+    lodMeshes: readonly TypesMeshAsset[] = [],
   ): Result<TextureGpuEntry | MeshGpuHandles, RhiError | AssetError | ImageError> {
     const id = handleSlot(handle);
     // Hit: O(1) cache lookup, never re-projects (AC-09 -- deriveRenderData*
@@ -977,7 +1104,7 @@ export class GpuResidencyCache {
         if (existing !== undefined) return ok(existing);
         const projected = deriveRenderDataMesh(pod);
         if (!projected.ok) return projected;
-        return this.uploadMeshById(key, pod, projected.value);
+        return this.uploadMeshById(key, pod, projected.value, lodMeshes);
       }
       case 'texture': {
         const texKey = this.worldKey(id, worldId);
@@ -1702,6 +1829,7 @@ export class GpuResidencyCache {
     id: string | number,
     mesh: TypesMeshAsset,
     renderData: MeshRenderData,
+    lodMeshes: readonly TypesMeshAsset[] = [],
   ): Result<MeshGpuHandles, RhiError> {
     const device = this.gpuDevice;
     if (device === undefined) {
@@ -1714,13 +1842,15 @@ export class GpuResidencyCache {
       );
     }
 
-    const indices = mesh.indices;
+    const packed = packMeshLodGeometry(mesh, renderData, lodMeshes);
+    if (!packed.ok) return packed;
+    const { vertices, indices, lodRanges } = packed.value;
     const indexBytesUnpadded = indices === undefined ? 0 : indices.byteLength;
-    const indexBytes = renderData.indexByteLength;
+    const indexBytes = ((indexBytesUnpadded + 3) >> 2) << 2;
 
     const vboResult = device.createBuffer({
       label: `mesh-${id}-vbo`,
-      size: renderData.vertexByteLength,
+      size: vertices.byteLength,
       usage: renderData.vertexUsage,
       mappedAtCreation: false,
     });
@@ -1740,7 +1870,7 @@ export class GpuResidencyCache {
       ibo = iboResult.value;
     }
 
-    const vboWriteResult = device.queue.writeBuffer(vbo, 0, mesh.vertices);
+    const vboWriteResult = device.queue.writeBuffer(vbo, 0, vertices);
     if (!vboWriteResult.ok) return err(vboWriteResult.error);
 
     if (indices !== undefined) {
@@ -1766,10 +1896,10 @@ export class GpuResidencyCache {
     const entry: MeshGpuHandles = {
       vertexBuffer: this.wrapBuf(vbo),
       indexBuffer: ibo === null ? null : this.wrapBuf(ibo),
-      vboBytes: renderData.vertexByteLength,
+      vboBytes: vertices.byteLength,
       iboBytes: indices === undefined ? 0 : indexBytes,
-      indexCount: renderData.indexCount,
-      indexFormat: renderData.indexFormat,
+      indexCount: mesh.indices === undefined ? 0 : mesh.indices.length,
+      indexFormat: indices instanceof Uint32Array ? 'uint32' : 'uint16',
       layout: renderData.layoutProjection.attributes.some(
         (attribute) => attribute.key === 'skinIndex' || attribute.key === 'skinWeight',
       )
@@ -1778,9 +1908,10 @@ export class GpuResidencyCache {
       layoutProjection: renderData.layoutProjection,
       uvSetCount: 1 + extraUvSets,
       vertexCount: mesh.vertices.byteLength / renderData.layoutProjection.arrayStride,
-      indexed: indices !== undefined,
+      indexed: mesh.indices !== undefined,
       topology: renderData.submeshes[0]?.topology ?? 'triangle-list',
       submeshes: renderData.submeshes,
+      ...(lodRanges === undefined ? {} : { lodRanges }),
     };
     this.meshGpuHandles.set(id, entry);
     this.meshResidencyEpoch += 1;

package/src/device/lifecycle-transaction.ts

@@ -0,0 +1,12 @@
+export {
+  type DeviceResourceKind,
+  DeviceResourceRef,
+  DeviceScope,
+  type DeviceScopeReceipt,
+  type DeviceScopeState,
+  type LifecycleFailure,
+  type LifecycleResourceSpec,
+  type LifecycleResult,
+  LifecycleTransaction,
+  type ResourceRef,
+} from './device-scope';