@forgeax/engine-render 0.1.7 → 0.1.20

package/src/transmission/__tests__/inspection.unit.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it } from 'vitest';
+import {
+  resolveTransmissionBackdropTopology,
+  type TransmissionBackdropResourceFacts,
+  TransmissionCandidateAdmission,
+  type TransmissionCapabilityFacts,
+} from '../backdrop';
+import {
+  estimateTransmissionBackdropBytes,
+  inspectTransmission,
+  inspectTransmissionFromAdmission,
+  type TransmissionInspectionInput,
+  transmissionInspectionToJson,
+} from '../inspection';
+
+function facts(overrides: Partial<TransmissionCapabilityFacts> = {}): TransmissionCapabilityFacts {
+  return {
+    format: 'rgba16float',
+    renderAttachment: true,
+    copySrc: true,
+    textureBinding: true,
+    mipView: true,
+    filteringSampler: true,
+    bindGroupLayout: true,
+    msaaResolve: true,
+    resourceCreation: true,
+    ...overrides,
+  };
+}
+
+function resource(overrides: Partial<TransmissionBackdropResourceFacts> = {}) {
+  return {
+    extent: { width: 4, height: 4 },
+    format: 'rgba16float',
+    mipCount: 2,
+    bytes: 160,
+    deviceGeneration: 3,
+    ...overrides,
+  } satisfies TransmissionBackdropResourceFacts;
+}
+
+function input(overrides: Partial<TransmissionInspectionInput> = {}): TransmissionInspectionInput {
+  return {
+    demand: { activeCount: 2, needsRoughMips: true },
+    topology: resolveTransmissionBackdropTopology({
+      demand: { activeCount: 2, needsRoughMips: true },
+      sourceSampleCount: 1,
+    }),
+    extent: { width: 4, height: 4 },
+    generation: 7,
+    lastKnownGood: true,
+    recovery: 'idle',
+    transmissionDrawCount: 2,
+    fallbackCount: 1,
+    ...overrides,
+  };
+}
+
+describe('detached transmission inspection', () => {
+  it('derives the bounded cost fields from demand and typed topology', () => {
+    const inspection = inspectTransmission(input());
+
+    expect(inspection).toEqual({
+      activeCount: 2,
+      needsRoughMips: true,
+      extent: { width: 4, height: 4 },
+      format: 'rgba16float',
+      mipCount: 2,
+      bytes: 160,
+      copyCount: 1,
+      transmissionDrawCount: 2,
+      fallbackCount: 1,
+      generation: 7,
+      singleLayer: true,
+      lifecycle: 'resident',
+      lastKnownGood: true,
+      recovery: 'idle',
+      capability: { ok: true, missing: [] },
+    });
+    expect(Object.isFrozen(inspection)).toBe(true);
+    expect(Object.isFrozen(inspection.extent)).toBe(true);
+    expect(estimateTransmissionBackdropBytes({ width: 4, height: 4 }, 2)).toBe(160);
+  });
+
+  it('restores exact zero physical work when demand has no active candidate', () => {
+    const inspection = inspectTransmission({
+      demand: { activeCount: 0, needsRoughMips: false },
+      topology: resolveTransmissionBackdropTopology({
+        demand: { activeCount: 0, needsRoughMips: false },
+        sourceSampleCount: 4,
+      }),
+      extent: { width: 320, height: 200 },
+      generation: 8,
+      lastKnownGood: false,
+      recovery: 'idle',
+    });
+
+    expect(inspection).toMatchObject({
+      activeCount: 0,
+      needsRoughMips: false,
+      mipCount: 0,
+      bytes: 0,
+      copyCount: 0,
+      transmissionDrawCount: 0,
+      fallbackCount: 0,
+      singleLayer: true,
+      lifecycle: 'inactive',
+    });
+  });
+
+  it('projects only committed admission facts and keeps a compatible LKG on rejection', () => {
+    const admission = new TransmissionCandidateAdmission();
+    const demand = { activeCount: 1, needsRoughMips: true } as const;
+    expect(admission.admit(demand, facts(), resource()).ok).toBe(true);
+
+    const rejected = admission.admit(demand, facts({ copySrc: false }), resource());
+    expect(rejected).toMatchObject({ ok: false, published: false, generation: 1 });
+
+    const inspection = inspectTransmissionFromAdmission({
+      admission: admission.inspectLifecycle(),
+      topology: resolveTransmissionBackdropTopology({ demand, sourceSampleCount: 1 }),
+      extent: { width: 99, height: 99 },
+      transmissionDrawCount: 1,
+    });
+    expect(inspection).toMatchObject({
+      generation: 1,
+      extent: { width: 4, height: 4 },
+      bytes: 160,
+      copyCount: 1,
+      lifecycle: 'resident',
+      lastKnownGood: true,
+      recovery: 'compatible-lkg',
+      capability: { ok: false, missing: ['copySrc'] },
+    });
+  });
+
+  it('does not expose live GPU objects and serializes deterministically', () => {
+    const inspection = inspectTransmission(
+      input({
+        capability: { ok: false, missing: ['resourceCreation'] },
+        lifecycle: 'failed',
+        recovery: 'rebuild-required',
+      }),
+    );
+    const serialized = transmissionInspectionToJson(inspection);
+    expect(JSON.parse(serialized)).toEqual(inspection);
+    expect(serialized).not.toMatch(/texture|view|encoder|queue/i);
+    expect(Object.keys(inspection)).toEqual([
+      'activeCount',
+      'needsRoughMips',
+      'extent',
+      'format',
+      'mipCount',
+      'bytes',
+      'copyCount',
+      'transmissionDrawCount',
+      'fallbackCount',
+      'generation',
+      'singleLayer',
+      'lifecycle',
+      'lastKnownGood',
+      'recovery',
+      'capability',
+    ]);
+  });
+
+  it('clears the old physical resource after device loss while retaining demand for rebuild', () => {
+    const admission = new TransmissionCandidateAdmission();
+    const demand = { activeCount: 1, needsRoughMips: false } as const;
+    admission.admit(demand, facts(), resource({ mipCount: 1, bytes: 128 }));
+    admission.markDeviceLost();
+
+    const inspection = inspectTransmissionFromAdmission({
+      admission: admission.inspectLifecycle(),
+      topology: resolveTransmissionBackdropTopology({ demand, sourceSampleCount: 1 }),
+      extent: { width: 4, height: 4 },
+    });
+    expect(inspection).toMatchObject({
+      activeCount: 1,
+      needsRoughMips: false,
+      mipCount: 0,
+      bytes: 0,
+      copyCount: 0,
+      generation: 1,
+      lifecycle: 'device-lost',
+      lastKnownGood: false,
+      recovery: 'rebuild-required',
+    });
+  });
+
+  it('retires an incompatible resize candidate instead of exposing stale LKG bytes', () => {
+    const admission = new TransmissionCandidateAdmission();
+    const demand = { activeCount: 1, needsRoughMips: true } as const;
+    expect(admission.admit(demand, facts(), resource()).ok).toBe(true);
+
+    const rejected = admission.admit(
+      demand,
+      facts({ copySrc: false }),
+      resource({ extent: { width: 8, height: 4 }, mipCount: 4, bytes: 352 }),
+    );
+    expect(rejected).toMatchObject({
+      ok: false,
+      published: false,
+      generation: 1,
+      demand,
+      missing: ['copySrc'],
+    });
+    expect(admission.inspectLifecycle()).toMatchObject({
+      lifecycle: 'failed',
+      lastKnownGood: false,
+      recovery: 'rebuild-required',
+    });
+    expect(admission.inspectLifecycle()).not.toHaveProperty('resource');
+  });
+
+  it('publishes a recovered resource after an explicit device-loss recovery', () => {
+    const admission = new TransmissionCandidateAdmission();
+    const demand = { activeCount: 1, needsRoughMips: true } as const;
+    expect(admission.admit(demand, facts(), resource()).ok).toBe(true);
+
+    admission.markRecoveryStarted();
+    expect(admission.inspectLifecycle()).toMatchObject({
+      lifecycle: 'recovering',
+      lastKnownGood: false,
+      recovery: 'rebuild-required',
+    });
+
+    const recovered = admission.admit(
+      demand,
+      facts(),
+      resource({ deviceGeneration: 4, extent: { width: 8, height: 4 }, mipCount: 3, bytes: 336 }),
+    );
+    expect(recovered).toMatchObject({ ok: true, published: true, generation: 2 });
+    expect(admission.inspectLifecycle()).toMatchObject({
+      lifecycle: 'resident',
+      lastKnownGood: true,
+      recovery: 'recovered',
+      resource: expect.objectContaining({ deviceGeneration: 4, extent: { width: 8, height: 4 } }),
+    });
+  });
+});

package/src/transmission/__tests__/lifecycle.integration.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import {
+  resolveTransmissionBackdropTopology,
+  type TransmissionBackdropResourceFacts,
+  TransmissionCandidateAdmission,
+  type TransmissionCapabilityFacts,
+} from '../backdrop';
+import { inspectTransmissionFromAdmission } from '../inspection';
+
+const capability: TransmissionCapabilityFacts = {
+  format: 'rgba16float',
+  renderAttachment: true,
+  copySrc: true,
+  textureBinding: true,
+  mipView: true,
+  filteringSampler: true,
+  bindGroupLayout: true,
+  msaaResolve: true,
+  resourceCreation: true,
+};
+
+function resource(
+  extent: { width: number; height: number },
+  deviceGeneration: number,
+): TransmissionBackdropResourceFacts {
+  return {
+    extent,
+    format: 'rgba16float',
+    mipCount: 1,
+    bytes: extent.width * extent.height * 8,
+    deviceGeneration,
+  };
+}
+
+describe('transmission backdrop lifecycle', () => {
+  it('retires a stale-size candidate instead of publishing it as compatible LKG', () => {
+    const admission = new TransmissionCandidateAdmission();
+    const demand = { activeCount: 1, needsRoughMips: false } as const;
+    admission.admit(demand, capability, resource({ width: 4, height: 4 }, 1));
+    const rejected = admission.admit(
+      demand,
+      { ...capability, copySrc: false },
+      resource({ width: 8, height: 4 }, 1),
+    );
+
+    expect(rejected).toMatchObject({ ok: false, published: false, generation: 1 });
+    expect(admission.inspectLifecycle()).not.toHaveProperty('resource');
+    expect(
+      inspectTransmissionFromAdmission({
+        admission: admission.inspectLifecycle(),
+        topology: resolveTransmissionBackdropTopology({ demand, sourceSampleCount: 1 }),
+        extent: { width: 8, height: 4 },
+        transmissionDrawCount: 1,
+      }),
+    ).toMatchObject({ lifecycle: 'failed', recovery: 'rebuild-required', bytes: 0 });
+  });
+
+  it('keeps demand through device loss and publishes a replacement generation', () => {
+    const admission = new TransmissionCandidateAdmission();
+    const demand = { activeCount: 1, needsRoughMips: true } as const;
+    admission.admit(demand, capability, resource({ width: 4, height: 4 }, 1));
+    admission.markDeviceLost();
+    expect(admission.inspectLifecycle()).toMatchObject({
+      demand,
+      lifecycle: 'device-lost',
+      lastKnownGood: false,
+      recovery: 'rebuild-required',
+    });
+
+    const replacement = admission.admit(demand, capability, resource({ width: 8, height: 4 }, 2));
+    expect(replacement).toMatchObject({ ok: true, published: true, generation: 2 });
+    expect(admission.inspectLifecycle()).toMatchObject({
+      lifecycle: 'resident',
+      lastKnownGood: true,
+      recovery: 'recovered',
+      resource: { deviceGeneration: 2, extent: { width: 8, height: 4 } },
+    });
+  });
+
+  it('returns exact zero physical work after the last active material is removed', () => {
+    const admission = new TransmissionCandidateAdmission();
+    admission.admit(
+      { activeCount: 1, needsRoughMips: false },
+      capability,
+      resource({ width: 4, height: 4 }, 1),
+    );
+    const zero = admission.admit({ activeCount: 0, needsRoughMips: false }, capability);
+    expect(zero).toMatchObject({ ok: true, published: true, generation: 2 });
+    expect(admission.inspectLifecycle()).toMatchObject({
+      demand: { activeCount: 0, needsRoughMips: false },
+      lifecycle: 'inactive',
+      lastKnownGood: false,
+      recovery: 'recovered',
+    });
+  });
+});

package/src/transmission/__tests__/oracle.unit.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beerLambertAttenuation,
+  fresnelF0,
+  fresnelReflectance,
+  isFiniteColor,
+  isWithinGuardBand,
+  resolveRefractionBackdrop,
+  roughnessToLod,
+  splitTransmissionEnergy,
+} from '../oracle.js';
+
+const finite = (value: number): boolean => Number.isFinite(value);
+
+describe('transmission CPU oracle', () => {
+  it('uses the dielectric F0 formula and increases with IOR', () => {
+    expect(fresnelF0(1.5)).toBeCloseTo(0.04, 8);
+    expect(fresnelF0(1.33)).toBeLessThan(fresnelF0(1.5));
+    expect(fresnelF0(2)).toBeGreaterThan(fresnelF0(1.5));
+  });
+
+  it('keeps total internal reflection as reflection', () => {
+    expect(fresnelReflectance(0.5, 1.5)).toBe(1);
+    expect(fresnelReflectance(1, 1 / 1.5)).toBeCloseTo(0.04, 8);
+  });
+
+  it('partitions transmission only from non-metal energy', () => {
+    const dielectric = splitTransmissionEnergy({
+      transmission: 1,
+      metallic: 0,
+      cosTheta: 1,
+      ior: 1.5,
+    });
+    const metal = splitTransmissionEnergy({
+      transmission: 1,
+      metallic: 1,
+      cosTheta: 1,
+      ior: 1.5,
+    });
+
+    expect(dielectric.transmission).toBeGreaterThan(0);
+    expect(metal.transmission).toBe(0);
+    expect(
+      dielectric.reflection +
+        dielectric.transmission +
+        dielectric.diffuse +
+        dielectric.metallicResidual,
+    ).toBeCloseTo(1, 8);
+    expect(
+      metal.reflection + metal.transmission + metal.diffuse + metal.metallicResidual,
+    ).toBeCloseTo(1, 8);
+  });
+
+  it('applies Beer attenuation per component and preserves neutral boundaries', () => {
+    expect(beerLambertAttenuation([0.25, 0.5, 1], 2, 4)).toEqual([0.5, Math.SQRT2 / 2, 1]);
+    expect(beerLambertAttenuation([0.25, 0.5, 1], 0, 4)).toEqual([1, 1, 1]);
+    expect(beerLambertAttenuation([0.25, 0.5, 1], 2)).toEqual([1, 1, 1]);
+    expect(beerLambertAttenuation([0, 0.5, 1], 1, 2)[0]).toBe(0);
+  });
+
+  it('keeps zero-color absorption finite', () => {
+    const attenuation = beerLambertAttenuation([0, 0, 0], 3, 2);
+    expect(attenuation).toEqual([0, 0, 0]);
+    expect(attenuation.every(finite)).toBe(true);
+  });
+
+  it('maps roughness squared to a bounded monotonic LOD', () => {
+    expect(roughnessToLod(0, 8)).toBe(0);
+    expect(roughnessToLod(0.5, 8)).toBe(2);
+    expect(roughnessToLod(1, 8)).toBe(8);
+    expect(roughnessToLod(0.75, 8)).toBeGreaterThan(roughnessToLod(0.5, 8));
+    expect(roughnessToLod(2, 8)).toBe(8);
+  });
+
+  it('rejects the protected edge guard band', () => {
+    expect(isWithinGuardBand([0.02, 0.5])).toBe(true);
+    expect(isWithinGuardBand([0.01, 0.5])).toBe(false);
+    expect(isWithinGuardBand([0.5, 0.98])).toBe(true);
+    expect(isWithinGuardBand([0.5, 0.99])).toBe(false);
+  });
+
+  it('falls back from an invalid refraction sample to environment then baseline', () => {
+    expect(
+      resolveRefractionBackdrop({
+        uv: [0.01, 0.5],
+        refracted: [0.1, 0.2, 0.3],
+        environment: [0.4, 0.5, 0.6],
+        unrefracted: [0.7, 0.8, 0.9],
+      }),
+    ).toEqual({ source: 'environment', color: [0.4, 0.5, 0.6] });
+    expect(
+      resolveRefractionBackdrop({
+        uv: [0.01, 0.5],
+        unrefracted: [0.7, 0.8, 0.9],
+      }),
+    ).toEqual({ source: 'unrefracted', color: [0.7, 0.8, 0.9] });
+    expect(
+      resolveRefractionBackdrop({
+        uv: [0.5, 0.5],
+        refracted: [0.1, 0.2, 0.3],
+        environment: [0.4, 0.5, 0.6],
+        unrefracted: [0.7, 0.8, 0.9],
+      }),
+    ).toEqual({ source: 'refracted', color: [0.1, 0.2, 0.3] });
+  });
+
+  it('guards non-finite inputs without producing non-finite output', () => {
+    const energy = splitTransmissionEnergy({
+      transmission: Number.NaN,
+      metallic: Number.POSITIVE_INFINITY,
+      cosTheta: Number.NaN,
+      ior: Number.NaN,
+    });
+    const values = [
+      fresnelF0(Number.NaN),
+      fresnelReflectance(Number.NaN, Number.NaN),
+      energy.reflection,
+      energy.transmission,
+      energy.diffuse,
+      energy.metallicResidual,
+      beerLambertAttenuation([Number.NaN, 0, 1], Number.NaN, 1)[0],
+      roughnessToLod(Number.NaN, 8),
+    ];
+    expect(values.every(finite)).toBe(true);
+    expect(
+      isFiniteColor(
+        resolveRefractionBackdrop({ uv: [Number.NaN, 0], unrefracted: [1, 1, 1] }).color,
+      ),
+    ).toBe(true);
+  });
+});

package/src/transmission/__tests__/projection.unit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PersistentTransmissionDemandProjection,
+  type TransmissionDemandCandidate,
+} from '../projection';
+
+function candidate(
+  transmission: number,
+  roughness: number,
+  overrides: Partial<TransmissionDemandCandidate> = {},
+): TransmissionDemandCandidate {
+  return {
+    attached: true,
+    ready: true,
+    transmission,
+    roughness,
+    ...overrides,
+  };
+}
+
+describe('persistent transmission demand projection', () => {
+  it('publishes only activeCount and needsRoughMips', () => {
+    const projection = new PersistentTransmissionDemandProjection();
+
+    expect(projection.inspect()).toEqual({ activeCount: 0, needsRoughMips: false });
+  });
+
+  it('counts only attached, ready materials with positive transmission', () => {
+    const projection = new PersistentTransmissionDemandProjection();
+
+    projection.apply([
+      { kind: 'upsert', key: 'smooth', candidate: candidate(0.5, 0) },
+      { kind: 'upsert', key: 'zero', candidate: candidate(0, 0.8) },
+      { kind: 'upsert', key: 'detached', candidate: candidate(0.8, 0.8, { attached: false }) },
+      { kind: 'upsert', key: 'unready', candidate: candidate(0.8, 0.8, { ready: false }) },
+    ]);
+
+    expect(projection.inspect()).toEqual({ activeCount: 1, needsRoughMips: false });
+  });
+
+  it('conservatively requests one shared rough mip chain for active rough transmission', () => {
+    const projection = new PersistentTransmissionDemandProjection();
+
+    projection.apply([{ kind: 'upsert', key: 'rough', candidate: candidate(0.8, 0.35) }]);
+
+    expect(projection.inspect()).toEqual({ activeCount: 1, needsRoughMips: true });
+  });
+
+  it('returns exact zero after the final active material is detached or removed', () => {
+    const projection = new PersistentTransmissionDemandProjection();
+    projection.apply([{ kind: 'upsert', key: 'only', candidate: candidate(1, 0.5) }]);
+
+    projection.apply([
+      { kind: 'upsert', key: 'only', candidate: candidate(1, 0.5, { attached: false }) },
+    ]);
+    expect(projection.inspect()).toEqual({ activeCount: 0, needsRoughMips: false });
+
+    projection.apply([{ kind: 'remove', key: 'only' }]);
+    expect(projection.inspect()).toEqual({ activeCount: 0, needsRoughMips: false });
+  });
+
+  it('does not scan or rebuild when no material delta is published', () => {
+    const projection = new PersistentTransmissionDemandProjection();
+    projection.apply([{ kind: 'upsert', key: 'stable', candidate: candidate(0.6, 0.2) }]);
+    const before = projection.inspect();
+
+    projection.apply([]);
+
+    expect(projection.inspect()).toEqual(before);
+  });
+});