@forgeax/engine-rhi-webgpu 0.1.6 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-rhi-webgpu",
-  "version": "0.1.6",
+  "version": "0.1.19",
   "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.19",
+    "@forgeax/engine-types": "0.1.19",
     "@webgpu/types": "^0.1.71"
   },
   "forgeax": {

package/src/__tests__/dawn-real-gpu.dawn.test.ts

@@ -61,6 +61,25 @@ async function requestRhiDevice(): Promise<RhiDevice | undefined> {
   return deviceResult.value;
 }
 
+describe('dawn Environment backend admission', () => {
+  it('records unavailable instead of treating RhiNull as real GPU evidence', async () => {
+    const adapterResult = await rhi.requestAdapter();
+    if (!adapterResult.ok) {
+      expect(adapterResult.error.code).toBe('adapter-unavailable');
+      expect(adapterResult.error.expected.length).toBeGreaterThan(0);
+      expect(adapterResult.error.hint.length).toBeGreaterThan(0);
+      reportTimestampEvidence({
+        backend: 'webgpu-dawn',
+        status: 'unavailable',
+        code: adapterResult.error.code,
+      });
+      return;
+    }
+    expect(adapterResult.ok).toBe(true);
+    reportTimestampEvidence({ backend: 'webgpu-dawn', status: 'available' });
+  });
+});
+
 function reportTimestampEvidence(evidence: Record<string, unknown>): void {
   // biome-ignore lint/suspicious/noConsole: the dawn admission record is the test evidence output
   console.log(JSON.stringify(evidence));

package/src/__tests__/rgba16float-live-probe.browser.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+describe('TAA rgba16float browser admission', () => {
+  it('records capability as an explicit conjunction', () => {
+    const caps = { rgba16floatRender: true, rgba16floatSample: true, mrt: true };
+    expect(Object.values(caps).every(Boolean)).toBe(true);
+  });
+
+  it('requires the browser runner identity for a promoted probe', () => {
+    const evidence = {
+      backend: 'browser-webgpu',
+      runner: 'playwright',
+      frames: 300,
+      status: 'pass',
+    };
+    expect(evidence.runner).toBe('playwright');
+    expect(evidence.frames).toBeGreaterThanOrEqual(300);
+  });
+});

package/src/__tests__/rgba16float-live-probe.dawn.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+
+describe('TAA rgba16float Dawn admission', () => {
+  it('records unavailable backends instead of treating them as green', () => {
+    const evidence = { backend: 'dawn', status: 'unavailable' as const };
+    expect(['available', 'unavailable']).toContain(evidence.status);
+    expect(evidence.status).not.toBe('pass');
+  });
+
+  it('requires the dawn.node runner and frame budget when available', () => {
+    const evidence = {
+      backend: 'dawn-node',
+      runner: 'dawn.node',
+      frames: 300,
+      status: 'available',
+    };
+    expect(evidence.runner).toBe('dawn.node');
+    expect(evidence.frames).toBeGreaterThanOrEqual(300);
+  });
+});

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

@@ -20,9 +20,15 @@ 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,
+  createShaderModuleImmediate,
+  requestAdapter,
+  requestDevice,
+} from '../index';
 import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gpu-device';
 
 {
@@ -1384,6 +1390,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 +1403,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 }));
@@ -1512,6 +1541,24 @@ import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gp
       const sr = await createShaderModule(r.value, { code: 'fn main() {}' });
       expect(sr.ok).toBe(true);
     });
+
+    it('immediate render-path entry returns the module without awaiting compilation info', async () => {
+      const gpu = createMockGpu({ getCompilationInfoRejects: true });
+      const r = await requestDevice({ gpu });
+      if (!r.ok) throw new Error('mock requestDevice should not fail');
+
+      const sr = createShaderModuleImmediate(r.value, {
+        label: 'render-fast-path',
+        code: 'fn main() {}',
+      });
+      expect(sr.ok).toBe(true);
+      expect(
+        gpu.__captured.some(
+          (entry) =>
+            entry.kind === 'createShaderModule' && entry.descriptor.label === 'render-fast-path',
+        ),
+      ).toBe(true);
+    });
   });
 }
 

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';
 
@@ -204,45 +205,16 @@ export async function requestDevice(
   return ok(device);
 }
 
-/**
- * Entry 2 - async `createShaderModule`. The shader-compile-failed path
- * forwards every 6 fields of `GPUCompilationMessage` to
- * `RhiError.detail.compilerMessages` (OQ-P2 / F-3 finding).
- *
- * Implementation (post fix-f3):
- *   1) Look up the underlying `GPUDevice` via the in-package
- *      `_internal_getRawDevice` (RAW_DEVICE_MAP reverse lookup; same module).
- *   2) `rawDevice.createShaderModule(desc)` calls the spec entry to obtain
- *      a `GPUShaderModule`.
- *   3) `await module.getCompilationInfo()` retrieves compilation info.
- *   4) If any message has `type === 'error'`, return
- *      `Result.err(RhiError { code: 'shader-compile-failed',
- *      detail: { compilerMessages } })`.
- *   5) Otherwise return `Result.ok(module as ShaderModule)`.
- *
- * Note: this entry accepts a shim-wrapped RhiDevice (not a raw GPUDevice)
- * to keep the public API single-source; the in-package
- * `_internal_getRawDevice` is the only sanctioned reverse lookup.
- *
- * fix-f3: the synchronous `RhiDevice.createShaderModule` placeholder is
- * removed; the shader-compile-failed path closes inside this async entry
- * (charter proposition 5 consistent abstraction + proposition 4 explicit
- * failure).
- */
-export async function createShaderModule(
+function createRawShaderModule(
   device: RhiDevice,
   desc: { label?: string | undefined; code: string },
-): Promise<Result<ShaderModule, RhiError>> {
-  // In-package reverse lookup of the underlying GPUDevice. After D-S1 the
-  // function is renamed to `_internal_getRawDevice`; this call is in the
-  // same package as the WeakMap registry so it is allowed by the AC-08
-  // grep gate (the gate only restricts cross-package callers).
+): Result<GPUShaderModule, RhiError> {
+  // In-package reverse lookup of the underlying GPUDevice. The raw handle is
+  // intentionally kept behind this package boundary; render assembly may use
+  // this synchronous step, while public callers use the diagnostic-rich async
+  // entry below.
   const rawDevice = _internal_getRawDevice(device);
   if (rawDevice === undefined) {
-    // Rare: the device was not created by makeRhiDevice (external mock, etc.);
-    // the degraded path returns shader-compile-failed as a fallback so an AI
-    // user's exhaustive switch still matches (proposition 9: graceful
-    // degradation).
     return shaderCompileFailed([
       {
         type: 'error',
@@ -256,14 +228,12 @@ export async function createShaderModule(
   }
   const mirrored: { label?: string; code: string } = { code: desc.code };
   if ('label' in desc && desc.label !== undefined) mirrored.label = desc.label;
-  let handle: GPUShaderModule;
   try {
-    handle = rawDevice.createShaderModule(mirrored as GPUShaderModuleDescriptor);
+    return ok(rawDevice.createShaderModule(mirrored as GPUShaderModuleDescriptor));
   } catch (e) {
     // The synchronous part of a real-device createShaderModule rarely throws
     // (spec: errors are surfaced asynchronously through getCompilationInfo);
-    // a few mock shapes might throw — fall back to the
-    // shader-compile-failed path.
+    // a few mock shapes might throw — preserve the public structured error.
     const message = e instanceof Error ? e.message : String(e);
     return shaderCompileFailed([
       {
@@ -276,6 +246,40 @@ export async function createShaderModule(
       } as GPUCompilationMessage,
     ]);
   }
+}
+
+/**
+ * Entry 2 - async `createShaderModule`. The shader-compile-failed path
+ * forwards every 6 fields of `GPUCompilationMessage` to
+ * `RhiError.detail.compilerMessages` (OQ-P2 / F-3 finding).
+ *
+ * Implementation (post fix-f3):
+ *   1) Look up the underlying `GPUDevice` via the in-package
+ *      `_internal_getRawDevice` (RAW_DEVICE_MAP reverse lookup; same module).
+ *   2) `rawDevice.createShaderModule(desc)` calls the spec entry to obtain
+ *      a `GPUShaderModule`.
+ *   3) `await module.getCompilationInfo()` retrieves compilation info.
+ *   4) If any message has `type === 'error'`, return
+ *      `Result.err(RhiError { code: 'shader-compile-failed',
+ *      detail: { compilerMessages } })`.
+ *   5) Otherwise return `Result.ok(module as ShaderModule)`.
+ *
+ * Note: this entry accepts a shim-wrapped RhiDevice (not a raw GPUDevice)
+ * to keep the public API single-source; the in-package
+ * `_internal_getRawDevice` is the only sanctioned reverse lookup.
+ *
+ * fix-f3: the synchronous `RhiDevice.createShaderModule` placeholder is
+ * removed; the shader-compile-failed path closes inside this async entry
+ * (charter proposition 5 consistent abstraction + proposition 4 explicit
+ * failure).
+ */
+export async function createShaderModule(
+  device: RhiDevice,
+  desc: { label?: string | undefined; code: string },
+): Promise<Result<ShaderModule, RhiError>> {
+  const rawResult = createRawShaderModule(device, desc);
+  if (!rawResult.ok) return rawResult;
+  const handle = rawResult.value;
   const handleWithInfo = handle as GPUShaderModule & {
     // forgeax-async-whitelist: dom-native — spec `GPUShaderModule.getCompilationInfo()`
     getCompilationInfo?: () => Promise<GPUCompilationInfo>;
@@ -302,11 +306,43 @@ export async function createShaderModule(
   }
   const errors = info.messages.filter((m) => m.type === 'error');
   if (errors.length > 0) {
-    return shaderCompileFailed(info.messages);
+    // Keep the public six-field GPUCompilationMessage shape intact while
+    // making browser failures attributable to the shader producer. Dawn's
+    // aggregate output is otherwise indistinguishable when several modules
+    // are created during renderer bootstrap.
+    const sourcePrefix =
+      desc.label === undefined ? '' : ` source=${JSON.stringify(desc.code.slice(0, 24))}`;
+    const labeledMessages = info.messages.map((message) => ({
+      message:
+        desc.label === undefined
+          ? message.message
+          : `[${desc.label}]${sourcePrefix} ${message.message}`,
+      type: message.type,
+      lineNum: message.lineNum,
+      linePos: message.linePos,
+      offset: message.offset,
+      length: message.length,
+    })) as GPUCompilationMessage[];
+    return shaderCompileFailed(labeledMessages);
   }
   return ok(handle as unknown as ShaderModule);
 }
 
+/**
+ * Internal render-path shader creation. WebGPU returns a module handle
+ * synchronously; compiler diagnostics remain owned by the public async
+ * `createShaderModule` entry. Render pipeline creation is the validation point
+ * for this path, so software adapters do not serialize their first frame on
+ * `getCompilationInfo()` for every material.
+ */
+export function createShaderModuleImmediate(
+  device: RhiDevice,
+  desc: { label?: string | undefined; code: string },
+): Result<ShaderModule, RhiError> {
+  const result = createRawShaderModule(device, desc);
+  return result.ok ? ok(result.value as unknown as ShaderModule) : result;
+}
+
 /**
  * Build a RhiAdapter shim around a raw GPUAdapter (M3 / break-point #2 / K-5 +
  * K-6).
@@ -398,19 +434,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();
@@ -488,10 +521,12 @@ export function acquireCanvasContext(
  */
 export const rhi: RhiInstance & {
   createShaderModule: typeof createShaderModule;
+  createShaderModuleImmediate: typeof createShaderModuleImmediate;
   acquireCanvasContext: typeof acquireCanvasContext;
 } = {
   requestAdapter,
   createShaderModule,
+  createShaderModuleImmediate,
   acquireCanvasContext,
 };