@forgeax/engine-render 0.1.20 → 0.1.23

package/src/pipeline/standard-post.ts

@@ -11,7 +11,11 @@ import type {
   RenderPipelineFrame,
   RenderPipelineTopology,
 } from '../render-pipeline';
-import { createRenderPipelineTarget, type RenderPipelineTarget } from '../render-pipeline';
+import {
+  createRenderPipelineTarget,
+  type RenderPipelineTarget,
+  resolveOutputDither,
+} from '../render-pipeline';
 import {
   addTypedBloomPasses,
   addTypedCompositePostEffects,
@@ -134,7 +138,7 @@ function missingTemporalContributor(
   return new SceneDataUnavailableError({
     featureIdentity: 'forgeax::standard',
     schema: 'forgeax::scene-data::temporal-v1',
-    lane: topology.lane.compute ? (topology.standardProfile?.lighting ?? 'direct') : 'cpu-webgl2',
+    lane: topology.lane.compute ? 'clustered' : 'cpu-webgl2',
     reason: 'producer-missing',
     missingContributorIds: [contributorId],
     omittedMissingContributorCount: 0,
@@ -165,9 +169,13 @@ export function addStandardPost(
   // left clear and the following Output Transform presents a black frame.
   const bloomActive = hdr && topology.camera.bloom === 'on' && topology.camera.tonemap !== 'none';
   const fxaa = !clearOnly && topology.camera.antialias === 'fxaa';
-  const msaa = !clearOnly && topology.camera.antialias === 'msaa' && topology.lane.multisample;
-  const linearLdr = !clearOnly && ((!hdr && topology.lane.storageBuffer) || fxaa || msaa);
+  // All non-clear Standard frames use the graph-owned float scene target and
+  // the shared Output Transform, even when AA is disabled or the backend has
+  // no storage buffers.  This keeps the final dither at one owner-level
+  // surface boundary instead of making no-AA/WebGL2 a silent bypass.
+  const linearLdr = !clearOnly && !hdr;
   const rawOnly = !clearOnly && topology.surface.profile?.kind === 'raw-only';
+  const outputDither = resolveOutputDither(topology.config);
   const motionBlur = !clearOnly && topology.temporal?.motionBlur === true;
   const postEffects = clearOnly ? [] : (topology.config?.postEffects ?? []);
   const rawOnlyPostInput =
@@ -312,7 +320,11 @@ export function addStandardPost(
         domain: 'display-encoded',
       });
       if (!output.ok) return output;
-      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, output.value);
+      // FXAA samples this display-encoded intermediate; leave dither to the
+      // final FXAA writer so the same pixel is not dithered twice.
+      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, output.value, {
+        dither: false,
+      });
       if (!outputTransform.ok) return outputTransform;
       const aa = addTypedFullscreenPass(context.graph, {
         name: 'fxaa',
@@ -326,13 +338,20 @@ export function addStandardPost(
         context.graph,
         postInput,
         rawOnlyPostInput.value,
+        {
+          dither: outputDither && postEffects.length === 0,
+        },
       );
       if (!transformed.ok) return transformed;
     } else if (rawOnly || linearLdr) {
-      const transformed = addTypedOutputTransformPass(context.graph, postInput, finalPresent);
+      const transformed = addTypedOutputTransformPass(context.graph, postInput, finalPresent, {
+        dither: outputDither,
+      });
       if (!transformed.ok) return transformed;
     } else {
-      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, finalPresent);
+      const outputTransform = addTypedOutputTransformPass(context.graph, postInput, finalPresent, {
+        dither: outputDither,
+      });
       if (!outputTransform.ok) return outputTransform;
     }
   }

package/src/pipeline/standard-profile.ts

@@ -1,25 +1,22 @@
 export const STANDARD_PIPELINE_ID = 'forgeax::standard' as const;
 export const STANDARD_LIGHT_COUNTS = [1, 32, 256] as const;
-/** Shared clustered-lighting facts consumed by pipeline, record, and buffers. */
-export const DEFAULT_CLUSTER_GRID = { x: 16, y: 9, z: 24 } as const;
-export const CLUSTER_GRID_STRIDE_U32 = 2;
-export const LIGHT_INDEX_LIST_CAPACITY = 1048576;
-export const MAX_LIGHTS = 256;
+export {
+  CLUSTER_GRID_STRIDE_U32,
+  DEFAULT_CLUSTER_GRID,
+  LIGHT_INDEX_LIST_CAPACITY,
+  MAX_LIGHTS,
+} from './standard-lighting/layout';
 
 export type StandardLightCount = (typeof STANDARD_LIGHT_COUNTS)[number];
-export type StandardLightingLane = 'direct' | 'clustered';
-export type StandardFallbackLane = 'native' | 'cpu-webgl2';
 export type StandardShadowMode = 'off' | 'hard' | 'filtered';
-export type StandardTone =
-  | 'none'
-  | 'aces-filmic'
-  | 'agx'
-  | 'cineon'
-  | 'linear'
-  | 'neutral'
-  | 'reinhard'
-  | 'reinhard-extended';
-export type StandardAntialias = 'none' | 'fxaa' | 'msaa';
+export type StandardVolumetricFogQuality = 'low' | 'high';
+
+export interface StandardVolumetricFogProfile {
+  readonly quality: StandardVolumetricFogQuality;
+  readonly depth: 48 | 64;
+  readonly tileSize: 4 | 16;
+}
+
 export const STANDARD_POST_STAGE_NAMES = [
   'transparent-blend',
   'bloom',
@@ -29,45 +26,28 @@ export const STANDARD_POST_STAGE_NAMES = [
   'present',
 ] as const;
 export type StandardPostStage = (typeof STANDARD_POST_STAGE_NAMES)[number];
-export type StandardVolumetricFogQuality = 'low' | 'high';
-
-export interface StandardVolumetricFogProfile {
-  readonly quality: StandardVolumetricFogQuality;
-  readonly depth: 48 | 64;
-  readonly tileSize: 4 | 16;
-}
-
 export interface StandardProfile {
   readonly pipelineId: typeof STANDARD_PIPELINE_ID;
   readonly lightCount: StandardLightCount;
-  readonly lighting: StandardLightingLane;
+  /** Graph topology selector; all local lights use the shared Cluster path. */
+  readonly renderPath: 'forward' | 'deferred';
   readonly shadows: StandardShadowMode;
   readonly pbr: boolean;
   readonly ibl: boolean;
   readonly ssao: boolean;
-  readonly bloom: boolean;
-  readonly tone: StandardTone;
-  readonly antialias: StandardAntialias;
-  readonly sky: boolean;
   /** Renderer-owned 1080p volume profile; tile width/height remain surface-derived. */
   readonly volumetricFog?: StandardVolumetricFogProfile | undefined;
-  readonly fallback: StandardFallbackLane;
   readonly postStages: typeof STANDARD_POST_STAGE_NAMES;
 }
 
 export const DEFAULT_STANDARD_PROFILE: StandardProfile = Object.freeze({
   pipelineId: STANDARD_PIPELINE_ID,
   lightCount: 32,
-  lighting: 'direct',
+  renderPath: 'forward',
   shadows: 'filtered',
   pbr: true,
   ibl: true,
   ssao: false,
-  bloom: true,
-  tone: 'aces-filmic',
-  antialias: 'fxaa',
-  sky: true,
-  fallback: 'native',
   postStages: STANDARD_POST_STAGE_NAMES,
 });
 
@@ -76,13 +56,3 @@ export function resolveVolumetricFogProfile(
 ): StandardVolumetricFogProfile {
   return profile.volumetricFog ?? { quality: 'high', depth: 64, tileSize: 4 };
 }
-
-export type StandardLane = StandardLightingLane | 'cpu-webgl2';
-
-export function resolveStandardLane(
-  profile: Pick<StandardProfile, 'lighting'>,
-  capabilities: { readonly compute: boolean; readonly storageBuffer: boolean },
-): StandardLane {
-  if (!capabilities.compute || !capabilities.storageBuffer) return 'cpu-webgl2';
-  return profile.lighting;
-}

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

@@ -287,6 +287,80 @@ export function variantSetFromVertexLayoutProjection(
   return ok(parts.join('+'));
 }
 
+/**
+ * Derive the capability axes shared by every Standard PBR draw owner.
+ *
+ * The all-true key is the canonical empty key used by the shader manifest;
+ * every other capability pair stays explicit so a no-local-light frame on a
+ * device without storage buffers cannot accidentally select a storage-backed
+ * PSO. Vertex-color is supplied here because the empty-key rule is only valid
+ * when that geometry-owned axis is also true.
+ */
+export function standardCapabilityVariantSet(
+  clustered: boolean,
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  if (clustered && storageBuffer && vertexColorAvailable) return '';
+  return `CLUSTER_FORWARD_AVAILABLE=${clustered}+STORAGE_BUFFER_AVAILABLE=${storageBuffer}`;
+}
+
+/**
+ * Project the frame-owned Standard topology onto its material variant axes.
+ *
+ * `StandardTopologyInputValue.kind` is the only runtime authority for the
+ * cluster axis: a frame with local lights must request the clustered artifact,
+ * while the no-local-light topology requests the direct artifact.  Keeping
+ * this projection beside the canonical key builder prevents PBR, skin, and
+ * sprite-lit record owners from independently inferring the active lane from
+ * whichever bind group happened to be constructed first.
+ */
+export function standardTopologyVariantSet(
+  topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+  probeBlendAvailable = false,
+): string {
+  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`;
+}
+
+/**
+ * Keep a clustered frame fail-closed when its unified group(2) resource is
+ * unavailable. A missing group is not evidence that the frame is direct; it
+ * is an invalid prepared resource state.
+ */
+export function standardTopologyBindGroupReady(
+  topology: { readonly kind: 'no-local-lights' | 'clustered' } | undefined,
+  clusterBindGroup: unknown,
+): boolean {
+  return (
+    topology?.kind !== 'clustered' || (clusterBindGroup !== null && clusterBindGroup !== undefined)
+  );
+}
+
+/** Derive the storage axis for Standard-compatible unlit material draws. */
+export function standardStorageVariantSet(
+  storageBuffer: boolean,
+  vertexColorAvailable: boolean,
+): string {
+  if (storageBuffer && vertexColorAvailable) return '';
+  return `STORAGE_BUFFER_AVAILABLE=${storageBuffer}+VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`;
+}
+
 /**
  * Build a `GPURenderPipelineDescriptor` from a PipelineSpec + shader modules.
  *
@@ -925,14 +999,14 @@ const TRI_GEOMETRY_PBR = {
   shaderUvSetCount: 8,
 };
 
-// M6 fix-up: URP-variant key string for the standard PBR shader. Mirrors the
-// boot-time variantSet computed at createRenderer.ts step 1b when
-// `isHdrpActive=false` and `storageBufferCapable=true` (the URP default
-// surface). The URP record path requests this exact string at every
+// M6 fix-up: non-clustered boot-variant key string for the standard PBR shader.
+// Mirrors the boot-time variantSet computed at createRenderer.ts step 1b when
+// clustered lighting is not yet admitted and `storageBufferCapable=true` (the
+// surface). The default record path requests this exact string at every
 // `getMaterialShaderPipeline` call site, so seeding the table with these
-// variants keeps the URP cache lookup hot from frame 1 instead of
+// variants keeps the default cache lookup hot from frame 1 instead of
 // skip-drawing the first ~1 frames while the async compile resolves.
-const URP_PBR_VARIANT_SET = 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
+const STANDARD_BOOT_VARIANT_SET = standardCapabilityVariantSet(false, true, false);
 
 /**
  * Build the boot-time pre-warm table: 15 standard PipelineSpec variants.
@@ -944,22 +1018,22 @@ const URP_PBR_VARIANT_SET = 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAI
  *
  * Matrix:
  *   - 8 base material variants — {unlit, standard-pbr} x {LDR, HDR} x {S1, S4}
- *   - 4 URP-variant standard-pbr — standard-pbr (variantSet=URP_PBR_VARIANT_SET)
- *     x {LDR, HDR} x {S1, S4}; URP record path requests these specs by
+ *   - 4 non-clustered standard-pbr — standard-pbr (variantSet=STANDARD_BOOT_VARIANT_SET)
+ *     x {LDR, HDR} x {S1, S4}; the default record path requests these specs by
  *     `getMaterialShaderPipeline` keying off `cacheKeyOf` so the boot-time
  *     prewarm seeds `materialShaderPipelineCache` and avoids a 1-frame
- *     async-compile skip-draw (M6 fix-up; see render-system-record.ts §URP)
+ *     async-compile skip-draw (M6 fix-up; see render-system-record.ts)
  *   - 3 fullscreen-post — tonemap (LDR S1) + skybox (HDR S1, HDR S4)
  *
- * Total: 15. The URP variant is PBR-only because:
- *   - unlit URP record path passes `variantSet=undefined` (the no-variant
+ * Total: 15. The non-clustered variant is PBR-only because:
+ *   - unlit record path passes `variantSet=undefined` (the no-variant
  *     boot-default entries already cover it; createRenderer.ts §unlitRsp)
  *   - sprite goes through `getMaterialShaderPipeline('forgeax::sprite', ...)`
  *     lazily at first transparent-LDR-split draw — no boot-time pre-warm.
- *   - HDRP variant (`variantSet=''` or compound `=true` form) is registered
+ *   - clustered variant (`variantSet=''` or compound `=true` form) is registered
  *     lazily when the clustered Standard profile activates, not at boot — adding clustered
  *     prewarm here would build PSOs against the URP layout (the boot-time
- *     `pbrModule` is the URP variant when `isHdrpActive=false`)
+ *     `pbrModule` is the non-clustered variant before a frame admits local lights)
  *
  * `ldrViewFormat` parameterises the LDR color attachment format. Callers
  * pass the runtime-resolved swap-chain view format (Channel 2 typically
@@ -1074,12 +1148,12 @@ export function buildSpecConstTable(
       renderState: undefined,
     },
 
-    // ── M6 fix-up: URP-variant standard-pbr prewarm ─────────────────────────
-    // URP record path (`getMaterialShaderPipeline`) requests
-    // `variantSet=URP_PBR_VARIANT_SET` for standard-shading entities; pre-M6
+    // ── M6 fix-up: non-clustered standard-pbr prewarm ─────────────────────────
+    // The default record path (`getMaterialShaderPipeline`) requests
+    // `variantSet=STANDARD_BOOT_VARIANT_SET` for standard-shading entities; pre-M6
     // the silent `selectStandardFallbackPipeline` shim served the no-variant
     // boot prewarm during the 1-frame async-compile warmup. With M6's
-    // explicit-failure surface, those URP requests must hit the boot prewarm
+    // explicit-failure surface, those requests must hit the boot prewarm
     // by their own variantSet — these 4 entries close that gap.
 
     // standard PBR URP LDR S1
@@ -1087,7 +1161,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_LDR_S1,
       geometry: TRI_GEOMETRY_PBR,
@@ -1098,7 +1172,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_LDR_S4,
       geometry: TRI_GEOMETRY_PBR,
@@ -1109,7 +1183,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_HDR_S1,
       geometry: TRI_GEOMETRY_PBR,
@@ -1120,7 +1194,7 @@ export function buildSpecConstTable(
       shader: {
         id: 'forgeax::default-standard-pbr',
         passKind: 'forward',
-        variantSet: URP_PBR_VARIANT_SET,
+        variantSet: STANDARD_BOOT_VARIANT_SET,
       },
       attachments: TRI_ATTACHMENTS_HDR_S4,
       geometry: TRI_GEOMETRY_PBR,

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/point-shadow-inspection.ts

@@ -0,0 +1,55 @@
+import type { PointShadowSnapshot } from './render-system-extract';
+
+/**
+ * Detached point-shadow budget facts from one completed extract/record frame.
+ *
+ * `requested` is the number of PointLight + PointLightShadow pairs. The
+ * renderer owns the bounded cube-array atlas, so `admitted`, `shadowed`, and
+ * `shadowAtlasOccupancy` are all derived from the layer sentinel emitted by
+ * the same extract owner. No consumer needs to maintain a second budget
+ * ledger.
+ */
+export interface PointShadowInspection {
+  readonly status: 'inactive' | 'ready' | 'over-budget';
+  readonly requested: number;
+  readonly admitted: number;
+  readonly shadowed: number;
+  readonly shadowAtlasOccupancy: number;
+  readonly shadowAtlasCapacity: number;
+}
+
+/** Project point-shadow snapshots to the public, JSON-safe inspection shape. */
+export function inspectPointShadow(
+  snapshots: readonly PointShadowSnapshot[],
+  shadowAtlasCapacity: number,
+): PointShadowInspection {
+  const requested = snapshots.length;
+  const admitted = snapshots.reduce(
+    (count, snapshot) =>
+      snapshot.shadowAtlasLayer >= 0 && snapshot.shadowAtlasLayer < shadowAtlasCapacity
+        ? count + 1
+        : count,
+    0,
+  );
+  // Never publish a misleading `ready` state when any requested shadow owns
+  // no atlas layer. The extract sentinel is the single admission projection;
+  // a partial or all-sentinel frame is therefore a failed/over-budget
+  // admission, not an active shadow path with incomplete output.
+  const status =
+    requested === 0
+      ? ('inactive' as const)
+      : requested > shadowAtlasCapacity || admitted !== requested
+        ? ('over-budget' as const)
+        : ('ready' as const);
+  return Object.freeze({
+    status,
+    requested,
+    admitted,
+    // A point shadow only samples an atlas after it owns an atlas layer. Keep
+    // these names explicit for AI diagnostics while deriving both from the
+    // one layer projection above.
+    shadowed: admitted,
+    shadowAtlasOccupancy: admitted,
+    shadowAtlasCapacity,
+  });
+}

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',
+    });
+  });
+});

package/src/prepare/extended-lighting/ltc-resources.ts

@@ -0,0 +1,136 @@
+// @forgeax/engine-render - DeviceScope-owned RectArea LTC resources.
+
+import type { Result, RhiDevice, RhiError, Texture } from '@forgeax/engine-rhi';
+import { LTC_TABLE_HEIGHT, LTC_TABLE_WIDTH, LTC_TABLES } from '@forgeax/engine-shader';
+import { err, ok } from '@forgeax/engine-types';
+import { type DeviceScope, LifecycleTransaction } from '../../device/device-scope';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../../gpu-texture-usage';
+import { deriveExtendedLightingCapability, EXTENDED_LIGHTING_TOPOLOGY } from './resources';
+
+export interface LtcResourcePlanInput {
+  readonly scope: DeviceScope;
+  readonly ltcAvailable: boolean;
+  readonly residentGeneration?: number;
+}
+
+export interface LtcResourcePlan {
+  readonly topology: typeof EXTENDED_LIGHTING_TOPOLOGY;
+  readonly generation: number;
+  readonly rectAdmission: 'admitted' | 'omitted';
+  readonly tableCount: number;
+  readonly uploadCount: number;
+}
+
+export interface LtcResourceCandidate {
+  readonly topology: typeof EXTENDED_LIGHTING_TOPOLOGY;
+  readonly generation: number;
+  readonly scope: DeviceScope;
+  readonly lambertTexture: Texture;
+  readonly ggxTexture: Texture;
+  readonly tableCount: 2;
+  readonly uploadCount: 2;
+}
+
+export function deriveLtcResourcePlan(input: LtcResourcePlanInput): LtcResourcePlan {
+  const admitted = input.ltcAvailable;
+  return {
+    topology: EXTENDED_LIGHTING_TOPOLOGY,
+    generation: input.scope.generation,
+    rectAdmission: admitted ? 'admitted' : 'omitted',
+    tableCount: admitted ? 2 : 0,
+    uploadCount: admitted && input.residentGeneration !== input.scope.generation ? 2 : 0,
+  };
+}
+
+function failure(expected: string, actual: string): Result<never, RhiError> {
+  return err({
+    code: 'webgpu-runtime-error',
+    expected,
+    hint: 'inspect device capabilities and retry the extendedLighting candidate',
+    detail: { error: { code: 'ltc-resource', message: actual } },
+  } as RhiError);
+}
+
+function textureBytes(table: Uint16Array): Uint8Array {
+  return new Uint8Array(table.buffer, table.byteOffset, table.byteLength);
+}
+
+/** Create both tracked tables atomically; unavailable LTC only omits Rect. */
+export async function createLtcResourceCandidate(input: {
+  readonly device: RhiDevice | undefined;
+  readonly scope: DeviceScope;
+}): Promise<Result<LtcResourceCandidate | undefined, RhiError>> {
+  if (input.device === undefined) return ok(undefined);
+  if (!deriveExtendedLightingCapability(input.device).admitted) return ok(undefined);
+  const device = input.device;
+
+  const transaction = new LifecycleTransaction(input.scope);
+  let lambertTexture: Texture | undefined;
+  let ggxTexture: Texture | undefined;
+  const createTable = (label: string, table: Uint16Array): Texture => {
+    const texture = device.createTexture({
+      label,
+      size: { width: LTC_TABLE_WIDTH, height: LTC_TABLE_HEIGHT, depthOrArrayLayers: 1 },
+      mipLevelCount: 1,
+      sampleCount: 1,
+      dimension: '2d',
+      format: 'rgba16float',
+      usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+      viewFormats: [],
+      textureBindingViewDimension: undefined,
+    });
+    if (texture === undefined || !texture.ok) {
+      throw texture?.error ?? new Error('LTC texture creation returned no result');
+    }
+    const write = device.queue.writeTexture(
+      { texture: texture.value, mipLevel: 0, origin: { x: 0, y: 0, z: 0 } },
+      textureBytes(table),
+      { offset: 0, bytesPerRow: LTC_TABLE_WIDTH * 8, rowsPerImage: LTC_TABLE_HEIGHT },
+      { width: LTC_TABLE_WIDTH, height: LTC_TABLE_HEIGHT, depthOrArrayLayers: 1 },
+    );
+    if (!write.ok) throw write.error;
+    return texture.value;
+  };
+
+  transaction.add({
+    kind: 'texture',
+    create: () => {
+      lambertTexture = createTable('extended-lighting-ltc-lambert', LTC_TABLES.lambert);
+      return lambertTexture;
+    },
+    cleanup: (value) => {
+      const destroyed = input.device?.destroyTexture(value);
+      if (destroyed !== undefined && !destroyed.ok) throw destroyed.error;
+    },
+  });
+  transaction.add({
+    kind: 'texture',
+    create: () => {
+      ggxTexture = createTable('extended-lighting-ltc-ggx', LTC_TABLES.ggx);
+      return ggxTexture;
+    },
+    cleanup: (value) => {
+      const destroyed = input.device?.destroyTexture(value);
+      if (destroyed !== undefined && !destroyed.ok) throw destroyed.error;
+    },
+  });
+
+  const committed = await transaction.commit();
+  if (!committed.ok)
+    return failure(committed.error.primary.expected, committed.error.primary.message);
+  if (lambertTexture === undefined || ggxTexture === undefined) {
+    return failure('two LTC textures', 'the transaction committed without both tables');
+  }
+  return ok({
+    topology: EXTENDED_LIGHTING_TOPOLOGY,
+    generation: input.scope.generation,
+    scope: input.scope,
+    lambertTexture,
+    ggxTexture,
+    tableCount: 2,
+    uploadCount: 2,
+  });
+}