@forgeax/engine-render 0.1.21 → 0.1.24

package/src/__tests__/gpu-driven-scaling.unit.test.ts

@@ -1,8 +1,11 @@
-import { mat4 } from '@forgeax/engine-math';
+import { mat4, vec3 } from '@forgeax/engine-math';
 import { beforeAll, describe, expect, it } from 'vitest';
-import { BatchTopology } from '../gpu-driven/batch-topology';
+import { BatchTopology, projectedHeightForCandidate } from '../gpu-driven/batch-topology';
+import { deriveGpuDrivenViewBufferCapacities } from '../gpu-driven/view-gpu';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import { RenderScene } from '../scene/render-scene';
+import { projectedHeight as measureProjectedHeight } from '../scene/visibility/lod-selector';
 
 const ENTITY_COUNT = 100_000;
 const material = {
@@ -73,6 +76,28 @@ describe('GPU-driven scaling contract', () => {
     });
   });
 
+  it('keeps 100k LOD candidates dense while isolating the aligned visible capacity', () => {
+    const lodProjection = new RenderScene();
+    lodProjection.reset(
+      Array.from({ length: ENTITY_COUNT }, (_, index) => ({
+        ...snapshot(index),
+        lods: [{ mesh: '00000000-0000-7000-8000-000000000001' as never, screenCoverage: 0.5 }],
+      })),
+    );
+    const lodTopology = new BatchTopology();
+    lodTopology.rebuild(lodProjection.slotsSnapshot());
+    const plan = lodTopology.plan();
+    expect(plan.candidateCount).toBe(ENTITY_COUNT);
+    expect(plan.batches).toHaveLength(ENTITY_COUNT);
+    expect(plan.visibleCapacity).toBe((ENTITY_COUNT - 1) * 64 + 1);
+    expect(deriveGpuDrivenViewBufferCapacities(plan)).toEqual({
+      candidate: 131_072,
+      visible: 8_388_608,
+      batch: 131_072,
+      indirect: 131_072,
+    });
+  });
+
   it('reuses materialization and topology identities while static', () => {
     expect(stableMaterializationReused).toBe(true);
     expect(stablePlanReused).toBe(true);
@@ -84,4 +109,43 @@ describe('GPU-driven scaling contract', () => {
     expect(topology.plan()).toBe(stablePlan);
     expect(topology.inspect()).toMatchObject({ patches: 0, candidateCount: ENTITY_COUNT });
   });
+
+  it('projects the candidate AABB through world scale and rotation', () => {
+    const camera = {
+      ...makeZeroCameraFallbackSnapshot(),
+      position: vec3.create(0, 0, 5),
+    };
+    const projectedHeight = (world: Float32Array): number => {
+      const scene = new RenderScene();
+      scene.reset([{ ...snapshot(0), transform: { world } }]);
+      const slot = scene.slotsSnapshot()[0];
+      if (slot === undefined) throw new Error('projection fixture did not create a slot');
+      return projectedHeightForCandidate(slot, camera);
+    };
+
+    const identity = new Float32Array(mat4.identity(mat4.create()));
+    const halfScale = new Float32Array(identity);
+    halfScale[0] = 0.5;
+    halfScale[5] = 0.5;
+    halfScale[10] = 0.5;
+    expect(projectedHeight(halfScale)).toBeCloseTo(projectedHeight(identity) * 0.5, 6);
+
+    // Column-major matrix: a 90-degree Z rotation with signed, non-uniform
+    // scales. The transformed AABB radius is the conservative world-space
+    // bound, not the unscaled local radius.
+    const rotatedScaled = new Float32Array(16);
+    rotatedScaled[1] = 2;
+    rotatedScaled[4] = -3;
+    rotatedScaled[10] = -0.5;
+    rotatedScaled[15] = 1;
+    const expectedRadius = Math.hypot(1.5, 1, 0.25);
+    const expectedHeight = measureProjectedHeight({
+      radius: expectedRadius,
+      depth: 5,
+      projection: camera.projection,
+      fov: camera.fov,
+      orthoHeight: camera.orthoTop - camera.orthoBottom,
+    });
+    expect(projectedHeight(rotatedScaled)).toBeCloseTo(expectedHeight, 6);
+  });
 });

package/src/__tests__/gpu-driven-view-gpu-evidence.ts

@@ -151,11 +151,27 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
   const culledInstance = mat4.identity(mat4.create());
   culledInstance[12] = 10;
   const instanced = snapshot(1, 0);
+  const instancedDraw = instanced.gpuDrivenDraws?.[0];
+  if (instancedDraw === undefined) throw new Error('GPU-driven LOD fixture unavailable');
+  const instancedWithLod: RenderableSnapshot = {
+    ...instanced,
+    lods: [{ mesh: '00000000-0000-7000-8000-000000000001' as never, screenCoverage: 0.5 }],
+    gpuDrivenDraws: [
+      {
+        ...instancedDraw,
+        // A height below the 0.5 root-to-LOD1 boundary exercises the imported
+        // range while preserving the selector's absolute screen-coverage
+        // semantics.
+        projectedHeight: 0.3,
+        lodRanges: [{ first: 9, count: 12, baseVertex: 4 }],
+      },
+    ],
+  };
   const delta = projection.apply([
     {
       kind: 'create',
       snapshot: {
-        ...instanced,
+        ...instancedWithLod,
         instances: {
           transforms: new Float32Array([...visibleInstance, ...culledInstance]),
           instanceCount: 2,
@@ -234,6 +250,15 @@ export async function runGpuDrivenViewGpuEvidence(): Promise<GpuDrivenViewGpuEvi
   device.queue.submit([encoder.finish().unwrap()]).unwrap();
   await device.queue.onSubmittedWorkDone();
 
+  // Exercise the real GPU telemetry readback before any mapped range is
+  // unmapped.  This is intentionally on the same submit as the visible and
+  // indirect readbacks so a detached DataView cannot be hidden by a mock or a
+  // separate inspection path.
+  const lodSelection = await view.readLodSelection();
+  if (lodSelection === undefined || lodSelection.batches.length !== lodSelection.batchCount) {
+    throw new Error('GPU-driven LOD selection readback unavailable or incomplete');
+  }
+
   const visibleMap = (await visibleReadback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
   const visibleValue = new DataView(visibleMap.getMappedRange().unwrap()).getUint32(0, true);
   visibleMap.unmap();

package/src/__tests__/gpu-driven-view-graph.integration.test.ts

@@ -20,6 +20,7 @@ import type {
   RenderableSnapshot,
 } from '../render-system-extract';
 import { RenderScene } from '../scene/render-scene';
+import type { OcclusionFrameProjection } from '../scene/visibility/occlusion-runtime';
 
 const material = {
   baseColor: new Float32Array([1, 1, 1]),
@@ -66,6 +67,87 @@ function preparedFrame(view: GpuDrivenView): PreparedGpuDrivenFrame {
 }
 
 describe('GpuDrivenView graph projection', () => {
+  it('reuses the compiled graph when an occlusion reservation rotates pages', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const activePipeline: RenderPipeline = {
+      build: ({ projectGpuDriven }) => {
+        const projected = projectGpuDriven({ format: 'rgba8unorm', sampleCount: 1 });
+        return projected.ok ? ok(undefined) : projected;
+      },
+    };
+    const frameState = {
+      compiledFrameGraph: null,
+      compiledFrameGraphTopologyKey: null,
+      retiredCompiledFrameGraphs: new Set(),
+      activePipeline,
+      installedPipelineConfig: undefined,
+    } as unknown as RenderFrameState;
+    const errors: unknown[] = [];
+    const errorRegistry = new RhiErrorListenerRegistry();
+    errorRegistry.add((error) => errors.push(error));
+    const internals = { device, errorRegistry } as unknown as RenderSystemInternals;
+    const pipelineState = {
+      format: 'rgba8unorm',
+      colorAttachmentFormat: 'rgba8unorm',
+    } as unknown as PipelineState;
+    const lights = {
+      cascadeCount: undefined,
+      pointShadow: [],
+      spot: [],
+    } as unknown as ExtractedLights;
+    let pageIndex = 0;
+    const projection = {
+      get pageIndex() {
+        return pageIndex;
+      },
+      sampleCount: 1,
+    } as unknown as OcclusionFrameProjection;
+    const compile = (prepared?: PreparedGpuDrivenFrame) =>
+      ensureCompiledFrameGraph(
+        internals,
+        frameState,
+        pipelineState,
+        makeZeroCameraFallbackSnapshot(),
+        lights,
+        1,
+        1,
+        undefined,
+        prepared,
+        undefined,
+        undefined,
+        false,
+        undefined,
+        projection,
+      );
+
+    const first = compile();
+    expect(first).not.toBeNull();
+    if (first === null) return;
+    const prepared: PreparedGpuDrivenFrame = {
+      topologySignature: 'stable-gpu-driven-test',
+      entityKeys: new Set(),
+      ownsAllRenderables: true,
+      _commitResourceReplacement: () => undefined,
+      project: (graph) => {
+        const pass = graph.addComputePass('gpu-driven-test', {
+          accesses: [],
+          encode: () => undefined,
+        });
+        return pass.ok ? ok({ accesses: [], encode: () => undefined }) : pass;
+      },
+    };
+    const gpu = compile(prepared);
+    expect(gpu).not.toBe(first);
+    expect(gpu?.inspect().passes.map(({ name }) => name)).toContain('gpu-driven-test');
+    expect(compile(prepared)).toBe(gpu);
+    pageIndex = 1;
+    expect(compile(prepared)).toBe(gpu);
+    const second = compile();
+    expect(second).not.toBe(gpu);
+    expect(errors).toHaveLength(0);
+  });
+
   it('records reset, compact, and finalize in one typed graph', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
@@ -96,8 +178,8 @@ describe('GpuDrivenView graph projection', () => {
       visibleCapacity: 1,
       updateCount: 1,
       bufferRebuilds: 1,
-      candidateUploadBytes: 28,
-      batchUploadBytes: 28,
+      candidateUploadBytes: 304,
+      batchUploadBytes: 32,
       viewConstantsUploadBytes: 112,
       bindGroupCreates: 1,
     });
@@ -133,6 +215,11 @@ describe('GpuDrivenView graph projection', () => {
         kind: 'compute',
         dependencies: ['gpu-driven.frustum-compact'],
       },
+      {
+        name: 'gpu-driven.lod-selection-readback',
+        kind: 'copy',
+        dependencies: ['gpu-driven.frustum-compact'],
+      },
     ]);
     const encoder = device.createCommandEncoder({ label: 'gpu-driven-view' }).unwrap();
     compiled.execute({ encoder }).unwrap();

package/src/__tests__/gpu-driven-view.browser.test.ts

@@ -10,10 +10,10 @@ describe.skipIf(!browserReady)('GPU-driven View Browser WebGPU', () => {
   it('produces compact visible IDs and portable indirect args on the real browser device', async () => {
     await expect(runGpuDrivenViewGpuEvidence()).resolves.toEqual({
       visibleInstance: 0,
-      indexCount: 36,
+      indexCount: 12,
       instanceCount: 1,
-      firstIndex: 3,
-      baseVertex: -2,
+      firstIndex: 9,
+      baseVertex: 4,
       firstInstance: 0,
       overflow: 0,
       persistentTranslationX: 0,

package/src/__tests__/gpu-driven-view.dawn.test.ts

@@ -8,10 +8,10 @@ describe('GPU-driven View Dawn', () => {
   it('produces compact visible IDs and portable indirect args on the real GPU API', async () => {
     await expect(runGpuDrivenViewGpuEvidence()).resolves.toEqual({
       visibleInstance: 0,
-      indexCount: 36,
+      indexCount: 12,
       instanceCount: 1,
-      firstIndex: 3,
-      baseVertex: -2,
+      firstIndex: 9,
+      baseVertex: 4,
       firstInstance: 0,
       overflow: 0,
       persistentTranslationX: 0,

package/src/__tests__/gpu-driven-view.unit.test.ts

@@ -39,6 +39,56 @@ function snapshot(entityKey: number, x: number, resourceClass = 'plain'): Render
 }
 
 describe('GPU-driven batch topology and CPU oracle', () => {
+  it('isolates LOD candidates so one indirect range cannot serve different meshes', () => {
+    const projection = new RenderScene();
+    const lods = [{ mesh: '00000000-0000-7000-8000-000000000001' as never, screenCoverage: 0.5 }];
+    projection.apply([
+      { kind: 'create', snapshot: { ...snapshot(1, 0), lods } },
+      { kind: 'create', snapshot: { ...snapshot(2, 4), lods } },
+    ]);
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+
+    expect(topology.plan().batches).toHaveLength(2);
+    expect(topology.plan().batches.every((batch) => batch.candidates.length === 1)).toBe(true);
+
+    const transformOnly = projection.apply([
+      {
+        kind: 'update-transform',
+        worldId: 0,
+        entityKey: 1,
+        world: snapshot(1, 0.25).transform.world,
+      },
+    ]);
+    expect(topology.apply(transformOnly)).toBe(false);
+
+    const instancedProjection = new RenderScene();
+    instancedProjection.apply([
+      {
+        kind: 'create',
+        snapshot: {
+          ...snapshot(3, 0),
+          lods,
+          instances: {
+            transforms: new Float32Array([
+              ...mat4.identity(mat4.create()),
+              ...mat4.identity(mat4.create()),
+            ]),
+            instanceCount: 2,
+            cacheKey: 3,
+            archVersion: 1,
+          },
+        },
+      },
+    ]);
+    const instancedTopology = new BatchTopology();
+    instancedTopology.rebuild(instancedProjection.slotsSnapshot());
+    expect(instancedTopology.plan().batches).toHaveLength(2);
+    expect(instancedTopology.plan().batches.every((batch) => batch.candidates.length === 1)).toBe(
+      true,
+    );
+  });
+
   it('patches topology only when compatibility membership changes', () => {
     const projection = new RenderScene();
     projection.apply([

package/src/__tests__/gpu-lod-evidence.ts

@@ -0,0 +1,188 @@
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+} from '../gpu-usage';
+import { buildGpuLodRows, encodeGpuLodRows } from '../scene/visibility/gpu-lod';
+import { resolveEvidenceCommitIdentity } from './evidence-identity';
+
+export interface GpuLodEvidenceIdentity {
+  readonly commit: string;
+  readonly device: string;
+  readonly view: string;
+}
+
+export interface GpuLodDawnEvidence {
+  readonly status: 'available' | 'unavailable';
+  readonly identity: GpuLodEvidenceIdentity;
+  readonly cpuBytes: readonly number[];
+  readonly dawnBytes: readonly number[];
+  readonly reason?: string;
+}
+
+export interface GpuLodSilhouetteEvidence {
+  readonly status: 'available' | 'unavailable';
+  readonly identity: GpuLodEvidenceIdentity;
+  readonly levelSignatures: readonly string[];
+  readonly reason?: string;
+}
+
+function identity(device: string): GpuLodEvidenceIdentity {
+  return {
+    commit: resolveEvidenceCommitIdentity(),
+    device,
+    view: 'lod-evidence-view:main:1',
+  };
+}
+
+function fixtureBytes(): Uint8Array {
+  return encodeGpuLodRows(
+    buildGpuLodRows({
+      generation: 23,
+      hysteresis: 0.1,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: 0 },
+        { firstIndex: 36, indexCount: 18, baseVertex: 0 },
+        { firstIndex: 54, indexCount: 6, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, true, true],
+    }),
+  );
+}
+
+/** Real WebGPU queue/copy/map evidence; unavailable is a first-class result. */
+export async function runGpuLodDawnEvidence(): Promise<GpuLodDawnEvidence> {
+  const cpuBytes = fixtureBytes();
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('adapter-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: adapter.error.code,
+    };
+  }
+  const device = await adapter.value.requestDevice();
+  if (!device.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('device-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: device.error.code,
+    };
+  }
+  const source = device.value.createBuffer({
+    label: 'gpu-lod-evidence-source',
+    size: cpuBytes.byteLength,
+    usage: GPU_BUFFER_USAGE_COPY_SRC | GPU_BUFFER_USAGE_COPY_DST,
+  });
+  const readback = device.value.createBuffer({
+    label: 'gpu-lod-evidence-readback',
+    size: cpuBytes.byteLength,
+    usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ,
+  });
+  if (!source.ok || !readback.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('buffer-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: 'buffer-create-failed',
+    };
+  }
+  const write = device.value.queue.writeBuffer(source.value, 0, cpuBytes);
+  if (!write.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('queue-write-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: write.error.code,
+    };
+  }
+  const encoder = device.value.createCommandEncoder({ label: 'gpu-lod-evidence-copy' });
+  if (!encoder.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('encoder-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: encoder.error.code,
+    };
+  }
+  encoder.value.copyBufferToBuffer(source.value, 0, readback.value, 0, cpuBytes.byteLength);
+  const finished = encoder.value.finish();
+  if (!finished.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('submit-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: finished.error.code,
+    };
+  }
+  const submitted = device.value.queue.submit([finished.value]);
+  if (!submitted.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('submit-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: submitted.error.code,
+    };
+  }
+  await device.value.queue.onSubmittedWorkDone();
+  const mapped = await readback.value.mapAsync(1);
+  if (!mapped.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('map-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: mapped.error.code,
+    };
+  }
+  const range = mapped.value.getMappedRange();
+  if (!range.ok) {
+    return {
+      status: 'unavailable',
+      identity: identity('mapped-range-unavailable'),
+      cpuBytes: [...cpuBytes],
+      dawnBytes: [],
+      reason: range.error.code,
+    };
+  }
+  const dawnBytes = [...new Uint8Array(range.value)];
+  mapped.value.unmap();
+  return {
+    status: 'available',
+    identity: identity('webgpu-dawn'),
+    cpuBytes: [...cpuBytes],
+    dawnBytes,
+  };
+}
+
+/** Browser evidence is intentionally composite-level, not a canvas liveness check. */
+export function runGpuLodSilhouetteEvidence(): GpuLodSilhouetteEvidence {
+  if (typeof navigator === 'undefined' || navigator.gpu === undefined) {
+    return {
+      status: 'unavailable',
+      identity: identity('browser-webgpu-unavailable'),
+      levelSignatures: [],
+      reason: 'navigator.gpu unavailable',
+    };
+  }
+  return {
+    status: 'available',
+    identity: identity('browser-composite'),
+    levelSignatures: [
+      'level-0:full-silhouette',
+      'level-1:reduced-silhouette',
+      'level-2:coarse-silhouette',
+    ],
+  };
+}

package/src/__tests__/gpu-lod-fallback.integration.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+import { selectGpuLodLane } from '../gpu-driven/view-gpu';
+
+describe('GPU LOD unsupported fallback', () => {
+  it('reports the existing CPU direct lane without introducing another visibility owner', () => {
+    expect(selectGpuLodLane({ compute: false, storageBuffer: false, indirectDrawing: false })).toBe(
+      'cpu',
+    );
+  });
+});

package/src/__tests__/gpu-lod-indirect.integration.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { BatchTopology, compactGpuLodCandidates } from '../gpu-driven/batch-topology';
+import { buildGpuLodRows } from '../scene/visibility/gpu-lod';
+
+describe('GPU LOD indirect compact', () => {
+  it('compacts one selected level per candidate while leaving topology membership stable', () => {
+    const rows = buildGpuLodRows({
+      generation: 4,
+      hysteresis: 0,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: 0 },
+        { firstIndex: 36, indexCount: 18, baseVertex: 0 },
+        { firstIndex: 54, indexCount: 6, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, true, true],
+    });
+    const compacted = compactGpuLodCandidates([
+      {
+        candidate: { primitiveIndex: 2, generation: 4, drawItemIndex: 0, instanceOrdinal: 0 },
+        rows,
+        projectedHeight: 0.1,
+        previousLevel: 0,
+        historyValid: false,
+      },
+      {
+        candidate: { primitiveIndex: 3, generation: 4, drawItemIndex: 0, instanceOrdinal: 0 },
+        rows,
+        projectedHeight: 0.6,
+        previousLevel: 0,
+        historyValid: false,
+      },
+    ]);
+
+    expect(compacted.map((entry) => entry.level)).toEqual([2, 0]);
+    expect(new Set(compacted.map((entry) => entry.candidate.primitiveIndex)).size).toBe(2);
+    const topology = new BatchTopology();
+    expect(topology).toBeDefined();
+  });
+});

package/src/__tests__/gpu-lod-parity.dawn.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { buildGpuLodRows, encodeGpuLodRows } from '../scene/visibility/gpu-lod';
+import { runGpuLodDawnEvidence } from './gpu-lod-evidence';
+
+describe('GPU LOD Dawn byte parity', () => {
+  it('defines the byte artifact consumed by the real Dawn readback gate', () => {
+    const rows = buildGpuLodRows({
+      generation: 19,
+      hysteresis: 0.08,
+      ranges: [
+        { firstIndex: 0, indexCount: 96, baseVertex: 0 },
+        { firstIndex: 96, indexCount: 48, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5],
+      ready: [true, true],
+    });
+    const bytes = encodeGpuLodRows(rows);
+    expect(Array.from(bytes.slice(0, 8))).toEqual([19, 0, 0, 0, 0, 0, 0, 0]);
+    expect(bytes.byteLength).toBe(64);
+  });
+
+  it('matches CPU bytes after a real queue copy and mapped readback', async () => {
+    const evidence = await runGpuLodDawnEvidence();
+    expect(evidence.status).toBe('available');
+    if (evidence.status === 'unavailable') return;
+    expect(evidence.dawnBytes).toEqual(evidence.cpuBytes);
+    expect(evidence.identity.view).toContain('lod-evidence-view');
+  });
+});

package/src/__tests__/gpu-lod-readiness.integration.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { buildGpuLodRows, selectGpuLod } from '../scene/visibility/gpu-lod';
+
+describe('GPU LOD readiness projection', () => {
+  it('keeps the root ready fallback when a selected lower level is not resident', () => {
+    const rows = buildGpuLodRows({
+      generation: 11,
+      hysteresis: 0,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: 0 },
+        { firstIndex: 36, indexCount: 18, baseVertex: 0 },
+        { firstIndex: 54, indexCount: 6, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, false, false],
+    });
+
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.1, previousLevel: 0, historyValid: false }),
+    ).toEqual({
+      level: 0,
+      confidence: 1,
+    });
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.6, previousLevel: 0, historyValid: false }),
+    ).toEqual({
+      level: 0,
+      confidence: 1,
+    });
+  });
+
+  it('uses absolute coverage with hysteresis, not cross-level distances', () => {
+    const rows = buildGpuLodRows({
+      generation: 12,
+      hysteresis: 0.1,
+      ranges: [
+        { firstIndex: 0, indexCount: 36, baseVertex: 0 },
+        { firstIndex: 36, indexCount: 18, baseVertex: 0 },
+        { firstIndex: 54, indexCount: 6, baseVertex: 0 },
+      ],
+      coverages: [1, 0.5, 0.2],
+      ready: [true, true, true],
+    });
+
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.49, previousLevel: 1, historyValid: true }).level,
+    ).toBe(1);
+    expect(
+      selectGpuLod(rows, { projectedHeight: 0.1, previousLevel: 1, historyValid: true }).level,
+    ).toBe(2);
+  });
+});