@forgeax/engine-runtime 0.1.4 → 0.1.7

package/src/__tests__/rhi-null-command-flow.unit.test.ts

@@ -1,273 +1,69 @@
-// feat-20260623-dummy-null-rhi-headless-backend / M3 / w17
-// T-b: RenderGraph pass scheduling + command flow dogfood unit test
-// (AC-04/05/06/07)
-//
-// Builds a world with one visible entity (MeshFilter + MeshRenderer +
-// DirectionalLight) running through the standard URP pipeline with RhiNull
-// backend. Asserts:
-//   1. Pass scheduling: perFramePassNames matches expected URP sequence
-//   2. Draw count >= 1 (AC-06)
-//   3. Bind group count >= 1 (AC-06)
-//   4. Resource lifecycle: create/destroy pairing (AC-07)
-//   5. BGL/PSO accounting: BindGroupLayout and RenderPipeline records (AC-05)
-//
-// File suffix .unit.test.ts ensures pnpm test:unit (vitest node) discovery.
-
-import type { World as WorldType } from '@forgeax/engine-ecs';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import type { Renderer as RendererType } from '@forgeax/engine-render';
-import type { Renderer } from '@forgeax/engine-render/internal';
-import {
-  Camera,
-  DirectionalLight,
-  MeshFilter,
-  MeshRenderer,
-} from '@forgeax/engine-render/internal';
-import type { RhiNullDevice } from '@forgeax/engine-rhi-null';
+import type { Renderer } from '@forgeax/engine-render';
 import { rhi } from '@forgeax/engine-rhi-null';
-import { Transform } from '@forgeax/engine-scene';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-const ENGINE = '../createRenderer';
+import { describe, expect, it } from 'vitest';
+import { requireRenderer } from './renderer-test-utils';
 
-function makeStubCanvas(w = 800, h = 600): HTMLCanvasElement {
-  return {
-    width: w,
-    height: h,
-    getContext(_kind: string): unknown {
-      return null;
-    },
-    addEventListener: () => undefined,
-    removeEventListener: () => undefined,
-  } as unknown as HTMLCanvasElement;
+function canvas(): HTMLCanvasElement {
+  return { width: 800, height: 600, getContext: () => null } as unknown as HTMLCanvasElement;
 }
 
-function buildManifestDataUrl(): string {
-  const manifest = {
-    schemaVersion: '1.0.0',
-    entries: [
-      { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
-      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
-      {
-        hash: 'tonemap0',
-        wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
-        glsl: '',
-        bindings: '',
-      },
-    ],
-  };
-  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
-}
+const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
 
-function makeWorld(): World {
-  const world = new World();
-  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
-  // Camera + Transform on SAME entity (required by extract system)
-  world.spawn(
-    { component: Transform, data: {} },
-    {
-      component: Camera,
-      data: {
-        fov: 60,
-        near: 0.1,
-        far: 1000,
-        tonemap: 4, // ACES filmic (TONEMAP_ACES_FILMIC)
-      },
-    },
-  );
-  // Light + Transform on same entity
-  world.spawn(
-    { component: Transform, data: {} },
-    {
-      component: DirectionalLight,
-      data: {
-        direction: [0.5, -1, -0.5],
-        castShadow: true,
-        intensity: 1,
-      },
-    },
-  );
-  // Visible entity: MeshFilter + MeshRenderer + Transform on same entity
-  world.spawn(
-    { component: Transform, data: {} },
-    { component: MeshFilter, data: { assetHandle: cubeHandle } },
-    { component: MeshRenderer, data: {} },
-  );
-  return world;
+function frameRequest(lease: Parameters<Renderer['draw']>[0]['leases'][number]) {
+  return { leases: [lease], camera: { lease }, environment: { lease } };
 }
 
-let renderer: Renderer | null = null;
-let rhiNullDevice: RhiNullDevice | null = null;
-
-beforeEach(() => {
-  vi.stubGlobal('navigator', { gpu: undefined });
-});
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-  if (renderer) {
-    try {
-      renderer.dispose();
-    } catch {
-      // ignore
-    }
-    renderer = null;
-  }
-  rhiNullDevice = null;
-});
-
-describe('rhi-null-command-flow.unit.test.ts (T-b)', () => {
-  async function loadEngine() {
-    return (await import(ENGINE)) as {
-      createRenderer: (
-        canvas: HTMLCanvasElement,
-        options?: { rhi?: unknown },
-        bundler?: { shaderManifestUrl?: string },
-      ) => Promise<Renderer>;
-    };
-  }
-
-  const rhiOptions = {
-    rhi: rhi as unknown as {
-      requestAdapter: () => unknown;
-      acquireCanvasContext: () => unknown;
-      createShaderModule: () => unknown;
-    },
-  };
-
-  const bundler = { shaderManifestUrl: buildManifestDataUrl() };
-
-  async function setupRendererAndDraw(): Promise<{
-    passNames: readonly string[];
-    totalDrawCount: number;
-    totalBindGroupCount: number;
-    recordCount: number;
-    kindCounts: Record<string, number>;
-  }> {
-    const engine = await loadEngine();
-    const canvas = makeStubCanvas();
-    renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-    await renderer.ready;
-
-    rhiNullDevice = renderer.device as unknown as RhiNullDevice;
-
-    // Reset frame-level counters before the draw call
-    rhiNullDevice.totalDrawCount = 0;
-    rhiNullDevice.totalBindGroupCount = 0;
-    rhiNullDevice.framePassNames = [];
-
-    const world = makeWorld();
-    if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-      throw new Error('World attachment failed');
-    }
-    (world as WorldType).update().unwrap();
-    renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-
-    const passNames = renderer.perFramePassNames;
-
-    const allRecords = rhiNullDevice.bookkeeper.allRecords();
-    const kindCounts: Record<string, number> = {};
-    for (const r of allRecords) {
-      kindCounts[r.kind] = (kindCounts[r.kind] ?? 0) + 1;
-    }
-
-    return {
-      passNames,
-      totalDrawCount: rhiNullDevice.totalDrawCount,
-      totalBindGroupCount: rhiNullDevice.totalBindGroupCount,
-      recordCount: rhiNullDevice.bookkeeper.recordCount(),
-      kindCounts,
-    };
-  }
-
-  describe('AC-04: Pass scheduling', () => {
-    it('perFramePassNames returns a non-empty array', async () => {
-      const { passNames } = await setupRendererAndDraw();
-      expect(passNames.length).toBeGreaterThan(0);
-    });
-
-    it('pass sequence includes main', async () => {
-      const { passNames } = await setupRendererAndDraw();
-      expect(passNames).toContain('main');
-    });
-
-    it('pass sequence includes tonemap passage', async () => {
-      const { passNames } = await setupRendererAndDraw();
-      const allNames = passNames.join(',');
-      expect(allNames).toContain('tonemap');
-    });
-
-    it('deliberately wrong expected pass name MUST fail (discriminative anchor)', async () => {
-      const { passNames } = await setupRendererAndDraw();
-      const fakeName = 'definitely-not-a-real-pass-name-xyzzy';
-      expect(passNames).not.toContain(fakeName);
-    });
-  });
-
-  describe('AC-06: Draw count + binding assembly', () => {
-    it('total draw count >= 1', async () => {
-      const { totalDrawCount } = await setupRendererAndDraw();
-      expect(totalDrawCount).toBeGreaterThanOrEqual(1);
-    });
-
-    it('total bind group count >= 1', async () => {
-      const { totalBindGroupCount } = await setupRendererAndDraw();
-      expect(totalBindGroupCount).toBeGreaterThanOrEqual(1);
-    });
-  });
-
-  describe('AC-05: BGL/PSO accounting', () => {
-    it('BindGroupLayout records exist in bookkeeper', async () => {
-      const { kindCounts } = await setupRendererAndDraw();
-      expect(kindCounts.BindGroupLayout ?? 0).toBeGreaterThanOrEqual(1);
-    });
-
-    it('RenderPipeline records exist in bookkeeper', async () => {
-      const { kindCounts } = await setupRendererAndDraw();
-      expect(kindCounts.RenderPipeline ?? 0).toBeGreaterThanOrEqual(1);
-    });
-
-    it('BindGroup records exist in bookkeeper', async () => {
-      const { kindCounts } = await setupRendererAndDraw();
-      expect(kindCounts.BindGroup ?? 0).toBeGreaterThanOrEqual(1);
-    });
-  });
-
-  describe('AC-07: Resource lifecycle', () => {
-    it('total record count is substantial (resources were created)', async () => {
-      const { recordCount } = await setupRendererAndDraw();
-      expect(recordCount).toBeGreaterThan(10);
-    });
-
-    it('Buffer entries exist in bookkeeper', async () => {
-      const { kindCounts } = await setupRendererAndDraw();
-      expect(kindCounts.Buffer ?? 0).toBeGreaterThanOrEqual(1);
-    });
+describe('RhiNull command flow', () => {
+  it('returns the synchronous receipt after the host submits a frame', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    const events: Array<{
+      readonly kind: string;
+      readonly frameId?: number;
+      readonly deviceGeneration?: number;
+    }> = [];
+    const unsubscribe = renderer.subscribe((event) => events.push(event));
+    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(frameRequest(attached.value));
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    expect(events.filter((event) => event.kind === 'frame-submitted')).toEqual([
+      {
+        kind: 'frame-submitted',
+        frameId: frame.value.frameId,
+        deviceGeneration: frame.value.deviceGeneration,
+      },
+    ]);
+    const completed = await frame.value.completed;
+    expect(completed.ok).toBe(true);
+    expect(renderer.inspect().frame.frameId).toBe(frame.value.frameId);
+    unsubscribe();
+    renderer.dispose();
   });
 
-  describe('perFramePassNames — calibration log', () => {
-    it('logs the actual pass names for calibration (informational)', async () => {
-      const engine = await loadEngine();
-      const canvas = makeStubCanvas();
-      renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-      await renderer.ready;
-      rhiNullDevice = renderer.device as unknown as RhiNullDevice;
-
-      rhiNullDevice.totalDrawCount = 0;
-      rhiNullDevice.totalBindGroupCount = 0;
-      rhiNullDevice.framePassNames = [];
-
-      const world = makeWorld();
-      if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-        throw new Error('World attachment failed');
-      }
-      (world as WorldType).update().unwrap();
-      renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-
-      const passNames = renderer.perFramePassNames;
-      expect(passNames.length).toBeGreaterThan(0);
-      expect(rhiNullDevice.totalDrawCount).toBeGreaterThanOrEqual(1);
+  it('observes the same receipt without exposing RHI command objects', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    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(frameRequest(attached.value));
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    const observation = await renderer.observe(frame.value, {
+      include: ['timings', 'draws', 'bindings'],
     });
+    expect(observation.ok).toBe(true);
+    if (observation.ok) expect(observation.value.frameId).toBe(frame.value.frameId);
+    expect(renderer).not.toHaveProperty('device');
+    expect(renderer).not.toHaveProperty('encoder');
+    expect(renderer).not.toHaveProperty('queue');
+    renderer.dispose();
   });
 });

package/src/__tests__/rhi-null-renderer-lifecycle.unit.test.ts

@@ -1,182 +1,54 @@
-// feat-20260623-dummy-null-rhi-headless-backend / M3 / w16
-// T-a: createRenderer lifecycle dogfood unit test (AC-02/03/11/12)
-//
-// Five scenarios covering the createRenderer-to-draw lifecycle with the
-// RhiNull headless backend injected via Channel 1 escape hatch
-// (createRenderer(canvas, { rhi: rhiNull })). All scenarios run in node
-// environment; no dawn/browser dependency.
-//
-// Scenario coverage matrix (plan-strategy D-3):
-//   1. createRenderer({rhi: rhiNull}) does not throw
-//   2. await renderer.ready does not reject (AC-02 — R-2 createShaderModule)
-//   3. renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }) does not crash (AC-03 — headless frame)
-//   4. await queue.onSubmittedWorkDone() resolves immediately (AC-12)
-//   5. renderer.dispose() then draw returns err (lifecycle guard)
-
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import type { Renderer } from '@forgeax/engine-render/internal';
-import {
-  Camera,
-  DirectionalLight,
-  MeshFilter,
-  MeshRenderer,
-} from '@forgeax/engine-render/internal';
 import { rhi } from '@forgeax/engine-rhi-null';
-import { Transform } from '@forgeax/engine-scene';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-const ENGINE = '../createRenderer';
-
-function makeStubCanvas(w = 800, h = 600): HTMLCanvasElement {
-  return {
-    width: w,
-    height: h,
-    getContext(_kind: string): unknown {
-      return null;
-    },
-    addEventListener: () => undefined,
-    removeEventListener: () => undefined,
-  } as unknown as HTMLCanvasElement;
-}
-
-/** Inline shader manifest so ready() doesn't fail fetching /shaders/manifest.json. */
-function buildManifestDataUrl(): string {
-  const manifest = {
-    schemaVersion: '1.0.0',
-    entries: [
-      { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
-      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
-      {
-        hash: 'tonemap0',
-        wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
-        glsl: '',
-        bindings: '',
-      },
-    ],
-  };
-  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
-}
+import { describe, expect, it } from 'vitest';
+import { requireRenderer } from './renderer-test-utils';
 
-function makeWorld(): World {
-  const world = new World();
-  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
-  // Camera + Transform on SAME entity (required by extract system)
-  world.spawn(
-    { component: Transform, data: {} },
-    { component: Camera, data: { fov: 60, near: 0.1, far: 1000 } },
-  );
-  // Light + Transform on same entity
-  world.spawn(
-    { component: Transform, data: {} },
-    { component: DirectionalLight, data: { direction: [0, -1, 0] } },
-  );
-  // Visible entity: MeshFilter + MeshRenderer + Transform on same entity
-  world.spawn(
-    { component: Transform, data: {} },
-    { component: MeshFilter, data: { assetHandle: cubeHandle } },
-    { component: MeshRenderer, data: {} },
-  );
-  return world;
+function canvas(): HTMLCanvasElement {
+  return { width: 800, height: 600, getContext: () => null } as unknown as HTMLCanvasElement;
 }
 
-let renderer: Renderer | null = null;
-
-beforeEach(() => {
-  vi.stubGlobal('navigator', { gpu: undefined });
-});
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-  if (renderer) {
-    try {
-      renderer.dispose();
-    } catch {
-      // ignore
-    }
-    renderer = null;
-  }
-});
-
-describe('rhi-null-renderer-lifecycle.unit.test.ts (T-a)', () => {
-  async function loadEngine() {
-    return (await import(ENGINE)) as {
-      createRenderer: (
-        canvas: HTMLCanvasElement,
-        options?: { rhi?: unknown },
-        bundler?: { shaderManifestUrl?: string },
-      ) => Promise<Renderer>;
-    };
-  }
+const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
 
-  const rhiOptions = {
-    rhi: rhi as unknown as {
-      requestAdapter: () => unknown;
-      acquireCanvasContext: () => unknown;
-      createShaderModule: () => unknown;
-    },
-  };
-
-  const bundler = { shaderManifestUrl: buildManifestDataUrl() };
-
-  it('1. createRenderer({rhi: rhiNull}) does not throw', async () => {
-    const engine = await loadEngine();
-    const canvas = makeStubCanvas();
-    renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-    expect(renderer).toBeDefined();
-    expect(renderer.device).toBeDefined();
-  });
-
-  it('2. await renderer.ready resolves ok (AC-02 — R-2 createShaderModule)', async () => {
-    const engine = await loadEngine();
-    const canvas = makeStubCanvas();
-    renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-    const ready = await renderer.ready;
-    expect(ready.ok).toBe(true);
-  });
-
-  it('3. renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }) does not crash (AC-03)', async () => {
-    const engine = await loadEngine();
-    const canvas = makeStubCanvas();
-    renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-    await renderer.ready;
-    const world = makeWorld();
-    renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-  });
-
-  it('4. await queue.onSubmittedWorkDone() resolves immediately (AC-12)', async () => {
-    const engine = await loadEngine();
-    const canvas = makeStubCanvas();
-    renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-    await renderer.ready;
-    const start = performance.now();
-    await renderer.device.queue.onSubmittedWorkDone();
-    const elapsed = performance.now() - start;
-    expect(elapsed).toBeLessThan(20);
+describe('RhiNull renderer lifecycle', () => {
+  it('reports ready inspection without an asynchronous ready property', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect(renderer.inspect().state).toBe('alive');
+    expect(renderer).not.toHaveProperty('ready');
+    renderer.dispose();
   });
 
-  it('5. renderer.dispose() then draw returns err (lifecycle guard)', async () => {
-    const engine = await loadEngine();
-    const canvas = makeStubCanvas();
-    renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-    await renderer.ready;
+  it('uses releaseSurface and restoreSurface as Result boundaries', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    const released = renderer.releaseSurface();
+    expect(released.ok).toBe(true);
+    expect(renderer.inspect().surface).toBe('released');
+    const restored = renderer.restoreSurface();
+    expect(restored.ok).toBe(true);
+    expect(renderer.inspect().surface).toBe('available');
     renderer.dispose();
-    const world = makeWorld();
-    const drawResult = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-    expect(drawResult.ok).toBe(false);
   });
 
-  it("6. no 'rhi-not-available' fires on ready (B-1: headless null backend has no preferred-canvas-format degradation)", async () => {
-    const engine = await loadEngine();
-    const canvas = makeStubCanvas();
-    renderer = await engine.createRenderer(canvas, rhiOptions, bundler);
-    const codes: string[] = [];
-    renderer.onError((e: { code: string }) => codes.push(e.code));
-    await renderer.ready;
-    // The 'null' backend's rgba8unorm swap-chain is its intended steady state,
-    // not a degraded fallback — selectSwapChainFormat's diagnostic must be
-    // suppressed for it (verify round-1 sandbox B-1). Falsifiable: remove the
-    // backendKind!=='null' guard in createRenderer and this turns red.
-    expect(codes).not.toContain('rhi-not-available');
+  it('attaches, updates, draws, and rejects a frame after disposal', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    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);
+    renderer.dispose();
+    expect(renderer.inspect().state).toBe('disposed');
+    expect(
+      renderer.draw({
+        leases: [attached.value],
+        camera: { lease: attached.value },
+        environment: { lease: attached.value },
+      }).ok,
+    ).toBe(false);
   });
 });