@forgeax/engine-render 0.1.20 → 0.1.23

package/src/extract/directional-shadow-projection.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-render - Directional CSM projection owner.
+
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
+import { directionalShadowQualityFromF32 } from '../components/directional-shadow-filter';
+
+/** Light-space bounds produced by one existing orthographic CSM fit. */
+export interface DirectionalShadowCascadeFit {
+  readonly split: number;
+  readonly minX: number;
+  readonly maxX: number;
+  readonly minY: number;
+  readonly maxY: number;
+  readonly minZ: number;
+  readonly maxZ: number;
+}
+
+/** Host projection sent to the shared View UBO. */
+export interface DirectionalShadowProjection {
+  readonly splitPlanes: Float32Array;
+  readonly directionalShadowQuality: DirectionalShadowQuality;
+}
+
+/**
+ * Project accepted Directional author facts and the existing CSM fit into the
+ * shared split vec4 lanes. `.x` is the split, `.y` is world units per texel,
+ * `.z` is the light-space depth span, and `.w` is reserved for the ABI.
+ */
+export function projectDirectionalShadow(
+  fits: readonly DirectionalShadowCascadeFit[],
+  mapSize: number,
+  shadowFilter: number,
+  shadowAngularRadius: number,
+  maxPenumbraTexels: number,
+): DirectionalShadowProjection | undefined {
+  if (!Number.isFinite(mapSize) || mapSize < 1) return undefined;
+  const directionalShadowQuality = directionalShadowQualityFromF32(
+    shadowFilter,
+    shadowAngularRadius,
+    maxPenumbraTexels,
+  );
+  if (directionalShadowQuality === undefined) return undefined;
+
+  const splitPlanes = new Float32Array(16);
+  for (let index = 0; index < fits.length && index < 4; index += 1) {
+    const fit = fits[index];
+    if (fit === undefined) continue;
+    const width = Math.abs(fit.maxX - fit.minX);
+    const height = Math.abs(fit.maxY - fit.minY);
+    const depth = Math.abs(fit.maxZ - fit.minZ);
+    const worldUnitsPerTexel = Math.max(width, height, Number.EPSILON) / mapSize;
+    const lightDepthWorldSpan = Math.max(depth, Number.EPSILON);
+    if (!Number.isFinite(worldUnitsPerTexel) || !Number.isFinite(lightDepthWorldSpan)) {
+      return undefined;
+    }
+    const lane = index * 4;
+    splitPlanes[lane] = fit.split;
+    splitPlanes[lane + 1] = worldUnitsPerTexel;
+    splitPlanes[lane + 2] = lightDepthWorldSpan;
+  }
+  return { splitPlanes, directionalShadowQuality };
+}

package/src/extract/environment.ts

@@ -76,6 +76,20 @@ export type EnvironmentSource =
 
 export interface FogFrame extends FogCandidate {}
 
+export interface FogParameterIssue {
+  readonly field: string;
+  readonly value: number;
+  readonly expected: string;
+}
+
+/** Structured failure retained when an invalid Fog update falls back to LKG. */
+export interface FogSelectionFailure {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: Readonly<Record<string, unknown>>;
+}
+
 export interface EnvironmentFrame {
   readonly source: EnvironmentSource;
   /** Descriptor of the real environment resource adopted for this frame. */
@@ -103,6 +117,49 @@ function freezeFog(candidate: FogCandidate): FogFrame {
   });
 }
 
+/** Validate the bounded Fog domain once for every frame-selection producer. */
+export function validateFogParameters(candidate: FogCandidate): FogParameterIssue | undefined {
+  if (candidate.color.length !== 3) {
+    return {
+      field: 'color',
+      value: candidate.color.length,
+      expected: 'exactly three finite channels in [0, 1]',
+    };
+  }
+  for (let index = 0; index < candidate.color.length; index += 1) {
+    const value = candidate.color[index];
+    if (value === undefined || !Number.isFinite(value) || value < 0 || value > 1) {
+      return {
+        field: `color[${index}]`,
+        value: value ?? Number.NaN,
+        expected: 'a finite number in [0, 1]',
+      };
+    }
+  }
+  if (!Number.isFinite(candidate.density) || candidate.density < 0) {
+    return { field: 'density', value: candidate.density, expected: 'a finite number >= 0' };
+  }
+  if (!Number.isFinite(candidate.heightFalloff) || candidate.heightFalloff < 0) {
+    return {
+      field: 'heightFalloff',
+      value: candidate.heightFalloff,
+      expected: 'a finite number >= 0',
+    };
+  }
+  if (
+    !Number.isFinite(candidate.maxOpacity) ||
+    candidate.maxOpacity < 0 ||
+    candidate.maxOpacity > 1
+  ) {
+    return {
+      field: 'maxOpacity',
+      value: candidate.maxOpacity,
+      expected: 'a finite number in [0, 1]',
+    };
+  }
+  return undefined;
+}
+
 function freezeAtmosphere(parameters: AtmosphereParameters): AtmosphereParameters {
   return Object.freeze({ ...parameters });
 }

package/src/extract/gpu-driven.ts

@@ -0,0 +1,108 @@
+import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
+import type { MeshAsset } from '@forgeax/engine-types';
+import {
+  type GpuDrivenDrawRange,
+  type PreparedGpuDrivenDraw,
+  type PrepareGpuDrivenDrawInput,
+  prepareGpuDrivenDraw,
+} from '../gpu-driven/prepared-draw';
+import type { MaterialSnapshot } from '../render-system-extract';
+
+export {
+  GpuDrivenPreparationError,
+  type GpuDrivenPreparationErrorCode,
+  type GpuDrivenPreparationErrorDetail,
+  type GpuDrivenPreparationReason,
+} from '../errors/gpu-driven';
+export {
+  type GpuDrivenDrawRange,
+  type GpuDrivenGeometryReceipt,
+  type GpuDrivenSkinReceipt,
+  type PreparedGpuDrivenDraw,
+  type PrepareGpuDrivenDrawInput,
+  prepareGpuDrivenDraw,
+} from '../gpu-driven/prepared-draw';
+
+export interface GpuDrivenDrawSnapshot {
+  readonly kind: GpuDrivenDrawRange['kind'];
+  readonly first: GpuDrivenDrawRange['first'];
+  readonly count: GpuDrivenDrawRange['count'];
+  readonly baseVertex: GpuDrivenDrawRange['baseVertex'];
+  readonly materialSlot: number;
+  readonly topology: GpuDrivenDrawRange['topology'];
+  readonly pipelineClass: string;
+  readonly materialResourceClass: string;
+  /** Producer-owned prepared ABI facts used by the PBR GPU lane. */
+  readonly prepared?: PreparedGpuDrivenDraw;
+}
+
+/**
+ * Resolves prepared facts once at extract time; record never re-reads assets.
+ * The resolver surfaces UV, reflection, vertex, alpha, resource, and
+ * generation failures as GpuDrivenPreparationError before recording.
+ */
+export function resolvePreparedGpuDrivenDraw(input: PrepareGpuDrivenDrawInput):
+  | { readonly ok: true; readonly value: PreparedGpuDrivenDraw }
+  | {
+      readonly ok: false;
+      readonly error: import('../errors/gpu-driven').GpuDrivenPreparationError;
+    } {
+  return prepareGpuDrivenDraw(input);
+}
+
+/** Keeps the artifact type visible at this owner boundary for contract checks. */
+export type PreparedGpuDrivenArtifact = MaterialShaderArtifact;
+
+/**
+ * Derives the resource identity consumed by the existing GPU-driven batch
+ * owner. The extract stage is the only place that resolves material values;
+ * this helper keeps the batch adapter from re-reading assets later.
+ */
+export function gpuDrivenMaterialResourceClass(material: MaterialSnapshot): string {
+  const textures = [...(material.textureHandles?.entries() ?? [])]
+    .map(([name, handle]) => [name, Number(handle)] as const)
+    .sort(([left], [right]) => left.localeCompare(right));
+  const samplers = [...(material.samplerHandles?.entries() ?? [])]
+    .map(([name, handle]) => [name, Number(handle)] as const)
+    .sort(([left], [right]) => left.localeCompare(right));
+  return JSON.stringify({
+    textures,
+    samplers,
+    video: [...(material.videoTextureFields?.keys() ?? [])].sort(),
+  });
+}
+
+/**
+ * Projects already-resolved mesh facts into the existing GPU-driven draw
+ * snapshot. No World or AssetRegistry access is permitted at this boundary.
+ */
+export function buildGpuDrivenDraws(input: {
+  readonly submeshes: readonly MeshAsset['submeshes'][number][];
+  readonly indexed: boolean;
+  readonly materials: readonly MaterialSnapshot[];
+  readonly fallbackMaterial: MaterialSnapshot;
+  readonly prepare?: (
+    draw: GpuDrivenDrawSnapshot,
+    material: MaterialSnapshot,
+  ) => PreparedGpuDrivenDraw | undefined;
+}): GpuDrivenDrawSnapshot[] {
+  let nonIndexedFirst = 0;
+  return input.submeshes.flatMap((submesh) => {
+    const drawMaterial = input.materials[submesh.materialSlot] ?? input.fallbackMaterial;
+    const first = input.indexed ? submesh.indexOffset : nonIndexedFirst;
+    nonIndexedFirst += submesh.vertexCount;
+    if (drawMaterial.transparent === true) return [];
+    const draw: GpuDrivenDrawSnapshot = {
+      kind: input.indexed ? ('indexed' as const) : ('non-indexed' as const),
+      first,
+      count: input.indexed ? submesh.indexCount : submesh.vertexCount,
+      baseVertex: 0,
+      materialSlot: submesh.materialSlot,
+      topology: submesh.topology,
+      pipelineClass: `${drawMaterial.materialShaderId ?? 'forgeax::default-unlit'}|${submesh.topology}|${JSON.stringify(drawMaterial.renderState ?? null)}`,
+      materialResourceClass: gpuDrivenMaterialResourceClass(drawMaterial),
+    };
+    const prepared = input.prepare?.(draw, drawMaterial);
+    return [prepared === undefined ? draw : { ...draw, prepared }];
+  });
+}

package/src/extract/visibility.ts

@@ -123,7 +123,7 @@ export function resolveVisibility(
     };
   };
 
-  return {
+  const snapshot: VisibilitySnapshot = {
     diagnostics: hierarchy.diagnostics,
     hasAnyIntent: intentCount > 0,
     hasAnyHiddenIntent,
@@ -136,4 +136,5 @@ export function resolveVisibility(
       return resolveEntity?.(entity)?.effective ?? 'visible';
     },
   };
+  return snapshot;
 }

package/src/features/fullscreen.ts

@@ -28,6 +28,9 @@ export function createFullscreenRenderFeature(
   const resourceName = `fullscreen.${options.identity.replace(/[^a-z0-9.-]/gi, '-').toLowerCase()}`;
   return Object.freeze({
     identity: options.identity,
+    requiredFullscreenPostProcesses: Object.freeze([
+      Object.freeze({ identity: options.identity, source: options.source }),
+    ]),
     extract: (_context: RenderFeatureExtractContext) => ok(undefined),
     plan: (_data: undefined, _context: RenderFeaturePlanContext) =>
       ok({

package/src/features/targets.ts

@@ -57,8 +57,11 @@ export function resolveStandardRenderFeatureTargets(input: {
   readonly colorAttachmentFormat: TextureFormat;
 }): readonly RenderFeatureTargetHandle[] {
   const sampleCount: 1 | 4 = input.antialias === 'msaa' && input.multisample ? 4 : 1;
+  // Standard always exposes the scene to features as a linear float target;
+  // the shared Output Transform owns the eventual RGBA8 write for every
+  // antialias mode, including no-AA/WebGL2.
   const linearLdr =
-    (input.tonemap === 'none' && input.storageBuffer) ||
+    input.tonemap === 'none' ||
     input.antialias === 'fxaa' ||
     (input.antialias === 'msaa' && input.multisample);
   const colorFormat =

package/src/features/types.ts

@@ -98,6 +98,16 @@ export interface RenderFeature<FrameData> {
    * the same lazy module cache used by prepared graphics.
    */
   readonly requiredMaterialShaders?: readonly string[];
+  /**
+   * Fullscreen program sources that must be module-ready before the first
+   * frame. The renderer seeds the same lazy post-process module cache used by
+   * the typed graph, so a synchronous frame driver cannot observe a cleared
+   * target while a boot-installed effect is compiling.
+   */
+  readonly requiredFullscreenPostProcesses?: readonly {
+    readonly identity: string;
+    readonly source: string;
+  }[];
   extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
   plan(data: FrameData, context: RenderFeaturePlanContext): Result<RenderFeaturePlan, RenderError>;
 }

package/src/fullscreen-post-process-pass.ts

@@ -67,7 +67,8 @@ export type PostProcessReadSampleType = 'depth';
  * no paramSchema (params are passed inline via a {type, value} struct — plan-strategy D-4).
  *
  * `params` carries the WGSL struct definition + default value. When `params` is
- * `undefined`, the post-process shader has no UBO (e.g. FXAA — Finding M2-1).
+ * `undefined`, the post-process shader has no params UBO. Special graph-owned
+ * passes such as FXAA may still register an internal policy UBO separately.
  *
  * `reads` declares graph resource keys this pass samples as input texture(s).
  * If omitted, the pass samples the swap-chain color attachment (default path).
@@ -81,7 +82,7 @@ export interface PostProcessShaderEntry {
   /** Composed WGSL source for the fragment stage (post-naga_oil). */
   readonly source: string;
   /**
-   * Params UBO schema. When undefined, the shader has no uniform buffer (e.g. FXAA)
+   * Params UBO schema. When undefined, the generic shader has no uniform buffer
    * and the BGL degrades to 2 entries (texture@0 + sampler@1). When present, the
    * primitive eager-creates a params UBO (at register, sized `byteSize`) and binds
    * it at bindgroup(1) binding(2) as part of a 3-entry BGL
@@ -104,6 +105,46 @@ export interface PostProcessShaderEntry {
   readonly reads?: readonly (string | PostProcessReadEntry)[] | undefined;
 }
 
+function postProcessSourceDigest(source: string): string {
+  let first = 0x811c9dc5;
+  let second = 0x9e3779b9;
+  for (let index = 0; index < source.length; index += 1) {
+    const code = source.charCodeAt(index);
+    first = Math.imul(first ^ code, 0x01000193);
+    second = Math.imul(second ^ (code + index), 0x01000193);
+  }
+  return `${source.length.toString(16)}-${(first >>> 0).toString(16).padStart(8, '0')}-${(second >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+/** Content-addressed PSO label shared by the post-process pipeline factory. */
+export function postProcessShaderPipelineLabel(identity: string, source: string): string {
+  return `post-process-${identity}-pso-${postProcessSourceDigest(source)}`;
+}
+
+/** Content-addressed shader-module label shared by prewarm and lazy paths. */
+export function postProcessShaderModuleLabel(identity: string, source: string): string {
+  return `${postProcessShaderPipelineLabel(identity, source)}-module`;
+}
+
+/**
+ * Stable declaration identity used by graph admission and the renderer's
+ * device-bound pipeline cache.  Shader source, bind-group-affecting params,
+ * and graph reads must move together when a feature reuses its identity.
+ */
+export function postProcessShaderEntrySignature(entry: PostProcessShaderEntry): string {
+  return JSON.stringify({
+    source: entry.source,
+    params:
+      entry.params === undefined
+        ? undefined
+        : {
+            byteSize: entry.params.byteSize,
+            defaultValue: Array.from(entry.params.defaultValue),
+          },
+    reads: entry.reads,
+  });
+}
+
 /** Whether a feature binding opts into the temporal multi-read contract. */
 export function isTemporalFullscreenBinding(values: Readonly<Record<string, unknown>>): boolean {
   return (

package/src/gpu-driven/batch-topology.ts

@@ -1,6 +1,10 @@
 import type { PrimitiveTopology } from '@forgeax/engine-types';
 import type { BatchTopologyInspection } from '../inspection-types';
+import type { CameraSnapshot } from '../render-contract';
 import type { RenderSceneApplyResult, RenderSceneSlot } from '../scene/render-scene-types';
+import { type GpuLodRow, selectGpuLod } from '../scene/visibility/gpu-lod';
+import { projectedHeight as measureProjectedHeight } from '../scene/visibility/lod-selector';
+import type { PreparedGpuDrivenDraw } from './prepared-draw';
 
 export type { BatchTopologyInspection } from '../inspection-types';
 
@@ -14,6 +18,12 @@ export interface GpuDrivenBatchKey {
   readonly topology: PrimitiveTopology;
   readonly pipelineClass: string;
   readonly materialResourceClass: string;
+  /** Stable producer-owned identity; topology never derives this from a shader name. */
+  readonly preparedIdentity?: string;
+  /** Resource identity projected by the prepared material contract. */
+  readonly resourceIdentity?: string;
+  /** Closed admission lane for the prepared Standard PBR draw. */
+  readonly admission?: 'opaque' | 'alpha-mask';
 }
 
 export interface GpuDrivenCandidate {
@@ -21,6 +31,16 @@ export interface GpuDrivenCandidate {
   readonly generation: number;
   readonly drawItemIndex: number;
   readonly instanceOrdinal: number;
+  /** Absolute coverage rows uploaded to the GPU selector; root is implicit. */
+  readonly lodCoverages?: readonly number[];
+  readonly lodHysteresis?: number;
+  readonly projectedHeight?: number;
+  readonly lodRanges?: readonly {
+    readonly first: number;
+    readonly count: number;
+    readonly baseVertex: number;
+  }[];
+  readonly prepared?: PreparedGpuDrivenDraw;
 }
 
 export interface GpuDrivenBatch {
@@ -40,6 +60,32 @@ export interface SubmissionPlan {
   readonly visibleCapacity: number;
 }
 
+export interface GpuLodCandidateInput {
+  readonly candidate: GpuDrivenCandidate;
+  readonly rows: readonly GpuLodRow[];
+  readonly projectedHeight: number;
+  readonly previousLevel: number;
+  readonly historyValid: boolean;
+}
+
+export interface GpuLodCompactCandidate {
+  readonly candidate: GpuDrivenCandidate;
+  readonly level: number;
+  readonly confidence: number;
+}
+
+/** Selects one level per stable topology candidate without mutating membership. */
+export function compactGpuLodCandidates(
+  inputs: readonly GpuLodCandidateInput[],
+): readonly GpuLodCompactCandidate[] {
+  return Object.freeze(
+    inputs.map((input) => {
+      const selection = selectGpuLod(input.rows, input);
+      return Object.freeze({ candidate: input.candidate, ...selection });
+    }),
+  );
+}
+
 interface MutableBatch {
   readonly batchId: number;
   readonly generation: number;
@@ -53,29 +99,100 @@ function eligibleKeys(slot: RenderSceneSlot): readonly GpuDrivenBatchKey[] {
   if (
     draws === undefined ||
     draws.length === 0 ||
+    snapshot.instances?.instanceCount === 0 ||
     snapshot.localAabb === undefined ||
     snapshot.skin !== undefined ||
+    snapshot.morph !== undefined ||
     snapshot.spriteInstances !== undefined
   ) {
     return [];
   }
-  return draws.map((draw) => ({
-    assetHandle: snapshot.assetHandle,
-    drawKind: draw.kind,
-    first: draw.first,
-    count: draw.count,
-    baseVertex: draw.baseVertex,
-    materialSlot: draw.materialSlot,
-    topology: draw.topology,
-    pipelineClass: draw.pipelineClass,
-    materialResourceClass: draw.materialResourceClass,
-  }));
+  return draws.flatMap((draw) => {
+    const prepared = draw.prepared;
+    const material = snapshot.materials[draw.materialSlot] ?? snapshot.material;
+    if (prepared !== undefined) {
+      const isStandardPbr =
+        (material.materialShaderId === 'forgeax::default-standard-pbr' &&
+          prepared.identity.material === 'forgeax::default-standard-pbr') ||
+        (material.materialShaderId === 'forgeax::default-standard-pbr-skin' &&
+          prepared.identity.material === 'forgeax::default-standard-pbr-skin');
+      const isAlphaBlend =
+        material.transparent === true || material.renderState?.blend !== undefined;
+      if (!isStandardPbr || isAlphaBlend || prepared.identity.deformation !== 'rigid') return [];
+      const preparedIdentity = `${prepared.identity.material}|${prepared.identity.geometry}|${prepared.identity.deformation}`;
+      const admission =
+        typeof material.paramSnapshot?.alphaCutoff === 'number' ? 'alpha-mask' : 'opaque';
+      return [
+        {
+          assetHandle: snapshot.assetHandle,
+          drawKind: draw.kind,
+          first: prepared.first,
+          count: prepared.count,
+          baseVertex: prepared.baseVertex,
+          materialSlot: draw.materialSlot,
+          topology: prepared.topology,
+          pipelineClass: preparedIdentity,
+          materialResourceClass: draw.materialResourceClass,
+          preparedIdentity,
+          resourceIdentity: draw.materialResourceClass,
+          admission,
+        },
+      ];
+    }
+    return [
+      {
+        assetHandle: snapshot.assetHandle,
+        drawKind: draw.kind,
+        first: draw.first,
+        count: draw.count,
+        baseVertex: draw.baseVertex,
+        materialSlot: draw.materialSlot,
+        topology: draw.topology,
+        pipelineClass: draw.pipelineClass,
+        materialResourceClass: draw.materialResourceClass,
+      },
+    ];
+  });
 }
 
 function keyText(key: GpuDrivenBatchKey): string {
   return JSON.stringify(key);
 }
 
+/**
+ * A GPU indirect draw has one index/vertex range for the whole batch.  LOD
+ * selection is per candidate, so sharing a batch between LOD candidates would
+ * let `finalizeView` pick the first candidate's range for every visible
+ * instance. Keep LOD candidates in single-candidate batches; ordinary meshes
+ * retain the existing compatibility batching path.
+ */
+function candidateBatchText(
+  key: GpuDrivenBatchKey,
+  primitiveIndex: number,
+  drawItemIndex: number,
+  instanceOrdinal: number,
+  hasLod: boolean,
+): string {
+  return hasLod
+    ? `${keyText(key)}|lod:${primitiveIndex}:${drawItemIndex}:${instanceOrdinal}`
+    : keyText(key);
+}
+
+function membershipTexts(slot: RenderSceneSlot): readonly string[] {
+  const keys = eligibleKeys(slot);
+  const instanceCount = slot.snapshot.instances?.instanceCount ?? 1;
+  const hasLod = (slot.snapshot.lods?.length ?? 0) > 0;
+  const texts: string[] = [];
+  for (let drawItemIndex = 0; drawItemIndex < keys.length; drawItemIndex += 1) {
+    const key = keys[drawItemIndex];
+    if (key === undefined) continue;
+    for (let instanceOrdinal = 0; instanceOrdinal < instanceCount; instanceOrdinal += 1) {
+      texts.push(candidateBatchText(key, slot.slot, drawItemIndex, instanceOrdinal, hasLod));
+    }
+  }
+  return texts;
+}
+
 function alignInstanceBase(value: number): number {
   // Raster binds each batch's visible-index and compact-transform segment at
   // a static storage-buffer offset. WebGPU requires those offsets to satisfy
@@ -85,6 +202,42 @@ function alignInstanceBase(value: number): number {
   return Math.ceil(value / 64) * 64;
 }
 
+export function projectedHeightForCandidate(slot: RenderSceneSlot, camera: CameraSnapshot): number {
+  const aabb = slot.snapshot.localAabb;
+  if (aabb === undefined || aabb.length < 6) return Number.NaN;
+  const halfX = Math.abs((aabb[3] ?? 0) - (aabb[0] ?? 0)) * 0.5;
+  const halfY = Math.abs((aabb[4] ?? 0) - (aabb[1] ?? 0)) * 0.5;
+  const halfZ = Math.abs((aabb[5] ?? 0) - (aabb[2] ?? 0)) * 0.5;
+  const world = slot.snapshot.transform.world;
+  // Transform the local AABB's half extents through the absolute value of the
+  // world 3x3. This is the conservative world-space sphere bound for every
+  // rotation and signed/non-uniform scale, and keeps CPU projection aligned
+  // with the world transform uploaded to the GPU selector.
+  const worldHalfX =
+    Math.abs(world[0] ?? 0) * halfX +
+    Math.abs(world[4] ?? 0) * halfY +
+    Math.abs(world[8] ?? 0) * halfZ;
+  const worldHalfY =
+    Math.abs(world[1] ?? 0) * halfX +
+    Math.abs(world[5] ?? 0) * halfY +
+    Math.abs(world[9] ?? 0) * halfZ;
+  const worldHalfZ =
+    Math.abs(world[2] ?? 0) * halfX +
+    Math.abs(world[6] ?? 0) * halfY +
+    Math.abs(world[10] ?? 0) * halfZ;
+  const radius = Math.hypot(worldHalfX, worldHalfY, worldHalfZ);
+  const dx = (world[12] ?? 0) - (camera.position[0] ?? 0);
+  const dy = (world[13] ?? 0) - (camera.position[1] ?? 0);
+  const dz = (world[14] ?? 0) - (camera.position[2] ?? 0);
+  return measureProjectedHeight({
+    radius,
+    depth: Math.hypot(dx, dy, dz),
+    projection: camera.projection,
+    fov: camera.fov,
+    orthoHeight: Math.abs(camera.orthoTop - camera.orthoBottom),
+  });
+}
+
 /** Stable compatibility grouping; per-view visibility never mutates this owner. */
 export class BatchTopology {
   private readonly batches = new Map<string, MutableBatch>();
@@ -119,15 +272,17 @@ export class BatchTopology {
       changed = this.remove(slot.slot) || changed;
       changed = this.add(slot) || changed;
     }
+    // Most updated slots are transform-only. A full renderable update can
+    // still carry a changed material/geometry/draw topology, so compare the
+    // stable batch memberships and patch only when that key actually changed.
+    // This keeps moving entities on the zero-work transform lane while making
+    // same-entity resource edits visible to the GPU-driven owner.
     for (const slot of delta.updatedSlots) {
-      const instanceCount = slot.snapshot.instances?.instanceCount ?? 1;
-      const nextTexts = eligibleKeys(slot).flatMap((key) =>
-        Array.from({ length: instanceCount }, () => keyText(key)),
-      );
-      const current = this.membershipByPrimitive.get(slot.slot) ?? [];
+      const previous = this.membershipByPrimitive.get(slot.slot) ?? [];
+      const next = membershipTexts(slot);
       if (
-        current.length === nextTexts.length &&
-        current.every((membership, index) => membership.batchText === nextTexts[index])
+        previous.length === next.length &&
+        previous.every((membership, index) => membership.batchText === next[index])
       ) {
         continue;
       }
@@ -198,26 +353,50 @@ export class BatchTopology {
     this.ineligiblePrimitives.delete(slot.slot);
     const memberships: Array<{ batchText: string; candidateKey: string }> = [];
     const instanceCount = slot.snapshot.instances?.instanceCount ?? 1;
+    const hasLod = (slot.snapshot.lods?.length ?? 0) > 0;
     for (let drawItemIndex = 0; drawItemIndex < keys.length; drawItemIndex += 1) {
       const key = keys[drawItemIndex];
       if (key === undefined) continue;
-      const text = keyText(key);
-      let batch = this.batches.get(text);
-      if (batch === undefined) {
-        const reused = this.freeBatchIds.pop();
-        const batchId = reused ?? this.generationByBatchId.length;
-        const generation = reused === undefined ? 0 : (this.generationByBatchId[batchId] ?? -1) + 1;
-        this.generationByBatchId[batchId] = generation;
-        batch = { batchId, generation, key, candidates: new Map() };
-        this.batches.set(text, batch);
-      }
       for (let instanceOrdinal = 0; instanceOrdinal < instanceCount; instanceOrdinal += 1) {
+        const text = candidateBatchText(key, slot.slot, drawItemIndex, instanceOrdinal, hasLod);
+        let batch = this.batches.get(text);
+        if (batch === undefined) {
+          const reused = this.freeBatchIds.pop();
+          const batchId = reused ?? this.generationByBatchId.length;
+          const generation =
+            reused === undefined ? 0 : (this.generationByBatchId[batchId] ?? -1) + 1;
+          this.generationByBatchId[batchId] = generation;
+          batch = { batchId, generation, key, candidates: new Map() };
+          this.batches.set(text, batch);
+        }
         const candidateKey = `${slot.slot}:${drawItemIndex}:${instanceOrdinal}`;
+        const draw = slot.snapshot.gpuDrivenDraws?.[drawItemIndex];
+        const prepared = draw?.prepared;
         batch.candidates.set(candidateKey, {
           primitiveIndex: slot.slot,
           generation: slot.generation,
           drawItemIndex,
           instanceOrdinal,
+          ...(draw?.projectedHeight === undefined ? {} : { projectedHeight: draw.projectedHeight }),
+          ...(slot.snapshot.lods === undefined
+            ? {}
+            : {
+                lodCoverages: [1, ...slot.snapshot.lods.map((lod) => lod.screenCoverage)],
+                ...(slot.snapshot.gpuDrivenDraws?.[drawItemIndex]?.lodRanges === undefined
+                  ? {}
+                  : {
+                      lodRanges: slot.snapshot.gpuDrivenDraws[drawItemIndex]
+                        ?.lodRanges as readonly {
+                        readonly first: number;
+                        readonly count: number;
+                        readonly baseVertex: number;
+                      }[],
+                    }),
+                ...(slot.snapshot.lodHysteresis === undefined
+                  ? {}
+                  : { lodHysteresis: slot.snapshot.lodHysteresis }),
+              }),
+          ...(prepared === undefined ? {} : { prepared }),
         });
         memberships.push({ batchText: text, candidateKey });
       }