@flighthq/render-wgpu 0.5.1-next.973.788d3d7 → 0.6.0

package/src/wgpuHost.test.ts

@@ -1,49 +1,39 @@
-import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
-import type { Entity, WgpuHostAcquisition, WgpuHostBackend } from '@flighthq/types/contract';
-import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { allocateEntity } from '@flighthq/entity/contract';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
 
+import type { WgpuDevice, WgpuHostAcquisition } from './contract.render-wgpu-types.ts';
+import { WgpuBufferUsage } from './contract.render-wgpu-types.ts';
+import { createTestWgpuSurface, testWgpuHost } from './wgpuHost.ts';
 import {
-  createWebWgpuHostBackend,
-  getWgpuHostBackend,
-  initializeWebWgpuHostBackend,
-  installWgpuHostBackend,
-  resetWgpuHostBackendForTest,
-  setWgpuHostBackend,
-} from './wgpuHost';
-import { createEmptyWgpuRegistries, createWgpuPipeline } from './wgpuPipeline';
-import {
+  createWgpuAcquisition,
   createWgpuRenderState,
-  createWgpuRenderStateFromCanvasElement,
   destroyWgpuRenderState,
-} from './wgpuRenderState';
-import { installWgpuMock } from './wgpuTestHelper';
-
-function fakeBackend(): WgpuHostBackend {
-  return entityBackend({
-    acquire: vi.fn(),
-    isSupported: vi.fn(() => true),
-    release: vi.fn(),
-  });
-}
-
-function entityBackend(fields: Omit<WgpuHostBackend, keyof Entity>): WgpuHostBackend {
-  return (() => {
-    const out = allocateEntity<WgpuHostBackend>();
-    Object.assign(out, fields);
-    return finishEntity(out);
-  })();
-}
+  releaseWgpuAcquisition,
+} from './wgpuRenderState.ts';
+import { installWgpuMock } from './wgpuTestHelper.ts';
 
 beforeAll(installWgpuMock);
-afterEach(resetWgpuHostBackendForTest);
 
-const _pipeline = createWgpuPipeline(createEmptyWgpuRegistries());
+describe('createTestWgpuSurface', () => {
+  const ATTACHMENT = { alphaMode: 'premultiplied', device: {} as WgpuDevice, format: 'bgra8unorm' } as const;
+
+  it('builds a surface the test host backend can resolve back to its canvas', () => {
+    const canvas = document.createElement('canvas');
+    const surface = createTestWgpuSurface(canvas);
 
-describe('createWebWgpuHostBackend', () => {
+    // The drawable lives on the runtime, not on the entity: nothing about the canvas is visible on the
+    // public surface, and the host is the only code that narrows it back.
+    expect(Object.keys(surface)).toEqual([]);
+    expect(() => testWgpuHost.attachSurface(surface, ATTACHMENT)).not.toThrow();
+  });
+});
+
+describe('testWgpuHost', () => {
   it('acquires Flight-owned browser handles and releases each native handle', async () => {
-    const backend = createWebWgpuHostBackend();
+    const backend = testWgpuHost;
     const canvas = document.createElement('canvas');
-    const acquisition = await backend.acquire(canvas, {});
+    const target = createTestWgpuSurface(canvas);
+    const acquisition = await backend.acquire(target, {});
     const unconfigure = vi.spyOn(acquisition.context, 'unconfigure');
     const destroy = vi.spyOn(acquisition.device, 'destroy');
 
@@ -53,14 +43,11 @@ describe('createWebWgpuHostBackend', () => {
     expect(destroy).toHaveBeenCalledOnce();
   });
 
-  // ★ THE BACKEND NO LONGER DECIDES OWNERSHIP. It used to return early for `caller`, which meant the whole
-  // contract lived in one implementation and any other backend could violate it unseen — and it also made
-  // the caller's own release verb a no-op. `release` now tears down whatever it is handed; Flight simply
-  // never hands it a caller-owned acquisition (see O1/O2), and `releaseWgpuAcquisition` hands it one only
-  // because the caller asked.
   it('tears down whatever it is handed, leaving the ownership decision to the caller', async () => {
-    const backend = createWebWgpuHostBackend();
-    const acquired = await backend.acquire(document.createElement('canvas'), {});
+    const backend = testWgpuHost;
+    const canvas = document.createElement('canvas');
+    const target = createTestWgpuSurface(canvas);
+    const acquired = await backend.acquire(target, {});
     const acquisition = allocateEntity<WgpuHostAcquisition>();
     Object.assign(acquisition, acquired);
     acquisition.ownership = 'caller' as const;
@@ -80,173 +67,57 @@ describe('createWebWgpuHostBackend', () => {
       },
     });
     try {
-      expect(createWebWgpuHostBackend().isSupported()).toBe(false);
+      expect(testWgpuHost.isSupported()).toBe(false);
     } finally {
       installWgpuMock();
     }
   });
-});
-
-describe('getWgpuHostBackend', () => {
-  it('returns one stable explicit web fallback', () => {
-    const first = getWgpuHostBackend();
-    const second = getWgpuHostBackend();
-    expect(first).toBe(second);
-  });
-});
 
-describe('initializeWebWgpuHostBackend', () => {
-  it('is the construction initializer of createWebWgpuHostBackend', () => {
-    expect(typeof initializeWebWgpuHostBackend).toBe('function');
-  });
-});
-
-describe('installWgpuHostBackend', () => {
-  it('preserves the first installed host identity', () => {
-    const first = fakeBackend();
-    installWgpuHostBackend(first);
-    installWgpuHostBackend(fakeBackend());
-    expect(getWgpuHostBackend()).toBe(first);
-  });
-});
-
-describe('resetWgpuHostBackendForTest', () => {
-  it('clears custom and host slots back to the web fallback', () => {
-    const fallback = getWgpuHostBackend();
-    const host = fakeBackend();
-    const custom = fakeBackend();
-    installWgpuHostBackend(host);
-    setWgpuHostBackend(custom);
-
-    resetWgpuHostBackendForTest();
-    expect(getWgpuHostBackend()).toBe(fallback);
-  });
-});
-describe('setWgpuHostBackend', () => {
-  it('routes acquisition and release through the same selected backend', async () => {
-    const web = createWebWgpuHostBackend();
-    const acquired = await web.acquire(document.createElement('canvas'), {});
-    // Flight-owned: the state acquired these, so destroying it releases them. The caller-owned case is the
-    // opposite assertion and lives in its own test below.
-    const acquisition = allocateEntity<WgpuHostAcquisition>();
-    Object.assign(acquisition, acquired);
-    acquisition.ownership = 'flight' as const;
-    const backend = entityBackend({
-      acquire: vi.fn(async () => acquisition),
-      isSupported: vi.fn(() => true),
-      release: vi.fn(),
-    });
+  it('routes acquisition and release through a caller-provided backend', async () => {
+    const web = testWgpuHost;
     const canvas = document.createElement('canvas');
-    setWgpuHostBackend(backend);
-
-    const state = await createWgpuRenderStateFromCanvasElement(canvas, _pipeline);
-    expect(backend.acquire).toHaveBeenCalledWith(canvas, { format: undefined, powerPreference: undefined });
-    expect(state.context).toBe(acquisition.context);
-    expect(state.device).toBe(acquisition.device);
-    expect(state.format).toBe(acquisition.format);
-    destroyWgpuRenderState(state);
-    expect(backend.release).toHaveBeenCalledOnce();
-    expect(backend.release).toHaveBeenCalledWith(acquisition);
-
-    web.release(acquired);
-  });
-
-  it('releases flight-owned handles through the selected backend when initialization fails', async () => {
-    const web = createWebWgpuHostBackend();
-    const acquired = await web.acquire(document.createElement('canvas'), {});
+    const target = createTestWgpuSurface(canvas);
+    const acquired = await web.acquire(target, {});
     const acquisition = allocateEntity<WgpuHostAcquisition>();
     Object.assign(acquisition, acquired);
-    acquisition.ownership = 'flight' as const;
-    const configure = vi.spyOn(acquisition.context, 'configure').mockImplementationOnce(() => {
-      throw new Error('configure failed');
-    });
-    const backend = entityBackend({
+    acquisition.ownership = 'caller' as const;
+    const backend: typeof web = {
       acquire: vi.fn(async () => acquisition),
+      attachSurface: vi.fn(() => null),
+      create: vi.fn(),
       isSupported: vi.fn(() => true),
       release: vi.fn(),
-    });
-    setWgpuHostBackend(backend);
+    } as typeof web;
+    const routeTarget = createTestWgpuSurface(document.createElement('canvas'));
+
+    const routed = await createWgpuAcquisition(backend, routeTarget);
+    expect(backend.acquire).toHaveBeenCalledWith(routeTarget, {});
+    expect(routed?.device).toBe(acquisition.device);
+    expect(routed?.format).toBe(acquisition.format);
 
-    expect(() => createWgpuRenderState(acquisition, _pipeline)).toThrow('configure failed');
+    releaseWgpuAcquisition(backend, acquisition);
     expect(backend.release).toHaveBeenCalledOnce();
     expect(backend.release).toHaveBeenCalledWith(acquisition);
 
-    configure.mockRestore();
     web.release(acquired);
   });
 
-  // ★ O2. The previous shape of this test used a CALLER-owned acquisition and asserted release WAS called,
-  // with a `vi.fn()` release that could not destroy anything — so it passed whether or not ownership was
-  // honoured. Flight now refuses to release borrowed handles even while unwinding a failure, and the
-  // backend here is deliberately one that would destroy them if asked.
-  it('O2: never releases caller-owned handles when initialization fails, whatever the backend does', async () => {
-    const web = createWebWgpuHostBackend();
-    const acquired = await web.acquire(document.createElement('canvas'), {});
-    const acquisition = allocateEntity<WgpuHostAcquisition>();
-    Object.assign(acquisition, acquired);
-    acquisition.ownership = 'caller' as const;
-    const configure = vi.spyOn(acquisition.context, 'configure').mockImplementationOnce(() => {
-      throw new Error('configure failed');
-    });
-    const destroy = vi.spyOn(acquisition.device, 'destroy');
-    const unconfigure = vi.spyOn(acquisition.context, 'unconfigure');
-    const backend = entityBackend({
-      acquire: vi.fn(async () => acquisition),
-      isSupported: vi.fn(() => true),
-      release: vi.fn((held) => {
-        held.context.unconfigure();
-        held.device.destroy();
-      }),
-    });
-    setWgpuHostBackend(backend);
+  it('never releases host handles when a state built on the device is destroyed', async () => {
+    const web = testWgpuHost;
+    const canvas = document.createElement('canvas');
+    const target = createTestWgpuSurface(canvas);
+    const acquired = await web.acquire(target, {});
+    const destroy = vi.spyOn(acquired.device, 'destroy');
+    const unconfigure = vi.spyOn(acquired.context, 'unconfigure');
+
+    destroyWgpuRenderState(createWgpuRenderState(acquired.device));
 
-    expect(() => createWgpuRenderState(acquisition, _pipeline)).toThrow('configure failed');
-    expect(backend.release).not.toHaveBeenCalled();
     expect(destroy).not.toHaveBeenCalled();
     expect(unconfigure).not.toHaveBeenCalled();
+    expect(acquired.device.createBuffer({ size: 4, usage: WgpuBufferUsage.COPY_DST }).size).toBe(4);
 
-    configure.mockRestore();
     destroy.mockRestore();
     unconfigure.mockRestore();
     web.release(acquired);
   });
-
-  // ★ O1. The destroy path, against a backend whose release really destroys.
-  it('O1: never releases caller-owned handles when the state is destroyed', async () => {
-    const web = createWebWgpuHostBackend();
-    const acquired = await web.acquire(document.createElement('canvas'), {});
-    const acquisition = allocateEntity<WgpuHostAcquisition>();
-    Object.assign(acquisition, acquired);
-    acquisition.ownership = 'caller' as const;
-    const destroy = vi.spyOn(acquisition.device, 'destroy');
-    const backend = entityBackend({
-      acquire: vi.fn(async () => acquisition),
-      isSupported: vi.fn(() => true),
-      release: vi.fn((held) => {
-        held.device.destroy();
-      }),
-    });
-    setWgpuHostBackend(backend);
-
-    const state = createWgpuRenderState(acquisition, _pipeline);
-    destroyWgpuRenderState(state);
-
-    expect(backend.release).not.toHaveBeenCalled();
-    expect(destroy).not.toHaveBeenCalled();
-    // The handles are still usable, which is the property the caller actually cares about.
-    expect(acquisition.device.createBuffer({ size: 4, usage: GPUBufferUsage.COPY_DST }).size).toBe(4);
-
-    destroy.mockRestore();
-    web.release(acquired);
-  });
-
-  it('takes precedence over host installation and reveals that host when cleared', () => {
-    const host = fakeBackend();
-    const custom = fakeBackend();
-    installWgpuHostBackend(host);
-    setWgpuHostBackend(custom);
-    expect(getWgpuHostBackend()).toBe(custom);
-    setWgpuHostBackend(null);
-    expect(getWgpuHostBackend()).toBe(host);
-  });
 });

package/src/wgpuMipmap.test.ts

@@ -1,15 +1,21 @@
-import type { WgpuRenderState } from '@flighthq/types/contract';
-
-import { generateWgpuMipmaps, getWgpuMipLevelCount, registerWgpuMipmapGeneration } from './wgpuMipmap';
-import { getWgpuRenderStateRuntime } from './wgpuRenderState';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import type {
+  WgpuCommandBuffer,
+  WgpuCommandEncoder,
+  WgpuRenderPassEncoder,
+  WgpuRenderState,
+  WgpuTexture,
+  WgpuTextureView,
+} from './contract.render-wgpu-types.ts';
+import { generateWgpuMipmaps, getWgpuMipLevelCount, registerWgpuMipmapGeneration } from './wgpuMipmap.ts';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper.ts';
 
 beforeAll(() => {
   installWgpuMock();
 });
 
-function makeTextureSpy(): GPUTexture {
-  return { createView: vi.fn(() => ({}) as GPUTextureView), destroy: () => {} } as unknown as GPUTexture;
+function makeTextureSpy(): WgpuTexture {
+  return { createView: vi.fn(() => ({}) as WgpuTextureView), destroy: () => {} } as unknown as WgpuTexture;
 }
 
 // Replaces the mock device's command encoder with one whose render passes are spies, so a test can
@@ -22,9 +28,9 @@ function spyEncoderPasses(state: WgpuRenderState): ReturnType<typeof vi.fn> {
         setBindGroup: vi.fn(),
         draw: vi.fn(),
         end: vi.fn(),
-      }) as unknown as GPURenderPassEncoder,
+      }) as unknown as WgpuRenderPassEncoder,
   );
-  const encoder = { beginRenderPass, finish: () => ({}) as GPUCommandBuffer } as unknown as GPUCommandEncoder;
+  const encoder = { beginRenderPass, finish: () => ({}) as WgpuCommandBuffer } as unknown as WgpuCommandEncoder;
   vi.spyOn(state.device, 'createCommandEncoder').mockReturnValue(encoder);
   return beginRenderPass;
 }

package/src/wgpuQuadMaterialRegistry.test.ts

@@ -0,0 +1,132 @@
+import { EntityRuntimeKey } from '@flighthq/entity/contract';
+import {
+  addLogSink,
+  createLogState,
+  createMemoryLogSink,
+  getMemoryLogSinkEntries,
+  removeLogSink,
+} from '@flighthq/log/contract';
+import type { LogState } from '@flighthq/log/contract';
+import type { LogEntry, MemoryLogSink } from '@flighthq/log/contract';
+import type { Material } from '@flighthq/materials/contract';
+import { StandardMaterialKind } from '@flighthq/materials/contract';
+import { enableRenderRegistriesGuards, explainRenderRegistriesMisses } from '@flighthq/render/contract';
+import { RenderRegistryTable } from '@flighthq/render/contract';
+
+import type {
+  WgpuDevice,
+  WgpuQuadMaterialRenderer,
+  WgpuRenderState,
+  WgpuShaderModule,
+} from './contract.render-wgpu-types.ts';
+import {
+  getWgpuQuadMaterialRenderer,
+  registerWgpuQuadMaterialRenderer,
+  resolveWgpuQuadMaterialRenderer,
+} from './wgpuQuadMaterialRegistry.ts';
+import { createWgpuDeviceState, createWgpuRenderStateRuntime, getWgpuRenderStateRuntime } from './wgpuRenderState.ts';
+
+// Each test logs into a fresh caller-owned state, so logOnce keys never leak between tests.
+let logState: LogState;
+
+beforeEach(() => {
+  logState = createLogState();
+});
+
+const TestKind = 'TestMaterial';
+const testRenderer: WgpuQuadMaterialRenderer = {
+  instanceFloatCount: 0,
+  getShaderModule: () => ({}) as WgpuShaderModule,
+};
+
+function makeState(): WgpuRenderState {
+  const device = {} as WgpuDevice;
+  const state = { device } as WgpuRenderState;
+  state[EntityRuntimeKey] = createWgpuRenderStateRuntime(createWgpuDeviceState(device));
+  return state;
+}
+
+function makeMaterial(kind: string): Material {
+  return { kind } as Material;
+}
+
+describe('getWgpuQuadMaterialRenderer', () => {
+  it('returns null when nothing is registered for the kind', () => {
+    expect(getWgpuQuadMaterialRenderer(makeState(), TestKind)).toBeNull();
+  });
+});
+
+describe('registerWgpuQuadMaterialRenderer', () => {
+  it('registers a renderer retrievable by kind', () => {
+    const state = makeState();
+    const before = getWgpuRenderStateRuntime(state).registries.materialRenderers;
+    registerWgpuQuadMaterialRenderer(state, TestKind, testRenderer);
+    expect(getWgpuQuadMaterialRenderer(state, TestKind)).toBe(testRenderer);
+    expect(getWgpuRenderStateRuntime(state).registries.materialRenderers).not.toBe(before);
+    expect(before.size).toBe(0);
+  });
+
+  it('is last-write-wins without mutating the earlier snapshot', () => {
+    const state = makeState();
+    const replacement: WgpuQuadMaterialRenderer = {
+      instanceFloatCount: 0,
+      getShaderModule: () => ({}) as WgpuShaderModule,
+    };
+    registerWgpuQuadMaterialRenderer(state, TestKind, testRenderer);
+    const before = getWgpuRenderStateRuntime(state).registries.materialRenderers;
+
+    registerWgpuQuadMaterialRenderer(state, TestKind, replacement);
+
+    expect(getWgpuQuadMaterialRenderer(state, TestKind)).toBe(replacement);
+    expect(before.get(TestKind)).toEqual(testRenderer);
+  });
+});
+
+describe('resolveWgpuQuadMaterialRenderer', () => {
+  it('returns null when nothing is registered — no built-in fallback', () => {
+    expect(resolveWgpuQuadMaterialRenderer(makeState(), null)).toBeNull();
+    expect(resolveWgpuQuadMaterialRenderer(makeState(), makeMaterial(TestKind))).toBeNull();
+  });
+
+  it('returns the registered renderer for a material kind', () => {
+    const state = makeState();
+    registerWgpuQuadMaterialRenderer(state, TestKind, testRenderer);
+    expect(resolveWgpuQuadMaterialRenderer(state, makeMaterial(TestKind))).toBe(testRenderer);
+  });
+
+  it('falls back to the renderer registered for StandardMaterialKind', () => {
+    const state = makeState();
+    registerWgpuQuadMaterialRenderer(state, StandardMaterialKind, testRenderer);
+    expect(resolveWgpuQuadMaterialRenderer(state, makeMaterial('Other'))).toBe(testRenderer);
+    expect(resolveWgpuQuadMaterialRenderer(state, null)).toBe(testRenderer);
+  });
+
+  it('reports the missing kind against the wgpu registrar, not the gl one', () => {
+    const state = makeState();
+    enableRenderRegistriesGuards(state, logState);
+    const sink = createMemoryLogSink(4);
+    addLogSink(logState, sink.sink);
+
+    try {
+      resolveWgpuQuadMaterialRenderer(state, makeMaterial(TestKind));
+
+      expect(explainRenderRegistriesMisses(state).misses).toEqual([
+        { kind: TestKind, registry: RenderRegistryTable.MaterialRenderer },
+      ]);
+      expect(readMemoryLogEntries(sink)[0]?.data).toMatchObject({
+        kind: TestKind,
+        message:
+          'resolveWgpuQuadMaterialRenderer: material kind has no registered renderer, so nodes using it do not draw — call registerWgpuQuadMaterialRenderer(state, kind, renderer)',
+        registry: RenderRegistryTable.MaterialRenderer,
+      });
+    } finally {
+      removeLogSink(logState, sink.sink);
+    }
+  });
+});
+
+function readMemoryLogEntries(handle: Readonly<MemoryLogSink>): LogEntry[] {
+  const entries: LogEntry[] = [];
+  getMemoryLogSinkEntries(entries, handle);
+  return entries;
+}