@forgeax/engine-render 0.1.21 → 0.1.23

package/src/__tests__/reflection-probe-owner-placement.unit.test.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const renderSystemPath = fileURLToPath(new URL('../render-system.ts', import.meta.url));
+const recordOwnerPath = fileURLToPath(new URL('../reflection/record-owner.ts', import.meta.url));
+const renderSystemSource = readFileSync(renderSystemPath, 'utf8');
+const recordOwnerSource = existsSync(recordOwnerPath) ? readFileSync(recordOwnerPath, 'utf8') : '';
+
+describe('ReflectionProbe owner placement', () => {
+  it('defines the owner exactly once under the reflection cluster', () => {
+    expect(existsSync(recordOwnerPath)).toBe(true);
+    expect(recordOwnerSource.match(/export class ReflectionProbeRecordOwner/g)).toHaveLength(1);
+    expect(renderSystemSource).not.toMatch(/class ReflectionProbeRecordOwner/);
+    expect(renderSystemSource).toContain(
+      "import { ReflectionProbeRecordOwner } from './reflection/record-owner';",
+    );
+  });
+
+  it('keeps render-system as the sole owner assembly and delegation point', () => {
+    expect(renderSystemSource.match(/new ReflectionProbeRecordOwner\(internals\)/g)).toHaveLength(
+      1,
+    );
+    expect(recordOwnerSource.match(/new ReflectionProbeRecordOwner\(/g)).toBeNull();
+    expect(renderSystemSource).toContain('reflectionProbeOwner.prepare(');
+    expect(renderSystemSource).toContain('reflectionProbeOwner.inspect()');
+    expect(renderSystemSource).toContain('reflectionProbeOwner.dispose()');
+  });
+
+  it('rejects a parallel SSR owner, cache, or commit ledger vocabulary', () => {
+    const combinedSource = `${renderSystemSource}\n${recordOwnerSource}`;
+    expect(combinedSource).not.toMatch(/\bSsrProbeManager\b/);
+    expect(combinedSource).not.toMatch(/\bSsrEnvironmentCache\b/);
+    expect(combinedSource).not.toMatch(
+      /\b(?:Ssr|SSR)(?:Probe|Environment).*(?:Ledger|Cache|Manager)\b/,
+    );
+    expect(combinedSource).not.toMatch(/\bcommitLedger\b/);
+  });
+});

package/src/__tests__/reflection-probe-record-owner.characterization.unit.test.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  commitProbeFilterStep,
+  createProbeFilterState,
+  type ProbeFilterState,
+  probeFilterIsSteady,
+} from '../reflection/filter';
+
+const renderSystemSource = readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8');
+const recordOwnerPath = fileURLToPath(new URL('../reflection/record-owner.ts', import.meta.url));
+const recordOwnerSource = existsSync(recordOwnerPath) ? readFileSync(recordOwnerPath, 'utf8') : '';
+const inlineOwnerStart = renderSystemSource.indexOf('class ReflectionProbeRecordOwner');
+const inlineOwnerEnd = renderSystemSource.indexOf(
+  'export function createRenderSystem',
+  inlineOwnerStart,
+);
+const inlineOwnerSource = renderSystemSource.slice(inlineOwnerStart, inlineOwnerEnd);
+const ownerSource = recordOwnerSource.includes('class ReflectionProbeRecordOwner')
+  ? recordOwnerSource
+  : inlineOwnerSource;
+const ownerContractsSource = `${renderSystemSource}\n${ownerSource}`;
+
+describe('ReflectionProbeRecordOwner characterization', () => {
+  it('keeps candidate resources invisible until an active generation exists', () => {
+    expect(ownerSource).toContain('class ReflectionProbeRecordOwner');
+    expect(ownerContractsSource).toContain('active: ProbeCubeSet | undefined;');
+    expect(ownerContractsSource).toContain('candidate: ProbeCubeSet;');
+    expect(ownerContractsSource).toContain('spare: ProbeCubeSet | undefined;');
+    expect(ownerSource).toContain('const active = resource.active;');
+    expect(ownerSource).toContain('if (active === undefined) return undefined;');
+    expect(ownerSource).toContain('filteredView: active.cubeView');
+  });
+
+  it('publishes only through the accepted submission completion boundary', () => {
+    expect(ownerSource).toContain('resource.pending = { rawCaptureFace, step };');
+    expect(ownerSource).toContain(
+      'completeSubmission: (submitted, completed, fallbackOutput, fallbackRequested = true) =>',
+    );
+    expect(ownerSource).toContain('if (!submitted || pending === undefined) continue;');
+    expect(ownerSource).toContain('resource.rawFaceCursor = Math.min(');
+    expect(ownerSource).toContain(
+      'resource.filter = commitProbeFilterStep(resource.filter, true);',
+    );
+    expect(ownerSource).toContain('resource.active = resource.candidate;');
+    expect(ownerSource).toContain(
+      'resource.candidate = resource.spare ?? previous ?? resource.candidate;',
+    );
+  });
+
+  it('discards failed completion and preserves incremental filter state', () => {
+    expect(ownerSource).toContain('fallbackRequested,');
+    expect(ownerSource).toContain('if (!fallbackRequested)');
+    expect(ownerSource).toContain('if (pending.step === undefined) continue;');
+    expect(ownerSource).toContain('if (resource.pending !== undefined) continue;');
+
+    const initial = createProbeFilterState({ probeIndex: 2, mipCount: 2 });
+    expect(commitProbeFilterStep(initial, false)).toEqual(initial);
+    const first = commitProbeFilterStep(initial, true);
+    expect(first.cursor).toBe(1);
+    expect(first.activeGeneration).toBe(0);
+    expect(probeFilterIsSteady(first)).toBe(false);
+    const complete = Array.from({ length: 11 }).reduce<ProbeFilterState>(
+      (state) => commitProbeFilterStep(state, true),
+      first,
+    );
+    expect(probeFilterIsSteady(complete)).toBe(true);
+    expect(complete.activeGeneration).toBe(1);
+  });
+
+  it('resets capture work on revision changes while retaining active generation identity', () => {
+    expect(ownerSource).toContain('if (existing.fact.revision !== fact.revision)');
+    expect(ownerSource).toContain('activeGeneration: existing.filter.activeGeneration');
+    expect(ownerSource).toContain('existing.rawFaceCursor = 0;');
+    expect(ownerSource).toContain('this.resources.clear();');
+    expect(ownerSource).toContain('this.pipelineWarmup = undefined;');
+  });
+
+  it('does not derive one fallback snapshot from the sorted first probe', () => {
+    expect(ownerSource).not.toContain('const selectedProbe = [...selections.values()]');
+    expect(ownerSource).toContain('fallbackProjections');
+    expect(ownerSource).toContain('renderableKey');
+    expect(ownerSource).toContain('sourceKey');
+    expect(ownerSource).toContain('producerId');
+    expect(ownerSource).toContain('rendererId');
+    expect(ownerSource).toContain('deviceGeneration');
+    expect(ownerSource).toContain('frameId');
+    expect(ownerSource).not.toContain('const first = this.fallbackReceipts.values()');
+    expect(ownerSource).toContain('reflectionFallbackReadback');
+  });
+
+  it('selects the committed neutral row when the environment source disappears', () => {
+    expect(ownerSource).toContain(
+      'this.selectFallbackReceiptKey(tickets, skylight !== undefined);',
+    );
+    expect(ownerSource).toContain("if (!skylightAvailable && this.lastSelection.kind !== 'probe')");
+    expect(ownerSource).toContain("pending.projection.source === 'neutral'");
+  });
+
+  it('does not publish an active receipt from a descriptor without readback', () => {
+    expect(ownerSource).toContain('fallbackOutput?.readback === undefined');
+    expect(ownerSource).toContain('this.fallbackReadback = Object.freeze');
+    expect(ownerSource).toContain("readbackStatus: 'complete'");
+    expect(ownerSource).not.toContain("readbackStatus: 'scheduled'");
+    expect(ownerSource).toContain('readbackHash: readback.hash');
+    expect(ownerSource).not.toContain('linearHdr: readback.linearHdr');
+    expect(ownerSource).toContain('const staged = this.pendingFallback.get(pending.ticket);');
+    expect(ownerSource).toContain('latestFallbackTickets');
+  });
+
+  it('keeps fallback capability and recovery facts on the same owner', () => {
+    expect(ownerSource).toContain('private fallbackFormatAvailable: boolean;');
+    expect(ownerSource).toContain('this.refreshFallbackCapabilities(frameId);');
+    expect(ownerSource).toContain('reflection-fallback-format-unavailable');
+    expect(ownerSource).toContain('retireFallbackState(frameId);');
+    expect(ownerSource).toContain('reflectionFallbackInspection');
+    expect(ownerSource).toContain('this.clearFallbackFailure();');
+  });
+});

package/src/__tests__/render-error-code-owner.test-d.ts

@@ -66,6 +66,7 @@ const expectedCodes = [
   'points-lines-material-unsupported',
   'points-lines-budget-exceeded',
   'points-lines-prepare-failed',
+  'light-resource-unavailable',
   'render-target-descriptor-invalid',
   'render-target-capability-missing',
   'render-target-state-invalid',

package/src/__tests__/render-feature-docs.unit.test.ts

@@ -15,9 +15,14 @@ const renderReadme = read('../../README.md');
 const runtimeReadme = read('../../../runtime/README.md');
 const appSkill = read('../../../../skills/forgeax-engine-app/SKILL.md');
 
-// M4-06 prepends the direct-light contract; keep the existing first-read
-// vocabulary assertion wide enough to cover that approved contract.
-const topSurface = renderReadme.slice(0, 20000);
+const firstReadHeading = '## RenderFeature: the producer seam (first-read index)';
+const firstReadStart = renderReadme.indexOf(firstReadHeading);
+const firstReadEnd = renderReadme.indexOf('\n## ', firstReadStart + firstReadHeading.length);
+const topSurface = renderReadme.slice(
+  firstReadStart,
+  firstReadEnd === -1 ? undefined : firstReadEnd,
+);
+const searchableTopSurface = topSurface.replace(/\s+/g, ' ');
 
 describe('RenderFeature documentation surface', () => {
   it('keeps the first-read public route and four-term vocabulary indexable', () => {
@@ -32,11 +37,11 @@ describe('RenderFeature documentation surface', () => {
       'Standard Pipeline',
       'RenderGraph pass',
     ]) {
-      expect(topSurface).toContain(token);
+      expect(searchableTopSurface).toContain(token);
     }
-    expect(topSurface).not.toContain('passContext.commands');
-    expect(topSurface).not.toContain('context.staging.addPass');
-    expect(topSurface).not.toContain('graph-only Wave 1 feature');
+    expect(searchableTopSurface).not.toContain('passContext.commands');
+    expect(searchableTopSurface).not.toContain('context.staging.addPass');
+    expect(searchableTopSurface).not.toContain('graph-only Wave 1 feature');
     expect(runtimeReadme).toContain('createRenderer(canvas, options?, bundler?)');
     expect(appSkill).toContain('Renderer feature assembly');
   });

package/src/__tests__/render-graph-fallback.integration.test.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+describe('Standard PBR fallback graph integration contract', () => {
+  it('keeps the fallback output at the canonical BRDF callsite', () => {
+    const source = readFileSync(
+      resolve(import.meta.dirname, '../../../shader/src/default-standard-pbr.wgsl'),
+      'utf8',
+    );
+    expect(source).toContain('sampleIblDiffuse');
+    expect(source).toContain('sampleIblSpecular');
+    expect(source).toContain('S_fallback');
+    expect(source).toContain('REFLECTION_FALLBACK_AVAILABLE');
+  });
+
+  it('does not introduce SSR history, trace, or Hi-Z work', () => {
+    const source = readFileSync(
+      resolve(import.meta.dirname, '../../../shader/src/default-standard-pbr.wgsl'),
+      'utf8',
+    );
+    expect(source).not.toMatch(/ssrHistory|rayMarch|hiz|hi-z/i);
+  });
+});

package/src/__tests__/render-perf/extended-lighting.bench.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { PROBE_MAX_CONTRIBUTORS, ProbeBlendSceneProjection } from '../../scene/probe-blend';
+
+const OBJECT_COUNT = 8;
+const PROBE_COUNT = PROBE_MAX_CONTRIBUTORS;
+const SAMPLE_COUNT = 5;
+
+function summarize(samplesMs: readonly number[]) {
+  const sorted = [...samplesMs].sort((left, right) => left - right);
+  return {
+    status: samplesMs.length === 0 ? 'not-run' : 'complete',
+    workload: 'probe-blend-8-objects-64-admitted',
+    sampleCount: samplesMs.length,
+    medianMs: sorted[Math.floor(sorted.length / 2)] ?? 0,
+    p95Ms: sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)] ?? 0,
+    recordByteLength: 160,
+    contributorCapacity: 64,
+  } as const;
+}
+
+function makeProbe(index: number) {
+  return {
+    identity: `m6-probe-${index}`,
+    position: [0, 0, 0] as const,
+    radius: 4,
+    irradiance: new Float32Array(27).fill(1),
+    admitted: true,
+  };
+}
+
+describe('M6 extended-lighting CPU performance carrier', () => {
+  it('measures all admitted contributors without a per-object top-K selection', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const probes = Array.from({ length: PROBE_COUNT }, (_, index) => makeProbe(index));
+    const objects = Array.from({ length: OBJECT_COUNT }, (_, objectKey) => ({
+      objectKey,
+      generation: 0,
+      position: [0, 0, 0] as const,
+    }));
+    const samples: number[] = [];
+    let sink = 0;
+
+    for (let sample = 0; sample < SAMPLE_COUNT; sample += 1) {
+      const start = performance.now();
+      const result = projection.apply({
+        objects: objects.map((object) => ({ ...object, generation: sample })),
+        probes,
+        skyIrradiance: [0.1, 0.2, 0.3],
+      });
+      samples.push(performance.now() - start);
+      expect(result.error).toBeUndefined();
+      expect(result.admittedProbeCount).toBe(PROBE_COUNT);
+      expect(result.records).toHaveLength(OBJECT_COUNT);
+      sink += result.records.reduce((sum, record) => sum + record.byteLength, 0);
+    }
+
+    const receipt = summarize(samples);
+    // biome-ignore lint/suspicious/noConsole: benchmark emits host evidence for the carrier receipt
+    console.info(JSON.stringify({ ...receipt, sink, host: process.platform }));
+    expect(sink).toBe(OBJECT_COUNT * SAMPLE_COUNT * 160);
+    expect(receipt.status).toBe('complete');
+    expect(receipt.sampleCount).toBe(SAMPLE_COUNT);
+    expect(Number.isFinite(receipt.medianMs)).toBe(true);
+    expect(Number.isFinite(receipt.p95Ms)).toBe(true);
+  }, 60_000);
+});