@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/occlusion-pass-routing.unit.test.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const typedPrimitivesSource = readFileSync(
+  new URL('../typed-render-graph-primitives.ts', import.meta.url),
+  'utf8',
+);
+
+describe('typed scene occlusion pass routing', () => {
+  it('only forwards a projection to the pass that owns its query set', () => {
+    expect(typedPrimitivesSource).toContain('const activeOcclusion = options.occlusion;');
+    expect(typedPrimitivesSource).not.toContain(
+      '...(internal.occlusion === undefined ? {} : { occlusion: internal.occlusion })',
+    );
+  });
+});

package/src/__tests__/occlusion-pass.dawn.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { buildOcclusionPassPlan } from '../scene/visibility/occlusion-pass';
+
+describe('occlusion pass Dawn contract', () => {
+  it('keeps resolve, copy, and async map in one shared submission plan', () => {
+    const plan = buildOcclusionPassPlan({
+      opaquePass: 'opaque',
+      depthResource: 'depth',
+      colorResource: 'color',
+      bounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+      queryIndex: 0,
+    });
+    expect(plan).toMatchObject({
+      resolve: { queryIndex: 0 },
+      copy: { asynchronous: true },
+      submitCount: 1,
+      mapSameFrame: false,
+    });
+  });
+});

package/src/__tests__/occlusion-pass.integration.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { buildOcclusionPassPlan } from '../scene/visibility/occlusion-pass';
+
+const bounds = { min: [-1, -1, -1] as const, max: [1, 1, 1] as const };
+
+describe('typed occlusion bounds pass', () => {
+  it('is ordered after opaque and only reads depth through a conservative proxy', () => {
+    expect(
+      buildOcclusionPassPlan({
+        opaquePass: 'opaque-main',
+        depthResource: 'depth-main',
+        colorResource: 'color-main',
+        bounds,
+        queryIndex: 3,
+      }),
+    ).toMatchObject({
+      after: 'opaque-main',
+      queryIndex: 3,
+      depth: { resource: 'depth-main', usage: 'depth-read-only' },
+      writesColor: false,
+      writesDepth: false,
+      submitCount: 1,
+    });
+  });
+
+  it.each([
+    { transparent: true },
+    { deformed: true },
+    { bounds: undefined },
+  ])('keeps non-queryable candidates visible: %o', (input) => {
+    expect(
+      buildOcclusionPassPlan({
+        opaquePass: 'opaque-main',
+        depthResource: 'depth-main',
+        colorResource: 'color-main',
+        bounds: input.bounds === undefined ? undefined : bounds,
+        queryIndex: 0,
+        ...(input.transparent === undefined ? {} : { transparent: input.transparent }),
+        ...(input.deformed === undefined ? {} : { deformed: input.deformed }),
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/__tests__/occlusion-pass.rhi-null.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { buildOcclusionPassPlan } from '../scene/visibility/occlusion-pass';
+
+describe('occlusion pass RhiNull structural contract', () => {
+  it('does not create color/depth writes and keeps query index separate from identity', () => {
+    const plan = buildOcclusionPassPlan({
+      opaquePass: 'opaque',
+      depthResource: 'depth',
+      colorResource: 'color',
+      bounds: { min: [-2, -2, -2], max: [2, 2, 2] },
+      queryIndex: 17,
+      identity: { primitiveSlot: 4, slotGeneration: 9 },
+    });
+    expect(plan).toMatchObject({
+      queryIndex: 17,
+      identity: { primitiveSlot: 4, slotGeneration: 9 },
+      writesColor: false,
+      writesDepth: false,
+    });
+    expect(plan?.depth.usage).toBe('depth-read-only');
+  });
+});

package/src/__tests__/occlusion-query-pool.rhi-null.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { OcclusionQueryPool } from '../scene/visibility/occlusion-query-pool';
+
+describe('occlusion query RhiNull structure', () => {
+  it('disposes pages and reuses them without exposing query identity', () => {
+    const pool = new OcclusionQueryPool();
+    expect(pool.inspect().disposed).toBe(false);
+    pool.dispose();
+    expect(pool.inspect()).toMatchObject({ disposed: true, inFlight: 0, availablePages: 0 });
+    expect(
+      pool.reserve({
+        viewKey: 'view',
+        attachmentId: 'attachment',
+        deviceGeneration: 1,
+        worldGeneration: 1,
+        primitiveSlot: 0,
+        slotGeneration: 1,
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/__tests__/occlusion-query-pool.unit.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import {
+  OCCLUSION_QUERY_PAGE_BYTES,
+  OCCLUSION_QUERY_PAGE_COUNT,
+  OCCLUSION_QUERY_PAGE_INDEX_LIMIT,
+  OcclusionQueryPool,
+} from '../scene/visibility/occlusion-query-pool';
+
+const identity = (index: number) => ({
+  viewKey: `view-${index}`,
+  attachmentId: 'attachment-1',
+  deviceGeneration: 4,
+  worldGeneration: 2,
+  primitiveSlot: index,
+  slotGeneration: 9,
+});
+
+describe('occlusion query pool budgets', () => {
+  it('owns three bounded pages with 4096 indices and 32 KiB resolve/staging each', () => {
+    const pool = new OcclusionQueryPool();
+    expect(pool.inspect()).toMatchObject({
+      pageCount: OCCLUSION_QUERY_PAGE_COUNT,
+      pageIndexLimit: OCCLUSION_QUERY_PAGE_INDEX_LIMIT,
+      resolveBytes: OCCLUSION_QUERY_PAGE_BYTES,
+      stagingBytes: OCCLUSION_QUERY_PAGE_BYTES,
+    });
+  });
+
+  it('fills one page to the 4096-index boundary before advancing fairly', () => {
+    const pool = new OcclusionQueryPool();
+    const firstPage = Array.from({ length: OCCLUSION_QUERY_PAGE_INDEX_LIMIT }, (_, index) =>
+      pool.reserve(identity(index)),
+    );
+    expect(firstPage.every((reservation) => reservation !== undefined)).toBe(true);
+    expect(firstPage[0]?.queryIndex).toBe(0);
+    expect(firstPage.at(-1)?.queryIndex).toBe(OCCLUSION_QUERY_PAGE_INDEX_LIMIT - 1);
+    expect(pool.reserve(identity(4096))?.pageIndex).toBe(1);
+  });
+
+  it('releases a page only after its tickets retire and then resets its index cursor', () => {
+    const pool = new OcclusionQueryPool();
+    const first = pool.reserve(identity(0));
+    const second = pool.reserve(identity(1));
+    expect(first).toBeDefined();
+    expect(second).toBeDefined();
+    if (first === undefined || second === undefined)
+      throw new Error('test fixture reservations must exist');
+    const firstTicket = pool.publish(first, { submitted: true, submissionGeneration: 7 });
+    const secondTicket = pool.publish(second, { submitted: true, submissionGeneration: 7 });
+    expect(firstTicket).toBeDefined();
+    expect(secondTicket).toBeDefined();
+    if (firstTicket === undefined || secondTicket === undefined)
+      throw new Error('test fixture tickets must exist');
+    pool.complete(firstTicket, 1);
+    expect(pool.inspect().inFlight).toBe(1);
+    pool.complete(secondTicket, 1);
+    const reused = pool.reserve(identity(2));
+    expect(reused).toMatchObject({ pageIndex: 0, queryIndex: 0 });
+  });
+
+  it('does not submit new queries to a page while its staging buffer is in flight', () => {
+    const pool = new OcclusionQueryPool();
+    const first = pool.reserve(identity(0));
+    expect(first).toBeDefined();
+    if (first === undefined) throw new Error('test fixture reservation must exist');
+    const ticket = pool.publish(first, { submitted: true, submissionGeneration: 7 });
+    expect(ticket).toBeDefined();
+    if (ticket === undefined) throw new Error('test fixture ticket must exist');
+
+    const next = pool.reserve(identity(1));
+    expect(next).toMatchObject({ pageIndex: 1, queryIndex: 0 });
+    expect(pool.inspect().availablePages).toBe(OCCLUSION_QUERY_PAGE_COUNT - 1);
+    pool.complete(ticket, 1);
+  });
+
+  it('reports no reservable pages while every page has an in-flight ticket', () => {
+    const pool = new OcclusionQueryPool();
+    const tickets = [];
+    for (let index = 0; index < OCCLUSION_QUERY_PAGE_COUNT; index += 1) {
+      const reservation = pool.reserve(identity(index));
+      expect(reservation).toBeDefined();
+      if (reservation === undefined) throw new Error('page reservation must exist');
+      const ticket = pool.publish(reservation, { submitted: true, submissionGeneration: 8 });
+      expect(ticket).toBeDefined();
+      if (ticket === undefined) throw new Error('page ticket must exist');
+      tickets.push(ticket);
+    }
+
+    expect(pool.inspect().availablePages).toBe(0);
+    expect(pool.reserve(identity(OCCLUSION_QUERY_PAGE_COUNT))).toBeUndefined();
+
+    for (const ticket of tickets) pool.complete(ticket, 0);
+    expect(pool.inspect().availablePages).toBe(OCCLUSION_QUERY_PAGE_COUNT);
+  });
+});

package/src/__tests__/occlusion-query-ticket.integration.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { OcclusionQueryPool } from '../scene/visibility/occlusion-query-pool';
+
+const identity = (primitiveSlot: number) => ({
+  viewKey: 'view-main',
+  attachmentId: 'attachment-1',
+  deviceGeneration: 8,
+  worldGeneration: 3,
+  primitiveSlot,
+  slotGeneration: 2,
+});
+
+describe('occlusion query ticket publication', () => {
+  it('does not publish a ticket before the shared submission succeeds', () => {
+    const pool = new OcclusionQueryPool();
+    const reservation = pool.reserve(identity(1));
+    if (reservation === undefined) throw new Error('reservation unavailable');
+    expect(
+      pool.publish(reservation, { submitted: false, submissionGeneration: 1 }),
+    ).toBeUndefined();
+    expect(pool.inspect().inFlight).toBe(0);
+    expect(pool.publish(reservation, { submitted: true, submissionGeneration: 2 })).toMatchObject({
+      queryIndex: reservation.queryIndex,
+      pageIndex: reservation.pageIndex,
+      submissionGeneration: 2,
+      primitiveSlot: 1,
+      deviceGeneration: 8,
+    });
+  });
+
+  it('accepts delayed and out-of-order completions only for matching generation identity', () => {
+    const pool = new OcclusionQueryPool();
+    const first = pool.reserve(identity(1));
+    const second = pool.reserve(identity(2));
+    if (first === undefined || second === undefined) throw new Error('reservation unavailable');
+    const firstTicket = pool.publish(first, { submitted: true, submissionGeneration: 4 });
+    const secondTicket = pool.publish(second, { submitted: true, submissionGeneration: 4 });
+    if (firstTicket === undefined || secondTicket === undefined)
+      throw new Error('ticket unavailable');
+    expect(pool.complete(secondTicket, 0)).toEqual({ status: 'accepted', visible: true });
+    expect(pool.complete(firstTicket, 7)).toEqual({ status: 'accepted', visible: true });
+    expect(pool.complete({ ...firstTicket, deviceGeneration: 7 }, 0)).toEqual({
+      status: 'stale',
+      visible: true,
+    });
+  });
+});

package/src/__tests__/occlusion-query.dawn.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { runOcclusionQueryDawnEvidence } from './occlusion-query.evidence';
+
+describe('occlusion query Dawn evidence', () => {
+  it('maps real zero and positive query results with identity and lifecycle evidence', async () => {
+    const evidence = await runOcclusionQueryDawnEvidence();
+    expect(evidence.status).toBe('available');
+    expect(evidence.identity.commit.length).toBeGreaterThan(0);
+    expect(evidence.identity.device).toBe('webgpu-dawn');
+    expect(evidence.zeroSamples).toBe(0);
+    expect(evidence.positiveSamples).toBeGreaterThan(0);
+    expect(evidence.outOfOrder).toBe(true);
+    expect(evidence.staleVisible).toBe(true);
+    expect(evidence.faultVisible).toBe(true);
+  });
+});

package/src/__tests__/occlusion-query.evidence.ts

@@ -0,0 +1,178 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import { GPU_TEXTURE_USAGE_RENDER_ATTACHMENT } from '../gpu-texture-usage';
+import { GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+import {
+  createOcclusionQueryResources,
+  recordOcclusionResolve,
+} from '../scene/visibility/occlusion-pass';
+import { OcclusionQueryPool } from '../scene/visibility/occlusion-query-pool';
+import { resolveEvidenceCommitIdentity } from './evidence-identity';
+
+export interface OcclusionQueryEvidenceIdentity {
+  readonly commit: string;
+  readonly device: string;
+  readonly view: string;
+}
+
+export interface OcclusionQueryDawnEvidence {
+  readonly status: 'available' | 'unavailable';
+  readonly identity: OcclusionQueryEvidenceIdentity;
+  readonly zeroSamples: number;
+  readonly positiveSamples: number;
+  readonly outOfOrder: boolean;
+  readonly staleVisible: boolean;
+  readonly faultVisible: boolean;
+  readonly reason?: string;
+}
+
+function identity(device: string): OcclusionQueryEvidenceIdentity {
+  return {
+    commit: resolveEvidenceCommitIdentity(),
+    device,
+    view: 'occlusion-query-evidence-view:main:1',
+  };
+}
+
+function unavailable(reason: string): OcclusionQueryDawnEvidence {
+  return {
+    status: 'unavailable',
+    identity: identity('webgpu-unavailable'),
+    zeroSamples: 0,
+    positiveSamples: 0,
+    outOfOrder: false,
+    staleVisible: true,
+    faultVisible: true,
+    reason,
+  };
+}
+
+async function requestDevice(): Promise<RhiDevice | OcclusionQueryDawnEvidence> {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) return unavailable(adapter.error.code);
+  const device = await adapter.value.requestDevice();
+  if (!device.ok) return unavailable(device.error.code);
+  return device.value;
+}
+
+function lifecycleEvidence(): Pick<
+  OcclusionQueryDawnEvidence,
+  'outOfOrder' | 'staleVisible' | 'faultVisible'
+> {
+  const pool = new OcclusionQueryPool();
+  const base = {
+    viewKey: 'evidence-view',
+    attachmentId: 'evidence-depth',
+    deviceGeneration: 1,
+    worldGeneration: 2,
+    primitiveSlot: 0,
+    slotGeneration: 1,
+  };
+  const first = pool.reserve({ ...base, primitiveSlot: 1 });
+  const second = pool.reserve({ ...base, primitiveSlot: 2 });
+  if (first === undefined || second === undefined) {
+    return { outOfOrder: false, staleVisible: true, faultVisible: true };
+  }
+  const firstTicket = pool.publish(first, { submitted: true, submissionGeneration: 4 });
+  const secondTicket = pool.publish(second, { submitted: true, submissionGeneration: 5 });
+  if (firstTicket === undefined || secondTicket === undefined) {
+    return { outOfOrder: false, staleVisible: true, faultVisible: true };
+  }
+  const secondCompletion = pool.complete(secondTicket, 3);
+  const firstCompletion = pool.complete(firstTicket, 0);
+  const staleCompletion = pool.complete({ ...firstTicket, slotGeneration: 99 }, 1);
+  return {
+    outOfOrder: secondCompletion.status === 'accepted' && firstCompletion.status === 'accepted',
+    staleVisible: staleCompletion.visible,
+    faultVisible: staleCompletion.visible,
+  };
+}
+
+export async function runOcclusionQueryDawnEvidence(): Promise<OcclusionQueryDawnEvidence> {
+  const requested = await requestDevice();
+  if (!('createQuerySet' in requested)) return requested;
+  const device = requested;
+  const resourcesResult = createOcclusionQueryResources(device, 0);
+  if (!resourcesResult.ok) return unavailable(resourcesResult.error.code);
+  const resources = resourcesResult.value;
+
+  const shader = await createShaderModule(device, {
+    label: 'occlusion-query-evidence-shader',
+    code: `
+@vertex fn vs(@builtin(vertex_index) vertex: u32) -> @builtin(position) vec4f {
+  var positions = array<vec2f, 3>(vec2f(-1.0, -1.0), vec2f(3.0, -1.0), vec2f(-1.0, 3.0));
+  return vec4f(positions[vertex], 0.0, 1.0);
+}
+@fragment fn fs() -> @location(0) vec4f {
+  return vec4f(1.0, 0.0, 0.0, 1.0);
+}
+`,
+  });
+  if (!shader.ok) return unavailable(shader.error.code);
+  const pipeline = device.createRenderPipeline({
+    label: 'occlusion-query-evidence-pipeline',
+    layout: 'auto',
+    vertex: { module: shader.value, entryPoint: 'vs', buffers: [] },
+    fragment: {
+      module: shader.value,
+      entryPoint: 'fs',
+      targets: [{ format: 'rgba8unorm' }],
+    },
+    primitive: { topology: 'triangle-list' },
+  });
+  if (!pipeline.ok) return unavailable(pipeline.error.code);
+  const texture = device.createTexture({
+    label: 'occlusion-query-evidence-target',
+    size: { width: 4, height: 4, depthOrArrayLayers: 1 },
+    format: 'rgba8unorm',
+    usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  } as never);
+  if (!texture.ok) return unavailable(texture.error.code);
+  const view = device.createTextureView(texture.value, {});
+  if (!view.ok) return unavailable(view.error.code);
+  const encoder = device.createCommandEncoder({ label: 'occlusion-query-evidence-submit' });
+  if (!encoder.ok) return unavailable(encoder.error.code);
+  const pass = encoder.value.beginRenderPass({
+    colorAttachments: [
+      {
+        view: view.value,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+      },
+    ],
+    occlusionQuerySet: resources.querySet,
+  });
+  const beginZero = pass.beginOcclusionQuery(0);
+  if (!beginZero.ok) return unavailable(beginZero.error.code);
+  const endZero = pass.endOcclusionQuery();
+  if (!endZero.ok) return unavailable(endZero.error.code);
+  const beginPositive = pass.beginOcclusionQuery(1);
+  if (!beginPositive.ok) return unavailable(beginPositive.error.code);
+  pass.setPipeline(pipeline.value);
+  pass.draw(3);
+  const endPositive = pass.endOcclusionQuery();
+  if (!endPositive.ok) return unavailable(endPositive.error.code);
+  pass.end();
+  const resolved = recordOcclusionResolve(encoder.value, resources, 0, 2);
+  if (!resolved.ok) return unavailable(resolved.error.code);
+  const command = encoder.value.finish();
+  if (!command.ok) return unavailable(command.error.code);
+  const submitted = device.queue.submit([command.value]);
+  if (!submitted.ok) return unavailable(submitted.error.code);
+  await device.queue.onSubmittedWorkDone();
+  const mapped = await resources.stagingBuffer.mapAsync(GPU_BUFFER_USAGE_MAP_READ, 0, 16);
+  if (!mapped.ok) return unavailable(mapped.error.code);
+  const range = mapped.value.getMappedRange(0, 16);
+  if (!range.ok) return unavailable(range.error.code);
+  const values = new BigUint64Array(range.value.slice(0));
+  const lifecycle = lifecycleEvidence();
+  mapped.value.unmap();
+  return {
+    status: 'available',
+    identity: identity('webgpu-dawn'),
+    zeroSamples: Number(values[0] ?? 0n),
+    positiveSamples: Number(values[1] ?? 0n),
+    ...lifecycle,
+  };
+}

package/src/__tests__/occlusion-query.rhi-null.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { OcclusionQueryPool } from '../scene/visibility/occlusion-query-pool';
+
+describe('occlusion query RhiNull structure', () => {
+  it('keeps zero, positive, out-of-order, and fault completions all-visible', () => {
+    const pool = new OcclusionQueryPool();
+    const base = {
+      viewKey: 'view',
+      attachmentId: 'depth-0',
+      deviceGeneration: 4,
+      worldGeneration: 9,
+      primitiveSlot: 2,
+      slotGeneration: 3,
+    };
+    const first = pool.reserve({ ...base, primitiveSlot: 1 });
+    const second = pool.reserve({ ...base, primitiveSlot: 2 });
+    expect(first && second).toBeTruthy();
+    if (first === undefined || second === undefined) return;
+    const firstTicket = pool.publish(first, { submitted: true, submissionGeneration: 10 });
+    const secondTicket = pool.publish(second, { submitted: true, submissionGeneration: 11 });
+    expect(firstTicket && secondTicket).toBeTruthy();
+    if (firstTicket === undefined || secondTicket === undefined) return;
+
+    expect(pool.complete(secondTicket, 7)).toMatchObject({ status: 'accepted', visible: true });
+    expect(pool.complete(firstTicket, 0)).toMatchObject({ status: 'accepted', visible: true });
+    expect(pool.complete({ ...firstTicket, slotGeneration: 99 }, 1)).toMatchObject({
+      status: 'stale',
+      visible: true,
+    });
+  });
+});

package/src/__tests__/occlusion-runtime.unit.test.ts

@@ -0,0 +1,120 @@
+import type { RhiRenderPassEncoder, ShaderModule } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { createVisibilityBudget } from '../scene/visibility/budget';
+import { VisibilityFacetStore } from '../scene/visibility/facet';
+import {
+  OcclusionRenderRuntime,
+  type OcclusionRuntimeCandidate,
+} from '../scene/visibility/occlusion-runtime';
+
+describe('occlusion runtime proxy encoding', () => {
+  it('binds one proxy buffer and advances firstVertex across candidates', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const facets = new VisibilityFacetStore(createVisibilityBudget(2));
+    const candidates: OcclusionRuntimeCandidate[] = [candidate(0, 3), candidate(1, 2)];
+    const runtime = new OcclusionRenderRuntime(device, facets, {
+      createShaderModule: () => ok({} as ShaderModule),
+    });
+    const writeBuffer = vi.spyOn(device.queue, 'writeBuffer');
+    const projection = runtime.prepareBatch(candidates, 1, false);
+    expect(projection).toBeDefined();
+    if (projection === undefined) return;
+
+    const vertexBindings: unknown[][] = [];
+    const draws: unknown[][] = [];
+    const beginQueries: number[] = [];
+    let endCount = 0;
+    const pass = {
+      setPipeline: () => undefined,
+      setVertexBuffer: (...args: unknown[]) => vertexBindings.push(args),
+      draw: (...args: unknown[]) => draws.push(args),
+      beginOcclusionQuery: (queryIndex: number) => {
+        beginQueries.push(queryIndex);
+        return ok(undefined);
+      },
+      endOcclusionQuery: () => {
+        endCount += 1;
+        return ok(undefined);
+      },
+    } as unknown as RhiRenderPassEncoder;
+
+    expect(projection.encodeProxyBounds(pass).ok).toBe(true);
+    expect(vertexBindings).toHaveLength(1);
+    expect(vertexBindings[0]?.[0]).toBe(0);
+    expect(vertexBindings[0]?.[2]).toBeUndefined();
+    expect(vertexBindings[0]?.[3]).toBeUndefined();
+    expect(beginQueries).toEqual([0, 1]);
+    expect(draws.map((draw) => draw.slice(0, 4))).toEqual([
+      [3, 1, 0, 0],
+      [2, 1, 3, 0],
+    ]);
+    expect(endCount).toBe(2);
+    expect(runtime.prepareBatch(candidates, 1, false)).toBeUndefined();
+    expect(runtime.prepareUnavailable).toBe(true);
+    const profilePhases: string[] = [];
+    projection.commit(false, 1, (phase, action) => {
+      profilePhases.push(phase);
+      return action();
+    });
+    expect(profilePhases).toEqual(['record/occlusion-query-submit']);
+
+    const nextProjection = runtime.prepareBatch(candidates, 1, false);
+    expect(nextProjection).toBeDefined();
+    if (nextProjection === undefined) return;
+    expect(nextProjection.encodeProxyBounds(pass).ok).toBe(true);
+    expect(writeBuffer).toHaveBeenCalledTimes(2);
+    const firstUpload = writeBuffer.mock.calls[0]?.[2];
+    const secondUpload = writeBuffer.mock.calls[1]?.[2];
+    expect(ArrayBuffer.isView(firstUpload) && ArrayBuffer.isView(secondUpload)).toBe(true);
+    if (ArrayBuffer.isView(firstUpload) && ArrayBuffer.isView(secondUpload)) {
+      expect(firstUpload.buffer).toBe(secondUpload.buffer);
+    }
+    nextProjection.commit(false, 2);
+    runtime.dispose();
+  });
+
+  it('cancels and requeues a reservation when the fixed scratch overflows', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const budget = createVisibilityBudget(1);
+    const facets = new VisibilityFacetStore(budget);
+    const oversized = candidate(0, budget.effectiveQueryBudget * 36 + 1);
+    facets.activateView(oversized.view);
+    expect(facets.setCandidate(oversized.view, oversized.primitive, oversized.candidate)).toBe(
+      true,
+    );
+    const runtime = new OcclusionRenderRuntime(device, facets, {
+      createShaderModule: () => ok({} as ShaderModule),
+    });
+
+    expect(runtime.prepareBatch([oversized], 1, true)).toBeUndefined();
+    expect(runtime.prepareUnavailable).toBe(true);
+    expect(facets.dequeueQueryCandidates(oversized.view, 1)).toHaveLength(1);
+    runtime.dispose();
+  });
+});
+
+function candidate(primitiveSlot: number, vertexCount: number): OcclusionRuntimeCandidate {
+  return {
+    view: {
+      attachmentId: 'color-depth',
+      cameraEntity: 7,
+      viewRole: 'main',
+      viewGeneration: 1,
+    },
+    primitive: {
+      attachmentId: 'color-depth',
+      worldGeneration: 3,
+      primitiveSlot,
+      slotGeneration: 1,
+    },
+    epoch: 0,
+    bounds: { min: [-1, -1, 0], max: [1, 1, 1] },
+    candidate: { level: 0, confidence: 1 },
+    deviceGeneration: 1,
+    proxyVertices: new Float32Array(vertexCount * 4),
+  };
+}

package/src/__tests__/pbr-view-layout.unit.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { buildPbrViewBglEntries } from '../pbr-pipeline';
+
+describe('PBR view bind-group layout', () => {
+  it('allows capture passes to select a per-face View UBO slot', () => {
+    const entries = buildPbrViewBglEntries({ storageBuffer: true });
+    const binding0 = entries[0];
+    expect(binding0?.binding).toBe(0);
+    expect(binding0?.buffer).toEqual({ type: 'uniform', hasDynamicOffset: true });
+    expect(
+      entries
+        .filter((entry) => entry.buffer?.hasDynamicOffset === true)
+        .map((entry) => entry.binding),
+    ).toEqual([0, 10]);
+  });
+});