@forgeax/engine-render 0.1.21 → 0.1.23

package/src/assembly/host-contract.ts

@@ -5,6 +5,7 @@ import type { RenderPipelineAsset } from '@forgeax/engine-types';
 import type { RecoverFailure } from '../errors/recover';
 import type { ObservationUnavailableError, RenderError } from '../errors/render';
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
+import type { GpuDrivenProductionInspection, LodOcclusionInspection } from '../inspection-types';
 import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
 import type { FrameObservation, FrameObservationOptions } from '../record/frame';
 import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
@@ -69,6 +70,15 @@ export interface RendererHostImplementation {
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   inspect(): RenderInspection;
+  /**
+   * Internal bounded inspection for high-cardinality producers. The public
+   * snapshot also carries the full persistent render-scene record table, which
+   * is intentionally not materialized for per-frame performance evidence.
+   */
+  inspectLodOcclusion(): {
+    readonly lodOcclusion: LodOcclusionInspection | undefined;
+    readonly gpuDriven: GpuDrivenProductionInspection;
+  };
   drawFrame(request: RenderFrameInput): RenderResult<FrameReceipt, RhiError | RenderError>;
   observe(
     receipt: FrameReceipt,

package/src/cluster-binner.ts

@@ -27,6 +27,7 @@
 
 import { type Mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { err, ok, type Result } from '@forgeax/engine-rhi';
+import type { RectAreaWorldFrame } from './render-system-extract';
 
 // ── types ──────────────────────────────────────────────────────────────────
 
@@ -174,6 +175,36 @@ export function deriveCullingRadius(range: number, intensity: number, threshold
   return Math.min(derived, 1000);
 }
 
+/** Conservative bounding-sphere radius for a finite Rect and its light range. */
+export function rectAreaClusterRadius(frame: RectAreaWorldFrame, range: number): number {
+  return Math.max(0, range) + Math.hypot(frame.halfWidth, frame.halfHeight);
+}
+
+/** Test the finite Rect's closest-point distance against a strict range window. */
+export function rectAreaIsInRange(
+  frame: RectAreaWorldFrame,
+  point: ArrayLike<number>,
+  range: number,
+): boolean {
+  const toPoint = vec3.create(
+    (point[0] ?? 0) - (frame.center[0] ?? 0),
+    (point[1] ?? 0) - (frame.center[1] ?? 0),
+    (point[2] ?? 0) - (frame.center[2] ?? 0),
+  );
+  const localX = Math.min(
+    frame.halfWidth,
+    Math.max(-frame.halfWidth, vec3.dot(toPoint, frame.axisX)),
+  );
+  const localY = Math.min(
+    frame.halfHeight,
+    Math.max(-frame.halfHeight, vec3.dot(toPoint, frame.axisY)),
+  );
+  const dx = (toPoint[0] ?? 0) - (frame.axisX[0] ?? 0) * localX - (frame.axisY[0] ?? 0) * localY;
+  const dy = (toPoint[1] ?? 0) - (frame.axisX[1] ?? 0) * localX - (frame.axisY[1] ?? 0) * localY;
+  const dz = (toPoint[2] ?? 0) - (frame.axisX[2] ?? 0) * localX - (frame.axisY[2] ?? 0) * localY;
+  return dx * dx + dy * dy + dz * dz < range * range;
+}
+
 // ── view_z_to_z_slice ──────────────────────────────────────────────────────
 
 /**

package/src/components/__tests__/lighting-authoring.unit.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import {
+  LightProbe,
+  RectAreaLight,
+  SpotLight,
+  validateLightProbeData,
+  validateRectAreaLightData,
+} from '../index';
+
+describe('lighting authoring contracts', () => {
+  it('exposes only the declared Rect, Spot modifier, and Probe fields', () => {
+    expect(Object.keys(RectAreaLight.fields)).toEqual([
+      'color',
+      'intensity',
+      'width',
+      'height',
+      'range',
+    ]);
+    expect(Object.keys(LightProbe.fields)).toEqual(['irradiance', 'radius']);
+    expect(SpotLight.fields.iesProfile.type).toBe('shared<IesProfileAsset>');
+    expect(SpotLight.fields.cookie.type).toBe('shared<TextureAsset>');
+    expect(SpotLight.fields.rollDeg.default).toBe(0);
+  });
+
+  it('keeps defaults and rejects invalid Rect/Probe facts before rendering', () => {
+    expect(RectAreaLight.fields.width.default).toBe(1);
+    expect(RectAreaLight.fields.height.default).toBe(1);
+    expect(LightProbe.fields.irradiance.type).toBe('array<f32, 27>');
+    expect(LightProbe.fields.radius.default).toBe(1e-4);
+
+    expect(validateRectAreaLightData({}).ok).toBe(true);
+    expect(validateRectAreaLightData({ width: 0 }).ok).toBe(false);
+    expect(validateRectAreaLightData({ intensity: Number.NaN }).ok).toBe(false);
+    expect(validateLightProbeData({ irradiance: new Float32Array(26), radius: 1 }).ok).toBe(false);
+    expect(validateLightProbeData({ irradiance: new Float32Array(27), radius: 1e-5 }).ok).toBe(
+      false,
+    );
+  });
+});

package/src/components/__tests__/rect-area-light.unit.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { buildRectAreaWorldFrame, rectAreaFacesPoint } from '../../render-system-extract';
+
+describe('RectAreaLight world frame', () => {
+  it('normalizes world axes while preserving authored half extents', () => {
+    const frame = buildRectAreaWorldFrame({
+      center: [1, 2, 3],
+      axisX: [0, 2, 0],
+      axisY: [-3, 0, 0],
+      width: 4,
+      height: 2,
+    });
+
+    expect(Array.from(frame.axisX)).toEqual([0, 1, 0]);
+    expect(Array.from(frame.axisY)).toEqual([-1, 0, 0]);
+    expect(Array.from(frame.normal)).toEqual([0, 0, 1]);
+    expect(frame.halfWidth).toBe(2);
+    expect(frame.halfHeight).toBe(1);
+  });
+
+  it('defines the front from the world-axis cross product', () => {
+    const frame = buildRectAreaWorldFrame({
+      center: [0, 0, 0],
+      axisX: [1, 0, 0],
+      axisY: [0, 1, 0],
+      width: 2,
+      height: 2,
+    });
+
+    expect(rectAreaFacesPoint(frame, [0, 0, 1])).toBe(true);
+    expect(rectAreaFacesPoint(frame, [0, 0, -1])).toBe(false);
+  });
+});

package/src/components/index.ts

@@ -5,6 +5,8 @@ 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';
@@ -18,6 +20,7 @@ export {
   pointShapeFromU32,
 } from './points';
 export { PostProcessParams } from './post-process-params';
+export { RectAreaLight } from './rect-area-light';
 export * from './reflection-probe';
 export {
   SceneInstance,

package/src/components/light-helpers.ts

@@ -14,7 +14,7 @@
 // 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';
@@ -264,3 +264,54 @@ export function validatePointLightShadowData(
   }
   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/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';

package/src/environment/lifecycle.ts

@@ -42,7 +42,11 @@ export class EnvironmentLifecycle {
   }
 
   isActive(generation: EnvironmentGeneration): boolean {
-    return this.active === generation;
+    return (
+      this.active?.generation === generation.generation &&
+      this.active.signature === generation.signature &&
+      this.active.scope === generation.scope
+    );
   }
 
   discard(generation: EnvironmentGeneration): void {
@@ -106,6 +110,9 @@ export class EnvironmentLifecycle {
         ),
       );
     }
+    if (this.active?.signature === frame.signature && this.active.scope.isAlive()) {
+      return ok(this.active.lane === lane ? this.active : this.laneView(this.active, lane));
+    }
     const existing = this.candidates.get(frame.signature);
     if (existing?.scope.isAlive()) {
       return ok(existing.lane === lane ? existing : this.laneView(existing, lane));

package/src/errors/gpu-driven.ts

@@ -0,0 +1,92 @@
+import type { MaterialShaderArtifactReceipt } from '@forgeax/engine-shader';
+
+export type GpuDrivenPreparationErrorCode =
+  | 'missing-material-receipt'
+  | 'missing-uv'
+  | 'reflection-mismatch'
+  | 'vertex-input-mismatch'
+  | 'alpha-mask-mismatch'
+  | 'resource-not-ready'
+  | 'stale-generation'
+  | 'skin-receipt-mismatch';
+
+export type GpuDrivenPreparationReason =
+  | 'material-receipt-missing'
+  | 'uv-set-missing'
+  | 'reflection-receipt-mismatch'
+  | 'vertex-semantic-mismatch'
+  | 'alpha-mask-receipt-missing'
+  | 'material-resource-missing'
+  | 'generation-stale'
+  | 'skin-address-missing';
+
+export interface GpuDrivenPreparationErrorDetail {
+  readonly reason: GpuDrivenPreparationReason;
+  readonly owner: 'material' | 'geometry' | 'skin' | 'generation';
+  readonly expected?: string;
+  readonly actual?: string;
+  readonly expectedGeneration?: number;
+  readonly actualGeneration?: number;
+}
+
+const ERROR_POLICY: Readonly<
+  Record<GpuDrivenPreparationErrorCode, { readonly expected: string; readonly hint: string }>
+> = {
+  'missing-material-receipt': {
+    expected: 'a producer-owned Standard PBR material receipt is present',
+    hint: 'cook and load the Standard PBR artifact, then retry preparation',
+  },
+  'missing-uv': {
+    expected: 'the geometry exposes every UV set named by the material receipt',
+    hint: 'repair the geometry UV semantic or route the draw to the CPU semantic lane',
+  },
+  'reflection-mismatch': {
+    expected: 'the loaded reflection receipt matches the artifact layout identity',
+    hint: 'rebuild the material artifact and reflection from one source, then retry',
+  },
+  'vertex-input-mismatch': {
+    expected: 'geometry vertex semantics match the material reflection receipt',
+    hint: 'repair the geometry vertex semantic layout or route the draw to the CPU lane',
+  },
+  'alpha-mask-mismatch': {
+    expected: 'the Alpha Mask cutoff is present in the material receipt',
+    hint: 'declare alphaCutoff in the Standard PBR material schema and recook it',
+  },
+  'resource-not-ready': {
+    expected: 'all material resource slots have resolved handles',
+    hint: 'resolve the declared texture and sampler resources before recording',
+  },
+  'stale-generation': {
+    expected: 'receipt and prepared inputs belong to the requested generation',
+    hint: 'discard stale GPU facts, rebuild the producer receipt, and retry the same draw',
+  },
+  'skin-receipt-mismatch': {
+    expected: 'skinned geometry has a current palette address receipt',
+    hint: 'rebuild the Skin palette receipt for this generation before recording',
+  },
+};
+
+export class GpuDrivenPreparationError extends Error {
+  readonly code: GpuDrivenPreparationErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GpuDrivenPreparationErrorDetail;
+
+  constructor(code: GpuDrivenPreparationErrorCode, detail: GpuDrivenPreparationErrorDetail) {
+    const policy = ERROR_POLICY[code];
+    super(`[GpuDrivenPreparationError ${code}] ${policy.expected}`);
+    this.name = 'GpuDrivenPreparationError';
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.detail = detail;
+  }
+}
+
+export interface GpuDrivenPreparedMaterial {
+  readonly receipt: MaterialShaderArtifactReceipt;
+  readonly resourceSlots: MaterialShaderArtifactReceipt['resourceSlots'];
+  readonly uvSets: MaterialShaderArtifactReceipt['uvSets'];
+  readonly vertexInputs: MaterialShaderArtifactReceipt['vertexInputs'];
+  readonly alphaMask: MaterialShaderArtifactReceipt['alphaMask'];
+}

package/src/errors/index.ts

@@ -1,3 +1,4 @@
 export * from './ecs-validation';
+export * from './gpu-driven';
 export * from './recover';
 export * from './render';