@forgeax/engine-render 0.1.21 → 0.1.24

package/src/pipeline/standard-lighting/light-frame.ts

@@ -2,12 +2,13 @@ import type { Mat4, Vec3 } from '@forgeax/engine-math';
 import type {
   DirectionalLightSnapshot,
   PointLightSnapshot,
+  RectAreaDirectLightSnapshot,
   SpotLightSnapshot,
 } from '../../render-system-extract';
 import type { StandardLightCount } from '../standard-profile';
 
 export interface StandardLocalLightInput {
-  readonly kind: 'point' | 'spot';
+  readonly kind: 'point' | 'spot' | 'rect-area';
   readonly position: Vec3;
   readonly range: number;
   /** Whether the shadow producer admitted this local light to its atlas. */
@@ -17,7 +18,7 @@ export interface StandardLocalLightInput {
    * it on the POD frame prevents Forward/Deferred from rebuilding a second
    * light list while leaving hand-authored unit fixtures source-free.
    */
-  readonly source?: PointLightSnapshot | SpotLightSnapshot;
+  readonly source?: PointLightSnapshot | SpotLightSnapshot | RectAreaDirectLightSnapshot;
 }
 
 export interface StandardLightFrame {

package/src/pipeline/standard-lighting/topology.ts

@@ -2,7 +2,7 @@ import { err, ok, type Result } from '@forgeax/engine-types';
 import type { PreparedStandardLighting } from './prepare';
 import type { StandardClusterTransport } from './transport';
 
-/** A prepared frame with no local lights on a non-storage direct backend. */
+/** A prepared frame with no local lights on a non-storage backend. */
 export interface StandardNoLocalTopologyInput {
   readonly kind: 'no-local-lights';
   readonly prepared: PreparedStandardLighting;

package/src/pipeline/standard-lighting/transport.ts

@@ -1,5 +1,6 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { type RenderError, StandardClusterTransportUnavailableError } from '../../errors/render';
+import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../../light-buffer-layout';
 import type { PreparedStandardLighting } from './prepare';
 
 export interface StandardClusterCapabilities {
@@ -71,7 +72,7 @@ export function selectStandardClusterTransport(
     occupiedClusterCount: occupiedClusterCount(prepared),
     clusterGridBytes: prepared.layout.clusterGridU32Length * Uint32Array.BYTES_PER_ELEMENT,
     lightIndexListBytes: prepared.membershipEntryCount * Uint32Array.BYTES_PER_ELEMENT,
-    lightDataBytes: requested * 64,
+    lightDataBytes: requested * BYTES_PER_DIRECT_LIGHT_SLOT,
     lightBoundsBytes: prepared.lightBounds.byteLength,
   });
 }

package/src/pipeline/standard-pipeline.ts

@@ -312,6 +312,7 @@ function buildStandardDeferredLane(
     ...(gpuDriven.value === undefined ? {} : { gpuDriven: gpuDriven.value }),
     passKind: 'forward',
     ...(transmissionActive ? { recordMode: 'opaque' as const } : {}),
+    ...(context.occlusion === undefined ? {} : { occlusion: context.occlusion }),
     extraAccesses: forwardExtraAccesses,
   });
   if (!forward.ok) return forward;
@@ -403,6 +404,7 @@ function buildStandardDeferredLane(
       depthSample.value,
       shadows.value.directional?.view,
       shadows.value.spot.view,
+      buffers.value,
     );
     if (!volume.ok) return volume;
   }

package/src/pipeline-builder.ts

@@ -122,6 +122,8 @@ export interface PipelineBuilderContext {
    * tonemap field (M9 keeps the LDR shape; HDR variants are OOS-M9).
    */
   readonly colorFormat: GPUTextureFormat;
+  /** Additional color targets for an MRT pass; the first target is colorFormat. */
+  readonly colorFormats?: readonly GPUTextureFormat[] | undefined;
   /** Depth attachment format, or `undefined` for a color-only pass. */
   readonly depthFormat: GPUTextureFormat | undefined;
   /**
@@ -324,7 +326,8 @@ export function buildPipelineForMaterialShader(
   // layout. The skinned variant additionally reads JOINTS_0 / WEIGHTS_0;
   // both layouts come from the same geometry projection used by the main
   // pass, so shadow rendering cannot silently reinterpret an 18F stream.
-  if (colorFormatsForPassKind(passKind, ctx.colorFormat).length === 0) {
+  const attachmentFormats = ctx.colorFormats ?? colorFormatsForPassKind(passKind, ctx.colorFormat);
+  if (attachmentFormats.length === 0) {
     // bug-20260619-csm RC-3 (AC-10): a material may supply a custom
     // ShadowCaster pass shader that carries a fragment stage (e.g. an
     // alpha-test cutout that calls `discard` and returns
@@ -399,7 +402,7 @@ export function buildPipelineForMaterialShader(
   const forwardSpec: PipelineSpec = {
     shader: { id, passKind, variantSet: undefined },
     attachments: {
-      colorFormats: colorFormatsForPassKind(passKind, ctx.colorFormat),
+      colorFormats: attachmentFormats,
       depthFormat: ctx.depthFormat,
       sampleCount: (sampleCount === 4 ? 4 : 1) as 1 | 4,
     },

package/src/pipeline-spec.ts

@@ -319,12 +319,23 @@ export function standardTopologyVariantSet(
   topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
   storageBuffer: boolean,
   vertexColorAvailable: boolean,
+  probeBlendAvailable = false,
 ): string {
-  return standardCapabilityVariantSet(
+  const capabilityVariantSet = standardCapabilityVariantSet(
     topology?.kind === 'clustered',
     storageBuffer,
     vertexColorAvailable,
   );
+  if (!probeBlendAvailable || !storageBuffer) return capabilityVariantSet;
+  // The canonical empty key cannot carry the clustered=true fact through
+  // resolveMaterialShaderVariantSet (an omitted cluster axis means false).
+  // Expand that base before adding the object-level Probe ABI axis so shader,
+  // group(3) bind group, and pipeline layout remain one exact variant.
+  const explicitCapabilityVariantSet =
+    capabilityVariantSet === ''
+      ? 'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true'
+      : capabilityVariantSet;
+  return `${explicitCapabilityVariantSet}+PROBE_BLEND_AVAILABLE=true`;
 }
 
 /**

package/src/plugin.ts

@@ -5,6 +5,7 @@ import { Camera } from './components/camera';
 import { DirectionalLight } from './components/directional-light';
 import { Instances } from './components/instances';
 import { Layer } from './components/layer';
+import { LightProbe } from './components/light-probe';
 import { Lines } from './components/lines';
 import { MeshFilter } from './components/mesh-filter';
 import { MeshRenderer } from './components/mesh-renderer';
@@ -12,6 +13,7 @@ import { PointLight } from './components/point-light';
 import { PointLightShadow } from './components/point-light-shadow';
 import { Points } from './components/points';
 import { PostProcessParams } from './components/post-process-params';
+import { RectAreaLight } from './components/rect-area-light';
 import { SceneInstance } from './components/scene-instance';
 import { SkyboxBackground } from './components/skybox-background';
 import { Skylight } from './components/skylight';
@@ -30,6 +32,7 @@ const RENDER_COMPONENTS: readonly Component[] = [
   DirectionalLight,
   Instances,
   Layer,
+  LightProbe,
   MeshFilter,
   MeshRenderer,
   PointLight,
@@ -37,6 +40,7 @@ const RENDER_COMPONENTS: readonly Component[] = [
   Points,
   Lines,
   PostProcessParams,
+  RectAreaLight,
   SceneInstance,
   SkyboxBackground,
   Skylight,

package/src/points-lines/__tests__/cache-recovery.unit.test.ts

@@ -154,4 +154,26 @@ describe('Points/Lines expansion cache and LKG recovery', () => {
     expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
     expect(preparation.inspect()).toMatchObject({ status: 'resident', lastKnownGood: true });
   });
+
+  it('abandons lost-device handles without invoking the dead-device destroy path', () => {
+    let destroys = 0;
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter: {
+        create: () => ok('lost-device-resource'),
+        upload: () => ok(64),
+        validate: () => ok(undefined),
+        destroy: () => {
+          destroys += 1;
+        },
+      },
+    });
+
+    expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
+    preparation.abandonForDeviceLoss();
+    preparation.abandonForDeviceLoss();
+
+    expect(destroys).toBe(0);
+    expect(preparation.inspect()).toMatchObject({ status: 'rebuild-pending', liveBytes: 0 });
+  });
 });

package/src/points-lines/prepare.ts

@@ -37,6 +37,8 @@ export interface PointsLinesLanePreparationAdapter<Resource> {
     mesh: MeshAsset,
   ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError>;
   resetForDeviceLoss(): void;
+  /** Drop lost-device handles without calling destroy on the dead device. */
+  abandonForDeviceLoss(): void;
   lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined;
   inspect(): PointsLinesPreparationInspection<Resource>;
 }
@@ -121,6 +123,12 @@ export class PointsLinesPreparation<Resource> {
     this.status = 'rebuild-pending';
   }
 
+  abandonForDeviceLoss(): void {
+    this.live = undefined;
+    this.pendingCandidateBytes = 0;
+    this.status = 'rebuild-pending';
+  }
+
   lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined {
     return this.live;
   }
@@ -171,6 +179,7 @@ export function createPointsLinesLanePreparationAdapter<Resource>(
     contract: createPointsLinesLaneContract(lane, backend),
     prepare: (snapshot, mesh) => preparation.prepare(snapshot, mesh),
     resetForDeviceLoss: () => preparation.resetForDeviceLoss(),
+    abandonForDeviceLoss: () => preparation.abandonForDeviceLoss(),
     lastKnownGood: () => preparation.lastKnownGood(),
     inspect: () => preparation.inspect(),
   };

package/src/points-lines/standard-owner.ts

@@ -0,0 +1,403 @@
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { err, ok } from '@forgeax/engine-rhi';
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { PointsLinesMaterialUnsupportedError } from '../errors/render';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
+import type { ValidatedRenderable } from '../record/frame-snapshot';
+import type {
+  PointsLinesRecordOwner,
+  PointsLinesRecordSubmission,
+  RenderSystemInternals,
+} from '../record/render-context';
+import type { RecoveryPointsLinesCandidate } from '../render-system';
+import { admitPointsLines } from './admission';
+import { PointsLinesExpansionCache } from './expansion-cache';
+import type { PointsLinesInspection, PointsLinesSourceError } from './inspection';
+import { inspectPointsLines } from './inspection';
+import {
+  createPointsLinesLanePreparationAdapter,
+  type PointsLinesLanePreparationAdapter,
+} from './prepare';
+import {
+  createPointsLinesLaneAdapter,
+  type PointsLinesBackend,
+  type PointsLinesLane,
+} from './record';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+type PointsLinesGpuResources = {
+  readonly vertexBuffer: import('@forgeax/engine-rhi').Buffer;
+  readonly indexBuffer: import('@forgeax/engine-rhi').Buffer;
+};
+type PointsLinesPreparationAdapter = PointsLinesLanePreparationAdapter<PointsLinesGpuResources>;
+
+/**
+ * The Standard renderer's single Points/Lines prepare owner.
+ *
+ * The retained snapshot is the identity boundary; this owner only resolves
+ * the source assets, runs admission, and publishes the existing preparation
+ * and record contracts to the main geometry loop. The expansion cache is
+ * shared across lanes and this owner keeps the one prepared vertex/index
+ * resource pair for each retained identity.
+ */
+export class StandardPointsLinesOwner implements PointsLinesRecordOwner {
+  private readonly cache = new PointsLinesExpansionCache();
+  private readonly preparations = new Map<string, PointsLinesPreparationAdapter>();
+  private readonly active = new Map<string, PointsLinesInspection>();
+  private readonly layoutProjection = deriveVertexLayoutProjection({
+    position: new Float32Array(0),
+    normal: new Float32Array(0),
+    uv: new Float32Array(0),
+    tangent: new Float32Array(0),
+  });
+
+  constructor(private readonly internals: RenderSystemInternals) {}
+
+  beginFrame(): void {
+    this.active.clear();
+  }
+
+  prepare(entry: ValidatedRenderable, clustered: boolean): PointsLinesRecordSubmission | undefined {
+    return this.prepareWithMaps(entry, clustered, this.internals, this.preparations, this.active);
+  }
+
+  prepareRecoveryCandidate(
+    entries: readonly ValidatedRenderable[],
+    clustered: boolean,
+    runtime: RenderSystemInternals,
+  ): RecoveryPointsLinesCandidate | undefined {
+    const stagedPreparations = new Map<string, PointsLinesPreparationAdapter>();
+    const stagedInspections = new Map<string, PointsLinesInspection>();
+    let pointEntryCount = 0;
+    try {
+      for (const entry of entries) {
+        const snapshot = entry.source.pointsLines;
+        if (snapshot?.component === undefined) continue;
+        pointEntryCount += 1;
+        const prepared = this.prepareWithMaps(
+          entry,
+          clustered,
+          runtime,
+          stagedPreparations,
+          stagedInspections,
+        );
+        if (prepared === undefined) {
+          throw new Error(
+            `recovery Points/Lines preparation failed for ${snapshot.worldId}:${snapshot.entityKey}`,
+          );
+        }
+      }
+    } catch (cause) {
+      for (const preparation of stagedPreparations.values()) {
+        preparation.resetForDeviceLoss();
+      }
+      throw cause;
+    }
+    if (pointEntryCount === 0) return undefined;
+
+    let released = false;
+    let published = false;
+    const candidate: RecoveryPointsLinesCandidate = {
+      createRecoveryRoot: (scope) => ({
+        kind: 'buffer',
+        create: () => {
+          if (!scope.isAlive() || released) {
+            throw new Error('Points/Lines recovery candidate scope is not active.');
+          }
+          return candidate;
+        },
+        cleanup: () => candidate.release(),
+      }),
+      publish: () => {
+        if (released || published) return;
+        this.preparations.clear();
+        for (const [key, preparation] of stagedPreparations) {
+          this.preparations.set(key, preparation);
+        }
+        published = true;
+      },
+      release: () => {
+        if (released || published) return;
+        released = true;
+        for (const preparation of stagedPreparations.values()) {
+          preparation.resetForDeviceLoss();
+        }
+        stagedPreparations.clear();
+        stagedInspections.clear();
+      },
+    };
+    return candidate;
+  }
+
+  private prepareWithMaps(
+    entry: ValidatedRenderable,
+    clustered: boolean,
+    runtime: RenderSystemInternals,
+    preparations: Map<string, PointsLinesPreparationAdapter>,
+    inspections: Map<string, PointsLinesInspection>,
+  ): PointsLinesRecordSubmission | undefined {
+    const snapshot = entry.source.pointsLines;
+    if (snapshot === undefined || snapshot.component === undefined || entry.world === undefined) {
+      return undefined;
+    }
+    const key = `${snapshot.worldId}:${snapshot.entityKey}`;
+    const topology = snapshot.component === 'Points' ? 'point-list' : 'line-list';
+    const backend = this.backend(runtime);
+    const lane = backend === 'wgpu-webgl2' ? 'cpu-webgl2' : clustered ? 'clustered' : 'direct';
+    const meshResult = resolveAssetHandle<MeshAsset>(
+      entry.world,
+      toShared<'MeshAsset'>(entry.source.assetHandle),
+    );
+    const materialResult = resolveAssetHandle<MaterialAsset>(
+      entry.world,
+      toShared<'MaterialAsset'>(snapshot.materialHandle),
+    );
+    if (!meshResult.ok || !materialResult.ok) {
+      this.publishRefusal(
+        inspections,
+        snapshot,
+        new PointsLinesMaterialUnsupportedError({
+          entity: snapshot.entityKey,
+          material: 'unresolved',
+          pass: 'forward',
+          module: 'asset-resolution',
+          reason: 'source MeshAsset or MaterialAsset could not be resolved',
+        }),
+      );
+      return undefined;
+    }
+    const admission = admitPointsLines({
+      entity: snapshot.entityKey,
+      mesh: meshResult.value,
+      material: materialResult.value,
+      ...(snapshot.style?.kind === 'points'
+        ? {
+            points: {
+              sizePx: snapshot.style.sizePx,
+              shape: snapshot.style.shape === 'circle' ? 1 : 0,
+            },
+          }
+        : { lines: { widthPx: snapshot.style?.widthPx ?? 1 } }),
+    });
+    if (!admission.ok) {
+      this.publishRefusal(inspections, snapshot, admission.error);
+      return undefined;
+    }
+    const geometryKey = this.cache.getOrCreate(snapshot, meshResult.value).key;
+    const prepKey = `${geometryKey}:${lane}:${backend}`;
+    let preparation = preparations.get(prepKey);
+    if (preparation === undefined) {
+      // A new expansion is visible cold upload work. Candidate preparation
+      // uses an unarmed runtime and stages the result; the published runtime
+      // is armed, so a missing staged resource fails before any RHI create.
+      runtime.recoveryColdWorkGuard?.noteUploadColdWork();
+      preparation = this.createPreparation(runtime, geometryKey, lane, backend);
+      preparations.set(prepKey, preparation);
+    } else if (preparation.lastKnownGood()?.geometry.key !== geometryKey) {
+      runtime.recoveryColdWorkGuard?.noteUploadColdWork();
+    }
+    const prepared = preparation.prepare(snapshot, meshResult.value);
+    if (!prepared.ok) {
+      const lkg = preparation.lastKnownGood();
+      if (lkg !== undefined) {
+        const lkgPlan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+          lkg.snapshot,
+          lkg.geometry,
+        );
+        const state = preparation.inspect();
+        inspections.set(
+          key,
+          inspectPointsLines({
+            snapshot,
+            topology,
+            lane,
+            pointCount: lkg.geometry.pointCount,
+            segmentCount: lkg.geometry.segmentCount,
+            sourceBytes: lkg.geometry.sourceBytes,
+            derivedBytes: lkg.geometry.derivedBytes,
+            cache: { hit: true, rebuilds: state.rebuilds, evictions: 0 },
+            drawCount: lkgPlan.drawCount,
+            uploadBytes: 0,
+            lastKnownGood: true,
+            refusal: {
+              code: prepared.error.code,
+              expected: prepared.error.expected,
+              hint: prepared.error.hint,
+              detail: prepared.error.detail,
+              generation: prepared.error.detail.generation,
+              lastKnownGood: true,
+            },
+          }),
+        );
+        return {
+          plan: lkgPlan,
+          vertexBuffer: lkg.resource.vertexBuffer,
+          indexBuffer: lkg.resource.indexBuffer,
+          layoutProjection: this.layoutProjection,
+        };
+      }
+      this.publishRefusal(inspections, snapshot, prepared.error);
+      return undefined;
+    }
+    const plan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+      snapshot,
+      prepared.value.geometry,
+    );
+    const state = preparation.inspect();
+    inspections.set(
+      key,
+      inspectPointsLines({
+        snapshot,
+        topology,
+        lane,
+        pointCount: prepared.value.geometry.pointCount,
+        segmentCount: prepared.value.geometry.segmentCount,
+        sourceBytes: prepared.value.geometry.sourceBytes,
+        derivedBytes: prepared.value.geometry.derivedBytes,
+        cache: {
+          hit: prepared.value.uploadedBytes === 0,
+          rebuilds: state.rebuilds,
+          evictions: 0,
+        },
+        drawCount: plan.drawCount,
+        uploadBytes: prepared.value.uploadedBytes,
+        lastKnownGood: prepared.value.lastKnownGood,
+      }),
+    );
+    return {
+      plan,
+      vertexBuffer: prepared.value.resource.vertexBuffer,
+      indexBuffer: prepared.value.resource.indexBuffer,
+      layoutProjection: this.layoutProjection,
+    };
+  }
+
+  resetForDeviceLoss(): void {
+    for (const preparation of this.preparations.values()) preparation.resetForDeviceLoss();
+    this.active.clear();
+  }
+
+  abandonForDeviceLoss(): void {
+    for (const preparation of this.preparations.values()) {
+      preparation.abandonForDeviceLoss();
+    }
+    this.active.clear();
+  }
+
+  dispose(): void {
+    this.resetForDeviceLoss();
+    this.preparations.clear();
+  }
+
+  inspections(): readonly PointsLinesInspection[] {
+    return [...this.active.values()];
+  }
+
+  private backend(runtime: RenderSystemInternals): PointsLinesBackend {
+    switch (runtime.device.caps.backendKind) {
+      case 'wgpu-webgl2':
+        return 'wgpu-webgl2';
+      case 'null':
+        return 'null';
+      default:
+        return 'webgpu';
+    }
+  }
+
+  private publishRefusal(
+    inspections: Map<string, PointsLinesInspection>,
+    snapshot: PointsLinesRetainedSnapshot,
+    error: PointsLinesSourceError,
+  ): void {
+    inspections.set(
+      `${snapshot.worldId}:${snapshot.entityKey}`,
+      inspectPointsLines({
+        snapshot,
+        topology: snapshot.component === 'Points' ? 'point-list' : 'line-list',
+        lane: 'refused',
+        pointCount: 0,
+        segmentCount: 0,
+        sourceBytes: 0,
+        derivedBytes: 0,
+        cache: { hit: false, rebuilds: 0, evictions: 0 },
+        drawCount: 0,
+        uploadBytes: 0,
+        lastKnownGood: false,
+        refusal: {
+          code: error.code,
+          expected: error.expected,
+          hint: error.hint,
+          detail: error.detail,
+          generation: snapshot.meshGeneration,
+          lastKnownGood: false,
+        },
+      }),
+    );
+  }
+
+  private createPreparation(
+    runtime: RenderSystemInternals,
+    geometryKey: string,
+    lane: PointsLinesLane,
+    backend: PointsLinesBackend,
+  ): PointsLinesPreparationAdapter {
+    return createPointsLinesLanePreparationAdapter(lane, backend, {
+      cache: this.cache,
+      adapter: {
+        create: (geometry) => {
+          const vertex = runtime.device.createBuffer({
+            label: `points-lines-vertices:${geometryKey}`,
+            size: Math.max(4, geometry.vertices.byteLength),
+            usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!vertex.ok) return err(vertex.error);
+          const index = runtime.device.createBuffer({
+            label: `points-lines-indices:${geometryKey}`,
+            size: Math.max(4, geometry.indices.byteLength),
+            usage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!index.ok) {
+            runtime.device.destroyBuffer(vertex.value);
+            return err(index.error);
+          }
+          return ok({ vertexBuffer: vertex.value, indexBuffer: index.value });
+        },
+        upload: (resource, geometry) => {
+          if (geometry.vertices.byteLength > 0) {
+            const vertexWrite = runtime.device.queue.writeBuffer(
+              resource.vertexBuffer,
+              0,
+              geometry.vertices,
+            );
+            if (!vertexWrite.ok) return err(vertexWrite.error);
+          }
+          if (geometry.indices.byteLength > 0) {
+            const indexWrite = runtime.device.queue.writeBuffer(
+              resource.indexBuffer,
+              0,
+              geometry.indices,
+            );
+            if (!indexWrite.ok) return err(indexWrite.error);
+          }
+          return ok(geometry.derivedBytes);
+        },
+        validate: (_resource, geometry) =>
+          geometry.expandedVertexCount > 0 && geometry.expandedIndexCount > 0
+            ? ok(undefined)
+            : err(new Error('Points/Lines expansion contains no drawable triangles')),
+        destroy: (resource) => {
+          runtime.device.destroyBuffer(resource.vertexBuffer);
+          runtime.device.destroyBuffer(resource.indexBuffer);
+        },
+      },
+    });
+  }
+}

package/src/prepare/__tests__/extended-lighting-capability.unit.test.ts

@@ -0,0 +1,56 @@
+import type { RhiCaps, RhiDevice } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { deriveExtendedLightingCapability } from '../extended-lighting/resources';
+
+const device = {
+  caps: {
+    backendKind: 'null',
+    compute: true,
+    storageBuffer: true,
+    storageTexture: true,
+    rgba16floatRenderable: true,
+    samplerAliasing: true,
+  } as RhiCaps,
+  limits: {
+    maxSampledTexturesPerShaderStage: 20,
+    maxTextureDimension2D: 4096,
+    maxTextureArrayLayers: 32,
+    maxUniformBuffersPerShaderStage: 12,
+  },
+} as unknown as RhiDevice;
+
+describe('extended lighting capability admission', () => {
+  it('derives admission from real format, filter, array, and uniform facts', () => {
+    expect(deriveExtendedLightingCapability(device)).toEqual({
+      admitted: true,
+      topology: 'extendedLighting',
+      reason: undefined,
+    });
+  });
+
+  it('rejects a device whose array or uniform limit cannot hold the contract', () => {
+    const limited = {
+      ...device,
+      limits: { ...device.limits, maxTextureArrayLayers: 16, maxUniformBuffersPerShaderStage: 0 },
+    } as RhiDevice;
+
+    expect(deriveExtendedLightingCapability(limited)).toMatchObject({
+      admitted: false,
+      topology: 'extendedLighting',
+      reason: expect.stringContaining('maxTextureArrayLayers'),
+    });
+  });
+
+  it('rejects the topology when the sampled-texture limit is below the shader contract', () => {
+    const limited = {
+      ...device,
+      limits: { ...device.limits, maxSampledTexturesPerShaderStage: 16 },
+    } as RhiDevice;
+
+    expect(deriveExtendedLightingCapability(limited)).toEqual({
+      admitted: false,
+      topology: 'extendedLighting',
+      reason: 'maxSampledTexturesPerShaderStage 16 < 20',
+    });
+  });
+});