@flighthq/render-wgpu 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.638.d4dbd4e

package/src/wgpuElement.test.ts

@@ -1,21 +1,135 @@
-import { createWgpuCanvasElement } from './wgpuElement';
+import {
+  createWgpuCanvasElement,
+  createWgpuRenderSurface,
+  getWgpuRenderSurfaceProvider,
+  resetWgpuRenderSurfaceProviderForTest,
+  setWgpuRenderSurfaceProvider,
+} from './wgpuElement';
 
 describe('createWgpuCanvasElement', () => {
-  it('sets CSS dimensions from width and height', () => {
-    const canvas = createWgpuCanvasElement(400, 300);
-    expect(canvas.style.width).toBe('400px');
-    expect(canvas.style.height).toBe('300px');
+  afterEach(() => resetWgpuRenderSurfaceProviderForTest());
+
+  it('preserves the canonical provider result identity', () => {
+    const surface = {} as HTMLCanvasElement;
+    setWgpuRenderSurfaceProvider({ createRenderSurface: () => surface });
+    expect(createWgpuCanvasElement(100, 200, 2)).toBe(surface);
+  });
+
+  it('throws an actionable Web-only setup error when the provider is absent', () => {
+    expect(() => createWgpuCanvasElement(100, 200)).toThrowError(
+      /enableHostWebWgpuRenderSurface\(\).*inject a WgpuRenderSurfaceProvider/,
+    );
+  });
+
+  it('throws the same setup error when the provider refuses', () => {
+    setWgpuRenderSurfaceProvider({ createRenderSurface: () => null });
+    expect(() => createWgpuCanvasElement(100, 200)).toThrowError(/enableHostWebWgpuRenderSurface\(\)/);
+  });
+});
+
+describe('createWgpuRenderSurface', () => {
+  afterEach(() => resetWgpuRenderSurfaceProviderForTest());
+
+  it('returns null when no provider is selected', () => {
+    expect(createWgpuRenderSurface(100, 200)).toBeNull();
+  });
+
+  it('passes exact dimensions and the default pixel ratio to the selected provider', () => {
+    const surface = {} as HTMLCanvasElement;
+    const createRenderSurface = vi.fn(() => surface);
+    setWgpuRenderSurfaceProvider({ createRenderSurface });
+    expect(createWgpuRenderSurface(100, 200)).toBe(surface);
+    expect(createRenderSurface).toHaveBeenCalledOnce();
+    expect(createRenderSurface).toHaveBeenCalledWith(100, 200, 1);
+  });
+
+  it('passes an explicit pixel ratio and preserves the provider result identity', () => {
+    const surface = {} as HTMLCanvasElement;
+    const createRenderSurface = vi.fn(() => surface);
+    setWgpuRenderSurfaceProvider({ createRenderSurface });
+    expect(createWgpuRenderSurface(300, 150, 2.5)).toBe(surface);
+    expect(createRenderSurface).toHaveBeenCalledWith(300, 150, 2.5);
+  });
+
+  it('selects replacements and reset restores omission', () => {
+    const first = {} as HTMLCanvasElement;
+    const second = {} as HTMLCanvasElement;
+    const firstProvider = { createRenderSurface: vi.fn(() => first) };
+    const secondProvider = { createRenderSurface: vi.fn(() => second) };
+    setWgpuRenderSurfaceProvider(firstProvider);
+    expect(getWgpuRenderSurfaceProvider()).toBe(firstProvider);
+    expect(createWgpuRenderSurface(1, 2)).toBe(first);
+    setWgpuRenderSurfaceProvider(secondProvider);
+    expect(getWgpuRenderSurfaceProvider()).toBe(secondProvider);
+    expect(createWgpuRenderSurface(3, 4)).toBe(second);
+    resetWgpuRenderSurfaceProviderForTest();
+    expect(getWgpuRenderSurfaceProvider()).toBeNull();
+    expect(createWgpuRenderSurface(5, 6)).toBeNull();
   });
 
-  it('scales pixel dimensions by pixelRatio', () => {
-    const canvas = createWgpuCanvasElement(200, 100, 2);
-    expect(canvas.width).toBe(400);
-    expect(canvas.height).toBe(200);
+  it('preserves provider refusal as null', () => {
+    setWgpuRenderSurfaceProvider({ createRenderSurface: () => null });
+    expect(createWgpuRenderSurface(100, 200)).toBeNull();
   });
 
-  it('defaults pixelRatio to 1', () => {
-    const canvas = createWgpuCanvasElement(300, 200);
-    expect(canvas.width).toBe(300);
-    expect(canvas.height).toBe(200);
+  it('lets a native host provide a surface without reading document', () => {
+    const surface = {} as HTMLCanvasElement;
+    setWgpuRenderSurfaceProvider({ createRenderSurface: () => surface });
+    withThrowingDocument(() => expect(createWgpuRenderSurface(100, 200)).toBe(surface));
+  });
+
+  it('returns null for omission and refusal without reading document', () => {
+    withThrowingDocument(() => {
+      expect(createWgpuRenderSurface(100, 200)).toBeNull();
+      setWgpuRenderSurfaceProvider({ createRenderSurface: () => null });
+      expect(createWgpuRenderSurface(100, 200)).toBeNull();
+    });
+  });
+});
+
+describe('getWgpuRenderSurfaceProvider', () => {
+  afterEach(() => resetWgpuRenderSurfaceProviderForTest());
+
+  it('returns the exact selected provider', () => {
+    const provider = { createRenderSurface: () => ({}) as HTMLCanvasElement };
+    setWgpuRenderSurfaceProvider(provider);
+    expect(getWgpuRenderSurfaceProvider()).toBe(provider);
   });
 });
+
+describe('resetWgpuRenderSurfaceProviderForTest', () => {
+  it('restores provider omission', () => {
+    setWgpuRenderSurfaceProvider({ createRenderSurface: () => ({}) as HTMLCanvasElement });
+    resetWgpuRenderSurfaceProviderForTest();
+    expect(getWgpuRenderSurfaceProvider()).toBeNull();
+    expect(createWgpuRenderSurface(1, 1)).toBeNull();
+  });
+});
+
+describe('setWgpuRenderSurfaceProvider', () => {
+  afterEach(() => resetWgpuRenderSurfaceProviderForTest());
+
+  it('replaces the selected provider', () => {
+    const first = { createRenderSurface: () => ({}) as HTMLCanvasElement };
+    const second = { createRenderSurface: () => ({}) as HTMLCanvasElement };
+    setWgpuRenderSurfaceProvider(first);
+    setWgpuRenderSurfaceProvider(second);
+    expect(getWgpuRenderSurfaceProvider()).toBe(second);
+  });
+});
+
+function withThrowingDocument(run: () => void): void {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'document');
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    get(): never {
+      throw new Error('portable WGPU code read document');
+    },
+  });
+  try {
+    run();
+  } finally {
+    if (descriptor === undefined) delete (globalThis as { document?: Document }).document;
+    else Object.defineProperty(globalThis, 'document', descriptor);
+  }
+}

package/src/wgpuHost.test.ts

@@ -0,0 +1,227 @@
+import type { WgpuHostBackend } from '@flighthq/types/contract';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import {
+  createWebWgpuHostBackend,
+  getWgpuHostBackend,
+  installWgpuHostBackend,
+  resetWgpuHostBackendForTest,
+  setWgpuHostBackend,
+} from './wgpuHost';
+import { createEmptyWgpuRegistries, createWgpuPipeline } from './wgpuPipeline';
+import {
+  createWgpuRenderState,
+  createWgpuRenderStateFromCanvasElement,
+  destroyWgpuRenderState,
+} from './wgpuRenderState';
+import { installWgpuMock } from './wgpuTestHelper';
+
+function fakeBackend(): WgpuHostBackend {
+  return {
+    acquire: vi.fn(),
+    isSupported: vi.fn(() => true),
+    release: vi.fn(),
+  } as WgpuHostBackend;
+}
+
+beforeAll(installWgpuMock);
+afterEach(resetWgpuHostBackendForTest);
+
+const _pipeline = createWgpuPipeline(createEmptyWgpuRegistries());
+
+describe('createWebWgpuHostBackend', () => {
+  it('acquires Flight-owned browser handles and releases each native handle', async () => {
+    const backend = createWebWgpuHostBackend();
+    const canvas = document.createElement('canvas');
+    const acquisition = await backend.acquire(canvas, {});
+    const unconfigure = vi.spyOn(acquisition.context, 'unconfigure');
+    const destroy = vi.spyOn(acquisition.device, 'destroy');
+
+    expect(acquisition.ownership).toBe('flight');
+    backend.release(acquisition);
+    expect(unconfigure).toHaveBeenCalledOnce();
+    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 acquisition = { ...acquired, ownership: 'caller' } as const;
+    const unconfigure = vi.spyOn(acquisition.context, 'unconfigure');
+    const destroy = vi.spyOn(acquisition.device, 'destroy');
+
+    backend.release(acquisition);
+    expect(unconfigure).toHaveBeenCalledOnce();
+    expect(destroy).toHaveBeenCalledOnce();
+  });
+
+  it('reports unsupported instead of propagating a throwing navigator.gpu getter', () => {
+    Object.defineProperty(globalThis.navigator, 'gpu', {
+      configurable: true,
+      get(): never {
+        throw new Error('host getter failed');
+      },
+    });
+    try {
+      expect(createWebWgpuHostBackend().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('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 = { ...acquired, ownership: 'flight' } as const;
+    const backend: WgpuHostBackend = {
+      acquire: vi.fn(async () => acquisition),
+      isSupported: vi.fn(() => true),
+      release: vi.fn(),
+    };
+    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 acquisition = { ...acquired, ownership: 'flight' } as const;
+    const configure = vi.spyOn(acquisition.context, 'configure').mockImplementationOnce(() => {
+      throw new Error('configure failed');
+    });
+    const backend: WgpuHostBackend = {
+      acquire: vi.fn(async () => acquisition),
+      isSupported: vi.fn(() => true),
+      release: vi.fn(),
+    };
+    setWgpuHostBackend(backend);
+
+    expect(() => createWgpuRenderState(acquisition, _pipeline)).toThrow('configure failed');
+    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 = { ...acquired, 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: WgpuHostBackend = {
+      acquire: vi.fn(async () => acquisition),
+      isSupported: vi.fn(() => true),
+      release: vi.fn((held) => {
+        held.context.unconfigure();
+        held.device.destroy();
+      }),
+    };
+    setWgpuHostBackend(backend);
+
+    expect(() => createWgpuRenderState(acquisition, _pipeline)).toThrow('configure failed');
+    expect(backend.release).not.toHaveBeenCalled();
+    expect(destroy).not.toHaveBeenCalled();
+    expect(unconfigure).not.toHaveBeenCalled();
+
+    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 = { ...acquired, ownership: 'caller' } as const;
+    const destroy = vi.spyOn(acquisition.device, 'destroy');
+    const backend: WgpuHostBackend = {
+      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/wgpuMaterialRegistry.test.ts

@@ -8,15 +8,18 @@ import {
   registerWgpuMaterialRenderer,
   resolveWgpuMaterialRenderer,
 } from './wgpuMaterialRegistry';
-import { createWgpuRenderStateRuntime, getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { createEmptyWgpuRegistries, createWgpuPipeline } from './wgpuPipeline';
+import { createWgpuDeviceState, createWgpuRenderStateRuntime, getWgpuRenderStateRuntime } from './wgpuRenderState';
 
 const TestKind = 'TestMaterial';
 const testRenderer: WgpuMaterialRenderer = { instanceFloatCount: 0, getShaderModule: () => ({}) as GPUShaderModule };
+const _pipeline = createWgpuPipeline(createEmptyWgpuRegistries());
 
 function makeState(): WgpuRenderState {
   // `device` is what the guard's message table dispatches on to name the wgpu registrar.
-  const state = { device: {} } as WgpuRenderState;
-  state[EntityRuntimeKey] = createWgpuRenderStateRuntime();
+  const device = {} as GPUDevice;
+  const state = { device } as WgpuRenderState;
+  state[EntityRuntimeKey] = createWgpuRenderStateRuntime(createWgpuDeviceState(device), _pipeline);
   return state;
 }
 

package/src/wgpuMipmap.test.ts

@@ -53,10 +53,10 @@ describe('generateWgpuMipmaps', () => {
     const state = await createWgpuRenderStateForTest();
     spyEncoderPasses(state);
     generateWgpuMipmaps(state, makeTextureSpy(), 4, 4, 'rgba8unorm');
-    const pipeline = getWgpuRenderStateRuntime(state).mipmapPipelineCache.get('rgba8unorm')?.pipeline;
+    const pipeline = getWgpuRenderStateRuntime(state).context.mipmapPipelineCache.get('rgba8unorm')?.pipeline;
     expect(pipeline).toBeDefined();
     generateWgpuMipmaps(state, makeTextureSpy(), 8, 8, 'rgba8unorm');
-    expect(getWgpuRenderStateRuntime(state).mipmapPipelineCache.get('rgba8unorm')?.pipeline).toBe(pipeline);
+    expect(getWgpuRenderStateRuntime(state).context.mipmapPipelineCache.get('rgba8unorm')?.pipeline).toBe(pipeline);
   });
 
   it('keeps linear and sRGB downsample pipelines distinct', async () => {
@@ -64,7 +64,7 @@ describe('generateWgpuMipmaps', () => {
     spyEncoderPasses(state);
     generateWgpuMipmaps(state, makeTextureSpy(), 4, 4, 'rgba8unorm');
     generateWgpuMipmaps(state, makeTextureSpy(), 4, 4, 'rgba8unorm-srgb');
-    expect(getWgpuRenderStateRuntime(state).mipmapPipelineCache.size).toBe(2);
+    expect(getWgpuRenderStateRuntime(state).context.mipmapPipelineCache.size).toBe(2);
   });
 });
 

package/src/wgpuPipeline.test.ts

@@ -0,0 +1,52 @@
+import type { WgpuPipeline } from '@flighthq/types/contract';
+import { EntityRuntimeKey } from '@flighthq/types/contract';
+
+import { createEmptyWgpuRegistries, createWgpuPipeline, getWgpuPipelineRegistries } from './wgpuPipeline';
+
+describe('createEmptyWgpuRegistries', () => {
+  it('creates empty tables for every required WGPU policy seam', () => {
+    const registries = createEmptyWgpuRegistries();
+    expect(registries.renderers.shape).toBe('keyed');
+    expect(registries.compressedTextureDecoder.shape).toBe('slot');
+    expect(registries.compressedTextureUpload.shape).toBe('slot');
+    expect(registries.customMaterialShaders.shape).toBe('keyed');
+    expect(registries.materialRenderers.shape).toBe('keyed');
+    expect(registries.meshMaterialRenderers.shape).toBe('keyed');
+    expect(registries.modifierSnippets.shape).toBe('keyed');
+    expect(registries.renderEffects.shape).toBe('keyed');
+    expect(registries.shapeRasterizer.shape).toBe('slot');
+    expect(registries.strokeTessellator.shape).toBe('slot');
+    expect(registries.textureResolvers.shape).toBe('keyed');
+    expect(registries.velocityWriters.shape).toBe('keyed');
+  });
+});
+
+describe('createWgpuPipeline', () => {
+  it('returns an Entity-backed pipeline with its own runtime identity', () => {
+    const registries = createEmptyWgpuRegistries();
+    const first = createWgpuPipeline(registries);
+    const second = createWgpuPipeline(registries);
+
+    expect(EntityRuntimeKey in first).toBe(true);
+    expect(first).not.toBe(second);
+    expect(first[EntityRuntimeKey]).not.toBe(second[EntityRuntimeKey]);
+  });
+
+  it('rejects a plain literal at the Entity boundary', () => {
+    const literal = { registries: createEmptyWgpuRegistries() } as unknown as WgpuPipeline;
+    expect(EntityRuntimeKey in literal).toBe(false);
+  });
+
+  it('carries the supplied immutable registration snapshot', () => {
+    const registries = createEmptyWgpuRegistries();
+    const pipeline = createWgpuPipeline(registries);
+    expect(getWgpuPipelineRegistries(pipeline)).toBe(registries);
+  });
+});
+
+describe('getWgpuPipelineRegistries', () => {
+  it('returns the registries captured by the explicit pipeline', () => {
+    const registries = createEmptyWgpuRegistries();
+    expect(getWgpuPipelineRegistries(createWgpuPipeline(registries))).toBe(registries);
+  });
+});