@forgeax/engine-rhi-webgpu 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-rhi-webgpu",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,8 +22,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-rhi": "0.1.23",
-    "@forgeax/engine-types": "0.1.23",
+    "@forgeax/engine-rhi": "0.1.25",
+    "@forgeax/engine-types": "0.1.25",
     "@webgpu/types": "^0.1.71"
   },
   "forgeax": {

package/src/__tests__/rhi-webgpu.unit.test.ts

@@ -563,6 +563,77 @@ import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gp
   }
 
   describe('MVP-1.1 runtime — verbatim pass-through of the 5 descriptors', () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    it('normalizes omitted dynamic Dawn limits from the adapter without mutating the descriptor', async () => {
+      const gpu = createMockGpu();
+      const descriptor: GPUDeviceDescriptor = { label: 'dynamic-limit-probe' };
+      const r = await requestDevice({ gpu, deviceDescriptor: descriptor });
+      expect(r.ok).toBe(true);
+      expect(descriptor).toEqual({ label: 'dynamic-limit-probe' });
+
+      const ev = lastOf(gpu.__captured, 'requestDevice');
+      expect(ev.options).toMatchObject({
+        label: 'dynamic-limit-probe',
+        requiredLimits: {
+          maxDynamicUniformBuffersPerPipelineLayout: 8,
+          maxDynamicStorageBuffersPerPipelineLayout: 4,
+        },
+      });
+    });
+
+    it('preserves explicit dynamic limits while filling only the omitted adapter-backed limit', async () => {
+      const gpu = createMockGpu();
+      const requiredLimits = { maxDynamicUniformBuffersPerPipelineLayout: 2 };
+      const r = await requestDevice({ gpu, deviceDescriptor: { requiredLimits } });
+      expect(r.ok).toBe(true);
+
+      const ev = lastOf(gpu.__captured, 'requestDevice');
+      expect(ev.options?.requiredLimits).toEqual({
+        maxDynamicUniformBuffersPerPipelineLayout: 2,
+        maxDynamicStorageBuffersPerPipelineLayout: 4,
+      });
+      expect(requiredLimits).toEqual({ maxDynamicUniformBuffersPerPipelineLayout: 2 });
+    });
+
+    it('clamps oversized dynamic limits to the adapter without mutating the descriptor', async () => {
+      const gpu = createMockGpu();
+      const requiredLimits = {
+        maxDynamicUniformBuffersPerPipelineLayout: 1_000_000,
+        maxDynamicStorageBuffersPerPipelineLayout: 1_000_000,
+      };
+      const r = await requestDevice({ gpu, deviceDescriptor: { requiredLimits } });
+      expect(r.ok).toBe(true);
+
+      const ev = lastOf(gpu.__captured, 'requestDevice');
+      expect(ev.options?.requiredLimits).toEqual({
+        maxDynamicUniformBuffersPerPipelineLayout: 8,
+        maxDynamicStorageBuffersPerPipelineLayout: 4,
+      });
+      expect(requiredLimits).toEqual({
+        maxDynamicUniformBuffersPerPipelineLayout: 1_000_000,
+        maxDynamicStorageBuffersPerPipelineLayout: 1_000_000,
+      });
+    });
+
+    it('applies the same normalization on the public adapter two-step path', async () => {
+      const gpu = createMockGpu();
+      vi.stubGlobal('navigator', { gpu });
+      const adapterResult = await requestAdapter();
+      expect(adapterResult.ok).toBe(true);
+      if (!adapterResult.ok) return;
+
+      const deviceResult = await adapterResult.value.requestDevice({
+        requiredLimits: { maxDynamicStorageBuffersPerPipelineLayout: 1 },
+      });
+      expect(deviceResult.ok).toBe(true);
+      const ev = lastOf(gpu.__captured, 'requestDevice');
+      expect(ev.options?.requiredLimits).toEqual({
+        maxDynamicUniformBuffersPerPipelineLayout: 8,
+        maxDynamicStorageBuffersPerPipelineLayout: 1,
+      });
+    });
+
     it('BufferDescriptor passes through size / usage / label / mappedAtCreation', async () => {
       const gpu = createMockGpu();
       const r = await requestDevice({ gpu });

package/src/device.ts

@@ -1525,6 +1525,10 @@ export function makeRhiDevice(rawDevice: GPUDevice): {
       return probe;
     },
     queue,
+    // The raw backend owns the only real loss-injection seam. Keep this
+    // Promise as a transparent observation boundary; a test provider must
+    // operate on the backend before this shim and must never be added to the
+    // public RHI surface.
     lost: rawDevice.lost as unknown as Promise<{
       readonly reason: 'destroyed' | 'unknown';
       readonly message: string;

package/src/index.ts

@@ -76,12 +76,51 @@ export interface GpuLike {
   requestAdapter(options?: GPURequestAdapterOptions | undefined): Promise<GpuAdapterLike | null>;
 }
 
-/** The `GPUAdapter` subset accepted at the provider seam — only the `requestDevice` entry is consumed. */
+/** The `GPUAdapter` subset accepted at the provider seam — capability limits plus `requestDevice`. */
 export interface GpuAdapterLike {
+  readonly limits?: GPUSupportedLimits | undefined;
   // forgeax-async-whitelist: dom-native — spec `GPUAdapter.requestDevice()` raw entry
   requestDevice(descriptor?: GPUDeviceDescriptor | undefined): Promise<GpuDeviceLike>;
 }
 
+const DYNAMIC_DEVICE_LIMIT_KEYS = [
+  'maxDynamicUniformBuffersPerPipelineLayout',
+  'maxDynamicStorageBuffersPerPipelineLayout',
+] as const;
+const SYNTHETIC_DAWN_DYNAMIC_LIMIT_DEFAULT = 1_000_000;
+
+/**
+ * Keep browser-native Dawn from synthesizing the 1,000,000 dynamic-buffer
+ * defaults or clamping Dawn's synthetic 1,000,000 request. The adapter's
+ * reported values are the only safe values for omitted/defaulted limits: they
+ * are finite, supported by this adapter, and do not mutate the caller's
+ * descriptor.
+ */
+function normalizeDeviceDescriptor(
+  adapter: { readonly limits?: GPUSupportedLimits | undefined },
+  descriptor?: GPUDeviceDescriptor | undefined,
+): GPUDeviceDescriptor | undefined {
+  const adapterLimits = adapter.limits;
+  if (adapterLimits === undefined || adapterLimits === null) return descriptor;
+
+  const requiredLimits = { ...(descriptor?.requiredLimits ?? {}) };
+  let changed = false;
+  for (const key of DYNAMIC_DEVICE_LIMIT_KEYS) {
+    const value = adapterLimits[key];
+    if (!Number.isFinite(value) || value < 1) continue;
+    const requested = requiredLimits[key];
+    if (
+      requested !== undefined &&
+      (requested <= value || requested !== SYNTHETIC_DAWN_DYNAMIC_LIMIT_DEFAULT)
+    ) {
+      continue;
+    }
+    requiredLimits[key] = value;
+    changed = true;
+  }
+  return changed ? { ...(descriptor ?? {}), requiredLimits } : descriptor;
+}
+
 /**
  * The `GPUDevice` subset accepted at the provider seam — exactly the fields the
  * shim actually touches (the 5 descriptor `createX` calls + features / limits /
@@ -196,7 +235,9 @@ export async function requestDevice(
 
   let rawDevice: GpuDeviceLike;
   try {
-    rawDevice = await adapter.requestDevice(opts.deviceDescriptor);
+    rawDevice = await adapter.requestDevice(
+      normalizeDeviceDescriptor(adapter, opts.deviceDescriptor),
+    );
   } catch (e) {
     return classifyRequestDeviceError(e);
   }
@@ -393,7 +434,7 @@ function makeRhiAdapter(rawAdapter: {
       let rawDevice: GpuDeviceLike;
       try {
         rawDevice = (await rawAdapter.requestDevice(
-          opts as GPUDeviceDescriptor | undefined,
+          normalizeDeviceDescriptor(rawAdapter, opts as GPUDeviceDescriptor | undefined),
         )) as GpuDeviceLike;
       } catch (e) {
         return classifyRequestDeviceError(e);