@forgeax/engine-rhi-webgpu 0.1.4 → 0.1.7

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();

package/src/internal/timestamp-query.ts

@@ -2,74 +2,6 @@
 
 import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
 
-export type TimestampQueryHealthCode =
-  | 'timestamp-query-unsupported'
-  | 'timestamp-query-encoder-missing'
-  | 'timestamp-query-generation-mismatch';
-
-export interface TimestampQueryHealth {
-  readonly status: 'ready' | 'fault';
-  readonly code: TimestampQueryHealthCode | undefined;
-  readonly expected: string;
-  readonly hint: string;
-  readonly deviceGeneration: number;
-  readonly expectedGeneration: number | undefined;
-}
-
-/**
- * Keep timestamp capability and device-generation checks structured. This is
- * also the health vocabulary used by recovery callers; a missing capability
- * or stale encoder is never reported as a fabricated timing interval.
- */
-export function timestampQueryHealth(input: {
-  readonly capability: boolean;
-  readonly encoderWriteTimestamp: boolean;
-  readonly deviceGeneration: number;
-  readonly expectedGeneration?: number | undefined;
-}): TimestampQueryHealth {
-  if (!input.capability) {
-    return {
-      status: 'fault',
-      code: 'timestamp-query-unsupported',
-      expected: 'device.caps.timestampQuery is true before timestamp queries are submitted',
-      hint: 'use the CPU timing path or recreate the renderer with timestamp-query capability',
-      deviceGeneration: input.deviceGeneration,
-      expectedGeneration: input.expectedGeneration,
-    };
-  }
-  if (
-    input.expectedGeneration !== undefined &&
-    input.deviceGeneration !== input.expectedGeneration
-  ) {
-    return {
-      status: 'fault',
-      code: 'timestamp-query-generation-mismatch',
-      expected: 'timestamp encoder generation matches the live device generation',
-      hint: 'discard the stale encoder and rebuild timestamp resources during device recovery',
-      deviceGeneration: input.deviceGeneration,
-      expectedGeneration: input.expectedGeneration,
-    };
-  }
-  if (!input.encoderWriteTimestamp) {
-    return {
-      status: 'fault',
-      code: 'timestamp-query-encoder-missing',
-      expected: 'underlying GPUCommandEncoder.writeTimestamp to be callable',
-      hint: 'timestamp-query is advertised but the raw encoder has no writeTimestamp method',
-      deviceGeneration: input.deviceGeneration,
-      expectedGeneration: input.expectedGeneration,
-    };
-  }
-  return {
-    status: 'ready',
-    code: undefined,
-    expected: 'timestamp-query capability and encoder are available for this device generation',
-    hint: 'continue with the timestamp query operation',
-    deviceGeneration: input.deviceGeneration,
-    expectedGeneration: input.expectedGeneration,
-  };
-}
-
 export function resolveTimestampQueries(args: {
   rawEncoder: GPUCommandEncoder;
   rawQuerySet: GPUQuerySet;
@@ -77,28 +9,7 @@ export function resolveTimestampQueries(args: {
   queryCount: number;
   rawDestination: GPUBuffer;
   destinationOffset: number;
-  readonly deviceGeneration?: number;
-  readonly expectedGeneration?: number;
 }): Result<void, RhiError> {
-  if (
-    args.deviceGeneration !== undefined &&
-    args.expectedGeneration !== undefined &&
-    args.deviceGeneration !== args.expectedGeneration
-  ) {
-    const health = timestampQueryHealth({
-      capability: true,
-      encoderWriteTimestamp: true,
-      deviceGeneration: args.deviceGeneration,
-      expectedGeneration: args.expectedGeneration,
-    });
-    return err(
-      new RhiError({
-        code: 'webgpu-runtime-error',
-        expected: health.expected,
-        hint: `${health.code}: ${health.hint}`,
-      }),
-    );
-  }
   try {
     args.rawEncoder.resolveQuerySet(
       args.rawQuerySet,
@@ -124,30 +35,11 @@ export function writeTimestamp(args: {
   rawEncoder: GPUCommandEncoder;
   rawQuerySet: GPUQuerySet;
   queryIndex: number;
-  readonly deviceGeneration?: number;
-  readonly expectedGeneration?: number;
 }): void {
   const encoderWithTimestamp = args.rawEncoder as unknown as {
     writeTimestamp?: (querySet: GPUQuerySet, queryIndex: number) => void;
   };
-  const writeTimestamp = encoderWithTimestamp.writeTimestamp;
-  const health = timestampQueryHealth({
-    capability: true,
-    encoderWriteTimestamp: typeof writeTimestamp === 'function',
-    deviceGeneration: args.deviceGeneration ?? 0,
-    expectedGeneration: args.expectedGeneration,
-  });
-  if (health.status === 'fault') {
-    throw new RhiError({
-      code: 'webgpu-runtime-error',
-      expected: health.expected,
-      hint:
-        health.code === 'timestamp-query-encoder-missing'
-          ? health.hint
-          : `${health.code}: ${health.hint}`,
-    });
-  }
-  if (typeof writeTimestamp !== 'function') {
+  if (typeof encoderWithTimestamp.writeTimestamp !== 'function') {
     throw new RhiError({
       code: 'webgpu-runtime-error',
       expected: 'underlying GPUCommandEncoder.writeTimestamp to be callable',
@@ -155,7 +47,7 @@ export function writeTimestamp(args: {
     });
   }
   try {
-    writeTimestamp(args.rawQuerySet, args.queryIndex);
+    encoderWithTimestamp.writeTimestamp(args.rawQuerySet, args.queryIndex);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new RhiError({

package/dist/__tests__/queue-write-range.browser.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=queue-write-range.browser.test.d.ts.map

package/dist/__tests__/queue-write-range.browser.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"queue-write-range.browser.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/queue-write-range.browser.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/rgba16float-live-probe.browser.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=rgba16float-live-probe.browser.test.d.ts.map

package/dist/__tests__/rgba16float-live-probe.browser.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rgba16float-live-probe.browser.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/rgba16float-live-probe.browser.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/rgba16float-live-probe.d.ts

@@ -1,12 +0,0 @@
-import { type Rgba16floatRenderTargetProbe } from '@forgeax/engine-rhi';
-export interface Rgba16floatLiveProbeEvidence {
-    readonly backend: string;
-    readonly initial: Rgba16floatRenderTargetProbe;
-    readonly loss: {
-        readonly reason: 'destroyed' | 'unknown';
-        readonly message: string;
-    };
-    readonly recovered: Rgba16floatRenderTargetProbe;
-}
-export declare function runRgba16floatLiveProbe(): Promise<Rgba16floatLiveProbeEvidence>;
-//# sourceMappingURL=rgba16float-live-probe.d.ts.map

package/dist/__tests__/rgba16float-live-probe.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rgba16float-live-probe.d.ts","sourceRoot":"","sources":["../../src/__tests__/rgba16float-live-probe.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACtF,QAAQ,CAAC,SAAS,EAAE,4BAA4B,CAAC;CAClD;AAgBD,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,4BAA4B,CAAC,CAerF"}

package/dist/__tests__/rgba16float-live-probe.dawn.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=rgba16float-live-probe.dawn.test.d.ts.map

package/dist/__tests__/rgba16float-live-probe.dawn.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rgba16float-live-probe.dawn.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/rgba16float-live-probe.dawn.test.ts"],"names":[],"mappings":""}

package/src/__tests__/queue-write-range.browser.test.ts

@@ -1,60 +0,0 @@
-import type { RhiDevice } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
-import { rhi } from '../index';
-
-async function requestRhiDevice(): Promise<RhiDevice | undefined> {
-  if (typeof navigator === 'undefined' || navigator.gpu === undefined) return undefined;
-  const adapter = await rhi.requestAdapter();
-  expect(adapter.ok).toBe(true);
-  if (!adapter.ok) return undefined;
-  const device = await adapter.value.requestDevice();
-  expect(device.ok).toBe(true);
-  if (!device.ok) return undefined;
-  return device.value;
-}
-
-describe('browser WebGPU queue.writeBuffer typed range', () => {
-  it('round-trips the exact selected typed-array elements', async () => {
-    const device = await requestRhiDevice();
-    if (device === undefined) return;
-    const target = device.createBuffer({
-      label: 'browser-write-range-target',
-      size: 32,
-      usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
-    });
-    const readback = device.createBuffer({
-      label: 'browser-write-range-readback',
-      size: 32,
-      usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
-    });
-    expect(target.ok && readback.ok).toBe(true);
-    if (!target.ok || !readback.ok) return;
-
-    const write = device.queue.writeBuffer(
-      target.value,
-      0,
-      new Float32Array([10, 20, 30, 40]),
-      1,
-      2,
-    );
-    expect(write.ok).toBe(true);
-    if (!write.ok) return;
-    const encoder = device.createCommandEncoder({ label: 'browser-write-range-copy' });
-    expect(encoder.ok).toBe(true);
-    if (!encoder.ok) return;
-    encoder.value.copyBufferToBuffer(target.value, 0, readback.value, 0, 32);
-    const finish = encoder.value.finish();
-    expect(finish.ok).toBe(true);
-    if (!finish.ok) return;
-    expect(device.queue.submit([finish.value]).ok).toBe(true);
-    await device.queue.onSubmittedWorkDone();
-    const mapped = await readback.value.mapAsync(GPUMapMode.READ);
-    expect(mapped.ok).toBe(true);
-    if (!mapped.ok) return;
-    const range = mapped.value.getMappedRange();
-    expect(range.ok).toBe(true);
-    if (!range.ok) return;
-    expect(Array.from(new Float32Array(range.value.slice(0)))).toEqual([20, 30, 0, 0, 0, 0, 0, 0]);
-    mapped.value.unmap();
-  });
-});

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

@@ -1,13 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { runRgba16floatLiveProbe } from './rgba16float-live-probe';
-
-describe('browser rgba16float live render/readback/recovery probe', () => {
-  it('reads the packed render target on the initial and fresh recovery device', async () => {
-    const evidence = await runRgba16floatLiveProbe();
-    expect(evidence.backend).toBe('webgpu');
-    expect(evidence.initial.pixel).toEqual([0.25, 0.5, 0.75, 1]);
-    expect(evidence.loss.reason).toBe('destroyed');
-    expect(evidence.recovered.pixel).toEqual(evidence.initial.pixel);
-    expect(typeof evidence.initial.timestampQuery).toBe('boolean');
-  });
-});

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

@@ -1,15 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { runRgba16floatLiveProbe } from './rgba16float-live-probe';
-
-describe('Dawn rgba16float live render/readback/recovery probe', () => {
-  it('reads the packed render target on the initial and fresh recovery device', async () => {
-    const evidence = await runRgba16floatLiveProbe();
-    expect(evidence.backend).toBe('webgpu');
-    expect(evidence.initial.pixel).toEqual([0.25, 0.5, 0.75, 1]);
-    expect(evidence.loss.reason).toBe('destroyed');
-    expect(evidence.recovered.pixel).toEqual(evidence.initial.pixel);
-    expect(typeof evidence.initial.timestampQuery).toBe('boolean');
-    // biome-ignore lint/suspicious/noConsole: emitted as live Dawn admission evidence
-    console.log(JSON.stringify({ kind: 'rgba16float-live-probe', ...evidence }));
-  });
-});

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

@@ -1,44 +0,0 @@
-import type { RhiDevice } from '@forgeax/engine-rhi';
-import {
-  probeRgba16floatRenderTarget,
-  type Rgba16floatRenderTargetProbe,
-} from '@forgeax/engine-rhi';
-import { _internal_getRawDevice, rhi } from '../index';
-
-export interface Rgba16floatLiveProbeEvidence {
-  readonly backend: string;
-  readonly initial: Rgba16floatRenderTargetProbe;
-  readonly loss: { readonly reason: 'destroyed' | 'unknown'; readonly message: string };
-  readonly recovered: Rgba16floatRenderTargetProbe;
-}
-
-async function probeFreshDevice(): Promise<{
-  readonly backend: string;
-  readonly device: RhiDevice;
-  readonly report: Rgba16floatRenderTargetProbe;
-}> {
-  const adapter = await rhi.requestAdapter();
-  if (!adapter.ok) throw adapter.error;
-  const device = await adapter.value.requestDevice();
-  if (!device.ok) throw device.error;
-  const probed = await probeRgba16floatRenderTarget(device.value);
-  if (!probed.ok) throw probed.error;
-  return { backend: device.value.caps.backendKind, device: device.value, report: probed.value };
-}
-
-export async function runRgba16floatLiveProbe(): Promise<Rgba16floatLiveProbeEvidence> {
-  const initial = await probeFreshDevice();
-  const rawDevice = _internal_getRawDevice(initial.device);
-  if (rawDevice === undefined)
-    throw new Error('live WebGPU probe requires its backend-owned device');
-  const lost = initial.device.lost;
-  rawDevice.destroy();
-  const loss = await lost;
-  const recovered = await probeFreshDevice();
-  return {
-    backend: initial.backend,
-    initial: initial.report,
-    loss,
-    recovered: recovered.report,
-  };
-}