@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/factory-contract.integration.test.ts

@@ -0,0 +1,280 @@
+import { World } from '@forgeax/engine-ecs';
+import { createProfiler } from '@forgeax/engine-profiler';
+import { Camera, type RenderFeature } from '@forgeax/engine-render';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderer as constructRenderer } from '../assembly/factory';
+
+function manifestUrl(): string {
+  return `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+}
+
+describe('factory contract', () => {
+  it('releases its profiler catalog contribution on dispose', async () => {
+    const profiler = createProfiler();
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { profiler, rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+
+    expect(profiler.phaseCatalog.render.length).toBeGreaterThan(0);
+    renderer.dispose();
+    expect(profiler.phaseCatalog.render).toEqual([]);
+  });
+
+  it('completes the receipt-bound create, attach, draw, observe, recover chain', async () => {
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    const lease = attached.value;
+    expect(world.update().ok).toBe(true);
+
+    const frame = renderer.draw({
+      leases: [lease],
+      camera: { lease },
+      environment: { lease },
+    });
+    expect(frame.ok).toBe(true);
+    if (!frame.ok || frame.value === undefined) return;
+
+    const observed = await renderer.observe(frame.value, { include: ['timings'] });
+    expect(observed.ok).toBe(true);
+    const recovered = await renderer.recover();
+    expect(recovered.ok).toBe(false);
+    if (!recovered.ok) expect(recovered.error.code).toBe('recover-not-needed');
+    renderer.dispose();
+  });
+
+  it('does not promote a graph feature without a fullscreen effect into post-effects', async () => {
+    let planCalls = 0;
+    const feature = {
+      identity: 'synthetic.graph-only',
+      extract: () => ok(undefined),
+      plan: () => {
+        planCalls += 1;
+        return ok({ resources: [], passes: [] });
+      },
+    };
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi, features: [feature] },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update().ok).toBe(true);
+    const frame = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(frame.ok).toBe(true);
+    expect(planCalls).toBe(1);
+    renderer.dispose();
+  });
+
+  it('keeps the active graph as LKG when a feature candidate cannot be projected', async () => {
+    let invalid = false;
+    const featureErrors: string[] = [];
+    const feature: RenderFeature<undefined> = {
+      identity: 'synthetic.candidate-lkg',
+      extract: () => ok(undefined),
+      plan: () => {
+        if (!invalid) return ok({ resources: [], passes: [] });
+        return ok({
+          resources: [
+            {
+              kind: 'compute-program' as const,
+              name: 'candidate.program',
+              program: {
+                wgsl: '@compute @workgroup_size(1) fn main() {}',
+                entryPoints: ['main'],
+                bindings: [
+                  {
+                    entries: [{ binding: 0, visibility: 4, buffer: { type: 'storage' } }],
+                  },
+                ],
+              },
+            },
+            {
+              kind: 'buffer' as const,
+              name: 'candidate.buffer',
+              size: 4,
+              usage: ['storage' as const],
+              data: new Uint32Array([0]),
+            },
+            {
+              kind: 'compute-bindings' as const,
+              name: 'candidate.bindings',
+              program: 'candidate.program',
+              entries: [{ binding: 0, resource: 'candidate.buffer' }],
+            },
+          ],
+          passes: [
+            {
+              kind: 'compute',
+              name: 'main',
+              program: 'candidate.program',
+              bindings: 'candidate.bindings',
+              dispatches: [{ kind: 'direct', entryPoint: 'main', workgroups: [1] }],
+            },
+          ],
+        });
+      },
+    };
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi, features: [feature] },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    const unsubscribe = renderer.onError((error) => featureErrors.push(error.code));
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+        { component: Camera, data: { fov: 1, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(
+      renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      }).ok,
+    ).toBe(true);
+    const lastKnownGoodPasses = [...renderer.perFramePassNames];
+    expect(lastKnownGoodPasses.length).toBeGreaterThan(0);
+
+    invalid = true;
+    expect(
+      renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      }).ok,
+    ).toBe(true);
+    await Promise.resolve();
+    expect(
+      renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      }).ok,
+    ).toBe(true);
+    expect(featureErrors).toContain('duplicate-pass-name');
+    expect(renderer.perFramePassNames).toEqual(lastKnownGoodPasses);
+    unsubscribe();
+    renderer.dispose();
+  });
+
+  it('attaches derived-state systems once without putting writes in draw', async () => {
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const world = new World();
+
+    expect(renderer.attach(world).ok).toBe(true);
+    expect(renderer.attach(world).ok).toBe(true);
+    expect(world.inspect().schedules.flatMap((schedule) => schedule.systems)).not.toEqual(
+      expect.arrayContaining([expect.objectContaining({ name: 'renderDerivedEntities' })]),
+    );
+    renderer.dispose();
+  });
+
+  it('releases one World without disposing the shared Renderer', async () => {
+    const first = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const second = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    const world = new World();
+
+    expect(first.attach(world).ok).toBe(true);
+    first.detachScene(world);
+    first.detachScene(world);
+    expect(second.attach(world).ok).toBe(true);
+    second.dispose();
+    first.dispose();
+  });
+
+  it('resolves a renderer for a host canvas and rejects missing input', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+    await expect(
+      constructRenderer({ getContext: () => null }, { rhi }, { shaderManifestUrl: manifest }),
+    ).resolves.toMatchObject({
+      attach: expect.any(Function),
+      draw: expect.any(Function),
+    });
+    await expect(constructRenderer(undefined, { rhi })).rejects.toBeInstanceOf(Error);
+  });
+
+  it('temporarily releases presentation while preserving the Renderer identity', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: manifest },
+    );
+    expect(renderer.releaseSurface().ok).toBe(true);
+    expect(renderer.releaseSurface().ok).toBe(true);
+    expect(renderer.draw([], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(false);
+    expect(renderer.restoreSurface().ok).toBe(true);
+    expect(renderer.restoreSurface().ok).toBe(true);
+    expect(renderer.draw([], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+  });
+
+  it('does not unconfigure a surface after its ownership was released', async () => {
+    let unconfigureCalls = 0;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      {
+        rhi: {
+          ...rhi,
+          acquireCanvasContext: () => ({
+            ok: true as const,
+            value: {
+              configure: () => ({ ok: true as const, value: undefined }),
+              unconfigure: () => {
+                unconfigureCalls += 1;
+              },
+              getConfiguration: () => undefined,
+              getCurrentTexture: () => ({
+                ok: true as const,
+                value: { __brand: 'TextureView' },
+              }),
+            },
+          }),
+        },
+      } as never,
+      { shaderManifestUrl: manifestUrl() },
+    );
+
+    expect(renderer.releaseSurface().ok).toBe(true);
+    expect(unconfigureCalls).toBe(1);
+    renderer.dispose();
+    expect(unconfigureCalls).toBe(1);
+  });
+});

package/src/__tests__/fallback-row-stride-surface.unit.test.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { FALLBACK_BYTES_PER_ROW } from '../ibl/skylight-bind-group';
+
+const ownerSource = readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8');
+const rendererSource = readFileSync(new URL('../assembly/factory.ts', import.meta.url), 'utf8');
+
+describe('fallback texture row-stride owner', () => {
+  it('keeps both 1x1 fallback upload paths on one owner', () => {
+    expect(FALLBACK_BYTES_PER_ROW).toBe(256);
+    expect(ownerSource.match(/export const FALLBACK_BYTES_PER_ROW\s*=\s*256/g)).toHaveLength(1);
+    expect(rendererSource).toContain('FALLBACK_BYTES_PER_ROW');
+    expect(rendererSource).not.toMatch(/const FALLBACK_BYTES_PER_ROW\s*=\s*256/);
+  });
+});

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

@@ -0,0 +1,112 @@
+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.js';
+import type { FrameObservationRequest, FrameReceipt } from '../render-contract';
+
+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::standard',
+    backendId: 'webgpu',
+    ...overrides,
+  };
+}
+
+describe('render current-frame observation producer contract', () => {
+  it('requires a receipt-bound request instead of a latest-frame getter', () => {
+    const receipt = null as unknown as FrameReceipt;
+    const request: FrameObservationRequest = { include: ['timings', 'draws'] };
+    // M6 red snapshot: observe must be bound to the exact receipt and request.
+    expect(receipt).toBeDefined();
+    expect(request.include).toEqual(['timings', 'draws']);
+  });
+
+  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::standard',
+      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 the Standard 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::standard' }),
+      12,
+    );
+    const hdrp = await observeCurrentFrame(
+      { semantic: 'linear-hdr', readback },
+      source({ pipelineId: 'forgeax::standard' }),
+      12,
+    );
+
+    expect(urp.ok && hdrp.ok).toBe(true);
+    if (urp.ok && hdrp.ok) {
+      expect(urp.value.metadata.pipelineId).toBe('forgeax::standard');
+      expect(hdrp.value.metadata.pipelineId).toBe('forgeax::standard');
+      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__/fullscreen-feature-plan.unit.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { createFullscreenRenderFeature } from '../features/fullscreen';
+import { freezeRenderFeaturePlan } from '../features/plan';
+
+describe('fullscreen RenderFeature plan', () => {
+  it('keeps the cooked effect on the Standard post-stage owner', () => {
+    const feature = createFullscreenRenderFeature({
+      identity: 'test::fullscreen',
+      source: '@fragment fn fs_main() -> @location(0) vec4f { return vec4f(1); }',
+      params: { byteSize: 4, defaultValue: new Uint8Array([1, 0, 0, 0]) },
+    });
+    const planned = feature.plan(undefined, {
+      caps: {} as never,
+      frame: { frameNumber: 1 },
+      generation: 1,
+      targets: [{ name: 'scene-color', kind: 'color', format: 'rgba16float', sampleCount: 1 }],
+    });
+
+    expect(planned.ok).toBe(true);
+    if (!planned.ok) return;
+    expect(
+      freezeRenderFeaturePlan(feature.identity, planned.value, [
+        { name: 'scene-color', kind: 'color', format: 'rgba16float', sampleCount: 1 },
+      ]).ok,
+    ).toBe(true);
+    expect(planned.value.resources[0]).toMatchObject({
+      kind: 'fullscreen-program',
+      source: '@fragment fn fs_main() -> @location(0) vec4f { return vec4f(1); }',
+    });
+    expect(planned.value.passes).toEqual([]);
+  });
+});

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

@@ -0,0 +1,167 @@
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+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 { MeshFilter, MeshRenderer } from '../components';
+import { GlyphText } from '../components/glyph-text';
+import { GpuResidencyCache } from '../device/gpu-residency';
+import { glyphTextLayoutSystem, resetGlyphBakeCache } from '../glyph-text-layout-system';
+
+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 GpuResidencyCache();
+
+  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 = resolveAssetHandle<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();
+    const residentStore = { updateMesh } as unknown as GpuResidencyCache;
+    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();
+    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);
+  });
+});