@forgeax/engine-rhi-null 0.1.2

package/src/queue.ts

@@ -0,0 +1,62 @@
+// @forgeax/engine-rhi-null/src/queue - headless command queue.
+//
+// All write* methods are no-ops returning ok; submit records nothing and
+// returns ok (AC-12). onSubmittedWorkDone resolves immediately so headless
+// read-back idioms never hang (the real GPU resolves after work completes; with
+// no pending work the headless backend resolves synchronously).
+//
+// Related: requirements AC-12 (submit ok + onSubmittedWorkDone resolves);
+// research Finding A1 row 4.
+
+import type {
+  Buffer,
+  CommandBuffer,
+  Result,
+  RhiError as RhiErrorType,
+  RhiQueue,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+
+/** Headless no-op queue. */
+export class RhiNullQueue implements RhiQueue {
+  writeBuffer(
+    _buffer: Buffer,
+    _bufferOffset: number,
+    _data: ArrayBufferView | ArrayBuffer,
+    _dataOffset?: number | undefined,
+    _size?: number | undefined,
+  ): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  writeTexture(
+    _destination: Pick<GPUTexelCopyTextureInfo, 'texture' | 'mipLevel' | 'origin' | 'aspect'>,
+    _data: ArrayBufferView | ArrayBuffer,
+    _dataLayout: Pick<GPUTexelCopyBufferLayout, 'offset' | 'bytesPerRow' | 'rowsPerImage'>,
+    _size: GPUExtent3DStrict,
+  ): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  copyExternalImageToTexture(
+    _source: Pick<GPUCopyExternalImageSourceInfo, 'source' | 'origin' | 'flipY'>,
+    _destination: Pick<
+      GPUCopyExternalImageDestInfo,
+      'texture' | 'mipLevel' | 'origin' | 'aspect' | 'colorSpace' | 'premultipliedAlpha'
+    >,
+    _copySize: GPUExtent3DStrict,
+  ): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  submit(_commandBuffers: readonly CommandBuffer[]): Result<void, RhiErrorType> {
+    return ok(undefined);
+  }
+
+  // forgeax-async-whitelist: dom-native — spec `GPUQueue.onSubmittedWorkDone`
+  // never rejects. The headless backend has no pending GPU work, so it resolves
+  // immediately (AC-12: read-back idioms must not hang).
+  onSubmittedWorkDone(): Promise<undefined> {
+    return Promise.resolve(undefined);
+  }
+}

package/src/shader.ts

@@ -0,0 +1,37 @@
+// @forgeax/engine-rhi-null/src/shader - headless shader module factory (R-2).
+//
+// createShaderModule is the highest-risk hidden contract: the createRenderer
+// ready chain resolves a shader module through a three-tier fallback
+// (RhiBackendPack.createShaderModule -> RhiDevice.createShaderModule duck-typed
+// -> err('rhi-not-available')). If RhiNull provides neither, createRenderer ->
+// ready REJECTS rhi-not-available and AC-02 / AC-10 / AC-13 all fail. RhiNull
+// exposes the top-level async factory (symmetric with rhi-webgpu) that skips
+// real WGSL compilation and returns a legal ShaderModule brand.
+//
+// Related: requirements AC-10 (shader brand skips compile) + AC-02
+// (createRenderer ready does not reject); research Finding A5 (three-tier
+// fallback, top-level factory recommended) + A6 (brand construction);
+// plan-strategy §4 R-2.
+
+import type {
+  Result,
+  RhiDevice,
+  RhiError as RhiErrorType,
+  ShaderModule,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+
+/**
+ * Build a shader module for the headless backend. No WGSL is compiled — the
+ * code is ignored and a legal ShaderModule brand is returned immediately
+ * (<1ms), so the ready chain's shader step always resolves ok (AC-10). Mirrors
+ * the rhi-webgpu top-level `createShaderModule(device, desc)` signature so
+ * Channel 1's RhiBackendPack picks it up via the same `'createShaderModule' in
+ * mod` probe.
+ */
+export function createShaderModule(
+  _device: RhiDevice,
+  _desc: { label?: string | undefined; code: string },
+): Promise<Result<ShaderModule, RhiErrorType>> {
+  return Promise.resolve(ok({} as unknown as ShaderModule));
+}