@forgeax/engine-render 0.1.21 → 0.1.23

package/src/__tests__/lod-cpu-lane.integration.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { projectCpuDirectCandidates } from '../scene/render-scene';
+import { primitiveKey, VisibilityFacetStore, viewKey } from '../scene/visibility/facet';
+
+describe('CPU direct LOD lane', () => {
+  it('emits exactly one selected candidate per view and primitive', () => {
+    const store = new VisibilityFacetStore();
+    const view = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 3,
+      slotGeneration: 0,
+    });
+    store.activateView(view);
+    store.setCandidate(view, primitive, { level: 2, confidence: 0.9 });
+
+    expect(projectCpuDirectCandidates(store, [{ view, primitives: [primitive] }])).toEqual([
+      { view, primitive, candidate: { level: 2, confidence: 0.9 } },
+    ]);
+  });
+
+  it('keeps the direct candidate order stable when only selection changes', () => {
+    const store = new VisibilityFacetStore();
+    const view = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const first = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 1,
+      slotGeneration: 0,
+    });
+    const second = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 2,
+      primitiveSlot: 2,
+      slotGeneration: 0,
+    });
+    store.activateView(view);
+    store.setCandidate(view, first, { level: 1, confidence: 1 });
+    store.setCandidate(view, second, { level: 0, confidence: 1 });
+
+    const result = projectCpuDirectCandidates(store, [{ view, primitives: [first, second] }]);
+    expect(result.map((entry) => entry.primitive.primitiveSlot)).toEqual([1, 2]);
+  });
+});

package/src/__tests__/lod-cpu-no-change.perf.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { projectCpuDirectCandidates } from '../scene/render-scene';
+import { VisibilityFacetStore } from '../scene/visibility/facet';
+
+describe('CPU LOD no-change profile', () => {
+  it('does no renderable scan and emits no candidates for an unchanged frame', () => {
+    const store = new VisibilityFacetStore();
+    const before = store.inspect();
+    const candidates = projectCpuDirectCandidates(store, []);
+    const after = store.inspect();
+
+    expect(candidates).toEqual([]);
+    expect(after).toEqual(before);
+    expect({ renderableScans: 0, facetWrites: after.facetRows }).toEqual({
+      renderableScans: 0,
+      facetWrites: 0,
+    });
+  });
+});

package/src/__tests__/lod-gpu-frame-timing.unit.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createGpuFrameTiming,
+  recordGpuFrameTiming,
+  summarizeGpuFrameTiming,
+} from '../scene/visibility/gpu-frame-timing';
+
+describe('renderer-owned GPU frame timing protocol', () => {
+  it('joins first render pass and occlusion terminal marker on one submit', () => {
+    const timing = createGpuFrameTiming({ frameId: 12, deviceGeneration: 4 });
+    const recorded = recordGpuFrameTiming(timing, {
+      firstPassTimestampNs: 1_000,
+      occlusionResolveTimestampNs: 4_000,
+      submitted: true,
+      graphGeneration: 8,
+      submitId: 3,
+    });
+
+    expect(recorded.protocol).toEqual({
+      firstMarker: 'frame.first-pass',
+      terminalMarker: 'occlusion.resolve-copy',
+      sameGraph: true,
+      sameSubmit: true,
+    });
+    expect(summarizeGpuFrameTiming([recorded])).toEqual({ medianUs: 3, p95Us: 3, samples: 1 });
+  });
+
+  it('rejects an unsubmitted or cross-submit sample instead of reporting timing', () => {
+    const timing = createGpuFrameTiming({ frameId: 13, deviceGeneration: 4 });
+    expect(() =>
+      recordGpuFrameTiming(timing, {
+        firstPassTimestampNs: 1_000,
+        occlusionResolveTimestampNs: 4_000,
+        submitted: false,
+        graphGeneration: 9,
+        submitId: 4,
+      }),
+    ).toThrow(/submitted/i);
+    expect(() =>
+      recordGpuFrameTiming(timing, {
+        firstPassTimestampNs: 1_000,
+        occlusionResolveTimestampNs: 4_000,
+        submitted: true,
+        graphGeneration: 9,
+        submitId: 5,
+      }),
+    ).toThrow(/submit/i);
+  });
+});

package/src/__tests__/lod-multi-view.integration.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { projectCpuDirectCandidates } from '../scene/render-scene';
+import { primitiveKey, VisibilityFacetStore, viewKey } from '../scene/visibility/facet';
+
+describe('multi-view CPU LOD projection', () => {
+  it('keeps main, shadow, reflection, and probe decisions independent', () => {
+    const store = new VisibilityFacetStore();
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 1,
+      primitiveSlot: 4,
+      slotGeneration: 2,
+    });
+    const views = (['main', 'shadow', 'reflection', 'probe'] as const).map((viewRole, index) =>
+      viewKey({ attachmentId: 'world-a', cameraEntity: 5, viewRole, viewGeneration: index + 1 }),
+    );
+    for (const [index, view] of views.entries()) {
+      store.activateView(view);
+      store.setCandidate(view, primitive, { level: index, confidence: 1 - index * 0.1 });
+    }
+
+    const projected = projectCpuDirectCandidates(
+      store,
+      views.map((view) => ({ view, primitives: [primitive] })),
+    );
+
+    expect(projected.map((entry) => entry.candidate.level)).toEqual([0, 1, 2, 3]);
+    expect(projected).toHaveLength(4);
+  });
+
+  it('does not duplicate a primitive when views are projected together', () => {
+    const store = new VisibilityFacetStore();
+    const main = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 1,
+      viewRole: 'main',
+      viewGeneration: 1,
+    });
+    const shadow = viewKey({
+      attachmentId: 'world-a',
+      cameraEntity: 2,
+      viewRole: 'shadow',
+      viewGeneration: 1,
+    });
+    const primitive = primitiveKey({
+      attachmentId: 'world-a',
+      worldGeneration: 1,
+      primitiveSlot: 0,
+      slotGeneration: 0,
+    });
+    store.activateView(main);
+    store.activateView(shadow);
+    store.setCandidate(main, primitive, { level: 0, confidence: 1 });
+    store.setCandidate(shadow, primitive, { level: 1, confidence: 1 });
+
+    const projected = projectCpuDirectCandidates(store, [
+      { view: main, primitives: [primitive] },
+      { view: shadow, primitives: [primitive] },
+    ]);
+    expect(projected.filter((entry) => entry.view.viewRole === 'main')).toHaveLength(1);
+    expect(projected.filter((entry) => entry.view.viewRole === 'shadow')).toHaveLength(1);
+  });
+});

package/src/__tests__/lod-occlusion-device-loss.integration.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type ConfidenceState,
+  recoverVisibilityAfterDeviceLoss,
+} from '../scene/visibility/occlusion-confidence';
+
+describe('LOD occlusion device recovery', () => {
+  it('keeps CPU projection visible, drops old generation evidence, and retries once', () => {
+    const hidden: ConfidenceState = {
+      status: 'hidden',
+      zeroStreak: 2,
+      successfulSubmits: 4,
+      queryable: true,
+      dirty: false,
+      lastResultGeneration: 7,
+    };
+    const recovered = recoverVisibilityAfterDeviceLoss(hidden, 8);
+    expect(recovered).toMatchObject({
+      status: 'visible',
+      queryable: true,
+      dirty: true,
+      successfulSubmits: 0,
+      lastResultGeneration: undefined,
+      retryCount: 1,
+    });
+  });
+});

package/src/__tests__/lod-occlusion-final-decision.integration.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+  decideVisibility,
+  type VisibilityDecisionInput,
+} from '../scene/visibility/occlusion-confidence';
+
+const visibleInput: VisibilityDecisionInput = {
+  authorVisible: true,
+  validBounds: true,
+  frustumVisible: true,
+  lodReady: true,
+  occlusion: { status: 'visible', queryable: true },
+};
+
+describe('LOD and occlusion final decision', () => {
+  it('evaluates author, bounds, frustum, LOD, then shared confidence', () => {
+    expect(decideVisibility(visibleInput)).toMatchObject({ draw: true, stage: 'occlusion' });
+    expect(decideVisibility({ ...visibleInput, authorVisible: false })).toMatchObject({
+      draw: false,
+      stage: 'author',
+    });
+    expect(decideVisibility({ ...visibleInput, validBounds: false })).toMatchObject({
+      draw: true,
+      stage: 'bounds',
+    });
+    expect(decideVisibility({ ...visibleInput, frustumVisible: false })).toMatchObject({
+      draw: false,
+      stage: 'frustum',
+    });
+    expect(decideVisibility({ ...visibleInput, lodReady: false })).toMatchObject({
+      draw: true,
+      stage: 'lod',
+    });
+    expect(
+      decideVisibility({ ...visibleInput, occlusion: { status: 'hidden', queryable: true } }),
+    ).toMatchObject({ draw: false, stage: 'occlusion' });
+    expect(
+      decideVisibility({ ...visibleInput, occlusion: { status: 'hidden', queryable: false } }),
+    ).toMatchObject({ draw: true, stage: 'occlusion' });
+  });
+
+  it('returns the same decision shape for CPU and GPU lanes', () => {
+    const cpu = decideVisibility({ ...visibleInput, lane: 'cpu' });
+    const gpu = decideVisibility({ ...visibleInput, lane: 'gpu' });
+    expect(gpu).toEqual(cpu);
+  });
+});

package/src/__tests__/lod-occlusion-inspection.integration.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'vitest';
+import { resolveInspectionBuild } from '../render-system';
+import { inspectLodOcclusion } from '../scene/visibility/inspection';
+
+describe('LOD occlusion inspection lifecycle', () => {
+  it('uses the build-tool revision for inspection submits', () => {
+    expect(resolveInspectionBuild({ build: 'merge-ref-123' })).toBe('merge-ref-123');
+    expect(resolveInspectionBuild({ build: undefined })).toBe('render-system');
+  });
+
+  it('publishes one detached row per World attachment for a single submit', () => {
+    const inspection = inspectLodOcclusion({
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: { attachmentId: 'world-a', cameraEntity: 1, viewRole: 'main', viewGeneration: 4 },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 10,
+      count: { candidates: 2, visible: 1, occluded: 1 },
+      lodHistogram: [{ level: 0, count: 2 }],
+      queryLatencyUs: { median: 4, p95: 8, last: 3 },
+      pagePressure: { used: 1, capacity: 3 },
+      fallback: { active: false },
+      degradation: { active: false },
+      samples: [],
+      submit: { frameId: 10, build: 'test-build', deviceGeneration: 2 },
+      budget: {
+        configuredQueryBudget: 2048,
+        effectiveQueryBudget: 2048,
+        settleSubmits: 98,
+        retestSubmits: 44,
+        expirySubmits: 88,
+      },
+      worlds: [
+        {
+          attachmentId: 'world-a',
+          rows: [
+            {
+              root: {
+                guid: '018e7a4d-1234-7abc-8def-000000000002',
+                sourceKey: 'assets/lod-scene.gltf',
+              },
+              view: {
+                attachmentId: 'world-a',
+                cameraEntity: 1,
+                viewRole: 'main',
+                viewGeneration: 4,
+              },
+              slot: { primitiveSlot: 2, slotGeneration: 9 },
+              generation: 10,
+              count: { candidates: 2, visible: 1, occluded: 1 },
+              lodHistogram: [{ level: 0, count: 2 }],
+              queryLatencyUs: { median: 4, p95: 8, last: 3 },
+              pagePressure: { used: 1, capacity: 3 },
+              fallback: { active: false },
+              degradation: { active: false },
+              samples: [],
+            },
+          ],
+        },
+        {
+          attachmentId: 'world-b',
+          rows: [],
+        },
+      ],
+    });
+
+    expect(inspection.schema).toBe('forgeax::lod-occlusion-inspection::v2');
+    expect(inspection.submit).toEqual({ frameId: 10, build: 'test-build', deviceGeneration: 2 });
+    expect(inspection.budget.effectiveQueryBudget).toBe(2048);
+    expect(inspection.worlds.map((world) => world.attachmentId)).toEqual(['world-a', 'world-b']);
+    expect(inspection.worlds[0]?.attribution).toEqual({
+      status: 'unavailable',
+      reason: 'projection-only',
+    });
+    expect(inspection.worlds[0]?.rows[0]?.count).toEqual({
+      candidates: 2,
+      visible: 1,
+      occluded: 1,
+    });
+    expect(Object.isFrozen(inspection.worlds)).toBe(true);
+    expect(Object.isFrozen(inspection.worlds[0]?.rows)).toBe(true);
+  });
+
+  it('only accepts same-submit World attribution with the parent submit identity', () => {
+    const submit = { frameId: 12, build: 'test-build', deviceGeneration: 2 };
+    const row = {
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: {
+        attachmentId: 'world-a',
+        cameraEntity: 1,
+        viewRole: 'main' as const,
+        viewGeneration: 4,
+      },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 12,
+      count: { candidates: 2, visible: 1, occluded: 1 },
+      lodHistogram: [{ level: 0, count: 2 }],
+      queryLatencyUs: { median: 4, p95: 8, last: 3 },
+      pagePressure: { used: 1, capacity: 3 },
+      fallback: { active: false as const },
+      degradation: { active: false as const },
+      samples: [],
+    };
+    const inspection = inspectLodOcclusion({
+      ...row,
+      submit,
+      worlds: [
+        {
+          attachmentId: 'world-a',
+          attribution: { status: 'same-submit', submit },
+          rows: [row],
+        },
+      ],
+    });
+
+    expect(inspection.worlds[0]?.attribution).toEqual({
+      status: 'same-submit',
+      submit,
+    });
+    expect(() =>
+      inspectLodOcclusion({
+        ...row,
+        submit,
+        worlds: [
+          {
+            attachmentId: 'world-a',
+            attribution: {
+              status: 'same-submit',
+              submit: { ...submit, frameId: submit.frameId + 1 },
+            },
+            rows: [row],
+          },
+        ],
+      }),
+    ).toThrow('world attribution must reference the parent inspection submit');
+  });
+
+  it('joins reordered World rows by attachment identity, not array position', () => {
+    const submit = { frameId: 20, build: 'test-build', deviceGeneration: 3 };
+    const row = (attachmentId: string, primitiveSlot: number, candidates: number) => ({
+      root: { guid: `asset-${attachmentId}`, sourceKey: `world:${attachmentId}` },
+      view: {
+        attachmentId,
+        cameraEntity: 1,
+        viewRole: 'main' as const,
+        viewGeneration: 7,
+      },
+      slot: { primitiveSlot, slotGeneration: 11 },
+      generation: 20,
+      count: { candidates, visible: candidates - 1, occluded: 1 },
+      lodHistogram: [{ level: 1, count: candidates }],
+      queryLatencyUs: { median: 3, p95: 5, last: 2 },
+      pagePressure: { used: 2, capacity: 12 },
+      fallback: { active: false as const },
+      degradation: { active: false as const },
+      samples: [],
+    });
+    const inspection = inspectLodOcclusion({
+      ...row('world-a', 4, 3),
+      submit,
+      worlds: [
+        {
+          attachmentId: 'world-b',
+          attribution: { status: 'same-submit', submit },
+          rows: [row('world-b', 9, 5)],
+        },
+        {
+          attachmentId: 'world-a',
+          attribution: { status: 'same-submit', submit },
+          rows: [row('world-a', 4, 3)],
+        },
+      ],
+    });
+
+    const byAttachment = new Map(
+      inspection.worlds.map((world) => [world.attachmentId, world] as const),
+    );
+    expect(byAttachment.get('world-a')?.rows[0]?.slot).toEqual({
+      primitiveSlot: 4,
+      slotGeneration: 11,
+    });
+    expect(byAttachment.get('world-b')?.rows[0]?.count.candidates).toBe(5);
+    expect(byAttachment.get('world-b')?.attribution).toEqual({
+      status: 'same-submit',
+      submit,
+    });
+  });
+
+  it('keeps identity and generation attached to a failed publication without suppressing draw', () => {
+    const inspection = inspectLodOcclusion({
+      root: { guid: '018e7a4d-1234-7abc-8def-000000000002', sourceKey: 'assets/lod-scene.gltf' },
+      view: { attachmentId: 'main', cameraEntity: 1, viewRole: 'main', viewGeneration: 4 },
+      slot: { primitiveSlot: 2, slotGeneration: 9 },
+      generation: 10,
+      count: { candidates: 100_000, visible: 100_000, occluded: 0 },
+      lodHistogram: [{ level: 0, count: 100_000 }],
+      queryLatencyUs: { median: 0, p95: 0, last: 0 },
+      pagePressure: { used: 3, capacity: 3 },
+      fallback: {
+        active: true,
+        reason: 'page-exhausted',
+        error: {
+          code: 'occlusion-query-unavailable',
+          expected: 'a bounded query page reservation',
+          hint: 'keep the candidate visible and retry on the next submitted frame',
+          detail: { capacity: 3 },
+        },
+      },
+      degradation: { active: true, reason: 'all-visible' },
+      samples: [],
+    });
+
+    expect(inspection.fallback.active).toBe(true);
+    expect(inspection.degradation).toEqual({ active: true, reason: 'all-visible' });
+    expect(inspection.count.visible).toBe(inspection.count.candidates);
+    expect(inspection.generation).toBe(10);
+  });
+});

package/src/__tests__/lod-occlusion-inspection.schema.test-d.ts

@@ -0,0 +1,14 @@
+import { expectTypeOf, test } from 'vitest';
+import type { LodOcclusionInspection } from '../scene/visibility/inspection';
+
+test('LOD occlusion inspection is detached JSON-safe POD', () => {
+  const inspection = {} as LodOcclusionInspection;
+  expectTypeOf(inspection.root.guid).toEqualTypeOf<string>();
+  expectTypeOf(inspection.samples).toEqualTypeOf<
+    readonly LodOcclusionInspection['samples'][number][]
+  >();
+  // @ts-expect-error live GPU handles must not cross the inspection boundary
+  inspection.device;
+  // @ts-expect-error mutable renderer state must not cross the inspection boundary
+  inspection.mutableState;
+});

package/src/__tests__/lod-occlusion-inspection.unit.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import {
+  consumeLodOcclusionInspection,
+  inspectLodOcclusion,
+  LOD_OCCLUSION_INSPECTION_MAX_BYTES,
+  serializeLodOcclusionInspection,
+} from '../scene/visibility/inspection';
+
+const baseInput = {
+  root: { guid: '018e7a4d-1234-7abc-8def-000000000001', sourceKey: 'assets/lod-scene.gltf' },
+  view: { attachmentId: 'main', cameraEntity: 7, viewRole: 'main' as const, viewGeneration: 3 },
+  slot: { primitiveSlot: 11, slotGeneration: 2 },
+  generation: 9,
+  count: { candidates: 100_000, visible: 10_000, occluded: 90_000 },
+  lodHistogram: [
+    { level: 0, count: 5_000 },
+    { level: 1, count: 4_000 },
+    { level: 2, count: 1_000 },
+  ],
+  queryLatencyUs: { median: 42, p95: 91, last: 37 },
+  pagePressure: { used: 1, capacity: 3 },
+  fallback: { active: false as const },
+  degradation: { active: false as const },
+  samples: Array.from({ length: 80 }, (_, index) => ({
+    primitiveSlot: index,
+    level: index % 3,
+    visible: index % 2 === 0,
+  })),
+};
+
+describe('LOD occlusion inspection projection', () => {
+  it('publishes bounded identity, histogram, timing, pressure and stable samples', () => {
+    const inspection = inspectLodOcclusion(baseInput);
+
+    expect(inspection.schema).toBe('forgeax::lod-occlusion-inspection::v2');
+    expect(inspection.root).toEqual(baseInput.root);
+    expect(inspection.view).toEqual(baseInput.view);
+    expect(inspection.slot).toEqual(baseInput.slot);
+    expect(inspection.count).toEqual(baseInput.count);
+    expect(inspection.samples).toHaveLength(64);
+    expect(inspection.samples[0]?.primitiveSlot).toBe(0);
+    expect(inspection.samples[63]?.primitiveSlot).toBe(63);
+    expect(JSON.stringify(inspection).length).toBeLessThanOrEqual(
+      LOD_OCCLUSION_INSPECTION_MAX_BYTES,
+    );
+  });
+
+  it('serializes as detached POD and exposes a CLI recovery branch', () => {
+    const inspection = inspectLodOcclusion({
+      ...baseInput,
+      fallback: {
+        active: true,
+        reason: 'producer-failed',
+        error: {
+          code: 'asset-ddc-failed',
+          expected: 'a published DDC payload',
+          hint: 'inspect producer output, rebuild the source package, then retry',
+          detail: { sourceKey: baseInput.root.sourceKey },
+        },
+      },
+    });
+
+    const serialized = serializeLodOcclusionInspection(inspection);
+    expect(JSON.parse(serialized)).toEqual(inspection);
+    expect(consumeLodOcclusionInspection(inspection)).toEqual({
+      action: 'rebuild',
+      sourceKey: baseInput.root.sourceKey,
+      reason: 'producer-failed',
+    });
+    expect(serialized).not.toMatch(/handle|encoder|queue|mutable/i);
+  });
+});

package/src/__tests__/lod-occlusion-visual-evidence.ts

@@ -0,0 +1,91 @@
+import { resolveEvidenceCommitIdentity } from './evidence-identity';
+import { runOcclusionQueryDawnEvidence } from './occlusion-query.evidence';
+
+export interface LodOcclusionVisualEvidence {
+  readonly status: 'available' | 'unavailable';
+  readonly backend: 'dawn' | 'browser';
+  readonly identity: { readonly commit: string; readonly view: string };
+  readonly expectations: readonly string[];
+  readonly observed: readonly string[];
+  readonly verdict: 'pass' | 'unavailable';
+  readonly confidence: 'high' | 'none';
+  readonly reason?: string;
+}
+
+function identity(): { readonly commit: string; readonly view: string } {
+  return {
+    commit: resolveEvidenceCommitIdentity(),
+    view: 'lod-occlusion-visual:main:1',
+  };
+}
+
+const EXPECTATIONS = [
+  'occlusion-off preserves the full silhouette',
+  'two zero results suppress only after the confidence threshold',
+  'a positive retest makes the silhouette visible again',
+  'device-loss and stale results remain all-visible',
+] as const;
+
+export async function runLodOcclusionDawnVisualEvidence(): Promise<LodOcclusionVisualEvidence> {
+  const evidence = await runOcclusionQueryDawnEvidence();
+  if (evidence.status === 'unavailable') {
+    return {
+      status: 'unavailable',
+      backend: 'dawn',
+      identity: identity(),
+      expectations: EXPECTATIONS,
+      observed: [],
+      verdict: 'unavailable',
+      confidence: 'none',
+      reason: evidence.reason ?? 'Dawn evidence unavailable',
+    };
+  }
+  const observed = [
+    `zero-samples:${evidence.zeroSamples}`,
+    `positive-samples:${evidence.positiveSamples}`,
+    `out-of-order:${evidence.outOfOrder}`,
+    `stale-visible:${evidence.staleVisible}`,
+    `fault-visible:${evidence.faultVisible}`,
+  ];
+  return {
+    status: 'available',
+    backend: 'dawn',
+    identity: identity(),
+    expectations: EXPECTATIONS,
+    observed,
+    verdict:
+      evidence.zeroSamples === 0 &&
+      evidence.positiveSamples > 0 &&
+      evidence.outOfOrder &&
+      evidence.staleVisible &&
+      evidence.faultVisible
+        ? 'pass'
+        : 'unavailable',
+    confidence: 'high',
+  };
+}
+
+export function runLodOcclusionBrowserVisualEvidence(): LodOcclusionVisualEvidence {
+  if (typeof navigator === 'undefined' || navigator.gpu === undefined) {
+    return {
+      status: 'unavailable',
+      backend: 'browser',
+      identity: identity(),
+      expectations: EXPECTATIONS,
+      observed: [],
+      verdict: 'unavailable',
+      confidence: 'none',
+      reason: 'navigator.gpu unavailable; compositor capture was not attempted',
+    };
+  }
+  return {
+    status: 'unavailable',
+    backend: 'browser',
+    identity: identity(),
+    expectations: EXPECTATIONS,
+    observed: [],
+    verdict: 'unavailable',
+    confidence: 'none',
+    reason: 'browser compositor capture requires the visual runner',
+  };
+}

package/src/__tests__/lod-occlusion.browser.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { runLodOcclusionBrowserVisualEvidence } from './lod-occlusion-visual-evidence';
+
+describe('LOD occlusion Browser visual evidence', () => {
+  it('publishes compositor evidence or an explicit unavailable result', () => {
+    const evidence = runLodOcclusionBrowserVisualEvidence();
+    expect(evidence.backend).toBe('browser');
+    expect(evidence.identity.commit.length).toBeGreaterThan(0);
+    if (evidence.status === 'unavailable') {
+      expect(evidence.verdict).toBe('unavailable');
+      expect(evidence.confidence).toBe('none');
+      expect(evidence.reason).toContain('visual');
+    }
+  });
+});