@forgeax/engine-rhi-webgpu 0.1.7 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-rhi-webgpu",
-  "version": "0.1.7",
+  "version": "0.1.19",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,8 +22,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-rhi": "0.1.7",
-    "@forgeax/engine-types": "0.1.7",
+    "@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

@@ -22,7 +22,13 @@ import type {
 import { type Result, RhiError, type RhiErrorCode } from '@forgeax/engine-rhi';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { makeRhiDevice } from '../device';
-import { acquireCanvasContext, createShaderModule, requestAdapter, requestDevice } from '../index';
+import {
+  acquireCanvasContext,
+  createShaderModule,
+  createShaderModuleImmediate,
+  requestAdapter,
+  requestDevice,
+} from '../index';
 import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gpu-device';
 
 {
@@ -1535,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/index.ts

@@ -205,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',
@@ -257,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([
       {
@@ -277,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>;
@@ -303,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).
@@ -486,10 +521,12 @@ export function acquireCanvasContext(
  */
 export const rhi: RhiInstance & {
   createShaderModule: typeof createShaderModule;
+  createShaderModuleImmediate: typeof createShaderModuleImmediate;
   acquireCanvasContext: typeof acquireCanvasContext;
 } = {
   requestAdapter,
   createShaderModule,
+  createShaderModuleImmediate,
   acquireCanvasContext,
 };