@forgeax/engine-render 0.1.6 → 0.1.19

package/src/points-lines/__tests__/cache-recovery.unit.test.ts

@@ -0,0 +1,157 @@
+import { err, type MeshAsset, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { type PointsLinesExpandedGeometry, PointsLinesExpansionCache } from '../expansion-cache';
+import { type PointsLinesGpuResourceAdapter, PointsLinesPreparation } from '../prepare';
+import { createPointsLinesLaneContract, createPointsLinesRecordPlan } from '../record';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function mesh(generation = 1): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0]),
+    indices: new Uint16Array([0, 1, 2, 3]),
+    attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0]) },
+    aabb: new Float32Array([0, 0, 0, 1, 1, 0]),
+    submeshes: [
+      { indexOffset: 0, indexCount: 4, vertexCount: 4, topology: 'line-list', materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: `lines-${generation}` }],
+  };
+}
+
+function snapshot(meshGeneration = 1, materialGeneration = 1) {
+  return createPointsLinesSnapshot({
+    worldId: 0,
+    entityKey: 4,
+    component: 'Lines',
+    meshHandle: 9,
+    meshGeneration,
+    materialHandle: 12,
+    materialGeneration,
+    style: { kind: 'lines', widthPx: 3 },
+    layer: 0,
+    visible: true,
+    sourceBounds: new Float32Array([0, 0, 0, 1, 1, 0]),
+    viewport: { width: 320, height: 200, dpr: 1 },
+    projection: new Float32Array(16),
+  });
+}
+
+describe('Points/Lines expansion cache and LKG recovery', () => {
+  it('reuses geometry when style changes and keeps style out of the cache key', () => {
+    const cache = new PointsLinesExpansionCache();
+    const first = cache.getOrCreate(snapshot(), mesh());
+    const styled = cache.getOrCreate(
+      createPointsLinesSnapshot({
+        ...snapshot(),
+        style: { kind: 'lines', widthPx: 9 },
+      }),
+      mesh(),
+    );
+    const material = cache.getOrCreate(snapshot(1, 2), mesh());
+
+    expect(first).toBe(styled);
+    expect(first).toBe(material);
+    expect(first.key).toContain('mesh:9:1');
+    expect(styled.key).not.toContain('width=9');
+    expect(styled.vertices).toEqual(first.vertices);
+    expect(styled.positions).toEqual(first.positions);
+    expect(first).toEqual<PointsLinesExpandedGeometry>(
+      expect.objectContaining({ sourceVertexCount: 4, segmentCount: 2 }),
+    );
+  });
+
+  it('destroys only a failed candidate and retains the previous live resource', () => {
+    const calls: string[] = [];
+    let failValidation = false;
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: () => {
+        calls.push('create');
+        return ok(`resource-${calls.filter((call) => call === 'create').length}`);
+      },
+      upload: (resource) => {
+        calls.push(`upload:${resource}`);
+        return ok(64);
+      },
+      validate: (resource) => {
+        calls.push(`validate:${resource}`);
+        return failValidation ? err(new Error('candidate validation fault')) : ok(undefined);
+      },
+      destroy: (resource) => calls.push(`destroy:${resource}`),
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+
+    const first = preparation.prepare(snapshot(), mesh());
+    expect(first.ok).toBe(true);
+    failValidation = true;
+    const failed = preparation.prepare(snapshot(2), mesh(2));
+
+    expect(failed.ok).toBe(false);
+    expect(calls).toContain('destroy:resource-2');
+    expect(preparation.inspect()).toMatchObject({
+      status: 'resident',
+      lastKnownGood: true,
+      liveResource: 'resource-1',
+      candidateBytes: 0,
+    });
+    expect(preparation.inspect().liveBytes).toBe(
+      preparation.lastKnownGood()?.geometry.derivedBytes,
+    );
+    expect(preparation.lastKnownGood()?.resource).toBe('resource-1');
+  });
+
+  it('reuses geometry for a changed style and records its new physical-pixel draw plan', () => {
+    let uploads = 0;
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: (geometry) => ok(geometry.key),
+      upload: (_resource, geometry) => {
+        uploads += 1;
+        return ok(geometry.derivedBytes);
+      },
+      validate: () => ok(undefined),
+      destroy: () => undefined,
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+    const first = preparation.prepare(snapshot(), mesh()).unwrap();
+    const changedSnapshot = createPointsLinesSnapshot({
+      ...snapshot(),
+      style: { kind: 'lines', widthPx: 9 },
+    });
+    const changed = preparation.prepare(changedSnapshot, mesh()).unwrap();
+    const plan = createPointsLinesRecordPlan(
+      changedSnapshot,
+      changed.geometry,
+      createPointsLinesLaneContract('direct', 'webgpu'),
+    );
+
+    expect(uploads).toBe(1);
+    expect(changed.geometry).toBe(first.geometry);
+    expect(plan.conservativeMarginPx).toBe(4.5);
+    expect(changed.geometry.vertices).toEqual(first.geometry.vertices);
+  });
+
+  it('rebuilds from the retained snapshot after device loss without stale bytes', () => {
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: () => ok('fresh'),
+      upload: () => ok(64),
+      validate: () => ok(undefined),
+      destroy: () => undefined,
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+
+    expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
+    preparation.resetForDeviceLoss();
+    expect(preparation.inspect()).toMatchObject({ status: 'rebuild-pending', liveBytes: 0 });
+    expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
+    expect(preparation.inspect()).toMatchObject({ status: 'resident', lastKnownGood: true });
+  });
+});

package/src/points-lines/__tests__/inspection-lanes.integration.test.ts

@@ -0,0 +1,146 @@
+import { type MeshAsset, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { PointsLinesMaterialUnsupportedError } from '../../errors/render';
+import { PointsLinesExpansionCache } from '../expansion-cache';
+import { inspectPointsLines, pointsLinesInspectionToJson } from '../inspection';
+import { type PointsLinesGpuResourceAdapter, PointsLinesPreparation } from '../prepare';
+import { createPointsLinesLaneContract, createPointsLinesRecordPlan } from '../record';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function mesh(): MeshAsset {
+  const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0]);
+  return {
+    kind: 'mesh',
+    vertices: positions,
+    indices: new Uint16Array([0, 1, 2, 3]),
+    attributes: { position: positions },
+    aabb: new Float32Array([0, 0, 0, 1, 1, 0]),
+    submeshes: [
+      { indexOffset: 0, indexCount: 4, vertexCount: 4, topology: 'line-list', materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: 'points-lines' }],
+  };
+}
+
+function snapshot(viewport = { width: 320, height: 200, dpr: 1 }) {
+  return createPointsLinesSnapshot({
+    worldId: 2,
+    entityKey: 7,
+    component: 'Lines',
+    meshHandle: 9,
+    meshGeneration: 3,
+    materialHandle: 12,
+    materialGeneration: 4,
+    style: { kind: 'lines', widthPx: 4 },
+    layer: 0,
+    visible: true,
+    sourceBounds: new Float32Array([0, 0, 0, 1, 1, 0]),
+    viewport,
+    projection: new Float32Array(16),
+  });
+}
+
+describe('Points/Lines inspection and recovery integration', () => {
+  it('publishes typed and JSON inspection for each shared lane', () => {
+    const geometry = new PointsLinesExpansionCache().getOrCreate(snapshot(), mesh());
+    for (const lane of ['direct', 'clustered', 'cpu-webgl2'] as const) {
+      const plan = createPointsLinesRecordPlan(
+        snapshot(),
+        geometry,
+        createPointsLinesLaneContract(lane, 'webgpu'),
+      );
+      const inspection = inspectPointsLines({
+        snapshot: snapshot(),
+        topology: 'line-list',
+        lane,
+        pointCount: geometry.pointCount,
+        segmentCount: geometry.segmentCount,
+        sourceBytes: geometry.sourceBytes,
+        derivedBytes: geometry.derivedBytes,
+        cache: { hit: false, rebuilds: 1, evictions: 0 },
+        drawCount: plan.drawCount,
+        uploadBytes: geometry.derivedBytes,
+        lastKnownGood: true,
+      });
+      const json = JSON.parse(pointsLinesInspectionToJson(inspection)) as typeof inspection;
+      expect(json).toMatchObject({
+        entityKey: 7,
+        worldId: 2,
+        topology: 'line-list',
+        lane,
+        segmentCount: 2,
+        drawCount: 1,
+        lastKnownGood: true,
+      });
+      expect(json.derivedBytes).toBeGreaterThan(json.sourceBytes);
+    }
+  });
+
+  it('keeps the same retained expansion through resize and recovers one LKG', () => {
+    const resources: string[] = [];
+    const adapter: PointsLinesGpuResourceAdapter<string> = {
+      create: () => {
+        const resource = `resource-${resources.length + 1}`;
+        resources.push(resource);
+        return ok(resource);
+      },
+      upload: () => ok(648),
+      validate: () => ok(undefined),
+      destroy: (resource) => resources.splice(resources.indexOf(resource), 1),
+    };
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter,
+    });
+    const first = preparation.prepare(snapshot(), mesh()).unwrap();
+    const resized = preparation
+      .prepare(snapshot({ width: 640, height: 360, dpr: 2 }), mesh())
+      .unwrap();
+
+    expect(resized.geometry).toBe(first.geometry);
+    expect(preparation.inspect()).toMatchObject({
+      status: 'resident',
+      lastKnownGood: true,
+      rebuilds: 1,
+    });
+    preparation.resetForDeviceLoss();
+    expect(preparation.inspect()).toMatchObject({ status: 'rebuild-pending', liveBytes: 0 });
+    preparation.prepare(snapshot({ width: 640, height: 360, dpr: 2 }), mesh()).unwrap();
+    expect(preparation.inspect()).toMatchObject({
+      status: 'resident',
+      lastKnownGood: true,
+      rebuilds: 2,
+    });
+    expect(resources).toEqual(['resource-1']);
+  });
+
+  it('keeps executable refusal hints on the same inspection surface', () => {
+    const inspection = inspectPointsLines({
+      snapshot: snapshot(),
+      topology: 'line-list',
+      lane: 'refused',
+      pointCount: 0,
+      segmentCount: 0,
+      sourceBytes: 0,
+      derivedBytes: 0,
+      cache: { hit: false, rebuilds: 0, evictions: 0 },
+      drawCount: 0,
+      uploadBytes: 0,
+      lastKnownGood: false,
+      refusal: {
+        ...new PointsLinesMaterialUnsupportedError({
+          entity: 7,
+          material: 'mat',
+          pass: 'forward',
+          module: 'test',
+          reason: 'unsupported test material',
+        }),
+        generation: 4,
+        lastKnownGood: false,
+      },
+    });
+    expect(JSON.parse(pointsLinesInspectionToJson(inspection)).refusal.hint).toContain(
+      'Materials.unlit',
+    );
+  });
+});

package/src/points-lines/__tests__/inspection.unit.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PointsLinesBudgetExceededError,
+  PointsLinesInvalidStyleError,
+  PointsLinesMaterialUnsupportedError,
+  PointsLinesPrepareFailedError,
+  PointsLinesStyleUnsupportedError,
+  PointsLinesTopologyMismatchError,
+} from '../../errors/render';
+import {
+  inspectPointsLines,
+  type PointsLinesInspection,
+  pointsLinesInspectionToJson,
+} from '../inspection';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function baseInput(): Parameters<typeof inspectPointsLines>[0] {
+  return {
+    snapshot: createPointsLinesSnapshot({
+      worldId: 2,
+      entityKey: 15,
+      component: 'Lines',
+      meshHandle: 5,
+      meshGeneration: 3,
+      materialHandle: 7,
+      materialGeneration: 4,
+      style: { kind: 'lines', widthPx: 2 },
+      layer: 1,
+      visible: true,
+      sourceBounds: new Float32Array([0, 0, 0, 1, 1, 0]),
+      viewport: { width: 640, height: 480, dpr: 2 },
+      projection: new Float32Array(16),
+    }),
+    topology: 'line-list',
+    lane: 'pending',
+    pointCount: 0,
+    segmentCount: 2,
+    sourceBytes: 64,
+    derivedBytes: 48,
+    cache: { hit: false, rebuilds: 1, evictions: 0 },
+    drawCount: 1,
+    uploadBytes: 48,
+    lastKnownGood: true,
+  };
+}
+
+describe('bounded Points/Lines inspection', () => {
+  it('projects normal typed facts and a JSON-safe equivalent', () => {
+    const inspection = inspectPointsLines(baseInput());
+
+    expect(inspection).toEqual<PointsLinesInspection>({
+      entityKey: 15,
+      worldId: 2,
+      component: 'Lines',
+      meshHandle: 5,
+      meshGeneration: 3,
+      materialHandle: 7,
+      materialGeneration: 4,
+      style: { kind: 'lines', widthPx: 2 },
+      topology: 'line-list',
+      lane: 'pending',
+      pointCount: 0,
+      segmentCount: 2,
+      sourceBytes: 64,
+      derivedBytes: 48,
+      cache: { hit: false, rebuilds: 1, evictions: 0 },
+      drawCount: 1,
+      uploadBytes: 48,
+      lastKnownGood: true,
+    });
+    expect(JSON.parse(pointsLinesInspectionToJson(inspection))).toEqual(inspection);
+  });
+
+  it('keeps refusal and recovery provenance bounded and typed', () => {
+    const refusal = inspectPointsLines({
+      ...baseInput(),
+      lane: 'refused',
+      lastKnownGood: false,
+      drawCount: 0,
+      uploadBytes: 0,
+      refusal: {
+        ...new PointsLinesPrepareFailedError({
+          owner: 'test',
+          generation: 3,
+          stage: 'prepare',
+          cause: 'test failure',
+          lastKnownGood: false,
+        }),
+        generation: 3,
+        lastKnownGood: false,
+      },
+    });
+    const recovery = inspectPointsLines({
+      ...baseInput(),
+      lane: 'pending',
+      cache: { hit: true, rebuilds: 2, evictions: 1 },
+      lastKnownGood: true,
+    });
+
+    expect(refusal.refusal?.code).toBe('points-lines-prepare-failed');
+    expect(refusal.drawCount).toBe(0);
+    expect(recovery.cache).toEqual({ hit: true, rebuilds: 2, evictions: 1 });
+    expect(pointsLinesInspectionToJson(refusal)).not.toContain('RHI');
+  });
+
+  it('preserves source detail for all six Points/Lines refusal paths', () => {
+    const errors = [
+      new PointsLinesInvalidStyleError({
+        entity: 15,
+        component: 'Lines',
+        field: 'widthPx',
+        value: 0,
+        expected: 'widthPx > 0',
+      }),
+      new PointsLinesTopologyMismatchError({
+        entity: 15,
+        submesh: 0,
+        expected: 'line-list',
+        actual: 'triangle-list',
+      }),
+      new PointsLinesStyleUnsupportedError({
+        lane: 'direct',
+        field: 'shape',
+        member: 'diamond',
+        supported: ['square', 'circle'],
+      }),
+      new PointsLinesMaterialUnsupportedError({
+        entity: 15,
+        material: 'mat',
+        pass: 'forward',
+        module: 'test',
+        reason: 'unsupported test material',
+      }),
+      new PointsLinesBudgetExceededError({
+        lane: 'direct',
+        requested: 9,
+        limit: 8,
+        unit: 'draws',
+      }),
+      new PointsLinesPrepareFailedError({
+        owner: 'test',
+        generation: 3,
+        stage: 'prepare',
+        cause: 'test failure',
+        lastKnownGood: false,
+      }),
+    ];
+
+    for (const error of errors) {
+      const inspection = inspectPointsLines({
+        ...baseInput(),
+        lane: 'refused',
+        drawCount: 0,
+        uploadBytes: 0,
+        lastKnownGood: false,
+        refusal: {
+          ...error,
+          generation: 3,
+          lastKnownGood: false,
+        },
+      });
+      expect(inspection.refusal).toMatchObject({
+        code: error.code,
+        expected: error.expected,
+        hint: error.hint,
+        detail: error.detail,
+      });
+      expect(JSON.parse(pointsLinesInspectionToJson(inspection)).refusal.detail).toEqual(
+        error.detail,
+      );
+    }
+  });
+});

package/src/points-lines/__tests__/lane-structural.integration.test.ts

@@ -0,0 +1,122 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { PointsLinesExpansionCache } from '../expansion-cache';
+import {
+  createPointsLinesLaneAdapter,
+  createPointsLinesLaneContract,
+  createPointsLinesRecordPlan,
+} from '../record';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function mesh(topology: 'point-list' | 'line-list', count: number): MeshAsset {
+  const vertices = new Float32Array(
+    Array.from({ length: count }, (_, index) => [index, index % 2, 0]).flat(),
+  );
+  return {
+    kind: 'mesh',
+    vertices,
+    indices: new Uint16Array(Array.from({ length: count }, (_, index) => index)),
+    attributes: { position: vertices },
+    aabb: new Float32Array([0, 0, 0, count, 1, 0]),
+    submeshes: [
+      { indexOffset: 0, indexCount: count, vertexCount: count, topology, materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: 'points-lines' }],
+  };
+}
+
+function snapshot(component: 'Points' | 'Lines' | undefined) {
+  return createPointsLinesSnapshot({
+    worldId: 1,
+    entityKey: 7,
+    component,
+    meshHandle: 11,
+    meshGeneration: 3,
+    materialHandle: 13,
+    materialGeneration: 2,
+    style:
+      component === 'Points'
+        ? { kind: 'points', sizePx: 16, shape: 'circle' }
+        : component === 'Lines'
+          ? { kind: 'lines', widthPx: 4 }
+          : undefined,
+    layer: 0,
+    visible: true,
+    sourceBounds: new Float32Array([0, 0, 0, 4, 1, 0]),
+    viewport: { width: 640, height: 480, dpr: 2 },
+    projection: new Float32Array(16),
+  });
+}
+
+describe('Points/Lines structural lane contract', () => {
+  it('marks RhiNull structural-only and preserves one shared lane contract', () => {
+    const adapter = createPointsLinesLaneAdapter('direct', 'null');
+    const geometry = new PointsLinesExpansionCache().getOrCreate(
+      snapshot('Points'),
+      mesh('point-list', 4),
+    );
+    const plan = adapter.createRecordPlan(snapshot('Points'), geometry);
+
+    expect(adapter.contract.evidence).toBe('structural-only');
+    expect(adapter.contract.authoring).toBe('shared');
+    expect(plan.drawCount).toBe(1);
+    expect(plan.shadowDrawCount).toBe(0);
+    expect(plan.graph).toEqual({ additionalAttachments: 0, additionalPasses: 0 });
+  });
+
+  it('keeps the component-off path exact-zero', () => {
+    const cache = new PointsLinesExpansionCache();
+    const offPath = snapshot(undefined);
+    const geometry = cache.getOrCreate(offPath, mesh('point-list', 4));
+    const plan = createPointsLinesRecordPlan(
+      offPath,
+      geometry,
+      createPointsLinesLaneContract('direct', 'webgpu'),
+    );
+
+    expect(offPath.dedicatedResourceBytes).toBe(0);
+    expect(geometry.sourceBytes).toBe(0);
+    expect(geometry.derivedBytes).toBe(0);
+    expect(plan.vertexCount).toBe(0);
+    expect(plan.indexCount).toBe(0);
+    expect(plan.drawCount).toBe(0);
+    expect(plan.graph).toEqual({ additionalAttachments: 0, additionalPasses: 0 });
+    expect(plan.shadowDrawCount).toBe(0);
+  });
+
+  it('reuses one expansion for 100 entities and stays within triangle bounds', () => {
+    const cache = new PointsLinesExpansionCache();
+    const authoring = snapshot('Points');
+    const source = mesh('point-list', 4);
+    const first = cache.getOrCreate(authoring, source);
+
+    for (let entity = 0; entity < 100; entity += 1) {
+      expect(cache.getOrCreate(authoring, source)).toBe(first);
+    }
+
+    const plan = createPointsLinesRecordPlan(
+      authoring,
+      first,
+      createPointsLinesLaneContract('clustered', 'webgpu'),
+    );
+    const primitiveCount = first.pointCount + first.segmentCount;
+    expect(cache.size).toBe(1);
+    expect(plan.vertexCount).toBeLessThanOrEqual(4 * primitiveCount);
+    expect(plan.indexCount).toBeLessThanOrEqual(6 * primitiveCount);
+    expect(plan.drawCount).toBe(1);
+  });
+
+  it('records WebGL2 capability provenance without compute storage or indirect', () => {
+    const contract = createPointsLinesLaneContract('cpu-webgl2', 'wgpu-webgl2');
+
+    expect(contract.capabilities).toEqual({ compute: false, storage: false, indirect: false });
+    expect(contract.material).toMatchObject({
+      source: 'MaterialAsset',
+      shadingModel: 'unlit',
+      clusteredLighting: false,
+      lit: false,
+    });
+    expect(contract.graph.additionalAttachments).toBe(0);
+    expect(contract.graph.additionalPasses).toBe(0);
+  });
+});