@forgeax/engine-render 0.1.2

package/src/__tests__/fog-temporal.integration.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
+import { RenderSceneProjection } from '../render-scene-projection';
+import type { TaaHistoryStore } from '../taa-history-store';
+import { summarizeTemporalCoverage } from '../temporal-coverage';
+import type { TemporalFrameBeginInput } from '../temporal-frame-transaction';
+import { TemporalFrameTransaction } from '../temporal-frame-transaction';
+
+function camera() {
+  return { ...makeZeroCameraFallbackSnapshot(), entityKey: 1, antialias: 'taa' as const };
+}
+
+const exactCoverage = summarizeTemporalCoverage([
+  {
+    identity: 'scene:opaque',
+    lane: 'rigid',
+    coverage: 'exact',
+    previous: 'last-submitted',
+  },
+]);
+
+function transaction(): TemporalFrameTransaction {
+  const history = {
+    beginFrame: () => ({
+      direction: 'a-to-b' as const,
+      valid: true,
+      resetReason: undefined,
+      commit: () => undefined,
+      abort: () => undefined,
+    }),
+    inspect: () => ({
+      enabled: true,
+      ownerGeneration: 1,
+      viewId: undefined,
+      width: 1,
+      height: 1,
+      format: 'rgba16float' as const,
+      direction: 'a-to-b' as const,
+      valid: true,
+      resetReason: undefined,
+      historyBytes: 0,
+      retiringGenerations: 0,
+    }),
+    resetForRecover: () => undefined,
+    dispose: () => undefined,
+  } as unknown as TaaHistoryStore;
+  return new TemporalFrameTransaction(history);
+}
+
+function commitRevision(
+  owner: TemporalFrameTransaction,
+  projection: RenderSceneProjection,
+  revision: number | undefined,
+): void {
+  const input = {
+    camera: camera(),
+    surfaceWidth: 1280,
+    surfaceHeight: 720,
+    projection,
+    visible: [],
+    coverage: exactCoverage,
+    reactiveRevision: revision,
+  } as unknown as TemporalFrameBeginInput;
+  owner.begin(input).commit();
+}
+
+function abortRevision(
+  owner: TemporalFrameTransaction,
+  projection: RenderSceneProjection,
+  revision: number | undefined,
+): void {
+  const input = {
+    camera: camera(),
+    surfaceWidth: 1280,
+    surfaceHeight: 720,
+    projection,
+    visible: [],
+    coverage: exactCoverage,
+    reactiveRevision: revision,
+  } as unknown as TemporalFrameBeginInput;
+  owner.begin(input).abort('queue-submit');
+}
+
+describe('Fog revision temporal lane', () => {
+  it('marks every accepted revision change current-only and lets a stable frame accumulate', () => {
+    const owner = transaction();
+    const projection = new RenderSceneProjection();
+
+    commitRevision(owner, projection, 1);
+    expect(owner.inspect().coverage).toMatchObject({ exact: 1, reactive: 1, missing: 0 });
+
+    commitRevision(owner, projection, 1);
+    expect(owner.inspect().coverage).toMatchObject({ exact: 1, reactive: 0, missing: 0 });
+
+    commitRevision(owner, projection, 2);
+    expect(owner.inspect().coverage).toMatchObject({ exact: 1, reactive: 1, missing: 0 });
+    commitRevision(owner, projection, 3);
+    expect(owner.inspect().coverage).toMatchObject({ exact: 1, reactive: 1, missing: 0 });
+
+    commitRevision(owner, projection, 3);
+    expect(owner.inspect().coverage).toMatchObject({ exact: 1, reactive: 0, missing: 0 });
+  });
+
+  it('keeps a failed candidate out of the comparison baseline', () => {
+    const owner = transaction();
+    const projection = new RenderSceneProjection();
+
+    commitRevision(owner, projection, 7);
+    abortRevision(owner, projection, 8);
+    expect(owner.inspect().coverage).toMatchObject({ exact: 1, reactive: 1, missing: 0 });
+
+    commitRevision(owner, projection, 7);
+    expect(owner.inspect().coverage).toMatchObject({ exact: 1, reactive: 0, missing: 0 });
+  });
+});

package/src/__tests__/frame-chain.unit.test.ts

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+import { buildFrameChain, prepareFrame, recordFrame } from '../frame-chain';
+
+describe('render frame chain', () => {
+  it('accepts an empty world and produces a recordable frame', () => {
+    const frame = buildFrameChain([]);
+    const prepared = prepareFrame(frame, { resources: new Map() });
+    expect(recordFrame(prepared).ok).toBe(true);
+  });
+
+  it('keeps one light snapshot identity across extract and record stages', () => {
+    const snapshot = { kind: 'spot', direction: [0, 1, 0] };
+    const extracted = buildFrameChain([snapshot]);
+    const prepared = prepareFrame(extracted, { resources: new Map() });
+
+    expect(prepared.extracted.worlds[0]).toBe(snapshot);
+    expect(recordFrame(prepared).ok).toBe(true);
+  });
+
+  it('keeps the light extract query owner singular', async () => {
+    const source = await readFile(new URL('../render-system-extract.ts', import.meta.url), 'utf8');
+    expect(source.match(/const spotLightQuery =/g)).toHaveLength(1);
+    expect(source.match(/const pointLightQuery =/g)).toHaveLength(1);
+  });
+});

package/src/__tests__/frame-observation.contract.test.ts

@@ -0,0 +1,103 @@
+import type { Texture } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  type FrameObservationReadback,
+  type FrameObservationSource,
+  observeCurrentFrame,
+} from '../record/frame-observation.js';
+
+const texture = {} as Texture;
+const usage = 0x10 | 0x04 | 0x01;
+
+function source(overrides: Partial<FrameObservationSource> = {}): FrameObservationSource {
+  return {
+    texture,
+    descriptor: {
+      texture,
+      format: 'rgba16float',
+      size: { width: 4, height: 2 },
+      usage,
+      sample: 1,
+    },
+    frameId: 12,
+    pipelineId: 'forgeax::urp',
+    backendId: 'webgpu',
+    ...overrides,
+  };
+}
+
+describe('render current-frame observation producer contract', () => {
+  it('observes only the producer-owned linear HDR target', async () => {
+    const readback: FrameObservationReadback = vi.fn(async (lease) => {
+      expect(lease.descriptor.format).toBe('rgba16float');
+      return ok(new Uint8Array(4 * 2 * 8));
+    });
+
+    const result = await observeCurrentFrame({ semantic: 'linear-hdr', readback }, source(), 12);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.bytes.byteLength).toBe(64);
+    expect(result.value.metadata).toMatchObject({
+      format: 'rgba16float',
+      size: { width: 4, height: 2 },
+      frameId: 12,
+      pipelineId: 'forgeax::urp',
+      backendId: 'webgpu',
+    });
+    expect(readback).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails closed for stale, missing, malformed, or final-canvas sources', async () => {
+    const readback: FrameObservationReadback = vi.fn(async () => ok(new Uint8Array(64)));
+    const cases: Array<[FrameObservationSource | undefined, string]> = [
+      [undefined, 'observation-unavailable'],
+      [source({ frameId: 11 }), 'observation-unavailable'],
+      [
+        source({ descriptor: { ...source().descriptor, format: 'bgra8unorm' } }),
+        'observation-unavailable',
+      ],
+      [
+        source({ descriptor: { ...source().descriptor, usage: 0x10 | 0x04 } }),
+        'observation-unavailable',
+      ],
+    ];
+
+    for (const [candidate, code] of cases) {
+      const result = await observeCurrentFrame({ semantic: 'linear-hdr', readback }, candidate, 12);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe(code);
+    }
+    expect(readback).not.toHaveBeenCalled();
+  });
+
+  it('preserves URP and HDRP producer identity without backend policy', async () => {
+    const readback: FrameObservationReadback = vi.fn(async () => ok(new Uint8Array(64)));
+    const urp = await observeCurrentFrame(
+      { semantic: 'linear-hdr', readback },
+      source({ pipelineId: 'forgeax::urp' }),
+      12,
+    );
+    const hdrp = await observeCurrentFrame(
+      { semantic: 'linear-hdr', readback },
+      source({ pipelineId: 'forgeax::hdrp' }),
+      12,
+    );
+
+    expect(urp.ok && hdrp.ok).toBe(true);
+    if (urp.ok && hdrp.ok) {
+      expect(urp.value.metadata.pipelineId).toBe('forgeax::urp');
+      expect(hdrp.value.metadata.pipelineId).toBe('forgeax::hdrp');
+      expect(urp.value.metadata.backendId).toBe(hdrp.value.metadata.backendId);
+    }
+  });
+
+  it('does not treat a final-canvas readback as a linear attachment', async () => {
+    const readback: FrameObservationReadback = vi.fn(async () => ok(new Uint8Array(4)));
+    const result = await observeCurrentFrame({ semantic: 'linear-hdr', readback }, undefined, 12);
+
+    expect(result.ok).toBe(false);
+    expect(readback).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/glyph-text-layout-recovery.unit.test.ts

@@ -0,0 +1,172 @@
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { Transform } from '@forgeax/engine-scene';
+import type { FontAsset, GlyphMetric, Handle, MeshAsset } from '@forgeax/engine-types';
+import { TextError } from '@forgeax/engine-types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { resolveRenderAsset } from '../assets/resolve-render-asset';
+import { MeshFilter, MeshRenderer } from '../components';
+import { GlyphText } from '../components/glyph-text';
+import { glyphTextLayoutSystem, resetGlyphBakeCache } from '../glyph-text-layout-system';
+import { GpuResourceStore } from '../gpu-resource-store';
+
+function metric(): GlyphMetric {
+  return {
+    advance: 10,
+    bearingX: 0,
+    bearingY: 8,
+    size: { w: 8, h: 8 },
+    region: { x: 0, y: 0, w: 8, h: 8 },
+  };
+}
+
+function makeFont(): FontAsset {
+  const glyphs = Object.fromEntries([65, 66, 67, 72, 105].map((code) => [String(code), metric()]));
+  return {
+    kind: 'font',
+    atlas: AssetGuid.random(),
+    sampler: AssetGuid.random(),
+    glyphs,
+    common: {
+      lineHeight: 12,
+      base: 8,
+      distanceRange: 4,
+      pxRange: 4,
+      atlasWidth: 64,
+      atlasHeight: 64,
+    },
+  };
+}
+
+function registerFont(world: World): number {
+  return world.allocSharedRef('FontAsset', makeFont()) as unknown as number;
+}
+
+function spawnLabel(world: World, fontHandle: number): EntityHandle {
+  return world
+    .spawn({
+      component: GlyphText,
+      data: {
+        fontHandle: fontHandle as unknown as Handle<'FontAsset', 'shared'>,
+        text: 'A',
+        fontSize: 1,
+        color: [1, 1, 1, 1],
+      },
+    })
+    .unwrap();
+}
+
+describe('glyph-text-layout-system font-cap recovery', () => {
+  const gpuStore = new GpuResourceStore();
+
+  beforeEach(() => resetGlyphBakeCache());
+
+  it('clears the rejected ninth label and rebuilds it on the next frame', () => {
+    const world = new World();
+    const fonts = Array.from({ length: 9 }, () => registerFont(world));
+    const prefix = fonts.slice(0, 8).map((fontHandle) => spawnLabel(world, fontHandle));
+    const rejected = spawnLabel(world, fonts[0] as number);
+    const unrelated = world.spawn({ component: Transform, data: { pos: [2, 3, 0] } }).unwrap();
+
+    expect(glyphTextLayoutSystem(world, gpuStore).ok).toBe(true);
+    const oldMeshHandle = (world.get(rejected, MeshFilter).unwrap() as { assetHandle: number })
+      .assetHandle;
+    const oldMaterialHandle = Number(
+      (world.get(rejected, MeshRenderer).unwrap() as unknown as { materials: readonly number[] })
+        .materials[0] ?? 0,
+    );
+    const baselineLiveRefs = world.sharedRefs._liveCount();
+
+    world
+      .set(rejected, GlyphText, {
+        fontHandle: fonts[8] as unknown as Handle<'FontAsset', 'shared'>,
+      })
+      .unwrap();
+    const overflow = glyphTextLayoutSystem(world, gpuStore);
+
+    expect(overflow.ok).toBe(false);
+    if (!overflow.ok) {
+      expect(overflow.error).toBeInstanceOf(TextError);
+      expect(overflow.error.code).toBe('font-concurrency-exceeded');
+      expect(overflow.error.expected).toBe('8');
+      expect(overflow.error.detail).toEqual({
+        active: 8,
+        limit: 8,
+        rejected: fonts[8],
+      });
+    }
+    expect(world.get(rejected, MeshFilter).ok).toBe(false);
+    expect(world.get(rejected, MeshRenderer).ok).toBe(false);
+    expect(world.sharedRefs._liveCount()).toBe(baselineLiveRefs - 2);
+    for (const entity of prefix) {
+      expect(world.get(entity, MeshFilter).ok).toBe(true);
+      expect(world.get(entity, MeshRenderer).ok).toBe(true);
+    }
+    expect(world.get(unrelated, Transform).ok).toBe(true);
+
+    world
+      .set(rejected, GlyphText, {
+        fontHandle: fonts[1] as unknown as Handle<'FontAsset', 'shared'>,
+      })
+      .unwrap();
+    expect(glyphTextLayoutSystem(world, gpuStore).ok).toBe(true);
+
+    const rebuiltMeshHandle = (world.get(rejected, MeshFilter).unwrap() as { assetHandle: number })
+      .assetHandle;
+    const rebuiltMaterialHandle = Number(
+      (world.get(rejected, MeshRenderer).unwrap() as unknown as { materials: readonly number[] })
+        .materials[0] ?? 0,
+    );
+    expect(rebuiltMeshHandle).not.toBe(oldMeshHandle);
+    expect(rebuiltMaterialHandle).not.toBe(oldMaterialHandle);
+    const rebuiltMesh = resolveRenderAsset<MeshAsset>(
+      world,
+      rebuiltMeshHandle as unknown as Handle<'MeshAsset', 'shared'>,
+    );
+    expect(rebuiltMesh.ok).toBe(true);
+    if (rebuiltMesh.ok) {
+      expect(rebuiltMesh.value.indices?.length).toBe(6);
+      expect(rebuiltMesh.value.vertices.length).toBeGreaterThan(0);
+    }
+    expect(world.sharedRefs._liveCount()).toBe(baselineLiveRefs);
+    expect(glyphTextLayoutSystem(world, gpuStore).ok).toBe(true);
+    expect(world.sharedRefs._liveCount()).toBe(baselineLiveRefs);
+
+    world.despawn(rejected).unwrap();
+    expect(glyphTextLayoutSystem(world, gpuStore).ok).toBe(true);
+    const afterCleanup = world.sharedRefs._liveCount();
+    expect(glyphTextLayoutSystem(world, gpuStore).ok).toBe(true);
+    expect(world.sharedRefs._liveCount()).toBe(afterCleanup);
+  });
+
+  it('replaces a resident GPU mesh when text changes its vertex shape', () => {
+    const updateMesh = vi.fn(() => ({
+      ok: false as const,
+      error: { code: 'mesh-shape-mismatch' } as never,
+    }));
+    const replaceMesh = vi.fn(() => ({ ok: true as const, value: undefined }));
+    const residentStore = { updateMesh, replaceMesh } as unknown as GpuResourceStore;
+    const world = new World();
+    const font = registerFont(world);
+    const label = spawnLabel(world, font);
+
+    expect(glyphTextLayoutSystem(world, residentStore).ok).toBe(true);
+    const meshHandle = (world.get(label, MeshFilter).unwrap() as { assetHandle: number })
+      .assetHandle;
+    const before = world.sharedRefs.resolve<'MeshAsset', MeshAsset>(meshHandle as never);
+    expect(before.ok).toBe(true);
+    if (!before.ok) return;
+    const oldVertexLength = before.value.vertices.length;
+
+    world.set(label, GlyphText, { text: 'ABC' }).unwrap();
+    expect(glyphTextLayoutSystem(world, residentStore).ok).toBe(true);
+
+    expect(updateMesh).toHaveBeenCalledOnce();
+    expect(replaceMesh).toHaveBeenCalledOnce();
+    const after = world.sharedRefs.resolve<'MeshAsset', MeshAsset>(meshHandle as never);
+    expect(after.ok).toBe(true);
+    if (!after.ok) return;
+    expect(after.value.vertices.length).not.toBe(oldVertexLength);
+    expect(after.value.indices?.length ?? 0).toBeGreaterThan(0);
+  });
+});