@forgeax/engine-render 0.1.21 → 0.1.24

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__/physical-clearcoat.integration.test.ts

@@ -0,0 +1,89 @@
+import { STANDARD_PIPELINE_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../materials.js';
+import {
+  buildBindGroupLayoutDescriptor,
+  materialBindGroupLayoutIdentity,
+} from '../pbr-pipeline.js';
+
+describe('Standard clearcoat root contract', () => {
+  it('keeps a declared factor-zero clearcoat physical and forward-only', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1], clearcoat: 0 });
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+    expect(material.parameters?.map((parameter) => parameter.name)).toContain('clearcoat');
+    expect(material.values).toMatchObject({ clearcoat: 0 });
+  });
+
+  it('retains a single root identity when coat maps are present', () => {
+    const options = {
+      baseColor: [1, 1, 1, 1] as const,
+      clearcoat: 0.8,
+      clearcoatRoughness: 0.2,
+      clearcoatTexture: 11,
+      clearcoatRoughnessTexture: 12,
+      clearcoatNormalTexture: 13,
+      clearcoatNormalScale: 0.5,
+    } as Parameters<typeof Materials.standard>[0] & Record<string, unknown>;
+    const material = Materials.standard(options);
+    expect(material.values).toMatchObject({
+      clearcoat: 0.8,
+      clearcoatRoughness: 0.2,
+      clearcoatTexture: 11,
+      clearcoatRoughnessTexture: 12,
+      clearcoatNormalTexture: 13,
+      clearcoatNormalScale: 0.5,
+    });
+  });
+
+  it('keys equivalent schema instances by the same merged layout identity', () => {
+    const withTexture = (name: string) => [
+      ...STANDARD_PIPELINE_PARAM_SCHEMA,
+      { name, type: 'texture2d' as const },
+    ];
+    const rigidR = withTexture('clearcoatTexture');
+    const rigidRClone = [...rigidR];
+    const rigidG = withTexture('clearcoatRoughnessTexture');
+    const rigidRg = [...rigidR, { name: 'clearcoatNormalTexture', type: 'texture2d' as const }];
+
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidRClone),
+    );
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).not.toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidG),
+    );
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).not.toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidRg),
+    );
+  });
+
+  it('keeps the built-in Standard IBL ABI stable when physical maps are appended', () => {
+    const schema = [
+      ...STANDARD_PIPELINE_PARAM_SCHEMA,
+      { name: 'clearcoatTexture', type: 'texture2d' as const },
+      { name: 'clearcoatNormalTexture', type: 'texture2d' as const },
+    ];
+    const descriptor = buildBindGroupLayoutDescriptor(
+      {
+        shader: { id: 'forgeax::default-standard-pbr', passKind: 'forward', variantSet: undefined },
+        attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+        geometry: { topology: 'triangle-list', vertexLayout: {} },
+        renderState: undefined,
+      },
+      { kind: 'pbr-material-merged', materialParamSchema: schema },
+    );
+
+    // The canonical seven texture pairs occupy bindings 1..14. IBL remains
+    // at 15..21 and transmission at 22..23; authored physical maps append at
+    // 24..27. Compacting the authored root here shifts WGSL IBL bindings and
+    // causes Dawn to reject the pipeline before any pixels are submitted.
+    expect(descriptor.entries).toHaveLength(28);
+    expect(descriptor.entries.slice(0, 15).map((entry) => entry.binding)).toEqual(
+      Array.from({ length: 15 }, (_, binding) => binding),
+    );
+    expect(descriptor.entries[15]?.texture).toMatchObject({ viewDimension: 'cube' });
+    expect(descriptor.entries[17]?.texture).toMatchObject({ viewDimension: 'cube' });
+    expect(descriptor.entries[22]?.sampler).toMatchObject({ type: 'filtering' });
+    expect(descriptor.entries[23]?.texture).toMatchObject({ viewDimension: '2d' });
+    expect(descriptor.entries.slice(24).map((entry) => entry.binding)).toEqual([24, 25, 26, 27]);
+  });
+});