@forgeax/engine-rhi-webgpu 0.1.6 → 0.1.7

package/package.json

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

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

@@ -20,9 +20,9 @@ import type {
   RhiCanvasContext,
 } from '@forgeax/engine-rhi';
 import { type Result, RhiError, type RhiErrorCode } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { makeRhiDevice } from '../device';
-import { acquireCanvasContext, createShaderModule, requestDevice } from '../index';
+import { acquireCanvasContext, createShaderModule, requestAdapter, requestDevice } from '../index';
 import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gpu-device';
 
 {
@@ -1384,6 +1384,8 @@ import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gp
   }
 
   describe('AC-10 — 4 error paths .code / .expected / .hint three-field assertions', () => {
+    afterEach(() => vi.unstubAllGlobals());
+
     it('adapter null -> code=adapter-unavailable + three non-empty string fields', async () => {
       const gpu = createMockGpu({ adapterNull: true });
       const e = unwrapErr(await requestDevice({ gpu }));
@@ -1395,6 +1397,27 @@ import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gp
       expect(e.hint.length).toBeGreaterThan(0);
     });
 
+    it('requestAdapter throw keeps the original failure instead of claiming adapter-unavailable', async () => {
+      vi.stubGlobal('navigator', {
+        gpu: {
+          requestAdapter: async () => {
+            throw new DOMException('WebGPU permission policy denied access', 'SecurityError');
+          },
+        },
+      });
+
+      const e = unwrapErr(await requestAdapter());
+      expect(e.code).toBe('webgpu-runtime-error');
+      expect(e.hint).toContain('wgpu/WebGL2 fallback');
+      expect(e.detail).toEqual({
+        error: {
+          code: 'request-adapter-threw',
+          name: 'SecurityError',
+          message: 'WebGPU permission policy denied access',
+        },
+      });
+    });
+
     it('feature not enabled -> code=feature-not-enabled + three non-empty string fields', async () => {
       const gpu = createMockGpu({ requestDeviceFeatureNotEnabled: true });
       const e = unwrapErr(await requestDevice({ gpu }));

package/src/errors.ts

@@ -17,8 +17,46 @@ export function adapterUnavailable(): Result<never, RhiError> {
   return err(
     new RhiError({
       code: 'adapter-unavailable',
-      expected: 'an available WebGPU adapter',
-      hint: 'check whether the browser supports WebGPU or enable the relevant flag',
+      expected: 'an available browser-native WebGPU adapter',
+      hint: 'this only reports the browser-native WebGPU channel; ForgeaX may continue through its wgpu/WebGL2 fallback, so do not conclude that the browser or machine is unsupported unless both backend causes fail',
+    }),
+  );
+}
+
+/** `GPU.requestAdapter()` rejected instead of reporting adapter absence with `null`. */
+export function requestAdapterFailed(cause: unknown): Result<never, RhiError> {
+  const record =
+    cause !== null && typeof cause === 'object'
+      ? (cause as { readonly name?: unknown; readonly message?: unknown })
+      : undefined;
+  const name = typeof record?.name === 'string' && record.name.length > 0 ? record.name : undefined;
+  let message =
+    typeof record?.message === 'string' && record.message.length > 0
+      ? record.message
+      : typeof cause === 'string'
+        ? cause
+        : '';
+  if (message.length === 0 && cause !== undefined) {
+    try {
+      const serialized = JSON.stringify(cause);
+      message = serialized && serialized !== '{}' ? serialized : 'unknown thrown object';
+    } catch {
+      message = 'unserializable thrown object';
+    }
+  }
+  if (message.length === 0) message = 'unknown requestAdapter failure';
+  return err(
+    new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'navigator.gpu.requestAdapter() resolves with an adapter or null',
+      hint: 'inspect detail.error before assigning the failure to WebGPU capability; the ForgeaX runtime can still attempt its wgpu/WebGL2 fallback',
+      detail: {
+        error: {
+          code: 'request-adapter-threw',
+          ...(name === undefined ? {} : { name }),
+          message,
+        },
+      },
     }),
   );
 }

package/src/index.ts

@@ -56,6 +56,7 @@ import {
   adapterUnavailable,
   featureNotEnabled,
   limitExceeded,
+  requestAdapterFailed,
   shaderCompileFailed,
 } from './errors';
 
@@ -398,19 +399,16 @@ export async function requestAdapter(
   if (ambient === undefined || ambient === null) {
     return adapterUnavailable();
   }
-  // bug-20260610: `navigator.gpu.requestAdapter()` may throw rather than return
-  // null when WebGPU is disabled at the browser level (observed on Edge with
-  // WebGPU flag off — "Failed to create WebGPU Context Provider"). Without this
-  // try/catch, the throw escapes structurally — engine `tryCreateWebGPURenderer`
-  // catches it as outcome=throw with a raw Error (no `.code`), and the rhi-wgpu
-  // wasm GL fallback never gets a chance to run on its own merits because the
-  // engine sees an unstructured failure. Treat any throw as adapter-unavailable
-  // so the structured fallback path (Channel 2 -> Channel 3) stays intact.
+  // `null` is the spec adapter-absence channel. A rejection is a different
+  // failure (permission policy, insecure context, browser/runtime fault, etc.)
+  // and must retain its cause instead of being rewritten as unsupported WebGPU.
+  // Both outcomes remain structured, so Runtime can still try its wgpu/WebGL2
+  // fallback without erasing the browser-native channel diagnosis.
   let adapter: unknown;
   try {
     adapter = await ambient.requestAdapter(opts as GPURequestAdapterOptions | undefined);
-  } catch {
-    return adapterUnavailable();
+  } catch (cause) {
+    return requestAdapterFailed(cause);
   }
   if (adapter === null) {
     return adapterUnavailable();